Loyalty (cashback)

A Prefiro expõe o programa de cashback como capability Loyalty do Open Delivery. Valores monetários na API são inteiros em centavos de BRL (ex.: R$ 10,50 → 1050).

Requer escopo od.crm ou od.all.

Identificadores estáveis

ID	Descrição
prefiro-cashback	Programa de loyalty
prefiro-cashback-reward	Reward tipo cashback (cost: 1 centavo por unidade)

Endpoints

Operação	Método	Path
Listar programas	GET	/loyalty/programs
Contas do cliente	GET	/customers/{customerId}/loyalty-accounts
Detalhe da conta	GET	/loyalty/accounts/{accountId}
Extrato	GET	/loyalty/accounts/{accountId}/transactions
Rewards	GET	/loyalty/rewards
Resgate	POST	/loyalty/redemptions

accountId é UUID determinístico — uma conta por cliente.

Resgate

Envie accountId, rewardId e quantity (centavos a resgatar). Saldo insuficiente → 409.

Eventos (webhook)

Quando webhook estiver configurado, a Prefiro envia envelopes LoyaltyEventEnvelope (não entram no polling de Orders):

eventType	Quando
loyalty.cashback.earned	Crédito vinculado a pedido
loyalty.points.adjusted	Ajuste manual ou extensão de crédito
loyalty.redemption.created	Resgate ou débito
loyalty.points.expired	Expiração de saldo

Headers iguais aos de pedidos: X-App-Id, X-App-MerchantId, X-App-Signature.

Extensão Prefiro — crédito adicional

Além do contrato OD, existe endpoint exclusivo para creditar cashback. Detalhes em Prefiro Extensions.

Especificação: Loyalty — Open Delivery.