Idempotência
external_order_id como chave, reserva antecipada, replay 200 com replayed:true e 409 PROCESSING_IN_FLIGHT.
O external_order_id é a chave de idempotência do pedido. A OnmIA reserva o
id antes de processar (reservation-first), o que torna seguro reenviar o mesmo
pedido em caso de timeout ou retry.
Comportamento
| Situação | Resposta |
|---|---|
Primeiro envio de um external_order_id | 201 (pedido criado). |
Reenvio do mesmo external_order_id já concluído | 200 com o mesmo shape + "replayed": true (mesmo order_id). |
| Envio concorrente enquanto o primeiro ainda processa | 409 PROCESSING_IN_FLIGHT. |
Falha no meio da criação (ex.: 500) | A reserva é desfeita; o retry com o mesmo id fica limpo. |
Replay
Reenviar um pedido já concluído retorna o mesmo order_id com a flag
replayed: true:
{
"order_id": "949e4706-c108-4a6c-b9cd-4e89c043935d",
"display_number": "#2026-000123",
"status": "confirmed",
"external_order_id": "ERP-PED-2026-4412",
"items_inserted": 2,
"stock_decremented": false,
"replayed": true
}stock_decremented no replay
No replay, stock_decremented é sempre false — o valor original não é
reconstruído. Integrações com decremento opt-in devem auditar pelo log de
movimentos de estoque da OnmIA, não por este campo.
Processamento concorrente
Se outra requisição com o mesmo external_order_id ainda estiver processando,
você recebe 409 PROCESSING_IN_FLIGHT. Faça retry com backoff usando o mesmo
external_order_id — você receberá o 201 ou o replay 200 quando o primeiro
concluir.
Nunca troque o external_order_id
Jamais mude o external_order_id para "destravar" um 409. Cada id novo
cria um pedido duplicado. Sempre reenvie o mesmo id; a idempotência cuida do
resto.