Vínculo e PIN

Duas rotas do contrato cuidam da identidade do cliente: o accounts:link, chamado uma vez na adesão, e a consulta de saldo, chamada sempre que o checkout precisa mostrar quanto o cliente tem. Depois do vínculo, a DeliveryVip só conhece o cliente pelo accountId que você devolveu.

O cliente adere, a DeliveryVip chama accounts:link, opcionalmente pede o PIN, e depois consulta o saldo para mostrar no checkout — Vínculo da conta, com PIN opcional

Vincular o cliente (`accounts:link`)

POST {api_base_url}/v1/loyalty/accounts:link

Chamada quando o cliente aceita participar do programa no checkout. O clique é o consentimento: consent.grantedAt é o momento do clique, com o offset da plataforma (-03:00). O perfil do cliente é atestado pela DeliveryVip: nunca chega um convidado nem um cadastro incompleto.

Corpo da requisição

string

obrigatório

O identificador do programa que você enviou no config push (program.id).

object

obrigatório

Perfil do cliente, completo.

Mostrar propriedades

string

obrigatório

CPF, somente dígitos.

string

obrigatório

Telefone em E.164 (ex.: +5511999998888).

string

obrigatório

E-mail do cliente.

string

obrigatório

Nome do cliente.

string

obrigatório

Data de nascimento, AAAA-MM-DD.

Registro do consentimento (LGPD). Guarde-o no seu lado.

Mostrar propriedades

string

obrigatório

Sempre loyalty_program.

string

obrigatório

Sempre granted.

string

obrigatório

Momento do clique, RFC 3339 com offset.

boolean

obrigatório

Espelha a capability enrollment do programa. Se true e o CPF não for membro, cadastre-o. Se false, um não-membro deve receber 404.

object

Presente apenas no reenvio depois de um desafio de PIN: {"type": "pin", "answer": "<PIN digitado>"}.

Exemplo

{
  "programId": "pb-123",
  "customer": {
    "document": "12345678909",
    "phone": "+5511999998888",
    "email": "maria@example.com",
    "name": "Maria",
    "birthDate": "1990-01-01"
  },
  "consent": {
    "purpose": "loyalty_program",
    "status": "granted",
    "grantedAt": "2026-09-04T12:00:00-03:00"
  },
  "enroll": true
}

Respostas do link

200 conta
200 desafio de PIN
403 PIN reprovado
404 adesão fechada

Conta localizada ou criada.

{
  "id": "acc-1",
  "programId": "pb-123",
  "balanceType": "cashback"
}

string

obrigatório

A conta do cliente no seu sistema. É por ela que a DeliveryVip consulta saldo e debita resgates.

string

O programa da conta.

string

cashback na v1.

O id da conta é opaco e estável: revincular o mesmo cliente deve devolver o mesmo id, byte a byte. É por ele que a DeliveryVip consulta saldo e debita resgates, nunca pelo CPF, que só trafega no link.

Quando o seu programa exige confirmação, responda com o desafio no lugar da conta:

{
  "challenge": { "type": "pin" }
}

A DeliveryVip pede o PIN ao cliente e reenvia o mesmo corpo acrescido de:

"challenge": { "type": "pin", "answer": "1234" }

O PIN é validado exclusivamente do seu lado, inclusive o rate limiting. A DeliveryVip nunca armazena nem loga o PIN.
Nunca responda id e challenge juntos. Se fizer, a DeliveryVip trata o challenge como autoritativo e descarta o id.

O CPF não é membro e o programa não aceita adesão pelo checkout (enroll: false). O cliente vê que precisa se cadastrar na loja.

Qualquer outra resposta (outro código, timeout, JSON inválido) conta como falha para o circuit breaker e o cliente vê o programa como indisponível no momento.

Saldo da conta

GET {api_base_url}/v1/loyalty/accounts/{accountId}

Consulta feita para exibir o saldo no checkout, só com o accountId opaco, nunca o CPF.

string

obrigatório

O id que você devolveu no accounts:link.

Resposta (200)

{
  "id": "acc-1",
  "programId": "pb-123",
  "balanceType": "cashback",
  "balance": 25.00,
  "currency": "BRL"
}

number

obrigatório

Saldo atual em BRL, como número JSON. Zeros à direita não são significativos: 25.0 e 25.00 são o mesmo número.

string

BRL. Se omitido, a DeliveryVip assume BRL.

object

Opcional. Limites de resgate só deste cliente; veja Limites por conta.

A DeliveryVip cacheia a resposta por 60 segundos por conta: o saldo exibido pode atrasar até 1 minuto em relação ao seu ledger.
404 significa que a conta não existe mais do seu lado: a DeliveryVip desfaz o vínculo e oferece a adesão de novo ao cliente. Nunca conta como falha para o circuit breaker.

Limites por conta

A resposta de saldo aceita, opcionalmente, o mesmo objeto redemptionLimits dos limites do programa:

{
  "id": "acc-1",
  "programId": "pb-123",
  "balanceType": "cashback",
  "balance": 25.00,
  "currency": "BRL",
  "redemptionLimits": {
    "min": { "type": "fixed", "value": 10.00 },
    "max": { "type": "percent", "value": 50 }
  }
}

Substituição integral, não merge campo a campo. Quando presente, o objeto da conta substitui por inteiro os limites do programa para aquele cliente.Declarar só max na conta significa que aquele cliente não tem mínimo, mesmo que o programa declare um:

Programa	Conta	Vale para o cliente
`min: fixed 5`, `max: percent 50`	ausente	`min: fixed 5`, `max: percent 50`
`min: fixed 5`, `max: percent 50`	`max: percent 80`	só `max: percent 80`, sem mínimo
`min: fixed 5`, `max: percent 50`	`min: fixed 10`	só `min: fixed 10`, sem máximo

O raciocínio: você é a autoridade sobre as suas próprias regras. Um merge produziria uma faixa que nenhum dos dois lados declarou. Este é o ponto que mais gera bug de integração: se o cliente deve manter o mínimo do programa, repita-o na conta.

Demais regras:

Omita o limite ausente; nunca envie null. null afirmaria “este cliente não tem mínimo”, que é diferente de “não declarei nada”.
Objeto ausente ou malformado (tipo fora de fixed/percent, valor ausente ou não positivo): valem os limites do programa.
Viaja no mesmo cache de 60 segundos do saldo: mudar a regra de um cliente leva até 1 minuto para chegar ao checkout.

Quando usar: só se as suas regras de fato variam por cliente, como tier, segmento ou acordo individual. Uma regra única para todos pertence ao programa, não repetida em toda conta.E um alerta de modelagem que vale generalizar: o canal em que um dado chega não determina o escopo do dado. Um limite que chega dentro de uma consulta por cliente não é, por isso, um limite por cliente. Se o valor é o mesmo para todos, ele é do programa, ainda que a sua API o devolva junto do cadastro do portador.

Próximo passo

Resgate e estorno

Com o cliente vinculado e o saldo na tela, o próximo passo é o débito do resgate no fechamento do pedido.

Visão geral

Guias

Contrato do operador

Referência

Vincular o cliente (`accounts:link`)

Corpo da requisição

Respostas do link

Saldo da conta

Limites por conta

Próximo passo

Resgate e estorno

​Vincular o cliente (accounts:link)

​Corpo da requisição

​Respostas do link

​Saldo da conta

​Limites por conta

​Próximo passo

Resgate e estorno

Vincular o cliente (`accounts:link`)

Corpo da requisição

Respostas do link

Saldo da conta

Limites por conta

Próximo passo