Idempotência - v1.0.0-beta.1 - [PC] Portabilidade de Crédito - CF

Segundo a W3C, “um método HTTP idempotente é um método HTTP que pode ser chamado muitas vezes sem resultados diferentes ou efeitos colaterais. Não importa se o método é chamado apenas uma vez ou dez vezes. O resultado deve ser o mesmo. Essencialmente, significa que o resultado de uma solicitação executada com sucesso é independente do número de vezes que ela é executada. Por exemplo, na aritmética, adicionar zero a um número é uma operação idempotente.”

Os métodos HTTP GET, PUT e DELETE são naturalmente idempotentes, assim como HEAD, OPTIONS e TRACE.
Por outro lado, os métodos POST e PATCH não são idempotentes por padrão e exigem um tratamento específico para que se comportem dessa forma. Implementar esse tratamento é essencial para evitar efeitos indesejados.

Por que é necessário tratarmos a Idempotência para Portabilidade de Crédito?

Imagine que uma solicitação de portabilidade seja realizada por meio da API Portabilidade de Crédito e, após alguns segundos, ocorra o retorno de uma mensagem de timeout. Nesse cenário, não é possível saber se a solicitação foi processada com sucesso. Caso uma nova requisição seja enviada sem o devido tratamento de idempotência, há o risco de a operação ser executada em duplicidade.

Como mitigarmos esse risco?

A instituição proponente deve enviar a solicitação acompanhada de um GUID de idempotência. Caso seja necessário reenviar a mesma requisição — por falha de comunicação ou qualquer outro motivo — o payload deve ser reenviado utilizando o mesmo GUID, garantindo que a operação não seja duplicada.
Já a instituição credora deve validar o GUID de idempotência recebido. Se identificar que o GUID já foi processado anteriormente, a nova solicitação deve ser descartada, evitando o reprocessamento da operação.

Importante:

Cada nova solicitação deve conter um GUID de idempotência exclusivo.
Além disso, a instituição proponente não deve utilizar o comportamento idempotente do endpoint POST /portabilities como forma de consultar o status do recurso.

Conjunto inicial de regras propostas na aplicação da idempotência:

A instituição proponente não deve alterar o corpo da solicitação ao reutilizar a mesma chave de idempotência. Caso isso ocorra, a instituição credora não deve modificar o recurso final.
A instituição credora não deve criar um novo recurso se a solicitação for identificada como idempotente. Na criação do recurso, a resposta da credora deve refletir o status atual do recurso (ou um status ao menos tão atualizado quanto o disponível nos canais eletrônicos existentes), retornando o código HTTP 202 (ACCEPTED), conforme o contexto da requisição.
A proponente não deve utilizar o comportamento idempotente como mecanismo de consulta de status dos recursos.
A credora pode utilizar a assinatura da mensagem em conjunto com a chave de idempotência para validar se o corpo da requisição permanece inalterado.
A chave de idempotência deve ser armazenada para controle quando a requisição for:
- Processada com sucesso (HTTP 202), ou
- Rejeitada por erro de negócio (HTTP 422).
O comportamento idempotente deve ser garantido por um período de 24 horas para uma mesma chave.
Toda nova requisição exige uma nova assinatura da mensagem, com um novo valor de jti e iat.

Cenários de uso de idempotência

Quando uma nova requisição for recebida com a mesma chave x-idempotency-key e a claim data do JWT idêntica à da requisição original, ela deve ser processada entregando exatamente o mesmo resultado anteriormente retornado. Isso significa que, se a requisição original tiver criado um recurso, esse mesmo recurso deverá ser retornado, com seu status atualizado.
Ao receber uma requisição com o mesmo x-idempotency-key e com a claim data do JWT com conteúdo diferente do original a requisição deverá ser recusada com o HTTP Status 422 com código ERRO_IDEMPOTENCIA;
Por outro lado, se a requisição reutilizar a mesma x-idempotency-key, mas contiver uma claim data diferente daquela enviada inicialmente, ela deve ser recusada com HTTP Status 422 e o código de erro ERRO_IDEMPOTENCIA. Da mesma forma, se a requisição contiver o mesmo x-idempotency-key, mas a claim iss não pertencer à organização que possui o software cliente (clientId), a solicitação deve ser recusada com HTTP Status 403.
A validação de idempotência deve ser realizada no escopo de cada endpoint individualmente ou seja, a reutilização de uma mesma chave x-idempotency-key entre endpoints diferentes deve ser permitida pela instituição credora.