> ## 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. # Listar faturas das lojas (obsoleto) > Obsoleto: use `GET /partner/v2/{partnerId}/invoices` ou `GET /partner/v2/{partnerId}/merchants/invoices`. A rota continua respondendo e envia os cabeçalhos `Deprecation: true` e `Sunset` (01/07/2025). Lista as faturas do mês das lojas dos parceiros autorizados para o token. ## OpenAPI ````yaml https://app.deliveryvip.com.br/swaggers/partner.yaml get /partner/v2/merchants/invoices openapi: 3.0.3 info: version: v2 title: API de Parceiros DeliveryVip description: >- A API de Parceiros da DeliveryVip permite que parceiros e revendas gerenciem as lojas (merchants) e as revendas da sua carteira: cadastro, consulta, membros, assinaturas, recursos contratados, aplicações autorizadas, planos e faturas. Todas as rotas exigem um access token OAuth 2.0 com o escopo `dv.partner`, enviado no cabeçalho `Authorization: Bearer `. O token dá acesso aos parceiros autorizados para a aplicação. O cabeçalho opcional `x-partners` (lista de UUIDs separados por vírgula) restringe a requisição a um subconjunto desses parceiros; um UUID fora da autorização do token resulta em `403`. Erros seguem o formato `{"status": "", "title": }`, em que `title` é um texto ou, em erros de validação, um objeto com as mensagens por campo. servers: - url: https://api.deliveryvip.com.br description: Produção security: - bearerAuth: [] tags: - name: Signup description: >- Cadastro público de loja, consumido por uma landing page e não pelo backend do parceiro. - name: Plans description: Planos disponíveis para as lojas do parceiro. - name: Invoices description: Faturas das lojas do parceiro. - name: Merchants description: Cadastro, listagem e consulta de lojas, vendas e faturas. - name: Merchants/Subscriptions description: >- Ativação, cancelamento, aviso, bloqueio e atualização da assinatura da loja. - name: Merchants/Members description: Adição, alteração e remoção de membros da loja. - name: Merchants/Applications description: Autorização e revogação de aplicações na loja. - name: Merchants/Features description: Contratação e cancelamento de recursos adicionais da loja. - name: Resales description: Cadastro, listagem e consulta de revendas e suas faturas. - name: Resales/Subscriptions description: >- Ativação, cancelamento, aviso, bloqueio e atualização da assinatura da revenda. - name: Resales/Members description: Adição, alteração e remoção de membros da revenda. - name: Resales/Applications description: Autorização e revogação de aplicações na revenda. paths: /partner/v2/merchants/invoices: get: tags: - Merchants summary: Listar faturas das lojas (obsoleto) description: >- Obsoleto: use `GET /partner/v2/{partnerId}/invoices` ou `GET /partner/v2/{partnerId}/merchants/invoices`. A rota continua respondendo e envia os cabeçalhos `Deprecation: true` e `Sunset` (01/07/2025). Lista as faturas do mês das lojas dos parceiros autorizados para o token. parameters: - $ref: '#/components/parameters/year' - $ref: '#/components/parameters/month' responses: '200': description: Lista de faturas. headers: Deprecation: $ref: '#/components/headers/Deprecation' Sunset: $ref: '#/components/headers/Sunset' content: application/json: schema: type: array items: $ref: '#/components/schemas/invoiceMerchant' '204': description: Nenhuma fatura no período. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' deprecated: true components: parameters: year: in: query name: year description: Ano de referência. Padrão é o ano corrente. schema: type: integer example: 2026 month: in: query name: month description: Mês de referência (1 a 12). Padrão é o mês corrente. schema: type: integer minimum: 1 maximum: 12 example: 10 headers: Deprecation: description: Sempre `true`, indicando que a rota está obsoleta. schema: type: string example: 'true' Sunset: description: Data a partir da qual a rota pode deixar de existir (formato HTTP-date). schema: type: string example: Tue, 01 Jul 2025 00:00:00 GMT schemas: invoiceMerchant: type: object required: - merchantId - partnerId - month - year - items properties: merchantId: type: string format: uuid description: UUID da loja. partnerId: type: string format: uuid description: UUID do parceiro da fatura. resaleId: type: string format: uuid description: UUID da revenda. Omitido quando a loja não é de revenda. month: type: integer description: Mês de referência. year: type: integer description: Ano de referência. items: type: array items: $ref: '#/components/schemas/legacyInvoiceItem' legacyInvoiceItem: type: object required: - itemType - quantity - usageTime properties: itemType: $ref: '#/components/schemas/itemType' quantity: type: integer description: Quantidade cobrada. usageTime: type: number format: float description: Fração do mês em que o item esteve ativo. totalPrice: type: number format: float description: >- Preço cheio do item no mês. Só vem quando o token representa o parceiro da fatura (não para tokens de revenda). totalUsageTimePrice: type: number format: float description: >- Preço proporcional a `usageTime`. Só vem quando o token representa o parceiro da fatura (não para tokens de revenda). metadata: $ref: '#/components/schemas/InvoiceItemMetadata' error: type: object properties: status: type: string description: Código HTTP, como texto. example: '422' title: description: >- Mensagem de erro. Em erros de validação, é um objeto com a lista de mensagens de cada campo. oneOf: - type: string - type: object additionalProperties: type: array items: type: string itemType: type: string description: Recurso cobrado. enum: - DELIVERY_TAKEOUT - DELIVERYBOT_NOTIFICATION - DELIVERYBOT_ASSISTANT - INDOOR_VIEWER - INDOOR_QRCODE - INDOOR_TABLET - DOMAIN_CUSTOM - GROWTH_DISCOUNT - INTEGRATION_MARKETING - INTEGRATION_LOGISTIC - SALES_REVENUE - ORDERS_COUNT - MULTI_STORE InvoiceItemMetadata: type: object description: >- Presente só em itens `DELIVERY_TAKEOUT` que têm metadados. Omitido para tokens que não representam o parceiro da fatura quando `tieredPricingRanges` seria a única chave. properties: agreementCode: type: string description: Código de contrato da assinatura. sales: type: object description: Resumo das vendas da loja no mês. properties: all: $ref: '#/components/schemas/InvoiceItemSalesSummary' success: $ref: '#/components/schemas/InvoiceItemSalesSummary' cancelled: $ref: '#/components/schemas/InvoiceItemSalesSummary' tieredPricingRanges: type: array description: >- Faixas de preço, presentes quando o modelo de cobrança é `VOLUME_BASE` ou `TIERED_BASE`. Só vem quando o token representa o parceiro da fatura. items: type: object properties: lastUnit: type: integer nullable: true description: Última unidade da faixa; `null` na faixa final. perUnitPrice: type: number format: float description: Preço por unidade. fixedRatePrice: type: number format: float description: Preço fixo da faixa. position: type: integer description: Posição da faixa. InvoiceItemSalesSummary: type: object properties: quantity: type: integer description: Quantidade de pedidos. totalPrice: type: number format: float description: Valor total dos pedidos. 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 Forbidden: description: >- Proibido. Retornado quando o token não tem o escopo `dv.partner`, quando o cabeçalho `x-partners` é inválido ou quando o `partnerId` não é autorizado para o token. content: application/json: schema: $ref: '#/components/schemas/error' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Access token OAuth 2.0 (opaco) com o escopo `dv.partner`, obtido em `POST /authentication/v1/oauth/token`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.