Fundamentos
Idempotência
Retente a criação de pré-autorização sem medo de gerar duas operações para a mesma nota.
Por que usar
Timeouts acontecem. Se o seu ERP enviou a pré-autorização e a resposta não chegou, ele não sabe se a operação foi
criada. Com o header Idempotency-Key, a retentativa é segura: a Oneos reconhece a chave e devolve a
mesma operação, sem criar outra.
Como enviar
Idempotency-Key: PED-4581-nf-48211- De 8 a 100 caracteres, só letras, números e
. _ : -. Um UUID serve. - Derive a chave do que você está pré-autorizando — pedido, nota, parcela — e não de um valor aleatório gerado a cada tentativa. Assim até uma retentativa depois de o seu sistema reiniciar reaproveita a mesma chave.
- Vale só para criar pré-autorização. O cancelamento não precisa: repeti-lo já é seguro, e a consulta é leitura.
- A chave é da empresa: duas chaves de API da mesma empresa compartilham o mesmo espaço de chaves.
O que a Oneos responde
| Situação | Resposta |
|---|---|
| Primeira vez com a chave | Processa normalmente. |
| Mesma chave e mesmo corpo, já concluída |
201 com a resposta original e o header Idempotency-Replayed: true.
É uma fotografia do momento da criação — o status pode ter mudado desde então.
|
| Mesma chave e corpo diferente | 409 IDEMPOTENCY_KEY_REUSED |
| Mesma chave enquanto a primeira ainda está sendo processada | 409 IDEMPOTENCY_REQUEST_IN_PROGRESS com Retry-After: 2 |
| A primeira tentativa terminou em erro (4xx ou 5xx) | A chave é liberada: reenviar com ela processa de novo. |
Por quanto tempo vale
A chave é lembrada por 7 dias. Depois disso, a mesma chave cria uma operação nova. Uma requisição parada no meio do processamento prende a chave por até 90 segundos.
JSON e multipart não se misturam
O mesmo conteúdo enviado como JSON e como multipart/form-data conta como corpo diferente.
Retente sempre no mesmo formato da primeira tentativa. O arquivo da nota entra na comparação pelo nome, tamanho e tipo.
Erros
| Status | Código | Quando acontece |
|---|---|---|
| 400 | IDEMPOTENCY_KEY_INVALID |
O header está fora do formato (tamanho ou caracteres). |
| 409 | IDEMPOTENCY_KEY_REUSED |
A chave já foi usada com outro corpo. Use outra chave para outra nota. |
| 409 | IDEMPOTENCY_REQUEST_IN_PROGRESS |
A mesma requisição ainda está em processamento.
Espere o Retry-After e repita.
|