Benefícios do consumidor

Na máquina, o consumidor identificado pelo CPF pode usar o saldo do programa de fidelidade do cliente. A ETech consulta o ERP externo antes do pagamento e nunca debita nada: o débito, o crédito e o estorno são do ERP externo, pelos eventos do Webhook de venda.

Como funciona

A máquina nunca fala com o ERP externo: ela pergunta à ETech, e a ETech chama as rotas que o ERP expõe.

O consumidor digita o CPF e monta o carrinho. A ETech chama o quote e recebe o saldo e a regra de uso.
O consumidor escolhe quanto usar. A ETech confere o valor contra o saldo e o teto da regra, sem chamar o ERP externo.
Se a regra pede código, a ETech pede ao ERP externo que envie o código ao consumidor, e depois repassa o código digitado para conferência.
O consumidor paga com o desconto. A venda concluída chega ao ERP externo pelo sale.completed, com o valor usado.
O ERP externo debita o saldo e credita a compra.

Antes do pagamento só há validação. Não existe reserva: uma venda que não se conclui não gera evento nenhum.
A venda nunca espera o ERP externo. Se ele não responder em 3 s, a máquina vende sem o benefício.

Cadastro e regras de chamada

O administrador do cliente cadastra a API no painel da ETech, em Integrações → Clientes e fidelidade, e escolhe "Programa do ERP externo" em Configurações → Operação.

Item	Regra
URL base	`https://`, porta 443, com nome que resolve para IP público. As rotas abaixo são relativas a ela
Autenticação	Um header com chave, de nome e valor cadastrados no painel, como `X-Api-Key`
Prazo	3 s por chamada, contando a conexão. Sem retentativa: o consumidor está em frente à máquina
Falhas	5 falhas seguidas pausam as chamadas por 60 s. Nesse tempo, a máquina vende sem o benefício
Redirect	Não é seguido: uma resposta `3xx` conta como falha

Toda chamada é um POST com Content-Type: application/json e User-Agent: etech-benefits/1. Qualquer resposta fora de 2xx conta como falha, exceto o 404 do quote (próxima seção). O CPF vai no corpo, nunca na URL.

As rotas que o ERP externo expõe

Saldo e regra

POST {URL base}/benefits/quote
X-Api-Key: <valor cadastrado>
Content-Type: application/json

{
  "document": "12345678909",
  "companyDocument": "33308424000177",
  "storeCode": "34",
  "items": [
    { "ean": "7891234567895", "quantity": 2, "unitPrice": 10.90 }
  ]
}

{
  "customer": { "name": "Maria Souza" },
  "loyalty": {
    "balance": 35.50,
    "rules": { "requiresConfirmationCode": true, "maxRedeemPercentOfTotal": 20 }
  }
}

document é o CPF, só dígitos. companyDocument é o CNPJ da empresa da máquina, e storeCode o código da loja da máquina na ETech.
unitPrice é o preço que a máquina vai cobrar, já com desconto. A ETech calcula o teto sobre a soma de quantity × unitPrice.
Consumidor desconhecido: responda 404. Consumidor sem programa: 200 com loyalty nulo. Nos dois casos a máquina segue sem benefício.
maxRedeemPercentOfTotal é o percentual máximo do total que o saldo pode cobrir. Ausente vale 100. A ETech usa o menor entre o saldo e esse teto.
Saldo não é reservado. O quote só informa; o débito vem com a venda concluída.

Pedido de código

Só é chamada quando requiresConfirmationCode é true, e só para quem escolheu usar o saldo. O ERP externo envia o código ao consumidor pelo canal dele (SMS, e-mail, app).

POST {URL base}/loyalty/confirmation-codes

{ "document": "12345678909", "amount": 4.36, "idempotencyKey": "5d0f3c1a-7b2e-4c19-9a40-8e6f2b1d7c55" }

{ "challengeId": "ch_0193" }

A mesma idempotencyKey devolve o mesmo challengeId, sem enviar outro código. A chave é o identificador do uso na ETech.

Conferência do código

POST {URL base}/loyalty/confirmation-codes/ch_0193/verify

{ "code": "482913" }

{ "valid": true }

Código errado ou vencido responde 200 com valid: false. O formato e a validade do código são do ERP externo.

Débito, crédito e estorno

O ERP externo movimenta o saldo pelos eventos de venda do webhook. A venda que usou o saldo traz o campo loyalty no data:

"loyalty": {
  "program": "ExternalErp",
  "usageId": "5d0f3c1a-7b2e-4c19-9a40-8e6f2b1d7c55",
  "amount": 4.36,
  "document": "12345678909"
}

Evento	O que o ERP externo faz
`sale.completed` com `loyalty`	Debita o `amount` do saldo do `document` e credita a compra, pela regra do programa dele
`sale.completed` sem `loyalty`	Só credita a compra, se o consumidor estiver identificado em `customer`
`sale.canceled`	Estorna o débito e o crédito daquela venda

Uma vez por venda. O webhook entrega pelo menos uma vez: debite e credite uma vez só por saleId.
O usageId é a mesma chave do pedido de código, e liga o débito ao código que o consumidor confirmou.
O desconto já foi dado. Quando o evento chega, a venda está paga: um saldo que mudou no meio não desfaz a venda, e o acerto fica com o ERP externo.

Como funciona​

Cadastro e regras de chamada​

As rotas que o ERP externo expõe​

Saldo e regra​

Pedido de código​

Conferência do código​

Débito, crédito e estorno​