Autenticação

Toda chamada usa o header X-API-Key. Não há Authorization: Bearer.

X-API-Key: onmia_<key_id>_<secret>
Content-Type: application/json

A chave é emitida pela OnmIA e exibida uma única vez. Envie sempre a chave completa (prefixo onmia_, key_id e secret) — o servidor faz parse do formato antes de qualquer consulta; chave malformada retorna 401 INVALID_API_KEY imediatamente.

• key_id: 16 caracteres hex (lookup O(1)).
• secret: 43 caracteres base64url (~256 bits).

Ordem de validação no servidor

Em cada requisição, o servidor avalia nesta ordem:

1. Feature flag do ambiente → 503 FEATURE_DISABLED se desligada.
2. Parse do header X-API-Key → 401 INVALID_API_KEY se ausente/malformado.
3. Lookup da chave no banco. Falha de infraestrutura aqui → 503 AUTH_UNAVAILABLE (a API fecha por segurança — fail-closed, nunca deixa passar).
4. Chave inexistente, inativa ou revogada → 401 INVALID_API_KEY. Não há cache de credencial: a revogação vale já na requisição seguinte.
5. Comparação de hash em tempo constante (timing-safe).
6. Síntese do escopo de loja da chave.
7. Rate limit por chave → 429 RATE_LIMITED.

Scopes

Chamada sem o scope necessário retorna 403 INSUFFICIENT_SCOPE com details.required_scope e details.granted_scopes.

Verificação de credencial

O /health não exige scope — é o teste inicial:

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

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

Escopo de loja

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

• Escritas em loja fora do escopo retornam 403 FORBIDDEN_STORE (nos lotes, por item — uma loja proibida invalida o item inteiro, sem efeito colateral).
• Leituras de pedido fora do escopo retornam 404 NOT_FOUND — a API não confirma a existência de recursos fora do seu escopo.

Segurança da chave

• A chave só é exibida uma vez na emissão. A OnmIA armazena apenas o hash — não há como recuperar o valor depois.
• O prefixo da chave (ex.: onmia_abc123...) é o único trecho seguro para aparecer em dashboards e logs de auditoria. O secret completo, nunca.
• Rotação: solicite a emissão de uma nova chave e a revogação da antiga. Como não há cache, a chave revogada morre imediatamente. Troque o segredo no seu lado antes de pedir a revogação.
• Suspeita de vazamento: solicite revogação imediata. A janela de exposição termina no momento da revogação.
• O header X-API-Key é redigido (redacted) nos logs do servidor OnmIA.