Introdução

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

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:write", "orders:read", "webhooks:manage"],
  "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. Receber a chave de teste e chamar /health.
2. Enviar 1 produto com products/bulk e conferir summary/results.
3. Ajustar estoque/preço com PATCH /stock.
4. Enviar 1 pedido com 2 itens e guardar order_id/display_number.
5. Reenviar o mesmo pedido e validar replayed: true.
6. Consultar pedido por external_order_id.
7. Registrar webhook (guardar o secret exibido uma única vez) e chamar /webhooks/{id}/test.
8. Validar a assinatura HMAC no ERP (raw body + janela de timestamp + compare em tempo constante).
9. Rodar um caso real de status cancelled e confirmar o order.status_changed no receptor.
10. Conferir GET /webhooks/{id}/deliveries e só então trocar para a chave definitiva.