> ## 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. # Enviar configuração de fidelidade > Cria ou substitui a configuração do programa de fidelidade do aplicativo autenticado para a loja (a última escrita prevalece). Antes de gravar qualquer coisa, a plataforma faz uma verificação síncrona: um GET /loyalty/ping assinado contra o `api_base_url` da extensão. Se o operador estiver inacessível ou a verificação da assinatura falhar, nada é gravado e a resposta é `422`. Exige o escopo `dv.loyalty` e a extensão de fidelidade declarada no aplicativo. ## OpenAPI ````yaml https://app.deliveryvip.com.br/swaggers/merchant.yaml put /merchant/v3/{merchantId}/loyalty/config openapi: 3.0.3 info: version: v3 title: API Merchant da DeliveryVip description: >- A API Merchant permite que integrações (PDVs, ERPs, operadores de fidelidade e afins) interajam com as lojas da plataforma: consumir eventos de pedidos, consultar detalhes e executar ações sobre pedidos, além de gerenciar cardápio, cupons, comandas, mesas e o programa de fidelidade. Todos os endpoints exigem autenticação com um token de acesso Bearer emitido pela API de autenticação, com o escopo `od.all` (as rotas de fidelidade exigem `dv.loyalty`). **Erros.** As respostas de erro têm o corpo `{"status": "", "title": ""}`. A exceção é o `401`, gerado na validação do token, cujo corpo é `{"title": "Unauthorized", "status": 401}` (status numérico). Um `403` por escopo insuficiente vem sem corpo. servers: - url: https://api.deliveryvip.com.br description: Produção security: - bearerAuth: [] tags: - name: Events description: >- Mudanças de estado e outras notificações relacionadas aos pedidos e ao salão (mesas e comandas) das lojas. - name: Orders description: 'Pedidos das lojas: consulta e ações de ciclo de vida.' - name: Discounts description: >- Cupons e descontos inteligentes da loja. Exige o recurso de descontos (`growth_discount`) contratado pela loja. - name: Tabs description: Comandas do salão da loja. - name: Places description: Mesas (QR Codes e tablets) do salão da loja. - name: Utils description: Endpoints utilitários. - name: Merchants description: Dados cadastrais, catálogo e status de funcionamento da loja. - name: Loyalty description: >- Configuração do programa de fidelidade enviada pelo operador de fidelidade (aplicativos que declaram a extensão de fidelidade; exige o escopo `dv.loyalty`). Observação sobre escopos: os endpoints de configuração abaixo exigem `dv.loyalty`, mas a leitura de pedidos — que é como o operador faz o acúmulo, já que o bloco `loyalty` fica no pedido — exige o escopo comum `od.all`. Uma integração de operador de fidelidade, portanto, solicita um token com os dois escopos (`scope=od.all dv.loyalty`). - name: Webhooks description: >- Eventos enviados ativamente ao aplicativo, em vez de consultados por polling. Um aplicativo com URL de webhook configurada recebe cada evento como um POST cujo corpo é um único objeto de evento — o mesmo schema retornado pelo endpoint de polling. O evento não traz o bloco `loyalty`: ele fica no pedido, que deve ser consultado em `orderURL`. Eventos entregues dessa forma não precisam ser confirmados (acknowledgment). **Verificação de assinatura (obrigatória).** Todo envio traz estes cabeçalhos: - `X-App-Signature` — HMAC-SHA256 em hexadecimal do **corpo bruto da requisição**, usando como chave o client secret do aplicativo. Calcule o digest sobre os bytes exatamente como recebidos, antes de qualquer parse ou re-serialização do JSON: fazer o parse e codificar de novo altera os bytes e o digest não vai bater. Compare usando comparação em tempo constante. Para um aplicativo que usa a extensão OpenDelivery, a chave é o **client secret da própria loja** (a credencial por loja, `ods_...`) sempre que a loja tiver uma; o client secret do aplicativo só é usado para lojas sem credencial própria. A renovação de um secret vale imediatamente: toda entrega enviada depois disso, inclusive novas tentativas e reenvios manuais, é assinada com o novo secret. - `X-App-Id` — identifica a plataforma como remetente. - `X-App-MerchantId` — a loja à qual o evento pertence: o `orderingAppMerchantId` do próprio aplicativo para aquela loja, quando configurado; caso contrário, o id da loja na plataforma. Rejeite qualquer requisição cuja assinatura não confira. A assinatura é a única prova de que o envio veio da plataforma, e um endpoint sem verificação permite que qualquer pessoa forje eventos de pedido. A assinatura cobre apenas o corpo e não carrega timestamp, então deduplique por `eventId`: uma nova tentativa, um reenvio manual ou uma requisição repetida trazem o mesmo `eventId`. **Entrega e novas tentativas.** Qualquer 2xx é sucesso. `408` e `429` são tratados como "tente mais tarde" e a entrega é repetida até 3 tentativas no total; qualquer outro status fora de 2xx — **inclusive 5xx** — é tratado como recusa definitiva e não é repetido automaticamente, ficando a entrega disponível para reenvio manual. Dez entregas consecutivas com falha suspendem os webhooks do aplicativo até que sejam reativados; uma entrega bem-sucedida zera essa contagem. Responda 2xx assim que o evento estiver armazenado de forma durável e faça o processamento de forma assíncrona: a plataforma usa timeouts curtos (3s para conectar, 5s para leitura) e um endpoint lento é registrado como falha. paths: /merchant/v3/{merchantId}/loyalty/config: put: tags: - Loyalty summary: Enviar configuração de fidelidade description: >- Cria ou substitui a configuração do programa de fidelidade do aplicativo autenticado para a loja (a última escrita prevalece). Antes de gravar qualquer coisa, a plataforma faz uma verificação síncrona: um GET /loyalty/ping assinado contra o `api_base_url` da extensão. Se o operador estiver inacessível ou a verificação da assinatura falhar, nada é gravado e a resposta é `422`. Exige o escopo `dv.loyalty` e a extensão de fidelidade declarada no aplicativo. parameters: - $ref: '#/components/parameters/merchantId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/loyaltyConfig' responses: '200': description: Configuração gravada. Retorna a configuração persistida. content: application/json: schema: $ref: '#/components/schemas/loyaltyConfig' '401': $ref: '#/components/responses/Unauthorized' '403': description: O token não tem o escopo `dv.loyalty` (sem corpo). '404': description: Loja não encontrada ou sem o aplicativo instalado. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- Falha de validação (`balanceTypes` deve incluir `cashback`; id e nome do programa são obrigatórios; `program` e `capabilities` são obrigatórios), o aplicativo não declara a extensão de fidelidade (`loyalty_extension_not_declared`) ou a verificação síncrona por ping falhou (nada foi gravado). content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: merchantId: in: path name: merchantId description: >- Id (UUID) da loja na plataforma. A loja precisa estar autorizada para o aplicativo. required: true schema: type: string format: uuid schemas: loyaltyConfig: type: object required: - program - capabilities properties: program: type: object required: - id - name properties: id: type: string description: Identificador do programa no operador. name: type: string description: Nome do programa. ownerType: type: string description: Titular do programa. enum: - store - chain - coalition default: store rulesUrl: type: string format: uri description: URL do regulamento do programa. capabilities: type: object required: - balanceTypes properties: balanceTypes: type: array items: type: string enum: - cashback description: Deve incluir `cashback` (o único tipo de saldo na v1). partialRedemption: type: boolean default: true description: Se o cliente pode resgatar só parte do saldo. enrollment: type: boolean default: true description: Se o operador aceita a adesão de novos clientes pela plataforma. redemptionLimits: type: object description: >- Limites comerciais opcionais por pedido. Omita o objeto, ou qualquer um dos limites, para não declarar limite ali. Percentuais incidem sobre a base resgatável — os itens do pedido menos os demais descontos do carrinho; frete e taxas nunca são resgatáveis, então um teto percentual é calculado sobre os itens, não sobre o total do pedido. properties: min: $ref: '#/components/schemas/redemptionLimit' max: $ref: '#/components/schemas/redemptionLimit' Error: type: object required: - title - status properties: status: type: string description: Código HTTP da resposta, como string. example: '404' title: description: >- Descrição do problema. Em erros de validação pode vir como objeto (campo → lista de mensagens) ou como lista. oneOf: - type: string - type: object - type: array items: type: string example: Record not found redemptionLimit: type: object description: >- Um único limite: valor fixo em BRL ou percentual da base resgatável. Um mínimo nunca aumenta o valor resgatado — apenas decide se o resgate é possível. required: - type - value properties: type: type: string enum: - fixed - percent value: type: number description: >- Valor em BRL quando `type` é `fixed`; de 0 a 100 quando `type` é `percent`. UnauthorizedError: type: object properties: title: type: string example: Unauthorized status: type: integer example: 401 responses: Unauthorized: description: Token ausente, inválido, expirado ou revogado. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Token de acesso opaco emitido pela API de autenticação (`POST /authentication/v1/oauth/token`). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.