Idempotência
idempotency_key em escritas de fidelidade, dedup de cupom por (cupom, order_id), e dedup de entregas de webhook por delivery_id e order.created na origem.
A API v1.1 expõe idempotência em dois lugares: nas escritas de fidelidade
(você controla com idempotency_key) e na entrega de webhooks (a OnmIA
deduplica na origem; você reforça com X-Onmia-Delivery-Id).
O ERP não cria pedidos
A idempotência de criação de pedido (POST /orders com external_order_id)
não existe mais — esses endpoints foram removidos em v1.1. O fluxo de pedido é
OnmIA→ERP (ver Pedidos). Idempotência de criação ficou só do
lado da OnmIA.
Escritas de fidelidade (idempotency_key)
Crédito/débito de pontos e resgate de cupom aceitam idempotency_key. Reenviar a
mesma chave produz um único efeito — o segundo envio é um replay sem novo
lançamento.
curl -sS https://api.onmia.com.br/integration/v1/loyalty/points \
-H "X-API-Key: $ONMIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "5537991129034",
"points": 100,
"idempotency_key": "erp-bonus-2026-06-13-3310"
}'| Situação | Resposta |
|---|---|
Primeiro envio de uma idempotency_key | 200 com idempotent_replay: false e o saldo atualizado. |
Reenvio da mesma idempotency_key | 200 com idempotent_replay: true e o saldo inalterado. |
| Débito maior que o saldo | 422 INSUFFICIENT_BALANCE. |
| Corrida concorrente no crédito | 409 CONFLICT (re-tente com a mesma chave). |
Uma chave por lançamento lógico
Gere um idempotency_key único por lançamento (ex.: erp-bonus-<cliente>-<data>,
erp-redeem-<pedido>). Reusar a mesma chave para lançamentos diferentes faz o
segundo ser engolido como replay. Trocar a chave a cada retry duplica o
efeito — sempre reenvie a mesma chave do lançamento original.
O resgate de cupom é idempotente por (cupom, order_id) além do
idempotency_key: marcar o mesmo cupom no mesmo pedido duas vezes não consome
duas vezes. Detalhes em Fidelidade.
Entrega de webhooks (dedup na origem)
Você não controla a idempotência da entrega — a OnmIA já a garante:
order.createdé dedupado na origem. Mesmo que dois caminhos internos disparem o mesmo pedido, você recebe no máximo uma entrega por endpoint.order.status_changed: cada transição (pedido + novo status) gera no máximo uma entrega por endpoint.- Retries reúsam o
delivery_id. As várias tentativas de uma mesma entrega carregam o mesmoX-Onmia-Delivery-Id(com timestamp e assinatura novos a cada tentativa).
Dedup do lado do ERP
Mesmo com dedup na origem, use X-Onmia-Delivery-Id como chave de dedup
interna no seu receptor. Se o seu endpoint responder 2xx mas a resposta se
perder na rede, a OnmIA pode reentregar — e o delivery_id igual te protege de
processar o mesmo evento duas vezes. Ver Webhooks.