Developers
Guias · Ruptura

Envio da venda

Envie a venda por loja e código de barras, com o perfil por hora que a ruptura por não venda precisa — uma vez ao dia, a cada intervalo ou em tempo real.

POST/sales/daily

Um envio é um dia de uma loja, no contrato bix.sales.daily/v1, com tudo o que a loja vendeu naquele dia até o momento do envio.

Quando enviar

Na frequência que o seu sistema permitir. Quanto mais perto do tempo real, mais cedo a ruptura aparece e mais cedo a loja confere a gôndola.

Frequência Como Quando a ruptura aparece
Tempo real (o ideal) A cada venda, ou a cada poucos minutos, o acumulado do dia Logo depois de o produto parar de vender
A cada intervalo (ex.: 15 ou 30 minutos) O acumulado do dia até aquele momento No envio seguinte ao produto parar de vender
Uma vez ao dia O dia anterior, fechado No dia seguinte

Em toda frequência, mande o acumulado do dia com complete: true e o profiles. Cada envio substitui o anterior daquele dia e o BIX recalcula a ruptura provável na hora. Um envio que só traz as vendas novas (complete: false) grava a venda, mas não recalcula a ruptura.

Quando a tarefa de auditoria vai para a loja depende da agenda configurada no BIX pelo cliente.

{
  "schema": "bix.sales.daily/v1",
  "source": "erp",
  "sale_date": "2026-11-09",
  "location": {"integration_code": "0012"},
  "complete": true,
  "rows": [
    {"product_code": "1001", "gtin": "7891234567890", "on_offer": false, "quantity": 44,
     "amount": 1227.6, "full_price_amount": 1227.6, "receipts": 39,
     "first_sale_at": "08:12", "last_sale_at": "21:40"}
  ],
  "profiles": [
    {"product_code": "1001", "quantity": 44, "receipts": 39,
     "hourly_qty": [0,0,0,0,0,0,0,0,2,3,4,5,3,2,3,4,5,6,4,2,1,0,0,0],
     "hourly_receipts": [0,0,0,0,0,0,0,0,2,3,4,5,3,2,3,4,5,6,4,2,1,0,0,0],
     "sale_moments": 39, "median_gap_minutes": 18, "max_gap_minutes": 95,
     "max_gap_start": "14:10", "max_gap_end": "15:45",
     "store_open_at": "07:02", "store_close_at": "21:55"}
  ]
}

rows: a venda

Uma linha por código de barras e por oferta (on_offer). Linhas repetidas no lote são somadas. receipts é o número de cupons que tiveram o produto, e é ele que diz "vende a cada quantos minutos". Devolução (quantidade negativa) fica de fora.

profiles: o perfil do dia

Por código interno (soma os códigos de barras do produto). Sem profiles, a ruptura por não venda não é avaliada: a venda é gravada e serve à rebaixa, mas nenhum sinal sai dela.

Durante o dia, o perfil vai até o momento do envio, e o intervalo que ainda está aberto conta: se o produto não vende desde 14:10 e você envia às 16:00, o maior intervalo sem venda vai de 14:10 a 16:00.

Campo O que é
hourly_qty / hourly_receipts Quantidade e cupons em cada hora, 24 posições, da 0h às 23h
store_open_at / store_close_at A janela da loja naquele dia (HH:MM)
max_gap_minutes, max_gap_start, max_gap_end O maior intervalo sem venda dentro da janela
median_gap_minutes, sale_moments O intervalo típico e quantos momentos de venda houve

Reenviar e corrigir

  • complete: true (padrão) substitui o dia daquela loja e daquele source. Reenviar o mesmo lote não duplica, e o lote corrigido corrige.
  • complete: false só soma as linhas enviadas, sem substituir o dia. Grava a venda, mas não recalcula a ruptura: para a ruptura, use sempre o acumulado com complete: true.
  • Até 50.000 linhas por envio. Linha inválida volta em rejected, com a posição, e o resto grava.