> ## 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. # Merchant API > Conheça os módulos da Merchant API e escolha por onde começar a integrar o seu PDV ou ERP. A Merchant API conecta o seu sistema (PDV, ERP, KDS, gestor de entregas) às lojas que instalaram o seu app na DeliveryVip. Com ela você recebe pedidos, atualiza o status, mantém o catálogo sincronizado e opera comandas, descontos e fidelidade. > [!NOTE] > > Seu PDV já implementa o padrão Open Delivery para outras plataformas? Veja o [Open Delivery](/docs/guides/open-delivery.md). Vai gerenciar lojas, assinaturas e faturas de uma rede? Esse é o papel da [Partner API](/docs/guides/partner.md). ## Para quem é | Seu sistema | O que você usa | | - | - | | PDV ou ERP que recebe pedidos | [Pedidos](/docs/guides/merchant/order.md) e [webhooks](/docs/guides/merchant/webhooks.md) ou [polling](/docs/guides/merchant/events.md). | | Sistema que é a fonte do cardápio | [Catálogo](/docs/guides/merchant/catalog-and-services.md). | | PDV de salão, com mesas e comandas | [Indoor](/docs/guides/merchant/indoor.md) e os pedidos `INDOOR`. | | Ferramenta de marketing ou CRM | [Descontos](/docs/guides/merchant/discount.md) e [Fidelidade](/docs/guides/merchant/loyalty.md). | ## Base URL e autenticação Todas as rotas exigem um token OAuth2 no header `Authorization`, com o scope `od.all` (as rotas de configuração de fidelidade pedem `dv.loyalty`). Veja [Autenticação](/docs/inicio/conceitos/autenticacao.md). | | | | - | - | | **Base URL** | `https://api.deliveryvip.com.br/merchant/v3` | | **Token** | `POST /authentication/v1/oauth/token` com `grant_type=client_credentials` e `scope=od.all`. Vale 24 horas e não tem `refresh_token`. | | **Alcance** | Um token atende todas as lojas que instalaram o seu app. As rotas por loja levam o `merchantId` no caminho: `/merchant/v3/{merchantId}/...`. | | **Formato** | JSON com chaves em camelCase. Datas em RFC 3339 com offset UTC-3; veja [Datas e horários](/docs/inicio/conceitos/datas-e-horarios.md). | ## Comece aqui **1. Crie o app e instale numa loja de teste** Siga a [Jornada do Developer](/docs/inicio/primeiros-passos/jornada-do-developer.md): conta, app com a permissão **Merchant API** e a loja de teste, pedida no [Discord](https://discord.gg/AJF8Yha4). **2. Receba o seu primeiro pedido** O tutorial [Receba seu primeiro pedido](/docs/guides/merchant/order/fluxo-de-integracao/recepcao-de-pedidos.md) vai do token ao pedido confirmado, com um script pronto em Node.js e Python. **3. Prepare para produção** Escolha o canal de eventos abaixo, complete o ciclo do pedido com as [ações](/docs/guides/merchant/order/fluxo-de-integracao/acoes-de-pedidos.md) e confira o checklist em [Testes e produção](/docs/inicio/testes-e-producao.md). ## Como os eventos chegam Tudo o que muda numa loja vira um evento. Você escolhe como recebê-los, e pode usar os dois canais juntos. > [card] [Webhooks](/docs/guides/merchant/webhooks.md) > > A DeliveryVip envia cada evento para a sua URL no momento em que ele acontece. **Recomendado** como canal principal. > [card] [Polling de eventos](/docs/guides/merchant/events.md) > > Você consulta a fila a cada 30 segundos e confirma o que processou. Ideal como reconciliação. | | Webhook | Polling | | - | - | - | | **Quem inicia** | A DeliveryVip faz um `POST` na sua URL. | O seu sistema chama `GET /merchant/v3/events:polling`. | | **Atraso** | Na hora. | Até 30 segundos. | | **Precisa de** | Uma URL pública que responda `2xx` rápido e valide a assinatura. | Só o token. Funciona atrás de firewall. | | **Confirmação** | A resposta `2xx`. Sem acknowledgment. | Acknowledgment obrigatório de todo evento recebido. | | **Se o seu sistema cair** | Falhas acumulam; 10 seguidas suspendem o envio. | Os eventos esperam na fila por até 24 horas. | > [!TIP] > > Os dois canais são independentes: um evento entregue por webhook continua no polling. O arranjo mais robusto é o **webhook como canal principal** e o **polling como reconciliação**. Se o seu sistema não pode receber chamadas da internet, use só o polling. ## Módulos > [card] [Pedidos](/docs/guides/merchant/order.md) > > Receba, confirme, prepare, despache e cancele pedidos de delivery, retirada e consumo no local. > [card] [Catálogo](/docs/guides/merchant/catalog-and-services.md) > > Consulte e sincronize categorias, produtos, opções e serviços de delivery e retirada. > [card] [Indoor](/docs/guides/merchant/indoor.md) > > Gerencie comandas e mesas do autoatendimento e responda a chamadas de garçom e pedidos de conta. > [card] [Descontos](/docs/guides/merchant/discount.md) > > Crie cupons e descontos automáticos e acompanhe o desempenho de cada um. > [card] [Ferramentas](/docs/guides/merchant/tools.md) > > Calcule a taxa de entrega para um endereço e consulte se a loja está aberta. > [card] [Fidelidade](/docs/guides/merchant/loyalty.md) > > Conecte o seu programa de cashback ao checkout: adesão, resgate e acúmulo. > [!NOTE] > > Indoor e Descontos estão em **beta** e ainda podem mudar. Acompanhe o [changelog](/docs/changelog.md). ## Erros comuns Os erros seguem o formato `{"status": "422", "title": "..."}`. Veja [Erros](/docs/inicio/conceitos/erros.md). | Status | Quando | O que fazer | | - | - | - | | `401 Unauthorized` | Token ausente, expirado (24 h) ou revogado. | Peça um token novo com as mesmas credenciais e repita a chamada uma vez. | | `403 Forbidden` | Token sem o scope da rota, filtro inválido no polling ou loja sem acesso em `x-polling-merchants`. | Confira o scope e os filtros; tire do header as lojas listadas no erro. | | `404 Not Found` | O recurso não existe, a loja não instalou o seu app, ou o pedido ainda aguarda a aprovação do pagamento online. | Confira o `merchantId` e se a instalação foi concluída. | | `422 Unprocessable Content` | Dados inválidos, ou ação que o estado do pedido não aceita (por exemplo, despachar um pedido cancelado). | Leia o `title` e siga o [ciclo de vida](/docs/guides/merchant/order/definicoes.md#ciclo-de-vida-do-pedido). | | `429 Too Many Requests` | Mais de 150 requisições em 10 segundos, ou polling mais de uma vez a cada 30 segundos. | Espere e repita com backoff. Veja [Rate limiting](/docs/inicio/conceitos/rate-limiting.md). | ## Próximos passos > [card] [Receba seu primeiro pedido](/docs/guides/merchant/order/fluxo-de-integracao/recepcao-de-pedidos.md) > > Do token ao pedido confirmado, com código pronto para rodar. > [card] [Testes e produção](/docs/inicio/testes-e-producao.md) > > Loja de teste, checklist de integração e o que muda ao liberar o app. > [card] [Referência](/docs/reference/merchant/v3.md) > > Todos os endpoints da Merchant API V3. > [card] [Conceitos](/docs/inicio/conceitos.md) > > Erros, paginação, datas, rate limiting e Postman. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.