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

# Listar faturas das lojas (descontinuado)

> Formato antigo das faturas das lojas, mantido por compatibilidade. Migre para as rotas com partnerId.

> [!WARNING]
>
> `GET /partner/v2/merchants/invoices` está **descontinuado**. A data de desligamento anunciada foi 01/07/2025: hoje a rota ainda responde, mas toda resposta traz os headers `Deprecation: true` e `Sunset: Tue, 01 Jul 2025 00:00:00 GMT` e ela pode ser removida a qualquer momento. Use [`GET /partner/v2/{partnerId}/merchants/invoices`](/docs/guides/partner/invoices/utilizando-a-api/listando-merchants-invoices) ou [`GET /partner/v2/{partnerId}/invoices`](/docs/guides/partner/invoices/utilizando-a-api/listando-invoices).

O endpoint devolve uma fatura por loja que o token alcança, para o mês pedido, com os itens que a DeliveryVip cobra do parceiro.

| Status | Quando |
| - | - |
| `200 OK` | Lista de faturas. |
| `204 No Content` | Nenhuma fatura no período. |
| `403 Forbidden` | `x-partners` fora do alcance do token. |

## Requisição

```bash cURL theme={null}
curl 'https://api.deliveryvip.com.br/partner/v2/merchants/invoices?year=2024&month=1' \
  --header 'Authorization: Bearer {token}'
```

```js Node.js theme={null}
const response = await fetch(
  'https://api.deliveryvip.com.br/partner/v2/merchants/invoices?year=2024&month=1',
  { headers: { Authorization: `Bearer ${token}` } },
)
```

```python Python theme={null}
response = requests.get(
    "https://api.deliveryvip.com.br/partner/v2/merchants/invoices",
    params={"year": 2024, "month": 1},
    headers={"Authorization": f"Bearer {token}"},
)
```

**year** `integer`

Ano. Sem ele, vale o ano corrente.

**month** `integer`

Mês, de 1 a 12. Sem ele, vale o mês corrente.

**x-partners** `string[]`

Restringe a parceiros ou revendas específicos, como em [Filtrar por Partners](/docs/guides/partner/merchant/utilizando-a-api/listar-merchants.md#filtrar-por-partners).

## Resposta

```json Resposta (200) theme={null}
[
  {
    "merchantId": "2a710c93-ece1-4d57-9038-6fc714c0e81b",
    "month": "1",
    "year": "2024",
    "items": [
      {
        "itemType": "DELIVERY_TAKEOUT",
        "quantity": 1,
        "usageTime": 0.5,
        "totalPrice": 150.0,
        "totalUsageTimePrice": 75.0,
        "metadata": {
          "agreementCode": "123456",
          "sales": {
            "all": { "quantity": 1059, "totalPrice": 96125.11 },
            "success": { "quantity": 1059, "totalPrice": 96125.11 },
            "cancelled": { "quantity": 0, "totalPrice": 0.0 }
          }
        }
      },
      { "itemType": "INDOOR_QRCODE", "quantity": 7, "usageTime": 0.5, "totalPrice": 35.0, "totalUsageTimePrice": 17.5 }
    ],
    "partnerId": "ba1fcc5c-8570-4a8d-b7dc-9d4077f85be8",
    "resaleId": "70d3fdf7-1c4a-49d5-8be9-171e417b8f61"
  }
]
```

**merchantId** `uuid`

ID da loja.

**month** `string | integer`

Mês da fatura. Repete o valor enviado na query (texto); sem o parâmetro, vem como número.

**year** `string | integer`

Ano da fatura, com a mesma regra de `month`.

**partnerId** `uuid`

ID do parceiro.

**resaleId** `uuid`

ID da revenda. Só aparece em lojas de revenda.

**items** `object[]`

Itens da fatura.

**propriedades**

**itemType** `string`

`DELIVERY_TAKEOUT`, `DELIVERYBOT_NOTIFICATION`, `DELIVERYBOT_ASSISTANT`, `INDOOR_VIEWER`, `INDOOR_QRCODE`, `INDOOR_TABLET`, `DOMAIN_CUSTOM`, `GROWTH_DISCOUNT`, `INTEGRATION_MARKETING`, `INTEGRATION_LOGISTIC`, `SALES_REVENUE`, `ORDERS_COUNT` ou `MULTI_STORE`. Veja [Definições de faturas](/docs/guides/partner/invoices/definicoes.md).

**quantity** `integer`

Quantidade usada no mês.

**usageTime** `number`

Fração do mês em que a assinatura da loja ficou ativa, de 0 a 1 (ex.: `0.5` para uma loja ativada no dia 16 de um mês de 30 dias).

**totalPrice** `number`

Valor do item no mês cheio, em reais: o que o parceiro paga à DeliveryVip. Só para token do parceiro dono da fatura.

**totalUsageTimePrice** `number`

Valor proporcional ao `usageTime`, em reais. Só para token do parceiro dono da fatura.

**metadata** `object`

Só no item `DELIVERY_TAKEOUT`: `agreementCode`, totais de vendas (`sales.all`, `sales.success`, `sales.cancelled`) e, quando o preço é por faixas, `tieredPricingRanges` (só para token do parceiro dono da fatura).

> [!NOTE]
>
> `totalPrice` e `totalUsageTimePrice` mostram quanto o **parceiro** paga à DeliveryVip pela loja, por isso só aparecem quando o token representa o parceiro dono da fatura. Para um token de revenda, os dois campos não são enviados (nem como `null`) e o `metadata` não traz `tieredPricingRanges`. `itemType`, `quantity`, `usageTime` e o resto do `metadata` continuam iguais.


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