O log de uma integração pode mostrar o endereço, a credencial, o código e o conteúdo de uma mesma chamada. Reconhecer as partes de uma requisição e de uma resposta ajuda a separar o que o sistema pediu do que o serviço respondeu.
A requisição
A requisição é a mensagem que o cliente envia ao serviço. Na versão 1.1 do HTTP, a requisição que cria uma cobrança no gateway de pagamento tem estas linhas, em forma resumida:
POST /v1/pagamentos HTTP/1.1: a linha inicial, com o método, o caminho e a versão do protocolo;Host: api.example.com: o nome do serviço de destino;Content-Type: application/json: o formato do conteúdo enviado;Authorization: Bearer <token>: a credencial, com o token mascarado;X-Correlation-ID: operacao-0001: um identificador de rastreio criado pelo sistema;- uma linha em branco, que separa os cabeçalhos do conteúdo;
{"pedido_id": "PED-0001", "valor_total": 50.00}: o corpo, com os dados da cobrança.
A primeira linha informa o método, que indica a intenção da chamada, o caminho, que indica o recurso dentro do serviço, e a versão do protocolo. As linhas seguintes são os cabeçalhos, com as informações de controle: o destino, o formato, a credencial e o rastreio. Depois da linha em branco vem o corpo, com os dados da operação. O conteúdo transportado no corpo também é chamado de payload.
As versões mais novas do HTTP representam essas informações de outra forma, e o log de um programa pode registrar só uma parte delas.
Os campos da cobrança
No contrato do gateway de pagamento, o corpo da criação de uma cobrança tem estes campos:
pedido_id: o número do pedido no site de vendas, que não pode se repetir em outra cobrança;cliente: um grupo com o identificador, o nome, o documento e o e-mail do cliente;forma_pagamentoeparcelas: a forma de cobrança e o número de parcelas;itens: a lista dos produtos, cada um com o código, a descrição, a quantidade e o valor unitário;frete: o valor do frete, opcional, que vale zero quando não é informado;valor_total: o valor da cobrança, que precisa ser igual à soma dos itens com o frete.
Essas regras pertencem ao contrato do gateway de pagamento. Outro fornecedor pode usar outros nomes e outras regras para a mesma operação.
A resposta
A resposta do gateway de pagamento à criação da cobrança tem estas linhas, também em forma resumida:
HTTP/1.1 201 Created: a linha inicial, com a versão e o código de situação;Content-Type: application/json: o formato do conteúdo;Location: /v1/pagamentos/PAG-0001: o endereço da cobrança criada;X-Request-ID: requisicao-0001: o identificador da requisição no serviço;- uma linha em branco;
{"id": "PAG-0001", "status": "pendente"}: o corpo, com o número da cobrança e a situação dela.
O código de situação, também chamado de status HTTP, informa como o serviço tratou a requisição. O código 201 indica que um recurso foi criado, e o cabeçalho Location aponta o endereço desse recurso. O corpo, porém, informa que a cobrança está pendente. A criação do registro não equivale à aprovação do pagamento.
Identificadores com funções diferentes
Os cabeçalhos X-Correlation-ID e X-Request-ID são exemplos de identificadores de rastreio usados por muitas aplicações, e não fazem parte de toda API. Junto com o número da cobrança e o horário, com o fuso, esses identificadores ajudam a relacionar os registros do sistema da loja com os registros do fornecedor.
Três identificadores aparecem com frequência e têm funções diferentes:
- Identificador do pedido: identifica o negócio, como o pedido PED-0001 do site de vendas.
- Identificador da requisição: identifica uma chamada específica, com início, duração e resposta próprios.
- Chave de idempotência: um código que permite ao serviço reconhecer a repetição de uma mesma operação, quando o contrato prevê esse recurso.
O pedido PED-0001 pode ter duas tentativas de consulta, cada uma com o seu identificador de requisição. Um identificador de rastreio ajuda a encontrar os registros, mas só impede uma cobrança em duplicidade quando o contrato atribui a ele essa função.
No suporte
Antes de interpretar o resultado, convém separar o método, o caminho, os cabeçalhos e o corpo. Os identificadores úteis ficam preservados, e a credencial fica mascarada, porque o fornecedor precisa localizar a operação, e não receber o token.
Para guardar
- A requisição traz o método, o caminho, os cabeçalhos e o corpo com os dados da operação.
- A resposta traz o código de situação, os cabeçalhos e o resultado.
- O código 201 confirma a criação do recurso, e não a aprovação do pagamento.
- O identificador do pedido, o identificador da requisição e a chave de idempotência têm funções diferentes.
A resposta tem o código 201 e a situação pendente. O pagamento está aprovado?
Não. A cobrança foi criada, mas o campo de situação informa que ela está pendente. O resultado final é acompanhado pelo mecanismo previsto no contrato.
Quais informações ajudam o fornecedor a localizar uma cobrança com erro?
A data e o horário, com o fuso, o número do pedido ou da cobrança e os identificadores de rastreio disponíveis. Esses dados relacionam a chamada aos registros do fornecedor, sem expor a credencial.