O que o ERP precisa ter

Os endpoints de inventário que o seu ERP expõe para o BIX abrir o inventário, enviar a contagem e encerrar, sem digitação.

Na página anterior, o seu ERP envia para o BIX o que a loja vai contar. Aqui é o caminho de volta: terminada a contagem, o BIX envia o resultado para o ERP, que ajusta o estoque. Para isso o ERP precisa expor um pequeno conjunto de endpoints de inventário, que o BIX chama em três momentos: abrir, enviar a contagem e encerrar.

sequenceDiagram
    participant BIX as BIX
    participant ERP as Seu ERP
    participant App as App na loja
    Note over BIX: tarefa de contagem criada
    BIX->>ERP: 1. abrir o inventário da loja
    ERP-->>BIX: id do inventário no ERP
    Note over ERP: saldo congelado neste momento
    BIX->>App: tarefa liberada para a loja
    App->>BIX: contagens, recontagens, divergência aprovada
    BIX->>ERP: 2. enviar a contagem (em lotes)
    BIX->>ERP: 3. encerrar o inventário
    ERP-->>BIX: processando
    BIX->>ERP: 4. consultar o resultado (opcional)
    ERP-->>BIX: ajuste apurado por produto

Os endereços abaixo são o padrão do BIX. Se o seu ERP já tem uma API de inventário com outros nomes e outro formato, o conector do BIX é ajustado a ela na implantação: o que importa é o ERP saber fazer as quatro coisas.

1. Abrir o inventário

O BIX abre o inventário no ERP quando a tarefa é criada, antes de a loja começar a contar. É nesse momento que o ERP tira a foto do saldo: o que for vendido ou recebido durante a contagem não entra na comparação.

POST https://seu-erp/inventories

{
  "reference": "BIX-5202-0012",
  "store_code": "0012",
  "competence_date": "2026-11-12",
  "description": "BIX 5202 - Loja 0012",
  "type": "partial",
  "freeze_stock": true,
  "scope": {"category_codes": ["01.02"], "product_codes": []}
}

Campo	O que é
`reference`	A identificação do BIX para esta contagem nesta loja. Única e sempre a mesma, mesmo se a chamada for repetida
`store_code`	O código da loja no ERP, o mesmo código de integração do BIX
`competence_date`	A data do inventário (AAAA-MM-DD)
`type`	`full` (a loja inteira) ou `partial` (só o `scope`)
`freeze_stock`	`true`: o ERP congela o saldo de comparação na abertura
`scope`	Em `partial`, os departamentos (`category_codes`) ou produtos (`product_codes`) que entram

Resposta esperada:

{"inventory_id": "88", "status": "open"}

A abertura precisa poder ser repetida

Se a resposta se perder no caminho, o BIX chama de novo com a mesma reference. O ERP devolve o inventário que já abriu, e não cria um segundo. Se o seu ERP não aceita uma referência, ele precisa ao menos permitir consultar os inventários abertos da loja pela descrição: o BIX consulta antes de abrir e só cria o que não existe.

2. Enviar a contagem

Quando a contagem termina no BIX (divergência conferida e recontagens feitas), o BIX envia a quantidade final de cada produto, em lotes de até 500 itens.

POST https://seu-erp/inventories/88/counts

{
  "items": [
    {"internal_code": "1001", "ean": "7891234567890", "quantity": 42, "warehouse_code": "LOJA"},
    {"internal_code": "1002", "ean": "7891234567906", "quantity": 0, "warehouse_code": "LOJA"}
  ]
}

Campo	O que é
`internal_code` e `ean`	O produto, pelos mesmos códigos que o ERP mandou no cadastro
`quantity`	A quantidade contada, em unidades (a caixa de 12 já vem como 12)
`warehouse_code`	O depósito, quando a loja separa loja e depósito

A quantidade é o total do produto, não um acréscimo: enviar o mesmo item de novo substitui o valor anterior. É o que deixa o envio seguro de repetir. Produto contado com zero vai com quantity: 0: é diferente de produto que não foi contado.

Resposta esperada: o resultado de cada item, para o BIX mostrar o que o ERP recusou.

{"results": [{"index": 0, "status": "ok"}, {"index": 1, "status": "error", "detail": "Produto inativo no ERP"}]}

3. Encerrar o inventário

Com tudo enviado, o BIX pede para o ERP encerrar e apurar o ajuste.

POST https://seu-erp/inventories/88/close

O encerramento costuma levar tempo no ERP. A resposta pode ser imediata (202) e o processamento seguir depois:

{"status": "processing"}

Encerrar sozinho ou deixar para o ERP

Alguns clientes preferem conferir no ERP antes de efetivar o ajuste. Nesse caso o BIX abre e envia a contagem, mas não encerra: quem fecha o inventário é a pessoa responsável, na tela do ERP. A escolha é feita na implantação.

4. Consultar o resultado (opcional)

Se o ERP expõe o resultado, o BIX consulta até o inventário estar fechado e mostra, ao lado da contagem, o ajuste que o ERP efetivou.

GET https://seu-erp/inventories/88

{
  "inventory_id": "88",
  "status": "closed",
  "closed_at": "2026-11-12T21:15:00-03:00",
  "items": [
    {"internal_code": "1001", "expected": 45, "counted": 42, "difference": -3, "cost_difference": -10.47}
  ]
}

status vai de open a processing e termina em closed ou error.

Regras do caminho de volta

O ERP nunca trava a loja. Se o ERP estiver fora do ar, a contagem segue normalmente no BIX, e o envio é refeito quando o ERP voltar.
Um inventário por loja. Uma tarefa com várias lojas abre um inventário em cada uma.
Escrita não é repetida às cegas. Abrir é seguro de repetir por causa da reference, e enviar porque a quantidade substitui. Se o seu ERP não garante uma das duas coisas, avise na implantação.
Autenticação: o BIX chama o ERP com a credencial que o ERP fornecer (token fixo ou OAuth2 com client credentials) e sai de um endereço IP fixo, que pode ser liberado no firewall.
Cancelar não é obrigatório. Se o ERP não tem como cancelar um inventário aberto, o BIX só o abre quando a tarefa é de fato criada, e quem descarta é a pessoa responsável, na tela do ERP.

Pronto para produção

[ ] O ERP abre o inventário por loja e devolve o id, sem duplicar quando a abertura é repetida.
[ ] O ERP recebe a contagem em lotes e substitui a quantidade quando o item vem de novo.
[ ] O ERP encerra (ou o cliente decidiu encerrar pela tela do ERP).
[ ] A credencial e o IP de origem do BIX estão liberados no ERP.
[ ] Um inventário de teste foi aberto, contado e encerrado numa loja piloto.