Developers
Guias · Começando

Credenciais e autenticação

Como a chave é criada, o que ela libera e como enviá-la em cada chamada.

Quem cria a chave

A chave é criada pelo administrador do BIX do cliente, na tela Configuração Global › API. Ao criar, ele define:

Campo O que faz
Nome Identifica você na lista de chaves e no log (ex.: "Fornecedor XPTO · estoque")
Acessos (escopos) Quais recursos a chave pode chamar. Cada endpoint exige um escopo
Lojas permitidas Opcional. Se preenchido, a chave só vê essas lojas
Expira em Opcional. Depois dessa data a chave para de funcionar

A chave aparece uma única vez, logo depois de criada. O BIX guarda só um resumo criptográfico dela e não consegue mostrá-la de novo. Se ela se perder, o administrador cria outra e revoga a antiga.

O formato

bix_k3m9x2p7q4ab_9fQ2r...Zt8
     └── prefixo ┘ └ segredo ┘

O prefixo (12 caracteres) identifica a chave no log e na tela sem expor o segredo. Ao falar com o suporte, informe o prefixo, nunca a chave inteira.

Enviando a chave

Toda chamada leva a chave no cabeçalho Authorization, com o esquema Bearer:

curl "https://demonstracao.appbix.com.br/external-api/v1/wms/stock-balances" \
  -H "Authorization: Bearer $BIX_API_KEY"
  • Sem o cabeçalho, a resposta é 401 com code missing_api_key.
  • Chave errada ou de outro ambiente: 401 invalid_api_key.
  • Chave revogada: 401 api_key_revoked. Chave vencida: 401 api_key_expired.
  • Chave válida, mas sem o escopo do endpoint: 403 insufficient_scope.

Guarde a chave como senha

Use um cofre de segredos ou variável de ambiente, nunca o código-fonte. Não a envie por e-mail aberto nem a coloque em URL: só no cabeçalho.

Escopos

Cada endpoint da referência mostra o escopo que exige. Leitura e envio são escopos separados: um fornecedor que só consulta não precisa poder gravar. Os disponíveis hoje:

Módulo Escopo Libera
Cadastros stores.read Lista as lojas do cliente, com o código de integração, e os grupos de lojas. GET/stores GET/store-groups
Cadastros catalog.read Lê produtos, estrutura mercadológica, fornecedores e compradores. GET/products GET/categories GET/suppliers GET/buyers
Cadastros catalog.write Cria e atualiza produtos, estrutura mercadológica, fornecedores e compradores. POST/products POST/categories POST/suppliers POST/buyers
Cadastros store_groups.write Cria e atualiza grupos de lojas e as lojas de cada um. POST/store-groups
Cadastros stock_prices.read Lê o preço e o saldo por loja informados pelo ERP. GET/stock-prices
Cadastros stock_prices.write Envia preço, saldo, curva e custos por loja. POST/stock-prices
Ruptura sales.write Envia a venda por loja e produto, com o perfil por hora, de uma vez ao dia até em tempo real (base da ruptura e da rebaixa). POST/sales/daily
Ruptura rupture.read Lê os itens auditados nas tarefas de ruptura e as rupturas prováveis apontadas pela venda. GET/rupture/items GET/rupture/signals
Validade expiry.read Lê as validades por loja e produto, com a cor do alerta. GET/expiries
Validade expiry.write Envia as validades (lotes e datas) que o ERP conhece. POST/expiries
Validade markdown.read Lê as rebaixas de preço por validade, no layout do contrato de publicação. GET/markdowns
Validade markdown.write Confirma que a rebaixa foi aplicada (ou recusada) no PDV. POST/markdowns/publications
WMS wms.stock.read Saldo atual por loja e por endereço, do módulo WMS. GET/wms/stock-balances GET/wms/bin-stocks
WMS wms.structure.read Depósitos, endereços e motivos de movimentação do WMS. GET/wms/storage-locations GET/wms/bins GET/wms/reasons
WMS wms.movements.read O livro de movimentações do WMS, inclusive os ajustes de inventário. GET/wms/movements
WMS wms.movements.write Lança no WMS entradas, saídas e vendas vindas do ERP. POST/wms/movements

Peça só os escopos que a integração usa. A chave não é editável: para ganhar um acesso, o administrador cria outra chave com o escopo a mais, e a antiga é revogada depois da troca.

Revogação e rotação

Revogar vale na hora: a chamada seguinte já recebe api_key_revoked. Para trocar de chave sem parar a integração:

  1. o administrador cria a chave nova;
  2. você troca no seu sistema;
  3. confirme no log que a chave antiga parou de ser usada;
  4. o administrador revoga a antiga.

O log da chave

Cada chamada, inclusive as recusadas, vira uma linha no log da chave, visível para o administrador: data, rota, parâmetros, resultado, quantidade de itens, duração e IP de origem. O log nunca guarda a chave, cabeçalhos ou corpo. Ele é o primeiro lugar a olhar quando algo "não chegou".