Criar credencial

O administrador da loja cria a API key em app.onmia.com.br → Configurações → Integrações. Secret copy-once, ID da Empresa, scopes, rate limit e rotação.

A chave de integração é criada pelo administrador da loja no dashboard da OnmIA. Não há criação de chave pelo portal de documentação nem por API — é uma ação de UI, autenticada com o login do admin.

Onde criar

Acesse app.onmia.com.br e faça login com a conta de administrador da loja (role admin ou usuário master).
Vá em Configurações → Integrações / API.
Clique em Nova chave de integração, dê um nome (ex.: ERP Produção), escolha os scopes e (opcionalmente) restrinja a lojas específicas.
Confirme. O secret aparece uma única vez na tela.

O secret aparece uma vez só

Esta é a única vez em que a chave secreta completa é exibida. Copie e guarde no cofre do ERP imediatamente. A OnmIA armazena apenas o hash — não há como recuperar o valor depois. Perdeu? Rotacione a chave para gerar um novo secret.

A chave completa tem o formato onmia_<key_id>_<secret> e é enviada no header X-API-Key (ver Autenticação).

ID da Empresa (merchant_id)

Na mesma página, o admin encontra o ID da Empresa (merchant_id) — um identificador (não é segredo). O ERP usa esse id para correlacionar os pedidos e clientes recebidos pela integração com o cadastro local. Ele também aparece na resposta de /health:

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

{ "status": "ok", "merchant_id": "b9e9ad81-…", "store_ids": [], "scopes": [ "…" ] }

Scopes disponíveis

Escolha apenas os scopes que o ERP realmente usa (princípio do menor privilégio).

Scope	Permite
`catalog:write`	Criar/atualizar catálogo via `POST /products/bulk`.
`stock:write`	Atualizar estoque e preço por loja via `PATCH /stock`.
`orders:read`	Consultar pedidos (`GET /orders/:id`, `GET ?external_order_id=`).
`webhooks:manage`	Configurar webhooks e ver entregas.
`loyalty:read`	Consultar programa, saldo, extrato e cupons de fidelidade.
`loyalty:write`	Creditar/debitar pontos e validar/resgatar cupons.

Scopes de fidelidade

loyalty:read e loyalty:write ficam disponíveis na própria tela do admin — o ERP sincroniza a fidelidade do próprio merchant (programa, saldo, créditos/débitos de pontos, cupons) usando a credencial criada aqui no app.onmia.

Não existe o scope orders:write — o ERP não cria pedidos (ver Pedidos).

Escopo de loja

Sem restrição (store_ids: []) = a chave opera todas as lojas do merchant.
Restrito = a chave só pode escrever/ler as lojas marcadas. Escrita em loja fora do escopo → 403 FORBIDDEN_STORE; leitura → 404 NOT_FOUND (sem vazar existência).

Confira o store_ids retornado por /health para saber em qual modo sua chave opera.

Rate limit

Cada chave nasce com 120 requisições por minuto (token bucket por chave). Se o volume legítimo do ERP passa disso, combine um limite maior com a OnmIA. Ver Rate limiting.

Revogar e rotacionar

Rotacionar: gera um novo secret mantendo o mesmo key_id. Troque o segredo no ERP antes de confirmar a rotação — o secret antigo deixa de funcionar na requisição seguinte (não há cache de credencial).
Revogar: desativa a chave imediatamente. A próxima requisição com a chave revogada recebe 401 INVALID_API_KEY.
Suspeita de vazamento: revogue na hora. A janela de exposição termina no momento da revogação.

Onde guardar a chave

Armazene a chave em cofre de segredos ou variável de ambiente do servidor. Nunca em frontend, app mobile, repositório git, planilha ou log. O header X-API-Key é redigido (redacted) nos logs do servidor OnmIA.