O que o ERP precisa ter para a rebaixa

Os endpoints de promoção que o seu ERP expõe para o BIX publicar a rebaixa direto no PDV e encerrá-la no fim da vigência.

A rebaixa pode chegar ao PDV de duas formas:

Na segunda forma, o BIX cria a promoção assim que a etiqueta é impressa e a encerra quando a rebaixa acaba. O ERP precisa expor três coisas: criar, consultar e encerrar uma promoção.

sequenceDiagram
    participant Loja as Loja (app)
    participant BIX as BIX
    participant ERP as Seu ERP
    participant PDV as Caixa
    BIX->>BIX: rebaixa calculada e aprovada
    Loja->>BIX: etiqueta impressa
    BIX->>ERP: 1. criar a promoção (preço, loja, vigência)
    ERP-->>BIX: id da promoção
    ERP->>PDV: carga de preço
    Note over BIX: rebaixa ativa
    BIX->>ERP: 2. consultar a promoção (opcional)
    BIX->>ERP: 3. encerrar a promoção
    Note over BIX: vendeu tudo, venceu ou mudou de cor

Os endereços abaixo são o padrão do BIX. Se o seu ERP já tem uma API de promoção com outros nomes, o conector do BIX é ajustado a ela na implantação.

1. Criar a promoção

POST https://seu-erp/promotions

O corpo é o mesmo contrato bix.markdown.publication/v1 que a GET/markdowns devolve, com uma reference para o ERP reconhecer uma chamada repetida:

{
  "reference": "BIX-MKD-4410",
  "schema": "bix.markdown.publication/v1",
  "markdown": {"percent": 30.0, "full_price": 7.49, "reduced_price": 5.24, "quantity": 18.0,
               "measurement": "UN", "starts_on": "2026-11-10", "ends_on": "2026-11-16",
               "expiry_date": "2026-11-20"},
  "store": {"code": "0012", "cnpj": "12345678000190"},
  "product": {"internal_code": "1001", "ean": "7891234567890", "description": "IOGURTE NATURAL 170G"},
  "external": {"code": "5000000010015"}
}

Resposta esperada:

{"promotion_id": "PROMO-77812", "status": "active"}

O código de barras de vencimento

O ponto delicado da rebaixa é cobrar o preço rebaixado só das unidades perto do vencimento, não do produto inteiro na loja. A forma mais segura é o produto ter um código de barras de vencimento: um segundo código, cadastrado no ERP, que só vai na etiqueta da rebaixa.

• O ERP aplica a promoção só nesse código. O caixa cobra o preço cheio de quem bipa o código normal e o rebaixado de quem bipa o da etiqueta.
• O BIX conhece o código pelo cadastro de produtos (POST/products, como mais um EAN do produto) e o envia em external.code. A etiqueta sai com ele.
• Sem esse código, a promoção vale para o produto inteiro naquela loja durante a vigência. Combine isso com o cliente antes de ligar a publicação.

2. Consultar a promoção (opcional)

GET https://seu-erp/promotions/PROMO-77812

{"promotion_id": "PROMO-77812", "status": "active", "starts_on": "2026-11-10", "ends_on": "2026-11-16"}

O BIX usa a consulta para confirmar que a promoção entrou e para descobrir uma promoção criada numa chamada cuja resposta se perdeu.

3. Encerrar a promoção

A rebaixa pode acabar antes do fim da vigência: o produto vendeu tudo, venceu ou mudou de cor (e ganhou outro percentual). Nesses casos o BIX encerra a promoção:

POST https://seu-erp/promotions/PROMO-77812/deactivate

{"promotion_id": "PROMO-77812", "status": "inactive"}

Quando a rebaixa muda de cor, o BIX encerra a promoção da cor anterior e cria uma nova, com o novo preço.

Regras

• O ERP nunca trava a loja. Se a publicação falhar, a rebaixa fica com o erro no Painel de Rebaixas do BIX, e a pessoa responsável vê o motivo e decide o que fazer.
• Uma promoção por rebaixa, por loja. Nada de promoção em rede a partir de uma rebaixa.
• Criar é seguro de repetir por causa da reference. Se o ERP não aceita uma referência, ele precisa permitir consultar as promoções do produto na loja, e o BIX procura antes de criar.
• Autenticação: o BIX chama o ERP com a credencial que o ERP fornecer e sai de um endereço IP fixo, que pode ser liberado no firewall.

Pronto para produção

• [ ] O ERP cria a promoção por loja, com preço e vigência, sem duplicar quando a chamada é repetida.
• [ ] O ERP encerra a promoção pelo id.
• [ ] Os produtos com rebaixa têm o código de barras de vencimento, ou o cliente aceitou a promoção no produto inteiro.
• [ ] Uma rebaixa de teste foi publicada e encerrada numa loja piloto, conferida no caixa.