> ## 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. # Changelog > As principais alterações nas APIs da DeliveryVip, da mais recente para a mais antiga. Novidades, mudanças de comportamento e breaking changes nas APIs. Use os filtros por produto para ver só o que afeta a sua integração. Rotas em descontinuação ficam em [Deprecations](/docs/deprecations.md). **22/10/2026** Faturas com valor proporcional e novos tipos de item * **Invoices:** os blocos de preço das faturas (`totalPrice[]` com `type`, `value` e `currency`) agora trazem também `usageTimeValue`, o valor **proporcional ao tempo em que a assinatura da loja ficou ativa** no mês. O `value` continua sendo o valor do mês cheio. Vale para `GET /partner/v2/{partnerId}/invoices`, `GET /partner/v2/{partnerId}/merchants/invoices` e `GET /partner/v2/{partnerId}/resales/invoices` (no resumo, nos itens e nos planos). [Saiba mais](/docs/guides/partner/invoices/definicoes.md) * **Invoices:** os itens de `GET /partner/v2/merchants/invoices` e `GET /partner/v2/resales/invoices` passam a trazer o valor em reais: `totalPrice` (mês cheio) e `totalUsageTimePrice` (proporcional ao `usageTime`). Os dois campos só são enviados quando o token representa o parceiro dono da fatura; para token de revenda eles não aparecem, assim como o `tieredPricingRanges` do `metadata`. [Saiba mais](/docs/guides/partner/merchant/utilizando-a-api/listar-faturas-dos-merchants.md) * **Invoices:** novos tipos de item nas faturas: `GROWTH_DISCOUNT` (descontos), `INTEGRATION_MARKETING` (integrações de marketing) e `INTEGRATION_LOGISTIC` (integrações de logística). [Saiba mais](/docs/guides/partner/invoices/definicoes.md) * **Resales:** `POST /partner/v2/resales/{resaleId}/activate`, `PUT /partner/v2/resales/{resaleId}/subscription` e `PUT /partner/v2/resales/{resaleId}/agreementCode` passam a ignorar o `planId`, já que a assinatura de uma revenda não tem plano. Antes, enviar `planId` resultava em erro `500`. [Saiba mais](/docs/guides/partner/resale/utilizando-a-api/gerenciar-assinatura-das-revendas.md) > [!WARNING] > > **Breaking change, Invoices:** em `GET /partner/v2/{partnerId}/resales/invoices`, o bloco `RECEIVABLE` passa a ser enviado só quando a tabela de preços de recebíveis está habilitada para o parceiro, como já acontecia em `GET /partner/v2/{partnerId}/invoices`. Sem ela, os arrays `totalPrice` do resumo, de cada plano e de cada item trazem apenas o bloco `PAYABLE`. Integrações que leem `totalPrice[1]` ou assumem dois blocos devem passar a procurar pelo campo `type`. Além disso, o resumo passa a considerar só as faturas de lojas vinculadas a revendas: um parceiro sem revendas, que antes recebia um grupo com `resaleId: null` com as lojas diretas, agora recebe `204 No Content`. [Saiba mais](/docs/guides/partner/invoices/utilizando-a-api/listando-resales-invoices.md) **15/10/2026** Imagem nas opções e image.url só com https * **Catálogo:** as opções (`options`) agora retornam a imagem no `GET /merchant/v3/{merchantId}`, no mesmo formato dos produtos (`image.url` e `image.checksum`). O campo só é enviado quando a opção possui imagem cadastrada. O envio de imagem para opções via `merchantUpdate`, `merchantUpsert` e `merchantForce` (`entityType: "OPTION"`) também passa a estar documentado. [Saiba mais](/docs/guides/merchant/catalog-and-services/details.md) > [!WARNING] > > **Breaking change, Catálogo:** o campo `image.url` de produtos (`ITEM`) e opções (`OPTION`) agora aceita **apenas URLs `https://`** no `merchantUpdate`, no `merchantUpsert` e no `merchantForce`. Até então, URLs `http://` também eram aceitas; agora a requisição é rejeitada com `422 Unprocessable Content`. Integrações que enviam imagens via `http://` devem migrar para `https://`. [Saiba mais](/docs/guides/merchant/catalog-and-services/actions/update.md) **24/09/2026** Limites comerciais de resgate na fidelidade * **Fidelidade:** o programa agora pode declarar **limites comerciais de resgate** por pedido em `capabilities.redemptionLimits` (`min` e `max`, cada um `fixed` em BRL ou `percent`). Omitir o objeto, ou um dos limites, significa **sem limite ali**: programas existentes seguem permitindo 100%. O teto estrutural continua valendo sempre, e percentuais incidem sobre os **itens** do pedido, nunca sobre o total (frete e taxas não são resgatáveis). [Saiba mais](/docs/guides/merchant/loyalty/ativando-o-programa.md#limites-de-resgate-redemptionlimits) * **Fidelidade:** a resposta de saldo (`GET /v1/loyalty/accounts/{accountId}`) passa a aceitar o mesmo objeto `redemptionLimits`, opcional, para operadores cujas regras variam por cliente. Quando presente, ele **substitui integralmente** os limites do programa para aquele cliente: não é merge campo a campo. [Saiba mais](/docs/guides/merchant/loyalty/contrato-do-operador/vinculo-e-pin.md#limites-por-conta) **23/09/2026** Open Delivery multi-loja e merchantStatus * **Open Delivery:** um mesmo app agora atende **várias lojas**. Declarando a extensão **Open Delivery**, cada loja que instala o app recebe um `client_secret` próprio (formato `ods_...`, o `client_id` continua sendo o do app) e o token emitido com ele vale só para aquela loja. A configuração (`merchantId`, URL de webhook e endpoint de catálogo) passa a ser **por loja**, assim como o circuito de webhooks: uma loja com endpoint fora do ar não interrompe as entregas das demais. [Saiba mais](/docs/guides/open-delivery/primeiros-passos.md) * **Open Delivery:** novo endpoint `GET /v1/merchantStatus?merchantId={id}` para acompanhar o processamento assíncrono disparado pelo `merchantUpdate`. Retorna `lastRead`, `status` (`SUCCESS`, `PROCESSING` ou `FAIL`) e `moreInfo` com o detalhe da falha. [Saiba mais](/docs/guides/open-delivery/catalogo.md#acompanhando-o-processamento-merchantstatus) **11/09/2026** Tipos individuais no menu dos produtos * **Catálogo:** o campo `menu` dos produtos agora usa os tipos individuais `DELIVERY`, `TAKEOUT` e `INDOOR`. O valor agregado `DELIVERY_TAKEOUT` continua **aceito no envio** por retrocompatibilidade (expandido automaticamente para `DELIVERY` + `TAKEOUT`) e ainda é **devolvido nas respostas** quando o produto tem entrega e retirada. Prefira os tipos individuais em novas integrações. [Saiba mais](/docs/guides/merchant/catalog-and-services/details.md) **10/09/2026** Extensão de fidelidade * **Fidelidade:** nova extensão de **fidelidade** para apps que operam programas de cashback: o cliente adere ao programa no checkout (com consentimento e PIN opcional), resgata saldo como desconto e acumula sobre pedidos concluídos. O app declara a extensão com uma `api_base_url`, ativa o programa por lojista via `PUT /merchant/v3/{merchantId}/loyalty/config` e implementa o contrato HTTP do operador (spec [loyalty\_operator.yaml](https://app.deliveryvip.com.br/swaggers/loyalty_operator.yaml)). Requer o novo scope `dv.loyalty` além do `od.all`. [Saiba mais](/docs/guides/merchant/loyalty.md) * **Order:** o pedido agora pode trazer o bloco `loyalty` (visível apenas para o app cujo programa o cliente aderiu), com `accountId`, `programId` e o `redemption` do pedido (`status` `CONFIRMED`/`REVERSED`). [Saiba mais](/docs/guides/merchant/loyalty/acumulo.md) **18/08/2026** Signup público na Partner API * **Signup:** novo endpoint público `POST /partner/v2/{partnerId}/signup` na API Partner para cadastrar lojas e contas de proprietários a partir de uma landing page. A resposta é a mesma para e-mail novo ou já cadastrado (proteção contra enumeração de usuários): a presença do campo `entryUrl` indica se a conta foi criada. [Saiba mais](/docs/guides/partner/signup.md) **10/08/2026** Datas em UTC no Open Delivery e filtros de polling * **Open Delivery:** as datas da API Open Delivery agora são serializadas em **UTC** (RFC 3339, sufixo `Z`, ex.: `2026-08-10T17:39:28Z`), conforme exigido pela spec OD. A API Merchant V3 segue usando UTC-3. [Saiba mais](/docs/inicio/conceitos/datas-e-horarios.md) * **Events:** os filtros `eventType` e `orderType` dos endpoints de polling (`GET /merchant/v3/events:polling` e `GET /v1/events:polling` do Open Delivery) seguem a serialização de arrays da spec OpenAPI (`style: form`, `explode: true`): repita o parâmetro na query, sem colchetes, ex.: `?eventType=CREATED&eventType=CANCELLED`. Valores inválidos retornam `403 Forbidden`. [Saiba mais](/docs/guides/merchant/order/fluxo-de-integracao/consultar-novos-pedidos.md#filtros) **07/08/2026** Polling limitado a 100 eventos * **Events:** o endpoint `GET /merchant/v3/events:polling` agora retorna no máximo **100 eventos por chamada**, sempre do mais antigo para o mais recente. Se a resposta vier com 100 eventos, envie o acknowledgment e chame o polling novamente em seguida, sem aguardar o intervalo usual, até receber menos de 100 eventos (ou `204 No Content`). Integrações que precisam de eventos em tempo real devem considerar os [webhooks](/docs/guides/merchant/webhooks.md) como canal principal. [Saiba mais](/docs/guides/merchant/order/fluxo-de-integracao/consultar-novos-pedidos.md#a-fila-de-eventos) **30/06/2026** Webhooks e novo prazo das deprecations * **Webhooks:** agora a API Merchant pode enviar os eventos de pedido e de indoor em tempo real para uma URL sua, como complemento ao polling. Configure a URL de notificação no painel e valide a assinatura `X-App-Signature`. [Saiba mais](/docs/guides/merchant/webhooks.md) * **Deprecations:** o prazo de descontinuação das rotas em deprecação (Merchant v1/v2, Tabs `available`/`unavailable` e Invoices/Agreement Code da Partner v2) foi adiado para **01/08/2026**. As rotas da Partner v1 já foram removidas e retornam `410 Gone`. [Saiba mais](/docs/deprecations.md) **16/05/2025** Modos de Mesa e Comanda * **Places:** com os novos modos de Mesa e Comanda, agora é possível abrir ou fechar uma mesa para consumo. [Saiba mais](/docs/guides/merchant/indoor/places-api.md) * **Order:** novos atributos no objeto `indoor` do pedido para suportar os modos de Mesa e Comanda. [Saiba mais](/docs/guides/merchant/order/fluxo-de-integracao/obter-detalhes-do-pedido.md) * **Event:** novos atributos nos eventos para suportar os modos de Mesa e Comanda. [Saiba mais](/docs/guides/merchant/indoor/fluxo-de-integracao/eventos-de-indoor.md) * **Deprecations:** as rotas `available` e `unavailable` das comandas entram em descontinuação. [Saiba mais](/docs/deprecations.md) **22/04/2025** Novo sistema de cobrança * **Plans:** implementamos um **novo sistema de cobrança**: toda assinatura agora deve estar vinculada a um **plano de cobrança** específico. [Saiba mais](/docs/guides/partner/plans.md) * **Invoices:** com a mudança no modelo de cobrança, o módulo de **Invoices** foi reestruturado. Agora é possível listar as faturas de cada merchant para verificar o plano associado, o consumo de recursos e os valores calculados pela nova tabela de preços. [Saiba mais](/docs/guides/partner/invoices.md) * **Deprecations:** para acomodar o novo sistema de cobrança, algumas rotas e versões de API serão descontinuadas. Consulte [Deprecations](/docs/deprecations.md) para a lista completa e os prazos de remoção. **20/02/2025** Catálogo: MODIFIER dentro de ITEM e métodos de pagamento * **Catalog & Services:** no `merchantUpdate` e no `merchantUpsert`, o `entityType` `MODIFIER` foi removido. Ele agora fica dentro de `ITEM`, que deve ser usado para manter o modifier atualizado. * **Catalog & Services:** agora é possível adicionar os métodos de pagamento pela API. **21/01/2025** Campo salesChannel nos pedidos * **SalesChannel:** novo campo `salesChannel` nos pedidos. [Saiba mais](/docs/guides/merchant/order/fluxo-de-integracao/obter-detalhes-do-pedido.md) **05/08/2024** Endpoints de descontos * **Descontos:** novos endpoints para adicionar, atualizar e remover descontos de um merchant na API Merchant. [Saiba mais](/docs/guides/merchant/discount.md) **29/07/2024** Listagem de pedidos * **Listar pedidos:** novo endpoint para listar os pedidos de um merchant na API Merchant. [Saiba mais](/docs/guides/merchant/order/listar-pedidos.md) **28/06/2024** Faturas de merchants e revendas * **Faturas dos merchants:** novo endpoint para listar as faturas do ano e mês dos merchants na API Partner. [Saiba mais](/docs/guides/partner/merchant/utilizando-a-api/listar-faturas-dos-merchants.md) * **Faturas das revendas:** novo endpoint para listar as faturas do ano e mês das revendas na API Partner. [Saiba mais](/docs/guides/partner/resale/utilizando-a-api/listar-faturas-das-revendas.md) **02/04/2024** Indoor no pedido, merchantId nos eventos, revendas e recursos * **Order:** `placeName` e `tabId` adicionados quando o pedido é do tipo `INDOOR`. [Saiba mais](/docs/guides/merchant/order/fluxo-de-integracao/obter-detalhes-do-pedido.md#entrega-retirada-e-indoor) * **Order events:** `merchantId` adicionado aos eventos. [Saiba mais](/docs/guides/merchant/order/fluxo-de-integracao/eventos-de-pedidos.md#estrutura-do-evento) * **Indoor events:** `merchantId`, `tabId`, `tabCode` e `tabName` adicionados. [Saiba mais](/docs/guides/merchant/indoor/fluxo-de-integracao/eventos-de-indoor.md) * **Assinatura:** nova rota para avisar um merchant sobre um possível bloqueio. [Saiba mais](/docs/guides/partner/merchant/utilizando-a-api/gerenciar-assinatura-dos-merchants.md#ativar-aviso) * **Revenda:** nova API para gerenciar as revendas. [Saiba mais](/docs/guides/partner/resale.md) * **Recursos:** nova API para gerenciar os recursos dos merchants. [Saiba mais](/docs/guides/partner/merchant/utilizando-a-api/gerenciar-recursos-dos-merchants.md) **10/10/2023** Entidade MODIFIER no catálogo * **Catalog & Services:** entidade `MODIFIER` adicionada ao `merchantUpdate` e ao `merchantUpsert`. [Saiba mais](/docs/guides/merchant/catalog-and-services.md) **04/10/2023** API de catálogo e novos filtros * **Catalog & Services:** agora é possível atualizar, inserir e administrar o catálogo de um merchant pela API. [Saiba mais](/docs/guides/merchant/catalog-and-services.md) * **Order events:** o polling de eventos passa a aceitar o filtro `orderType`. [Saiba mais](/docs/guides/merchant/order/fluxo-de-integracao/consultar-novos-pedidos.md#filtros) * **Listar merchants:** a lista de merchants passa a aceitar o filtro por `identifier`. [Saiba mais](/docs/guides/partner/merchant/utilizando-a-api/listar-merchants.md#filtros) **01/08/2023** Tracking de pedidos * **Order API:** agora é possível fazer o tracking de um pedido. [Saiba mais](/docs/guides/merchant/order/fluxo-de-integracao/acoes-de-pedidos.md#tracking) **25/07/2023** Permissão de aplicativos por merchant * **Partner API:** agora é possível adicionar ou remover a permissão de uma aplicação para um merchant. [Saiba mais](/docs/guides/partner/merchant/utilizando-a-api/gerenciar-permissao-de-aplicativos-dos-merchants.md) **02/03/2023** Taxa de entrega por coordenada * **Merchant Tools:** agora é possível saber a taxa de entrega a partir de uma latitude e longitude. [Saiba mais](/docs/guides/merchant/tools.md) **23/02/2023** Pedidos e comandas indoor * **Merchant Indoor:** agora é possível receber pedidos e cadastrar comandas do tipo indoor. [Saiba mais](/docs/guides/merchant/indoor.md) **26/12/2022** MagicLink, membros e cadastro de merchants * **MagicLink:** agora é possível logar um membro sem senha. [Saiba mais](/docs/guides/partner/merchant/utilizando-a-api/membros-do-merchant.md#magiclink) * **Membros:** agora é possível listar, adicionar, atualizar e remover membros de um merchant. [Saiba mais](/docs/guides/partner/merchant/utilizando-a-api/membros-do-merchant.md) * **Cadastrar merchant:** agora é possível adicionar um merchant a um partner. [Saiba mais](/docs/guides/partner/merchant/utilizando-a-api/adicionar-um-merchant.md) * **Novo filtro:** ao listar merchants ou vendas, agora é possível filtrar só os merchants dos partners desejados. [Saiba mais](/docs/guides/partner/merchant/utilizando-a-api/listar-merchants.md#filtrar-por-partners) **21/12/2022** Ação delivered * **Nova order action:** nova ação `delivered` na API de pedidos. [Saiba mais](/docs/guides/merchant/order/fluxo-de-integracao/acoes-de-pedidos.md#pedido-entregue) **31/10/2022** Partner API V2 * **Partner API V2:** com ela é possível controlar as assinaturas dos merchants e acompanhar o faturamento delas. [Saiba mais](/docs/guides/partner.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.