Idempotência
Repita uma requisição com segurança, sem criar uma correspondência em dobro.
Uma conexão pode cair depois que a CartaFlow recebeu a sua requisição, mas antes de a resposta chegar ao seu sistema. Nesse caso, você não sabe se a correspondência foi criada. Se repetir a chamada sem cuidado, o seu cliente pode receber duas faturas.
O cabeçalho Idempotency-Key resolve isso. Envie um valor único por operação. Se a requisição for repetida com a mesma chave, a API devolve a resposta da primeira vez em vez de criar outro objeto.
curl -X POST "https://api.cartaflow.com.br/v1/letters" \
-H "Authorization: Bearer $CARTAFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: fatura-2026-10-0042" \
-d '{
"to": { "name": "Destinatário Exemplo", "postal_code": "01001-000", "number": "128" },
"document": { "type": "url", "url": "https://arquivos.exemplo.com.br/faturas/2026-10-0042.pdf" }
}'Onde usar
Todos os POST aceitam Idempotency-Key: criar correspondências, uploads e verificações, simular o preço, cancelar e conferir códigos. Use sempre em POST /v1/letters e POST /v1/verifications, que geram cobrança.
As requisições em multipart/form-data, com arquivo, aceitam a chave da mesma forma: POST /v1/letters e POST /v1/letters/quote.
GET não precisa de chave: repetir uma consulta não muda nada. Cancelar duas vezes também é seguro: a segunda chamada devolve o objeto já cancelado, sem erro.
O PUT do arquivo para o upload_url de um upload não vai para a API e não usa Idempotency-Key. Se ele falhar, crie um upload novo e envie o arquivo para o novo upload_url.
Como funciona
| Situação | Resposta |
|---|---|
| Primeira requisição com a chave | Processada normalmente. A resposta fica guardada por 24 horas. |
| Mesma chave, mesmo endpoint e mesmo corpo | A resposta guardada, com o mesmo status e o mesmo corpo, e o cabeçalho Idempotent-Replayed: true. Nada é criado nem cobrado de novo. |
| Mesma chave com outro corpo ou em outro endpoint | 409 com idempotency_key_reused. Nada é criado. |
| Mesma chave enquanto a primeira ainda está em andamento | 409 com idempotency_key_in_use. Espere um segundo e repita. |
| A primeira terminou com erro 5xx | A resposta não é guardada. Como nada foi criado, a repetição é processada como nova. |
As respostas 2xx e 4xx ficam guardadas. Uma requisição que falhou por um erro seu, como um CEP inválido, continua falhando com a mesma chave. Corrija o corpo e use uma chave nova.
Depois de 24 horas a chave expira e pode ser usada de novo como se fosse nova.
Como escolher a chave
A chave precisa representar a operação, não a tentativa. Todas as tentativas da mesma operação usam a mesma chave.
- Use um identificador do seu negócio, como o id da fatura ou do pedido:
fatura-2026-10-0042. Ele já é único e continua o mesmo quando o seu sistema reinicia. - Ou gere um UUID e guarde antes de chamar. Salve a chave junto do registro no seu banco e só depois faça a requisição. Assim, se o processo cair, a nova tentativa usa a mesma chave.
Não gere uma chave nova a cada tentativa: isso desliga a proteção.
A chave pode ter até 255 caracteres. Uma chave vazia ou maior que isso recebe 400 com invalid_idempotency_key.
Repetir com segurança
Repita requisições que falharam por falha de rede, tempo esgotado, 429, 500 ou 503, sempre com a mesma Idempotency-Key e com espera crescente entre as tentativas. Veja Erros para o passo a passo e um exemplo de código.