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

# Detalhes da loja

> Leia em uma chamada os dados da loja, os serviços, as formas de pagamento e o catálogo completo.

`GET /merchant/v3/{merchantId}` devolve tudo o que a DeliveryVip sabe sobre a loja: dados cadastrais, endereço, serviços de entrega e retirada, formas de pagamento e o catálogo completo. Use para conferir o estado atual antes de sincronizar, ou para montar o catálogo no seu sistema pela primeira vez.

## Requisição

```bash cURL theme={null}
curl 'https://api.deliveryvip.com.br/merchant/v3/{merchantId}' \
  --header 'Authorization: Bearer {token}'
```

```js Node.js theme={null}
const response = await fetch(`https://api.deliveryvip.com.br/merchant/v3/${merchantId}`, {
  headers: { Authorization: `Bearer ${token}` },
})
const merchant = await response.json()
```

```python Python theme={null}
response = requests.get(
    f"https://api.deliveryvip.com.br/merchant/v3/{merchant_id}",
    headers={"Authorization": f"Bearer {token}"},
)
merchant = response.json()
```

| Status | Quando |
| - | - |
| `200 OK` | A loja foi encontrada. O corpo traz os campos abaixo. |
| `401 Unauthorized` | Token ausente, expirado ou inválido. |
| `404 Not Found` | O `merchantId` não existe ou a loja não autorizou o seu app. |

## Estrutura da loja

![Estrutura do merchant: informações básicas, serviços, formas de pagamento e catálogo](https://mintcdn.com/deliveryvip-a4256422/ELxpcniK2_BP8zxT/images/merchant-arc.jpg?fit=max\&auto=format\&n=ELxpcniK2_BP8zxT\&q=85\&s=f61a3f91d7c3f790d7b8546d81ff1c37)

Estrutura do merchant

> [!NOTE]
>
> Campos opcionais sem valor são **omitidos** da resposta, não enviados como `null`. O mesmo vale para as listas do catálogo: uma loja sem produtos não traz a chave `items`.

**id** `uuid` *required*

Identificador da loja. É o `merchantId` usado nas rotas.

**lastUpdate** `datetime` *required*

Última alteração no cadastro da loja, com fuso horário (por exemplo `2023-09-26T18:29:16-03:00`).

**ttl** `integer` *required*

Sugestão de intervalo, em segundos, para consultar a loja de novo. Hoje é sempre `3600`.

**status** `string` *required*

`AVAILABLE` quando a loja está aberta, `UNAVAILABLE` quando está fechada.

**basicInfo** `object` *required*

Dados cadastrais da loja.

**propriedades**

**name** `string`

Nome fantasia.

**document** `string`

CNPJ ou CPF, só com dígitos.

**corporateName** `string`

Razão social.

**description** `string`

Descrição da loja. Só vem quando preenchida.

**contactEmails** `string[]`

E-mails de contato. Só vem quando a loja tem e-mail e e-mail do responsável cadastrados.

**contactPhones** `object`

Só vem quando a loja tem telefone.

**propriedades**

**commercialNumber** `string`

Telefone comercial no formato E.164.

**createdAt** `datetime`

Data de cadastro da loja.

**address** `object`

Endereço da loja.

**propriedades**

**country** `string`

Sigla do país.

**state** `string`

Sigla do estado.

**city** `string`

Cidade.

**district** `string`

Bairro.

**street** `string`

Rua.

**number** `string`

Número.

**complement** `string`

Complemento. Só vem quando preenchido.

**reference** `string`

Ponto de referência. Só vem quando preenchido.

**postalCode** `string`

CEP.

**formattedAddress** `string`

Endereço completo em uma linha.

**coordinates** `object`

`latitude` e `longitude` da loja.

**services** `object[]` *required*

Sempre dois itens: um `DELIVERY` e um `TAKEOUT`.

**propriedades**

**status** `string`

`AVAILABLE` se a loja aceita o serviço, `UNAVAILABLE` se não.

**serviceType** `string`

`DELIVERY` (entrega) ou `TAKEOUT` (retirada).

**serviceTime** `integer`

Tempo do serviço, em minutos.

**paymentMethods** `object[]`

Formas de pagamento, ordenadas por `index`.

**propriedades**

**id** `uuid`

Identificador da forma de pagamento.

**index** `integer`

Posição na lista.

**name** `string`

Nome exibido ao cliente.

**mode** `string`

`CASH`, `CREDIT`, `DEBIT`, `PIX`, `MEAL_VOUCHER`, `FOOD_VOUCHER` ou `OTHER`.

**externalCode** `string`

Código no seu sistema. Só vem quando preenchido.

**status** `string`

`AVAILABLE` ou `UNAVAILABLE`.

**options** `object[]`

Opções do catálogo, em ordem alfabética.

**propriedades**

**id** `uuid`

Identificador da opção.

**name** `string`

Nome da opção.

**description** `string`

Descrição. Só vem quando preenchida.

**externalCode** `string`

Código no seu sistema. Só vem quando preenchido.

**status** `string`

`AVAILABLE` ou `UNAVAILABLE`.

**image** `object`

Só vem quando a opção tem imagem.

**propriedades**

**url** `string`

Endereço da imagem.

**checksum** `string`

MD5 do arquivo em Base64. Compare com o checksum da sua imagem para saber se precisa enviá-la de novo.

**optionGroups** `object[]`

Grupos de opções, em ordem alfabética.

**propriedades**

**id** `uuid`

Identificador do grupo.

**name** `string`

Nome do grupo.

**externalCode** `string`

Código no seu sistema. Só vem quando preenchido.

**status** `string`

`AVAILABLE` ou `UNAVAILABLE`.

**optionIds** `uuid[]`

IDs das opções que fazem parte do grupo.

**categories** `object[]`

Categorias, ordenadas por `index`.

**propriedades**

**id** `uuid`

Identificador da categoria.

**index** `integer`

Posição no cardápio.

**name** `string`

Nome da categoria.

**description** `string`

Descrição. Só vem quando preenchida.

**externalCode** `string`

Código no seu sistema. Só vem quando preenchido.

**status** `string`

`AVAILABLE` ou `UNAVAILABLE`.

**items** `object[]`

Produtos, ordenados por `index`.

**propriedades**

**id** `uuid`

Identificador do produto.

**index** `integer`

Posição dentro da categoria.

**name** `string`

Nome do produto.

**description** `string`

Descrição. Só vem quando preenchida.

**externalCode** `string`

Código no seu sistema. Só vem quando preenchido.

**status** `string`

`AVAILABLE` ou `UNAVAILABLE`.

**ean** `string`

Código de barras EAN. Só vem quando preenchido.

**menu** `string[]`

Onde o produto é vendido: `DELIVERY` (entrega), `TAKEOUT` (retirada) e `INDOOR` (consumo no local).

Quando o produto tem `DELIVERY` **e** `TAKEOUT`, a lista inclui **também** o valor agregado `DELIVERY_TAKEOUT`, mantido por retrocompatibilidade. Baseie-se nos tipos individuais e ignore o agregado.

**price** `object`

**propriedades**

**value** `number`

Preço atual.

**originalValue** `number`

Preço original. Quando é maior que `value`, o produto está em promoção.

**currency** `string`

Sempre `BRL`.

**categoryId** `uuid`

Categoria do produto.

**image** `object`

`url` e `checksum` da imagem, como em `options`. Só vem quando o produto tem imagem.

**modifiers** `object[]`

Modificadores do produto, ordenados por `index`. Só vem quando o produto tem modificadores.

**propriedades**

**id** `uuid`

Identificador do modificador.

**index** `integer`

Posição no produto.

**name** `string`

Pergunta exibida ao cliente, por exemplo "Escolha os sabores".

**externalCode** `string`

Código no seu sistema. Só vem quando preenchido.

**status** `string`

`AVAILABLE` ou `UNAVAILABLE`.

**rule** `string`

Como o preço das opções escolhidas é calculado: `ADDITION`, `APPORTIONMENT` ou `HIGHEST`. Veja as [regras de preço](/docs/guides/merchant/catalog-and-services/actions.md#regras-de-preço-do-modificador).

**minPermitted** `integer`

Mínimo de opções que o cliente precisa escolher.

**maxPermitted** `integer`

Máximo de opções que o cliente pode escolher. `0` significa sem limite.

**optionGroups** `object[]`

Grupos de opções do modificador.

**propriedades**

**optionGroupId** `uuid`

ID do grupo de opções.

**index** `integer`

Posição do grupo no modificador.

**options** `object[]`

Opções do grupo neste modificador, com preço próprio.

**propriedades**

**optionId** `uuid`

ID da opção.

**index** `integer`

Posição da opção.

**status** `string`

`AVAILABLE` ou `UNAVAILABLE`.

**price** `object`

`value`, `originalValue` e `currency` da opção neste modificador.

> [accordion] Exemplo de resposta completa
>
> ```json 200 OK theme={null}
> {
>   "id": "8c64a3f9-65d7-4e3b-9a2d-7c85bc3b3a17",
>   "lastUpdate": "2023-09-26T18:29:16-03:00",
>   "ttl": 3600,
>   "status": "AVAILABLE",
>   "basicInfo": {
>     "name": "Pizzaria Exemplo",
>     "document": "12345678000190",
>     "corporateName": "Pizzaria Exemplo LTDA",
>     "contactEmails": ["contato@exemplo.com.br"],
>     "contactPhones": { "commercialNumber": "+5511999999999" },
>     "createdAt": "2022-01-10T09:00:00-03:00",
>     "address": {
>       "country": "BR",
>       "state": "SP",
>       "city": "São Paulo",
>       "district": "Moema",
>       "street": "Avenida Exemplo",
>       "number": "100",
>       "postalCode": "04000-000",
>       "formattedAddress": "Avenida Exemplo, 100 - Moema, São Paulo - SP",
>       "coordinates": {
>         "latitude": -23.6,
>         "longitude": -46.66
>       }
>     }
>   },
>   "services": [
>     { "status": "AVAILABLE", "serviceType": "DELIVERY", "serviceTime": 15 },
>     { "status": "AVAILABLE", "serviceType": "TAKEOUT", "serviceTime": 15 }
>   ],
>   "paymentMethods": [
>     {
>       "id": "41678b1b-1902-4f34-b7b0-e2271e93283c",
>       "index": 1,
>       "name": "Visa - Crédito",
>       "mode": "CREDIT",
>       "externalCode": "13",
>       "status": "AVAILABLE"
>     }
>   ],
>   "options": [
>     {
>       "id": "c6f193a1-93ea-4aa6-af50-8cc6ed40fb7e",
>       "name": "Calabresa",
>       "description": "Molho de tomate, mussarela e calabresa",
>       "externalCode": "152",
>       "status": "AVAILABLE",
>       "image": {
>         "url": "https://exemplo.com/calabresa.jpg",
>         "checksum": "9fOMBLAAaCVVpx03oiViRQ=="
>       }
>     }
>   ],
>   "optionGroups": [
>     {
>       "id": "b4a8a52e-2dd8-4d94-a198-2e68a7ee2d68",
>       "name": "Sabores tradicionais",
>       "externalCode": "2",
>       "status": "AVAILABLE",
>       "optionIds": ["c6f193a1-93ea-4aa6-af50-8cc6ed40fb7e"]
>     }
>   ],
>   "categories": [
>     {
>       "id": "d37d1183-d544-4d15-a067-0f0ad38f7680",
>       "index": 1,
>       "name": "Pizzas",
>       "status": "AVAILABLE"
>     }
>   ],
>   "items": [
>     {
>       "id": "a3a74a38-9b1d-4c6f-8c53-63eafcdac477",
>       "index": 1,
>       "name": "Pizza Gigante",
>       "description": "Até 4 sabores",
>       "externalCode": "104",
>       "status": "AVAILABLE",
>       "menu": ["DELIVERY", "TAKEOUT", "INDOOR", "DELIVERY_TAKEOUT"],
>       "price": { "value": 50.0, "originalValue": 50.0, "currency": "BRL" },
>       "categoryId": "d37d1183-d544-4d15-a067-0f0ad38f7680",
>       "image": {
>         "url": "https://exemplo.com/pizza.jpg",
>         "checksum": "9fOMBLAAaCVVpx03oiViRQ=="
>       },
>       "modifiers": [
>         {
>           "id": "5a451f76-9e48-49e5-9a62-181bfc6b1a92",
>           "index": 1,
>           "name": "Escolha os sabores",
>           "status": "AVAILABLE",
>           "rule": "HIGHEST",
>           "minPermitted": 1,
>           "maxPermitted": 4,
>           "optionGroups": [
>             {
>               "optionGroupId": "b4a8a52e-2dd8-4d94-a198-2e68a7ee2d68",
>               "index": 1,
>               "options": [
>                 {
>                   "optionId": "c6f193a1-93ea-4aa6-af50-8cc6ed40fb7e",
>                   "index": 1,
>                   "status": "AVAILABLE",
>                   "price": { "value": 0.0, "originalValue": 0.0, "currency": "BRL" }
>                 }
>               ]
>             }
>           ]
>         }
>       ]
>     }
>   ]
> }
> ```

## Status e horários da loja

Para saber só se a loja está aberta e quais são os horários de atendimento, use `GET /merchant/v3/{merchantId}/status`. A resposta é bem menor que a da loja completa.

```bash theme={null}
curl 'https://api.deliveryvip.com.br/merchant/v3/{merchantId}/status' \
  --header 'Authorization: Bearer {token}'
```

**status** `string` *required*

`AVAILABLE` (aberta) ou `UNAVAILABLE` (fechada).

**services** `object[]` *required*

Um item com o `id` da loja e `serviceHours[].weekHours[]`: cada faixa traz `dayOfWeek` (por exemplo `["MONDAY"]`) e `timePeriods` com `startTime` e `endTime` no horário local da loja (`HH:MM:SS`).

**orderingAppMerchantId** `uuid` *required*

ID da loja na DeliveryVip.

## Próximos passos

> [card] [Ações](/docs/guides/merchant/catalog-and-services/actions.md)
>
> Escolha entre update, upsert e force para sincronizar o catálogo.

> [card] [Upsert](/docs/guides/merchant/catalog-and-services/actions/upsert.md)
>
> Crie ou altere produtos, opções e categorias.


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