Depois de um tempo esgotado sem resposta, repetir uma chamada pode apenas consultar de novo ou pode gerar outra cobrança. Os conceitos de método seguro e de operação idempotente descrevem o efeito pedido por uma chamada e ajudam a avaliar se a repetição é segura.
O método seguro
Um método seguro tem o sentido de leitura: quem chama não pede nenhuma alteração no recurso. Isso não significa ausência de qualquer efeito. O servidor pode registrar o acesso, atualizar contadores ou executar outras tarefas internas.
Os métodos GET, HEAD e OPTIONS são seguros pela definição do HTTP. Uma aplicação que usa o GET para efetuar uma cobrança contraria essa definição, e o nome do método não torna inofensiva uma implementação incorreta. Uma consulta também tem custo e pode estar sujeita a limites de chamadas.
A operação idempotente
Uma operação idempotente tem o mesmo efeito pretendido quando a mesma requisição é aplicada uma vez ou várias vezes. As respostas de cada tentativa e os registros podem ser diferentes.
Remover um recurso duas vezes, por exemplo, pode produzir o código 204, de sucesso sem conteúdo, na primeira tentativa e o código 404, de recurso não encontrado, na segunda. O efeito pretendido continua o mesmo: o recurso deixa de existir. Idempotência não significa receber duas respostas iguais.
Pela definição do HTTP, os métodos GET, HEAD, OPTIONS, PUT e DELETE são idempotentes. Os métodos POST e PATCH não têm essa garantia. Um PATCH que define um valor pode ser idempotente, enquanto outro que soma uma quantidade acrescenta o valor de novo a cada execução.
Repetir uma cobrança
Uma API pode tornar repetível uma operação de criação feita por POST com uma chave de idempotência, um código que o sistema envia junto com a operação e que o serviço usa para reconhecer uma repetição. A API também pode usar um identificador único do negócio, como o número do pedido. Nos dois casos, o contrato explica como a chave funciona, por quanto tempo ela vale e o que acontece quando uma repetição chega com dados diferentes.
Quando um POST de cobrança termina sem resposta, o fornecedor pode ter processado a cobrança. A situação é consultada pelo mecanismo da integração, e a repetição segue a política do contrato. Uma consulta que não encontra a cobrança, ou que a encontra pendente, também precisa ser interpretada pelo contrato, e não autoriza, sozinha, a criação de outra cobrança.
O alcance da proteção
A chave precisa representar a mesma intenção, com os mesmos dados exigidos pelo contrato. Gerar uma chave nova a cada repetição transforma um único pagamento em cobranças independentes. Reutilizar a chave de um pagamento em outro pagamento também é incorreto.
O serviço guarda a chave por um prazo, e cada contrato define esse prazo, a conta ou a operação em que a chave vale e o tratamento de chamadas simultâneas. Depois que o prazo termina, a mesma chave pode voltar a criar um recurso. Não existe um prazo único para todos os gateways, PBMs e soluções de TEF.
Mesmo em uma operação idempotente, repetir sem limite consome recursos do serviço. O prazo, o limite de tentativas e a consulta da situação continuam necessários.
No suporte
Antes de reenviar uma operação, convém identificar o efeito dela e a proteção contra repetição. Em uma cobrança com resultado desconhecido, a situação é consultada primeiro, e a repetição usa o mesmo identificador ou a mesma chave, quando o contrato exige.
Para guardar
- Um método seguro pede apenas leitura, sem prometer ausência de efeitos internos.
- Idempotente significa o mesmo efeito pretendido, e não a mesma resposta.
- O POST não é idempotente pela definição do HTTP, e o contrato pode protegê-lo com uma chave.
- Uma chave nova a cada tentativa pode criar cobranças em duplicidade.
- Um POST sem resposta pode ter sido processado.
Um DELETE recebeu o código 204, e a repetição recebeu o código 404. Isso contraria a idempotência?
Não. O recurso continua removido, embora a segunda resposta informe que ele não foi encontrado. O efeito pretendido é o mesmo.
Um POST de cobrança terminou em tempo esgotado. É possível reenviar só porque não houve resposta?
Não. A cobrança pode ter sido processada. A situação é consultada primeiro, e a repetição segue o procedimento do fornecedor, com a mesma chave de idempotência quando ela existe.