FAQ

Respostas para os erros e dúvidas mais comuns na integração. Para o detalhe de cada código, veja a página de Erros.

503 FEATURE_DISABLED em tudo, inclusive /health?

O ambiente ainda não foi habilitado pela OnmIA. Não é problema da sua chave — enquanto o ambiente está desligado, toda chamada retorna 503. Confirme com o contato OnmIA o status do go-live.

401 INVALID_API_KEY mas a chave "parece certa"?

• Envie a chave completa no formato onmia_<key_id>_<secret> no header X-API-Key — não em Authorization, sem Bearer.
• Confira espaços e quebras de linha ao copiar do cofre.
• Se a chave foi rotacionada, a antiga morre imediatamente (não há cache de credencial).

403 INSUFFICIENT_SCOPE vs. 403 FORBIDDEN_STORE?

• INSUFFICIENT_SCOPE: sua chave não tem a permissão da rota (veja details.granted_scopes). Peça à OnmIA o scope que falta.
• FORBIDDEN_STORE: a chave tem o scope, mas o store_id enviado está fora da lista de lojas da chave. Confira o store_ids retornado pelo /health.

Como recebo um pedido novo da OnmIA?

Pelo webhook order.created. Todo pedido criado em qualquer canal (catálogo, WhatsApp/IA, manual, iFood) dispara o evento com o pedido completo. O ERP não cria pedidos pela API. Registre o webhook com events: ["order.created", "order.status_changed"] e trate o evento no seu endpoint receptor. Ver Pedidos e Webhooks.

404 ao chamar POST /integration/v1/orders?

Esperado: a rota foi removida em v1.1 (e o scope orders:write deixou de existir). Pare de enviar pedidos; passe a receber via order.created. As leituras GET /orders/:id e GET /orders?external_order_id= continuam (scope orders:read).

404 CUSTOMER_NOT_FOUND na fidelidade?

O cliente não existe na OnmIA para o phone/external_id enviado. A fidelidade é find-only (não cria cliente). Confira o telefone (com/sem nono dígito) ou o external_id cadastrado. Ver Fidelidade.

422 INSUFFICIENT_BALANCE ao debitar pontos?

O débito é maior que o saldo de pontos do cliente. Cheque o saldo antes via GET /loyalty/balance e ajuste o valor do débito.

Por que o estoque não baixa quando um pedido é criado?

Design intencional. O ERP é a autoridade de estoque: a venda já decrementou no seu sistema, então envie o saldo novo via PATCH /stock.

Webhook não chega?

1. Confira os requisitos do receptor: HTTPS, host público, sem redirect, resposta 2xx em menos de 10s.
2. Consulte GET /webhooks/:id/deliveries e leia status, attempt_count, response_status e last_error — eles dizem exatamente o que o worker viu (ex.: HTTP 500 do endpoint do parceiro, bloqueio SSRF, timeout).
3. last_error mencionando faixa privada/reservada: seu DNS está resolvendo para IP interno (split-horizon DNS). Exponha um hostname com resolução pública.
4. consecutive_failures alto em GET /webhooks: seu receptor está derrubando entregas em série; corrija e valide com POST /webhooks/:id/test.
5. Entrega dead não volta: reconcilie via GET /orders e siga — novos eventos entram normalmente.

Há também uma página dedicada de Troubleshooting com a tabela de erros comuns e os comandos de diagnóstico.

Assinatura HMAC nunca bate?

99% dos casos: o framework fez parse do JSON e você re-serializou. Capture o raw body (bytes) antes do middleware de JSON e assine sobre "<timestamp>.<raw_body>". Detalhes em Webhooks.