> ## 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.

# Fazer onboarding da loja

> Registra (ou atualiza) os dados do Software Service para a loja do token: o seu identificador da loja (`merchantId`), a URL e a chave para consulta do merchant (getMerchant) e a URL do webhook de pedidos. Responde 201 no primeiro registro e 204 nas atualizações.



## OpenAPI

````yaml https://app.deliveryvip.com.br/swaggers/opendelivery.yaml put /v1/merchantOnboarding
openapi: 3.0.3
info:
  version: v1
  title: API OpenDelivery DeliveryVip
  description: >-
    API compatível com o padrão Open Delivery (Abrasel), em que a DeliveryVip
    atua como Ordering Application para Software Services (PDVs e sistemas de
    gestão). A autenticação usa OAuth 2.0 `client_credentials` no endpoint
    `/oauth/token` deste mesmo host, com o escopo `od.all` (tokens sem esse
    escopo recebem 403). Os tokens são opacos e enviados no header
    `Authorization: Bearer <token>`. Datas são retornadas em UTC (ISO 8601).
servers:
  - url: https://od.deliveryvip.com.br
    description: Produção
security:
  - bearerAuth: []
tags:
  - name: OAuth
    description: Emissão de access tokens para a API OpenDelivery.
  - name: Versions
    description: Versões da API implementadas. Não exigem autenticação.
  - name: Events
    description: >-
      Mudanças de estado e outras notificações dos pedidos das lojas vinculadas
      ao aplicativo.
  - name: Orders
    description: Detalhes do pedido e ações sobre ele.
  - name: Merchants
    description: Onboarding da loja, abertura/fechamento e atualização de catálogo.
paths:
  /v1/merchantOnboarding:
    put:
      tags:
        - Merchants
      summary: Fazer onboarding da loja
      description: >-
        Registra (ou atualiza) os dados do Software Service para a loja do
        token: o seu identificador da loja (`merchantId`), a URL e a chave para
        consulta do merchant (getMerchant) e a URL do webhook de pedidos.
        Responde 201 no primeiro registro e 204 nas atualizações.
      operationId: merchantOnboarding
      parameters:
        - in: query
          name: merchantId
          description: Identificador da loja no Software Service.
          required: true
          schema:
            type: string
          example: 313AE66A-5AE4-4FD7-A552-A089CD71F063
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                getMerchantURL:
                  type: object
                  description: >-
                    Endpoint do Software Service que retorna os dados e o
                    catálogo da loja.
                  properties:
                    baseURL:
                      type: string
                      format: uri
                      description: URL base do endpoint getMerchant.
                      example: https://pdv.exemplo.com.br/
                    apiKey:
                      type: string
                      description: Chave enviada nas chamadas ao getMerchant.
                      example: chave-secreta
                ordersWebhookURL:
                  type: string
                  format: uri
                  description: URL que receberá os eventos de pedido via webhook.
                  example: https://pdv.exemplo.com.br/newEvent
      responses:
        '201':
          description: Onboarding registrado.
        '204':
          description: Onboarding atualizado.
        '400':
          description: '`merchantId` ausente, corpo ausente ou URL inválida.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: '400'
                title: merchantId is required
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/MultipleMerchants'
        '422':
          description: >-
            O aplicativo não declarou a extensão OpenDelivery
            (`open_delivery_extension_not_declared`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      required:
        - title
        - status
      properties:
        title:
          type: string
          description: Descrição do problema. Várias mensagens vêm separadas por `|`.
          example: Record not found
        status:
          type: string
          description: Código HTTP da resposta, como texto.
          example: '404'
  responses:
    Unauthorized:
      description: Token ausente, inválido ou expirado.
      content:
        application/json:
          schema:
            type: object
            properties:
              title:
                type: string
                example: Unauthorized
              status:
                type: integer
                example: 401
    MultipleMerchants:
      description: >-
        O token está vinculado a mais de uma loja e a operação exige uma única
        (`Token must be associated with a single merchant`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Access token opaco obtido em `POST /oauth/token` (host
        `od.deliveryvip.com.br`) com `grant_type=client_credentials` e escopo
        `od.all`.

````

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