Idempotência

Redes instáveis, tempos esgotados e reinícios de servidor fazem parte de qualquer integração. A idempotência garante que repetir o envio de uma proposta nunca crie uma proposta duplicada.

Como funciona

Criar proposta assíncrona exige o campo idempotencyKey, um texto de até 128 caracteres que identifica a proposta do seu lado.

Situação	Resposta
Primeira requisição com a chave	HTTP 202 com um novo requestId.
Mesma chave, mesmo conteúdo	HTTP 202 com a mesma solicitação. Nenhuma proposta nova é criada e a operação não é cobrada outra vez.
Mesma chave, conteúdo diferente	HTTP 409 com code igual a IDEMPOTENCY_PAYLOAD_MISMATCH.

A chave vale por parceiro: duas chaves iguais enviadas por parceiros diferentes não interferem entre si.

Nota

Criar proposta, a versão síncrona, não aceita idempotencyKey. Para repetir envios com segurança, use a versão assíncrona.

Escolher a chave

• Use um identificador estável da proposta no seu sistema, como o ID interno da proposta ou um UUID gerado e salvo antes do primeiro envio.
• Use uma chave nova para cada proposta diferente.
• Nunca reutilize a chave de uma proposta para enviar outra, mesmo depois de a primeira ser recusada.

Fluxo recomendado

1. Gere e salve a idempotencyKey junto com a proposta no seu sistema.
2. Envie a proposta com Criar proposta assíncrona.
3. Se receber HTTP 202, salve o requestId.
4. Se a requisição falhar por tempo esgotado, erro de rede ou HTTP 5xx, repita com a mesma chave e o mesmo conteúdo.
5. Se não souber se o primeiro envio chegou, recupere a solicitação com Buscar solicitação usando o parâmetro idempotencyKey.

Conflitos

code	Causa	O que fazer
IDEMPOTENCY_PAYLOAD_MISMATCH	A chave já foi usada com outro conteúdo.	Se for a mesma proposta, reenvie o conteúdo original. Se for outra proposta, use uma chave nova.
ACTIVE_REQUEST	Já existe uma solicitação ativa para o mesmo cliente e operação.	Acompanhe a solicitação existente antes de enviar outra.