> ## 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": "<eventId>"}] (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.

# Signed reachability check

> Called synchronously while the operator pushes a merchant configuration. Verify the signature (HMAC of an empty string) and answer 2xx. Any non-2xx, timeout or invalid signature makes DeliveryVip reject the configuration push with 422 — nothing is stored.



## OpenAPI

````yaml https://app.deliveryvip.com.br/swaggers/loyalty_operator.yaml get /v1/loyalty/ping
openapi: 3.0.3
info:
  version: v1
  title: DeliveryVip Loyalty Operator Contract
  description: >-
    The HTTP contract a loyalty operator must implement to serve the DeliveryVip
    loyalty extension. DeliveryVip is the ordering application: it CALLS these
    endpoints on the api_base_url declared by the operator's app (loyalty
    extension, dv.loyalty scope). Every request is signed with HMAC-SHA256 of
    the RAW body (empty string for body-less requests) using the app's OAuth
    secret — verify the signature against the exact bytes received, never a
    re-serialization. Respond fast: DeliveryVip uses 3s connect / 5s read
    timeouts, and 5 transport failures (timeout/5xx) within 5 minutes open a
    circuit breaker for the whole extension. Business answers (409/422/403/404)
    never count as failures. Configuration is pushed the other way (operator ->
    DeliveryVip) via PUT/DELETE /merchant/v3/{merchantId}/loyalty/config — see
    the Merchant API swagger; the PUT triggers a synchronous signed GET
    /v1/loyalty/ping here before anything is stored. That push is also where an
    operator declares its commercial boundaries per order
    (capabilities.redemptionLimits: an optional min and max, each fixed BRL or
    percent of the redeemable base). DeliveryVip enforces them before calling
    this API, so the amount below always already respects whatever the operator
    declared. Canonical byte-pinned request/response examples live in the
    platform repository under test/fixtures/files/loyalty/.
servers:
  - url: '{api_base_url}'
    description: >-
      The base URL the operator declares on the loyalty extension (https only;
      may include a path prefix).
    variables:
      api_base_url:
        default: https://operator.example.com/dv/v1
security:
  - appId: []
    appMerchantId: []
    appSignature: []
tags:
  - name: Handshake
    description: Synchronous verification during the config push.
  - name: Accounts
    description: >-
      Customer identity and balance. The account id must be opaque and stable
      across relinks.
  - name: Redemptions
    description: Synchronous balance debit (checkout) and its explicit idempotent reversal.
paths:
  /v1/loyalty/ping:
    get:
      tags:
        - Handshake
      summary: Signed reachability check
      description: >-
        Called synchronously while the operator pushes a merchant configuration.
        Verify the signature (HMAC of an empty string) and answer 2xx. Any
        non-2xx, timeout or invalid signature makes DeliveryVip reject the
        configuration push with 422 — nothing is stored.
      responses:
        '204':
          description: Operator reachable and signature valid.
components:
  securitySchemes:
    appId:
      type: apiKey
      in: header
      name: X-App-Id
      description: The uid of the operator's OAuth application on DeliveryVip.
    appMerchantId:
      type: apiKey
      in: header
      name: X-App-MerchantId
      description: The UUID of the merchant (company) the call concerns.
    appSignature:
      type: apiKey
      in: header
      name: X-App-Signature
      description: >-
        Hex HMAC-SHA256 of the raw request body (empty string when there is no
        body), keyed with the app's OAuth secret. Verify against the exact bytes
        received.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.