Introdução

A OnmIA Integration API v1 é a superfície REST server-to-server para ERPs, PDVs e middlewares integrarem catálogo, estoque, pedidos, fidelidade e webhooks com a plataforma OnmIA. O contrato formal (schemas completos de request/response) vive na API Reference, gerada do OpenAPI.

O fluxo em uma frase

Você empurra catálogo e estoque para a OnmIA, e a OnmIA empurra os pedidos para o seu ERP via webhook assinado. Pedido é unidirecional OnmIA→ERP: o ERP não cria pedidos — ele os recebe.

        ┌──────────────────── OnmIA ────────────────────┐
        │  catálogo público · WhatsApp/IA · dashboard ·  │
        │  iFood  →  todos geram pedido na OnmIA          │
        └───────────────────────┬───────────────────────┘
                                 │  webhook order.created (HMAC)
                                 ▼
   seu ERP  ◄────────────────────────────────────────────  recebe pedido completo
      │                                                     (cliente, itens, totais)
      │  PATCH /stock  (estoque é autoridade do ERP)
      │  POST /products/bulk (catálogo)
      └──────────────────────────────────────────────────►  OnmIA

• Catálogo e estoque: o ERP é a autoridade. Você envia produtos (POST /products/bulk) e o saldo de estoque/preço (PATCH /stock).
• Pedidos: nascem na OnmIA em qualquer canal e chegam ao ERP pelo webhook order.created. Mudanças de status chegam por order.status_changed.
• Fidelidade: o ERP consulta programa, saldo e extrato, e pode creditar/debitar pontos e validar cupons (Fidelidade).

Base URL

Produção:

https://api.onmia.com.br

Todas as rotas vivem sob o namespace versionado:

/integration/v1

Ambientes e ativação

• A API é protegida por feature flag no servidor. Enquanto o ambiente não estiver habilitado, toda chamada — inclusive /health — retorna 503 FEATURE_DISABLED. Isso não é problema da sua chave: é o ambiente que ainda não foi ligado pela OnmIA.
• A chave de teste tem store_ids limitado à loja de teste. É o fluxo previsto no runbook de go-live: você valida catálogo, pedido e webhook contra essa loja antes de receber a chave definitiva.

O que a API faz

Primeiro teste

O endpoint /health não exige nenhum scope — serve como verificação de credencial:

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

Resposta esperada (200):

{
  "status": "ok",
  "merchant_id": "b9e9ad81-0000-0000-0000-000000000000",
  "store_ids": [],
  "scopes": ["catalog:write", "stock:write", "orders:read", "webhooks:manage", "loyalty:read", "loyalty:write"],
  "ts": "2026-06-12T12:00:00.000Z"
}

store_ids: [] significa todas as lojas do merchant. Quando vier preenchido, a chave só pode escrever/ler aquelas lojas.

Sequência recomendada de integração

1. Criar a chave de integração no painel e chamar /health (Criar credencial).
2. Enviar 1 produto com products/bulk e conferir summary/results.
3. Ajustar estoque/preço com PATCH /stock.
4. Registrar webhook com events: ["order.created", "order.status_changed"] (guardar o secret exibido uma única vez) e chamar /webhooks/{id}/test.
5. Validar a assinatura HMAC no ERP (raw body + janela de timestamp + compare em tempo constante).
6. Gerar um pedido de teste na loja de teste (catálogo, WhatsApp ou lançamento manual no dashboard) e confirmar o order.created completo no receptor (cliente, itens com external_id, totais).
7. Mudar o status desse pedido pelo dashboard e confirmar o order.status_changed no receptor.
8. Consultar o pedido por external_order_id/id para validar a reconciliação por leitura.
9. Validar a fidelidade: GET /loyalty/balance?phone= de um cliente conhecido e (se aplicável) um POST /loyalty/points idempotente.
10. Conferir GET /webhooks/{id}/deliveries (status delivered, consecutive_failures: 0) e só então trocar para a chave definitiva.