Developers
Guias · Começando

Ambientes

Sandbox para desenvolver, um endereço de produção por cliente, e por que a chave só vale no seu ambiente.

Um ambiente por cliente

Cada cliente do BIX tem um ambiente próprio, com endereço próprio:

Ambiente URL base da API
Sandbox https://demonstracao.appbix.com.br/external-api/v1
Produção https://<ambiente>.appbix.com.br/external-api/v1

O <ambiente> é o nome do cliente no BIX. É o mesmo endereço que a equipe dele usa para entrar no sistema, trocando forbix.com.br por appbix.com.br quando for o caso.

A chave pertence ao ambiente

A chave é criada dentro de um ambiente e só existe nele. Usada em outro endereço, ela recebe 401 invalid_api_key, mesmo sendo válida. Se o mesmo integrador atende dois clientes, são duas chaves, uma em cada ambiente.

Sandbox

O sandbox é o ambiente de demonstração do BIX. Ele tem a mesma API da produção, com dados fictícios, e serve para desenvolver e testar sem risco. Peça ao seu contato no BIX uma chave de sandbox.

O sandbox recebe as versões novas da API antes da produção. Um endpoint que já existe no sandbox pode ainda não ter chegado ao ambiente do seu cliente. O que está nesta documentação já está em produção.

Primeira chamada

export BIX_API_KEY="bix_..."     # a chave de sandbox
curl -i "https://demonstracao.appbix.com.br/external-api/v1/wms/stock-balances?page_size=5" \
  -H "Authorization: Bearer $BIX_API_KEY"

Uma resposta 200 com data e pagination confirma que chave, ambiente e escopo estão certos. Qualquer erro da API vem em JSON, com code: ver Erros e limites.

403 sem JSON

Se vier um 403 que não é um JSON com code, a chamada foi barrada pela proteção de borda, antes de chegar à API. Isso acontece com alguns IPs de provedores de nuvem e de outros países. Informe ao suporte o IP de saída do seu servidor.

Contrato da versão em produção

O arquivo OpenAPI de cada ambiente fica em https://<ambiente>.appbix.com.br/external-api/openapi.json e descreve exatamente a versão que aquele ambiente roda. O desta documentação está em /openapi.json e serve para importar no Postman ou no Insomnia.