Pedidos

POST /orders (status confirmed), GET /orders/{id}, busca por external_order_id, PATCH de status e autoridade de estoque.

Envie pedidos do ERP para a OnmIA com POST /integration/v1/orders. Escritas exigem o scope orders:write; leituras, orders:read.

Criar pedido

curl -sS https://api.onmia.com.br/integration/v1/orders \
  -H "X-API-Key: $ONMIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_order_id": "ERP-PED-2026-4412",
    "external_display_id": "4412",
    "store_id": "c5745b49-3883-45f9-8dc4-63cc7d9f2611",
    "status": "confirmed",
    "customer": { "name": "Jader Costa", "phone": "5537991129034", "email": null },
    "items": [
      { "external_id": "ERP-7891", "quantity": 2, "unit_price": 17.99 },
      { "external_id": "ERP-8001", "quantity": 1, "unit_price": 32.0 }
    ],
    "delivery_type": "pickup",
    "freight_price": 0,
    "payment_method": "pix",
    "payment_status": "paid",
    "metadata": { "erp_terminal": "PDV-02" }
  }'

Campos do payload

Campo	Obrigatório	Regras
`external_order_id`	sim	Chave de idempotência do pedido no ERP.
`external_display_id`	não	Número curto exibível (ex.: número do cupom).
`store_id`	sim	UUID; deve estar no escopo da chave (`403 FORBIDDEN_STORE`).
`status`	não	Na criação, somente `confirmed` é aceito (default).
`customer.name`	sim	—
`customer.phone`	sim	Mínimo 8 dígitos; normalizado para E.164 BR sem `+`.
`customer.email`	não	Aceita `null`.
`items[]`	sim	1 a 500 itens; `quantity` > 0 (decimal ok); `unit_price` >= 0; `notes` opcional.
`delivery_type`	sim	`pickup` ou `delivery`.
`freight_price`	não	>= 0, default 0.
`payment_method`	sim	Texto livre do ERP (ex.: `pix`, `cash`, `credit_card`).
`payment_status`	não	`pending`, `awaiting`, `paid`, `failed`, `refunded`.
`change_for`	não	Troco para (>= 0, aceita `null`).
`delivery_address`	não	Objeto JSON livre.
`metadata`	não	Objeto JSON livre, persistido para auditoria.

O unit_price enviado é confiado como está (a venda já aconteceu no seu sistema). A OnmIA localiza o cliente por telefone (tolerante à variação do nono dígito) e cria se não existir — dados de cliente já existente são preservados, o pedido nunca sobrescreve nome/email cadastrados.

Resposta de criação (201):

{
  "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
}

Item sem produto mapeado

Se algum external_id dos itens não existir no catálogo, o pedido retorna 422 UNMAPPED_ITEMS (com details.unmapped_external_ids) e não é criado — sem efeito parcial. Cadastre os produtos via POST /products/bulk antes.

Autoridade de estoque

Por padrão a OnmIA não decrementa estoque ao receber pedido via API — por design, o ERP é a autoridade e envia o saldo novo via PATCH /stock após a venda. Chaves especiais podem ter decremento opt-in (combinado na emissão); nesse modo, estoque insuficiente retorna 400 INSUFFICIENT_STOCK e o pedido não é criado.

Consultar por id

curl -sS https://api.onmia.com.br/integration/v1/orders/$ORDER_ID \
  -H "X-API-Key: $ONMIA_API_KEY"

Retorna o pedido completo (com items). Pedido inexistente, de outro merchant ou de loja fora do escopo: 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.

Atualizar status

curl -sS -X PATCH https://api.onmia.com.br/integration/v1/orders/$ORDER_ID/status \
  -H "X-API-Key: $ONMIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "cancelled" }'

{ "order_id": "949e4706-...", "status": "cancelled", "previous_status": "confirmed" }

Status v1 aceitos nesta rota: confirmed e cancelled. Outro valor: 400 VALIDATION_ERROR.
A transição é validada pela máquina de estados. Transição inválida (ex.: cancelar pedido já entregue): 409 INVALID_TRANSITION. O parceiro não pode pular estados.