Referência da API
Todos os endpoints da API pública do BIX, agrupados por módulo. Esta página é gerada do código: o que está aqui é exatamente o que a API faz.
Endereço
| Ambiente | URL base |
|---|---|
| Sandbox | https://demonstracao.appbix.com.br/external-api/v1 |
| Produção | https://<ambiente>.appbix.com.br/external-api/v1 |
Cada cliente do BIX tem o seu ambiente (<ambiente>), e a chave só vale nele. Veja
Ambientes.
Autenticação
Authorization: Bearer bix_xxxxxxxxxxxx_...A chave é criada pelo administrador do cliente em Configuração Global › API. Veja Credenciais e autenticação.
Endpoints
Cadastros
GET
/stores
Listar lojas
GET
/products
Listar produtos
POST
/products
Enviar produtos (criar ou atualizar)
GET
/categories
Listar a estrutura mercadológica
POST
/categories
Enviar a estrutura mercadológica
GET
/stock-prices
Listar preço e saldo por loja
POST
/stock-prices
Enviar preço e saldo por loja
GET
/suppliers
Listar fornecedores
POST
/suppliers
Enviar fornecedores
GET
/buyers
Listar compradores
POST
/buyers
Enviar compradores
GET
/store-groups
Listar grupos de lojas
POST
/store-groups
Enviar grupos de lojas
Ruptura
POST
/sales/daily
Enviar a venda
GET
/rupture/items
Itens auditados
GET
/rupture/signals
Rupturas prováveis
Validade
GET
/expiries
Listar validades
POST
/expiries
Enviar validades
GET
/markdowns
Listar rebaixas
POST
/markdowns/publications
Confirmar a rebaixa no PDV
WMS
GET
/wms/stock-balances
Saldo atual por loja e produto
GET
/wms/bin-stocks
Saldo por endereço
GET
/wms/storage-locations
Listar depósitos
GET
/wms/bins
Listar endereços
GET
/wms/reasons
Listar motivos de movimentação
GET
/wms/movements
Ler o livro de movimentações
POST
/wms/movements
Enviar entradas, saídas e vendas
Escopos
Cada endpoint exige um escopo, liberado na chave.
| Módulo | Escopo | O que libera |
|---|---|---|
| Cadastros | stores.read | Lista as lojas do cliente, com o código de integração, e os grupos de lojas. |
| Cadastros | catalog.read | Lê produtos, estrutura mercadológica, fornecedores e compradores. |
| Cadastros | catalog.write | Cria e atualiza produtos, estrutura mercadológica, fornecedores e compradores. |
| Cadastros | store_groups.write | Cria e atualiza grupos de lojas e as lojas de cada um. |
| Cadastros | stock_prices.read | Lê o preço e o saldo por loja informados pelo ERP. |
| Cadastros | stock_prices.write | Envia preço, saldo, curva e custos por loja. |
| 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). |
| Ruptura | rupture.read | Lê os itens auditados nas tarefas de ruptura e as rupturas prováveis apontadas pela venda. |
| Validade | expiry.read | Lê as validades por loja e produto, com a cor do alerta. |
| Validade | expiry.write | Envia as validades (lotes e datas) que o ERP conhece. |
| Validade | markdown.read | Lê as rebaixas de preço por validade, no layout do contrato de publicação. |
| Validade | markdown.write | Confirma que a rebaixa foi aplicada (ou recusada) no PDV. |
| WMS | wms.stock.read | Saldo atual por loja e por endereço, do módulo WMS. |
| WMS | wms.structure.read | Depósitos, endereços e motivos de movimentação do WMS. |
| WMS | wms.movements.read | O livro de movimentações do WMS, inclusive os ajustes de inventário. |
| WMS | wms.movements.write | Lança no WMS entradas, saídas e vendas vindas do ERP. |
Paginação
Listagens usam page (a partir de 1) e page_size (padrão 50,
máximo 100). Acima do máximo a chamada é recusada com invalid_parameter.
Veja Paginação e sincronização.
Erros
Todo erro vem como {"code": "...", "detail": "..."}. Decida pelo code, que é
estável; o detail é texto para pessoas.
| HTTP | code | Quando |
|---|---|---|
| 400 | invalid_parameter | Parâmetro com valor inválido (o detail diz qual). |
| 401 | api_key_expired | A chave passou da data de expiração. |
| 401 | api_key_revoked | A chave foi revogada na Configuração Global › API. |
| 401 | invalid_api_key | A chave não existe neste ambiente ou está errada. |
| 401 | missing_api_key | A chamada veio sem o cabeçalho "Authorization: Bearer <chave>". |
| 403 | insufficient_scope | A chave não tem o acesso que este endpoint exige. |
| 403 | module_disabled | O cliente não tem o módulo deste endpoint habilitado. |
| 403 | store_not_allowed | A chave está restrita a algumas lojas e uma das pedidas não é delas. |
| 404 | not_found | Rota inexistente. |
| 405 | method_not_allowed | Método HTTP não aceito nesta rota. |
| 409 | idempotency_key_reused | O Idempotency-Key já foi usado, nas últimas 24 horas, numa chamada com outro corpo. |
| 429 | rate_limited | Limite de chamadas por minuto da chave atingido. Respeite o Retry-After. |
| 500 | internal_error | Erro interno. Tente de novo; se persistir, fale com o suporte. |