> ## 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. # Partner API > Gerencie lojas, revendas, assinaturas, planos e faturas da sua rede na DeliveryVip. A Partner API é para quem administra uma rede de lojas na DeliveryVip: **parceiros** (white label) e as **revendas** deles. Com ela você cadastra lojas, controla assinaturas e recursos contratados, gerencia quem acessa cada painel e consulta vendas e faturas, tudo a partir do seu próprio sistema. > [!NOTE] > > Vai integrar um PDV para receber pedidos de uma loja? Esse é o papel da [Merchant API](/docs/guides/merchant.md). A Partner API cuida da gestão comercial da rede, não da operação de pedidos. ## Hierarquia Toda loja (merchant) pertence a um parceiro. Ela pode ser atendida **diretamente** pelo parceiro ou por uma **revenda** dele. A revenda também tem assinatura própria e só existe abaixo de um parceiro. ![O parceiro tem revendas e lojas atendidas direto; cada revenda tem as próprias lojas](https://mintcdn.com/deliveryvip-a4256422/ELxpcniK2_BP8zxT/images/partner-hierarquia.png?fit=max\&auto=format\&n=ELxpcniK2_BP8zxT\&q=85\&s=fa40a7dc506df685d3b474dd4d0b2a57) A hierarquia de parceiro, revendas e lojas O token alcança tudo o que está abaixo de quem autorizou o seu app: | Quem autorizou o app | Lojas | Revendas | Planos | Faturas | | - | - | - | - | - | | **Parceiro** | Todas: diretas e das revendas | Lista, cria e gerencia | Todos os planos com visibilidade `PUBLIC`, `RESALE` ou `DIRECT_MERCHANT` | Todas, com preços do parceiro | | **Revenda** | Só as lojas da revenda | Não acessa | Planos do parceiro com visibilidade `PUBLIC` ou `RESALE` | Só as das suas lojas | ## Autenticação A Partner API usa OAuth2 com o scope **`dv.partner`**. O parceiro ou a revenda autoriza o seu app pelo token de autorização (veja [distribuição direta](/docs/inicio/primeiros-passos/distribuicao-direta.md)) e você troca as credenciais por um token de acesso: ```bash theme={null} curl 'https://api.deliveryvip.com.br/authentication/v1/oauth/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'client_id={clientId}' \ --data-urlencode 'client_secret={clientSecret}' \ --data-urlencode 'scope=dv.partner' ``` Envie o token em todas as chamadas, no header `Authorization: Bearer {token}`. Todas as rotas ficam em `https://api.deliveryvip.com.br/partner/v2`. Detalhes de expiração e renovação em [Autenticação](/docs/inicio/conceitos/autenticacao.md). > [!WARNING] > > Um mesmo token pode representar mais de um parceiro ou revenda, se todos autorizaram o seu app. Nas listagens, use o header `x-partners` para receber dados de um só. Veja [Filtrar por Partners](/docs/guides/partner/merchant/utilizando-a-api/listar-merchants.md#filtrar-por-partners). ## Primeira chamada: liste suas lojas **1. Gere o token** Use o `client_credentials` acima com o scope `dv.partner`. **2. Liste as lojas** Chame `GET /partner/v2/merchants`. A resposta traz até as lojas das suas revendas. ```bash cURL theme={null} curl 'https://api.deliveryvip.com.br/partner/v2/merchants' \ --header 'Authorization: Bearer {token}' ``` ```js Node.js theme={null} const response = await fetch('https://api.deliveryvip.com.br/partner/v2/merchants', { headers: { Authorization: `Bearer ${token}` }, }) const merchants = response.status === 204 ? [] : await response.json() ``` ```python Python theme={null} response = requests.get( "https://api.deliveryvip.com.br/partner/v2/merchants", headers={"Authorization": f"Bearer {token}"}, ) merchants = [] if response.status_code == 204 else response.json() ``` **3. Guarde o seu partnerId** Cada loja traz `partnerId` (o parceiro) e, quando for de revenda, `resaleId`. As rotas de cadastro, planos e faturas usam esse ID no caminho: `/partner/v2/{partnerId}/...`. > [!TIP] > > `200 OK` com a lista de lojas, da mais recente para a mais antiga. `204 No Content` quer dizer que o token ainda não alcança nenhuma loja. ## O que você pode fazer > [card] [Lojas](/docs/guides/partner/merchant.md) > > Cadastre lojas, gerencie assinatura, recursos, membros e apps autorizados. Consulte vendas. > [card] [Revendas](/docs/guides/partner/resale.md) > > Cadastre revendas e gerencie assinatura, membros e apps autorizados. > [card] [Planos](/docs/guides/partner/plans.md) > > Consulte os planos de cobrança que você usa nas assinaturas das lojas. > [card] [Faturas](/docs/guides/partner/invoices.md) > > Consulte o fechamento mensal de cada loja e o resumo por revenda. > [card] [Cadastro](/docs/guides/partner/signup.md) > > Cadastre loja e proprietário a partir de uma landing page pública. > [card] [Referência](/docs/reference/partner/v2.md) > > Todos os endpoints da Partner API V2. ## Erros comuns Os erros seguem o formato `{"status": "422", "title": "..."}`. Veja [Erros](/docs/inicio/conceitos/erros.md). | Status | Quando | | - | - | | `401 Unauthorized` | Token ausente, expirado ou revogado. | | `403 Forbidden` | Token sem o scope `dv.partner`, `x-partners` ou `partnerId` fora do alcance do token, ou filtro de assinatura inválido. | | `404 Not Found` | A loja, revenda, membro ou plano não existe ou não está abaixo de quem autorizou o app. | | `422 Unprocessable Content` | Dados inválidos ou transição de assinatura não permitida. | > [!NOTE] > > A Partner API V1 foi descontinuada e suas rotas foram removidas. Use apenas a V2. Veja [Deprecações](/docs/deprecations.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.