Visão geral da integração

O que a API pública do BIX faz, quem envia o quê e por onde começar.

O BIX organiza a operação de loja: contagem de estoque, auditoria de ruptura, controle de validade, WMS. Para isso ele precisa dos dados do seu ERP (produtos, lojas, saldo, vendas). Em troca, devolve o que a loja encontrou: o que foi contado, o que faltou na gôndola, o que vai vencer.

A API pública é a porta para essa troca. Ela é separada da API que o aplicativo do BIX usa e foi feita para sistemas:

uma chave por integrador, criada pelo administrador do cliente, que só acessa o que foi liberado nela (escopos e, se quiser, algumas lojas);
toda chamada fica registrada, inclusive as recusadas, e o cliente vê o log da chave;
contrato estável: erros com código fixo, paginação previsível e versão no endereço.

Como os dados circulam

flowchart LR
    ERP["Seu ERP / sistema"] -- "1. envia: cadastros, saldo, vendas, validades" --> API["API pública do BIX"]
    API --> BIX["BIX (tarefas na loja, pelo app)"]
    BIX -- "contagens, rupturas, alertas, saldos" --> API
    API -- "2. lê: consulta paginada" --> ERP
    BIX -- "3. recebe: avisos e resultado (contagem, rebaixa)" --> ERP

Na prática, toda integração tem três partes:

O que você envia: os cadastros base (lojas, produtos, preço e saldo) e os dados de cada módulo (vendas para a ruptura, validades para a validade).
O que você lê: o resultado do trabalho na loja, consultado por página e de forma incremental, com updated_since.
O que o BIX envia para você: quando o ERP expõe os endpoints, o próprio resultado: a contagem do inventário (O que o ERP precisa ter) e a promoção da rebaixa (O que o ERP precisa ter para a rebaixa). Com os eventos e webhooks, também os avisos de quando uma tarefa termina ou um dado muda (Eventos e webhooks).

Os módulos

Módulo	Para quê	Comece por
Cadastros base	Lojas, produtos, estrutura mercadológica, fornecedores, compradores, preço e saldo: a base de todos os outros	O que integrar
Contagem	Inventário da loja, com a divergência contra o saldo do ERP	O que integrar para a Contagem
Ruptura	O produto que falta na gôndola, apontado pela venda e conferido na loja	O que integrar para a Ruptura
Validade	Datas de validade, alertas por cor e rebaixa de preço perto do vencimento	O que integrar para a Validade
WMS	Estoque por endereço: entradas, saídas, vendas e o saldo de cada posição	O que integrar no WMS

Toda mudança na API é registrada em Novidades.

Por onde começar

Peça ao administrador do BIX do cliente uma chave com os acessos de que você precisa: Credenciais e autenticação.
Confira o endereço do ambiente e faça a primeira chamada no sandbox: Ambientes.
Leia Conceitos (loja, produto e item de estoque) e Paginação e sincronização antes de escrever o laço de leitura, e Envio em lote e idempotência antes do primeiro envio.
Carregue os cadastros base: O que integrar.
Trate os erros pelo código: Erros e limites.

Algum termo desconhecido? O Glossário explica cada um em uma frase.