As duas camadas de resultado

Um benefício pode ser recusado em uma resposta com o código 200, e uma cobrança pode ser criada e continuar pendente. Esses casos só ficam claros quando o resultado técnico da chamada e o resultado do negócio são lidos juntos.

O resultado técnico

O resultado técnico mostra como a chamada transcorreu. O status HTTP informa como a camada que respondeu tratou a requisição. Uma exceção registrada pelo programa informa uma falha anterior à resposta, como na conexão, na negociação TLS ou na leitura. Esses dados localizam a etapa da chamada, mas não resumem a operação de negócio.

O resultado de negócio

O corpo da resposta informa o que aconteceu com a operação: um pagamento aprovado, um benefício recusado ou um processamento ainda pendente. O contrato define os campos e o significado de cada código. Nem todo erro informado no corpo é uma recusa de negócio, porque o corpo também registra erros de validação e falhas internas da aplicação.

Três situações mostram as duas camadas na mesma resposta:

• no gateway de pagamento, o código 201 com a situação recusado indica que a cobrança foi registrada e que o pagamento foi recusado, e a origem da recusa depende do motivo informado;
• no PBM, o código 200 com "situacao": "erro" e "codigo": 14 exige a tabela de códigos do fornecedor, e, quando essa tabela define o código 14 como cartão inválido, a resposta registra uma recusa do benefício;
• em um serviço SOAP, o código 200 pode acompanhar um retorno normal com um código de recusa no corpo, e uma falha da aplicação pode vir em um elemento Fault, com outra forma de leitura.

As duas camadas pertencem à mesma chamada e se complementam. O status HTTP e o corpo também podem se contradizer, e uma contradição com o contrato é, por si, uma informação útil para a análise.

Quando o log não mostra o status

Alguns logs registram só o corpo da resposta. Nesses casos, os campos registrados e as exceções da mesma operação e da mesma tentativa orientam a leitura. Uma resposta de negócio válida mostra que houve resposta, mas não permite reconstruir o status HTTP omitido. A ausência do status no log também não prova uma falha anterior ao HTTP.

Final, pendente e desconhecido

A situação de uma operação cabe em uma destas três categorias:

• Final: o resultado conclusivo daquela operação, segundo o contrato, como a autorização ou a recusa de uma pré-autorização.
• Pendente: um estado conhecido, que ainda exige acompanhamento.
• Desconhecido: a situação de quem observa, quando a resposta não chegou ou não foi registrada.

Um resultado final não impede eventos posteriores, e um pagamento aprovado ainda pode ser cancelado ou estornado. O resultado desconhecido descreve o que se sabe sobre a operação, e não uma situação gravada no fornecedor. Gravar a operação como recusada só para retirá-la da lista de pendências pode esconder uma cobrança que aconteceu.

Uma consulta que encontra a cobrança pendente esclarece mais do que o tempo esgotado da primeira tentativa, mas ainda não comprova o pagamento. A conclusão acompanha a evidência mais recente da mesma operação e as mudanças de situação permitidas no contrato.