Pedidos
Os pedidos fluem do OnmIA para o ERP automaticamente via webhook. O ERP recebe e consulta — não cria pedidos.
Os pedidos nascem no OnmIA (catálogo público, agente de WhatsApp/IA,
dashboard, iFood) e são enviados ao seu ERP automaticamente via o webhook
order.created, com todos os dados do pedido. O ERP não cria pedidos na
OnmIA.
A criação de pedidos pelo ERP (POST /integration/v1/orders) e a alteração de
status (PATCH) não existem nesta API — foram removidas em v1.1, junto com o
scope orders:write. O fluxo de pedido é unidirecional: OnmIA → ERP. Para
receber, registre um webhook (ver Webhooks). Para consultar,
use os GET abaixo (orders:read).
Como os pedidos chegam ao ERP
- Um pedido é feito no OnmIA por qualquer canal.
- A OnmIA dispara
order.createdpara os webhooks ativos do seu cliente, com o pedido completo (cliente, endereço, itens comexternal_id, pagamento, frete, totais). - Mudanças de status posteriores disparam
order.status_changed.
O payload completo de order.created está documentado em
Webhooks.
order.created — receber o pedido novo
Dispara em todos os canais (catálogo PWA, WhatsApp/IA, lançamento manual no
dashboard, iFood), uma vez por pedido, deduplicado na origem. Trate este
evento no seu endpoint receptor para dar entrada do pedido no ERP. O campo
items[].external_id é a chave do produto no seu catálogo (o mesmo enviado
em products/bulk) — use para mapear cada linha.
order.status_changed — acompanhar o andamento
Dispara a cada transição relevante (confirmação, separação, saída para entrega,
entrega, cancelamento) conduzida pelos canais OnmIA (picking, entregador, iFood,
dashboard). Traz um resumo com previous_status e status (sem itens).
Detectar a finalização do pedido
Para saber que um pedido terminou (e fechar/baixar no ERP), filtre o evento
order.status_changed por status ∈ { "delivered", "cancelled" } (estados
terminais). delivered = pedido entregue; cancelled = pedido cancelado.
Os demais valores são estados intermediários — ver
Ciclo de vida do pedido.
Consultar pedido por id
curl -sS https://api.onmia.com.br/integration/v1/orders/$ORDER_ID \
-H "X-API-Key: $ONMIA_API_KEY"Scope orders:read. Resposta (200) com os itens do pedido:
{
"order_id": "949e4706-c108-4a6c-b9cd-4e89c043935d",
"display_number": "#2026-000123",
"status": "confirmed",
"store_id": "c5745b49-3883-45f9-8dc4-63cc7d9f2611",
"external_order_id": "ERP-PED-2026-4412",
"external_display_id": "4412",
"subtotal": 67.98,
"freight_price": 0,
"total": 67.98,
"payment_method": "pix",
"payment_status": "paid",
"delivery_type": "pickup",
"created_at": "2026-06-12T15:04:05.000Z",
"items": [
{ "product_id": "f0a1b2c3-d4e5-4f60-8172-93a4b5c6d7e8", "quantity": 2, "unit_price": 17.99, "notes": null },
{ "product_id": "a9b8c7d6-e5f4-4321-9098-76543210fedc", "quantity": 1, "unit_price": 32.0, "notes": null }
]
}Pedido inexistente, de outro merchant (ou de loja fora do escopo da chave) →
404 NOT_FOUND (sem vazar existência).
Consultar por external_order_id
curl -sS "https://api.onmia.com.br/integration/v1/orders?external_order_id=ERP-PED-2026-4412" \
-H "X-API-Key: $ONMIA_API_KEY"Retorna sempre um array: vazio ([]) quando não encontrado, ou 1 elemento
(resumo sem items) quando encontrado. Resolve por merchant_id + external_order_id. external_order_id ausente → 400 VALIDATION_ERROR.
Use as leituras acima para reconciliação — quando uma entrega de webhook
falhar/morrer (dead) ou você quiser confirmar o estado atual.
Autoridade de estoque
O ERP é a autoridade de estoque. A OnmIA não decrementa estoque do ERP — você
envia o saldo novo por PATCH /integration/v1/stock. Pedidos
feitos no OnmIA já refletem o estoque que você sincronizou.
Estoque e preço
PATCH /stock — set absoluto de estoque/preço por loja, store_id por item, PRODUCT_NOT_FOUND e remoção de price_override.
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.