> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Documentação das APIs da DeliveryVip, em português. Regras que mais quebram integrações: (1) Merchant API: faça polling em GET /merchant/v3/events:polling no máximo a cada 30 s por token; confirme todo evento recebido com POST /merchant/v3/events/acknowledgment e corpo [{"id": ""}] (o campo lido é id, não eventId), inclusive eventos repetidos ou que o sistema não trata; deduplique por eventId; o evento é só um aviso, busque o pedido na orderURL. (2) Tokens client_credentials valem 24 h e não têm refresh_token: peça outro ao receber 401. (3) Webhooks: valide a assinatura HMAC sobre o corpo bruto e responda 2xx rápido; o polling é a reconciliação. (4) Open Delivery: host od.deliveryvip.com.br, um client_secret por loja, datas em UTC. (5) Fidelidade: o operador implementa 5 rotas assinadas com HMAC e chama o config push; o estorno precisa ser idempotente. (6) Partner API: scope dv.partner. Não invente endpoints: use a referência gerada das specs OpenAPI. # Fidelidade > Conecte seu programa de fidelidade ao checkout da DeliveryVip: o cliente adere, resgata cashback e acumula, com o saldo sempre sob o seu controle. A extensão de **fidelidade** permite que o seu sistema atue como **operador de fidelidade** dentro da DeliveryVip: o cliente adere ao seu programa direto no checkout, resgata saldo (cashback) como desconto no pedido e acumula sobre os pedidos concluídos, tudo sem que o saldo saia do seu lado. ## Papéis | Papel | Quem | O que faz | | - | - | - | | **Ordering Application** | DeliveryVip | Dona do checkout e dos pedidos: apresenta o programa ao cliente, coleta o consentimento, aplica o desconto do resgate e emite os eventos de pedido. | | **Operador de fidelidade** | Seu app | Dono do programa: hospeda o ledger (saldos, regras de acúmulo, cadastro de membros) e implementa o [contrato HTTP](/docs/guides/merchant/loyalty/contrato-do-operador.md) que a DeliveryVip chama. | O dinheiro de fidelidade **nunca vive do lado da DeliveryVip**. A plataforma guarda apenas o vínculo do cliente com o programa (consentimento e um `accountId` opaco que você fornece) e o registro dos resgates. Saldo, extrato e regras de acúmulo são seus. ## As duas metades da integração A integração tem dois sentidos, com autenticações diferentes. Vale ter isso claro antes de escrever qualquer código. ![O cliente HTTP do operador chama a Merchant API com OAuth; o checkout da DeliveryVip chama o servidor do contrato do operador com HMAC; eventos de pedido chegam por webhook](https://mintcdn.com/deliveryvip-a4256422/ELxpcniK2_BP8zxT/images/fidelidade-duas-metades.png?fit=max\&auto=format\&n=ELxpcniK2_BP8zxT\&q=85\&s=c63b6181ec93e1ad8309f1cc087467bd) As duas metades da integração: o que você chama e o que a DeliveryVip chama > [card] [1. APIs que você chama](/docs/guides/merchant/loyalty/ativando-o-programa.md) > > Autenticação **OAuth2** (client credentials) e a API Merchant V3: > > * `PUT`/`DELETE /merchant/v3/{merchantId}/loyalty/config`: o **config push** que ativa o programa por loja; > * `GET /merchant/v3/orders/{orderId}`: a leitura do pedido para o [acúmulo](/docs/guides/merchant/loyalty/acumulo.md). > [card] [2. O contrato que você implementa](/docs/guides/merchant/loyalty/contrato-do-operador.md) > > Cinco rotas sob a `api_base_url` do seu app, chamadas pela DeliveryVip com **assinatura HMAC**: > > * `ping`, `accounts:link` e a consulta de saldo; > * o débito do resgate e o estorno. ## O que o cliente vê No checkout (tanto na loja própria quanto no marketplace: o programa acompanha a loja), o cliente vê um **card do seu programa**: * **Só para clientes identificados**: a adesão é oferecida a clientes logados (nunca convidados) com cadastro completo: nome, telefone, e-mail, CPF e data de nascimento. Se faltar CPF ou data de nascimento, o checkout pede para completar. * **Opt-in com consentimento**: o clique de adesão é o consentimento (LGPD). Se o seu programa exigir, um **PIN** é solicitado e validado por você. * **Resgate com limite**: o cliente escolhe quanto do saldo usar. O resgate se aplica **somente à soma dos itens**: frete e taxas nunca entram. * **1 resgate por pedido**. Um resgate que cobre 100% do pedido vira o pagamento `REDEEM`. ## A jornada de ponta a ponta ![Config push e ping, adesão, consulta de saldo, resgate no pedido e acúmulo a partir do evento CONCLUDED](https://mintcdn.com/deliveryvip-a4256422/ELxpcniK2_BP8zxT/images/fidelidade-ponta-a-ponta.png?fit=max\&auto=format\&n=ELxpcniK2_BP8zxT\&q=85\&s=12dea1970f46935a230676760f6109ea) A jornada de ponta a ponta ## Escopo da v1 * Tipo de saldo: **cashback** (valor em BRL). Outros tipos de saldo poderão ser adicionados em versões futuras do contrato. * O programa pode ser de loja (`store`), rede (`chain`) ou coalizão (`coalition`). ## Comece por aqui > [card] [Primeiros passos](/docs/guides/merchant/loyalty/primeiros-passos.md) > > Crie o app com o scope `dv.loyalty`, declare a extensão de fidelidade e obtenha o token com os dois scopes necessários. > [card] [Ativando o programa](/docs/guides/merchant/loyalty/ativando-o-programa.md) > > Ative o programa por loja com o config push, verificado na hora por um ping assinado no seu endpoint. > [card] [Contrato do operador](/docs/guides/merchant/loyalty/contrato-do-operador.md) > > As cinco rotas HTTP que o seu sistema implementa e a DeliveryVip chama, todas assinadas com HMAC-SHA256 do corpo bruto. > [card] [Acúmulo](/docs/guides/merchant/loyalty/acumulo.md) > > Receba o evento, busque o pedido com `od.all` e leia o bloco `loyalty`. A base de cálculo é sua. > [card] [Operador mínimo](/docs/guides/merchant/loyalty/operador-minimo.md) > > Um operador completo em Node.js ou Python, ativo em uma loja de teste: adesão, saldo, resgate e estorno. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.