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

# Catálogo

> Consulte e sincronize o catálogo, os serviços e as formas de pagamento das lojas que instalaram o seu app.

A API de catálogo mantém o cardápio da loja na DeliveryVip igual ao do seu sistema. Você lê tudo em uma chamada e escreve com uma de três rotas, conforme o tamanho da mudança.

| Endpoint | Para quê |
| - | - |
| `GET /merchant/v3/{merchantId}` | Ler dados da loja, serviços, formas de pagamento e o catálogo completo. |
| `POST /merchant/v3/{merchantId}/merchantUpdate` | Alterar objetos que já existem. |
| `POST /merchant/v3/{merchantId}/merchantUpsert` | Criar ou alterar objetos de um tipo. |
| `POST /merchant/v3/{merchantId}/merchantForce` | Reescrever o catálogo: o que não vier na lista é removido. |

Todas as rotas exigem o token no header `Authorization` (veja [autenticação](/docs/inicio/conceitos/autenticacao.md)) e só aceitam lojas que autorizaram o seu app.

## Como o catálogo se organiza

Opções e grupos de opções são cadastrados uma vez e reaproveitados. Um produto usa modificadores, e cada modificador aponta para grupos de opções.

![Categoria contém produtos; o produto tem modificadores; o modificador usa grupos de opções; o grupo contém opções](https://mintcdn.com/deliveryvip-a4256422/ELxpcniK2_BP8zxT/images/catalogo-estrutura.png?fit=max\&auto=format\&n=ELxpcniK2_BP8zxT\&q=85\&s=493c93e4b7b049cb99c76931f7008dca)

Como o catálogo se organiza

| Entidade | O que é | Exemplo |
| - | - | - |
| `CATEGORY` | Seção do cardápio. | Pizzas |
| `ITEM` | Produto vendido, sempre dentro de uma categoria. | Pizza Gigante |
| `modifiers` | Pergunta feita ao cliente ao escolher o produto, com regra de preço e limites de escolha. Existe só dentro de um `ITEM`. | Escolha os sabores (1 a 4) |
| `OPTION_GROUP` | Lista reutilizável de opções. | Sabores tradicionais |
| `OPTION` | Escolha individual. | Calabresa |
| `SERVICE` | Entrega (`DELIVERY`) e retirada (`TAKEOUT`): disponibilidade e tempo de preparo. | Entrega em 40 min |
| `PAYMENT_METHOD` | Forma de pagamento aceita na loja. | Visa crédito |

> [!NOTE]
>
> Os IDs são gerados pelo seu sistema. Crie um UUID para cada objeto e use o mesmo UUID em todas as chamadas seguintes: é ele que liga o objeto da DeliveryVip ao registro do seu sistema.

## Por onde seguir

> [card] [Detalhes](/docs/guides/merchant/catalog-and-services/details.md)
>
> O que o `GET` da loja devolve, campo a campo.

> [card] [Ações](/docs/guides/merchant/catalog-and-services/actions.md)
>
> Qual rota usar, regras comuns e erros.


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