> ## 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. # Listar pedidos > Lista os pedidos da loja, do mais recente para o mais antigo, com paginação por cursor. Quando há mais páginas, a resposta traz os cabeçalhos `X-Next-Cursor`/`X-Previous-Cursor` e `Link` (`rel="next"` e `rel="prev"`). ## OpenAPI ````yaml https://app.deliveryvip.com.br/swaggers/merchant.yaml get /merchant/v3/{merchantId}/orders openapi: 3.0.3 info: version: v3 title: API Merchant da DeliveryVip description: >- A API Merchant permite que integrações (PDVs, ERPs, operadores de fidelidade e afins) interajam com as lojas da plataforma: consumir eventos de pedidos, consultar detalhes e executar ações sobre pedidos, além de gerenciar cardápio, cupons, comandas, mesas e o programa de fidelidade. Todos os endpoints exigem autenticação com um token de acesso Bearer emitido pela API de autenticação, com o escopo `od.all` (as rotas de fidelidade exigem `dv.loyalty`). **Erros.** As respostas de erro têm o corpo `{"status": "", "title": ""}`. A exceção é o `401`, gerado na validação do token, cujo corpo é `{"title": "Unauthorized", "status": 401}` (status numérico). Um `403` por escopo insuficiente vem sem corpo. servers: - url: https://api.deliveryvip.com.br description: Produção security: - bearerAuth: [] tags: - name: Events description: >- Mudanças de estado e outras notificações relacionadas aos pedidos e ao salão (mesas e comandas) das lojas. - name: Orders description: 'Pedidos das lojas: consulta e ações de ciclo de vida.' - name: Discounts description: >- Cupons e descontos inteligentes da loja. Exige o recurso de descontos (`growth_discount`) contratado pela loja. - name: Tabs description: Comandas do salão da loja. - name: Places description: Mesas (QR Codes e tablets) do salão da loja. - name: Utils description: Endpoints utilitários. - name: Merchants description: Dados cadastrais, catálogo e status de funcionamento da loja. - name: Loyalty description: >- Configuração do programa de fidelidade enviada pelo operador de fidelidade (aplicativos que declaram a extensão de fidelidade; exige o escopo `dv.loyalty`). Observação sobre escopos: os endpoints de configuração abaixo exigem `dv.loyalty`, mas a leitura de pedidos — que é como o operador faz o acúmulo, já que o bloco `loyalty` fica no pedido — exige o escopo comum `od.all`. Uma integração de operador de fidelidade, portanto, solicita um token com os dois escopos (`scope=od.all dv.loyalty`). - name: Webhooks description: >- Eventos enviados ativamente ao aplicativo, em vez de consultados por polling. Um aplicativo com URL de webhook configurada recebe cada evento como um POST cujo corpo é um único objeto de evento — o mesmo schema retornado pelo endpoint de polling. O evento não traz o bloco `loyalty`: ele fica no pedido, que deve ser consultado em `orderURL`. Eventos entregues dessa forma não precisam ser confirmados (acknowledgment). **Verificação de assinatura (obrigatória).** Todo envio traz estes cabeçalhos: - `X-App-Signature` — HMAC-SHA256 em hexadecimal do **corpo bruto da requisição**, usando como chave o client secret do aplicativo. Calcule o digest sobre os bytes exatamente como recebidos, antes de qualquer parse ou re-serialização do JSON: fazer o parse e codificar de novo altera os bytes e o digest não vai bater. Compare usando comparação em tempo constante. Para um aplicativo que usa a extensão OpenDelivery, a chave é o **client secret da própria loja** (a credencial por loja, `ods_...`) sempre que a loja tiver uma; o client secret do aplicativo só é usado para lojas sem credencial própria. A renovação de um secret vale imediatamente: toda entrega enviada depois disso, inclusive novas tentativas e reenvios manuais, é assinada com o novo secret. - `X-App-Id` — identifica a plataforma como remetente. - `X-App-MerchantId` — a loja à qual o evento pertence: o `orderingAppMerchantId` do próprio aplicativo para aquela loja, quando configurado; caso contrário, o id da loja na plataforma. Rejeite qualquer requisição cuja assinatura não confira. A assinatura é a única prova de que o envio veio da plataforma, e um endpoint sem verificação permite que qualquer pessoa forje eventos de pedido. A assinatura cobre apenas o corpo e não carrega timestamp, então deduplique por `eventId`: uma nova tentativa, um reenvio manual ou uma requisição repetida trazem o mesmo `eventId`. **Entrega e novas tentativas.** Qualquer 2xx é sucesso. `408` e `429` são tratados como "tente mais tarde" e a entrega é repetida até 3 tentativas no total; qualquer outro status fora de 2xx — **inclusive 5xx** — é tratado como recusa definitiva e não é repetido automaticamente, ficando a entrega disponível para reenvio manual. Dez entregas consecutivas com falha suspendem os webhooks do aplicativo até que sejam reativados; uma entrega bem-sucedida zera essa contagem. Responda 2xx assim que o evento estiver armazenado de forma durável e faça o processamento de forma assíncrona: a plataforma usa timeouts curtos (3s para conectar, 5s para leitura) e um endpoint lento é registrado como falha. paths: /merchant/v3/{merchantId}/orders: get: tags: - Orders summary: Listar pedidos description: >- Lista os pedidos da loja, do mais recente para o mais antigo, com paginação por cursor. Quando há mais páginas, a resposta traz os cabeçalhos `X-Next-Cursor`/`X-Previous-Cursor` e `Link` (`rel="next"` e `rel="prev"`). parameters: - $ref: '#/components/parameters/merchantId' - in: query name: orderType[] description: Filtra pelo tipo do pedido. schema: type: array items: type: string enum: - DELIVERY - TAKEOUT - INDOOR - DINE_IN - in: query name: starts_at description: >- Data inicial (inclusive). Se informada sem `ends_in`, vai até o fim do dia atual. schema: type: string format: date - in: query name: ends_in description: Data final (inclusive). Exige `starts_at`. schema: type: string format: date - $ref: '#/components/parameters/views' - $ref: '#/components/parameters/perPage' - $ref: '#/components/parameters/next' - $ref: '#/components/parameters/previous' responses: '200': description: Página de pedidos. headers: X-Next-Cursor: $ref: '#/components/headers/X-Next-Cursor' X-Previous-Cursor: $ref: '#/components/headers/X-Previous-Cursor' Link: $ref: '#/components/headers/Link' content: application/json: schema: type: array items: $ref: '#/components/schemas/order' '204': description: Nenhum pedido encontrado. '400': $ref: '#/components/responses/BadRequestCursor' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '406': $ref: '#/components/responses/NotAcceptable' components: parameters: merchantId: in: path name: merchantId description: >- Id (UUID) da loja na plataforma. A loja precisa estar autorizada para o aplicativo. required: true schema: type: string format: uuid views: in: query name: views[] description: >- Formato dos complementos dos itens. Por padrão, os complementos vêm achatados em `items[].options`. Com `optionGroups`, vêm agrupados em `items[].optionGroups`. `groupOptions` é o nome antigo do agrupamento (gera `items[].optionsGroup`) e está descontinuado. schema: type: array items: type: string enum: - optionGroups - groupOptions perPage: in: query name: per_page description: >- Itens por página. Padrão 30; valores informados são limitados entre 30 e 250. schema: type: integer minimum: 30 maximum: 250 default: 30 next: in: query name: next description: >- Cursor da próxima página (valor de `X-Next-Cursor`). Não pode ser combinado com `previous`. schema: type: string previous: in: query name: previous description: >- Cursor da página anterior (valor de `X-Previous-Cursor`). Não pode ser combinado com `next`. schema: type: string headers: X-Next-Cursor: description: Cursor da próxima página, quando existir. schema: type: string X-Previous-Cursor: description: Cursor da página anterior, quando existir. schema: type: string Link: description: Links de paginação (`rel="next"` e `rel="prev"`), quando existirem. schema: type: string schemas: order: type: object properties: id: type: string format: uuid description: Id do pedido. type: type: string description: >- Tipo do pedido. Pedidos de consumo no local são retornados como `INDOOR`. enum: - DELIVERY - TAKEOUT - INDOOR displayId: type: string description: Código curto do pedido, exibido para a loja e o cliente. salesChannel: type: string description: Canal de venda do pedido. enum: - STORE - MARKETPLACE - TABLET - QRCODE - TAB createdAt: type: string format: date-time description: Data e hora de criação do pedido. orderTiming: type: string description: Pedido imediato ou agendado. enum: - INSTANT - SCHEDULED preparationStartDateTime: type: string format: date-time description: Início previsto do preparo (atualmente igual a `createdAt`). lastEvent: type: string description: >- Último evento do pedido, derivado do seu estado atual. Omitido quando o estado não corresponde a nenhum destes valores. enum: - CREATED - CONFIRMED - READY_FOR_PICKUP - CONCLUDED - CANCELLED merchant: type: object properties: id: type: string description: >- Id da loja: o id que o aplicativo usa para a loja (`orderingAppMerchantId`), quando configurado; caso contrário, o UUID da loja na plataforma. name: type: string items: type: array items: type: object properties: id: type: string format: uuid index: type: integer description: Posição do item no pedido. name: type: string externalCode: type: string description: Código externo do item. Omitido quando vazio. unit: type: string description: Unidade de medida. Sempre `UN`. enum: - UN ean: type: string description: Código EAN. Omitido quando vazio. quantity: type: integer specialInstructions: type: string description: Observação do cliente para o item. Omitida quando vazia. unitPrice: $ref: '#/components/schemas/money' optionsPrice: $ref: '#/components/schemas/money' totalPrice: $ref: '#/components/schemas/money' options: type: array description: >- Complementos escolhidos (formato padrão). Omitido quando o item não tem complementos. items: $ref: '#/components/schemas/orderOption' optionGroups: type: array description: Complementos agrupados (view `optionGroups`). items: $ref: '#/components/schemas/orderOptionGroup' optionsGroup: type: array deprecated: true description: Complementos agrupados (view `groupOptions`, descontinuada). items: $ref: '#/components/schemas/orderOptionGroup' otherFees: type: array description: Taxas do pedido. Presente apenas em pedidos de entrega. items: type: object properties: name: type: string type: type: string enum: - DELIVERY_FEE - SERVICE_FEE - TIP - MIN_ORDER_FEE receivedBy: type: string enum: - MARKETPLACE - MERCHANT - LOGISTIC_SERVICES receiverDocument: type: string price: $ref: '#/components/schemas/money' discounts: type: array description: Descontos aplicados. Omitido quando o pedido não tem desconto. items: type: object properties: amount: $ref: '#/components/schemas/money' target: type: string description: Sobre o que o desconto incide. enum: - CART - DELIVERY_FEE sponsorshipValues: type: array description: Quem financia o desconto. items: type: object properties: name: type: string enum: - MARKETPLACE - MERCHANT amount: $ref: '#/components/schemas/money' discountCode: type: string description: Código ou título do desconto. total: type: object description: Totais do pedido. properties: itemsPrice: $ref: '#/components/schemas/money' otherFees: $ref: '#/components/schemas/money' discount: $ref: '#/components/schemas/money' orderAmount: $ref: '#/components/schemas/money' payments: type: object properties: prepaid: type: number description: Valor já pago online. pending: type: number description: Valor a receber na entrega ou retirada. methods: type: array items: type: object properties: value: type: number currency: type: string enum: - BRL type: type: string description: Momento do pagamento. enum: - PREPAID - PENDING - ONLINE - OFFLINE method: type: string description: Forma de pagamento. enum: - CREDIT - DEBIT - MEAL_VOUCHER - FOOD_VOUCHER - DIGITAL_WALLET - PIX - CASH - CREDIT_DEBIT - COUPON - REDEEM - PREPAID_REDEEM - OTHER brand: type: string description: Bandeira. Omitida quando não se aplica. example: VISA methodInfo: type: string description: >- Informação adicional da forma de pagamento. Omitida quando vazia. changeFor: type: number description: >- Valor para o qual levar troco. Presente apenas quando há troco. loyalty: $ref: '#/components/schemas/loyaltyBlock' customer: type: object description: Cliente. Omitido quando o pedido não tem nome de comprador. properties: id: type: string format: uuid name: type: string documentNumber: type: string description: CPF/CNPJ do cliente. Omitido quando não informado. phone: type: object properties: number: type: string description: Telefone no formato E.164, sem formatação. example: '5511999999999' email: type: string description: E-mail. Omitido para clientes convidados (sem cadastro). ordersCountOnMerchant: type: integer description: Quantidade de pedidos do cliente na loja. schedule: type: object description: Janela do agendamento. Presente apenas em pedidos agendados. properties: scheduledDateTimeStart: type: string format: date-time scheduledDateTimeEnd: type: string format: date-time delivery: type: object description: Dados da entrega. Presente apenas em pedidos de entrega. properties: deliveredBy: type: string enum: - MERCHANT estimatedDeliveryDateTime: type: string format: date-time deliveryAddress: $ref: '#/components/schemas/address' takeout: type: object description: Dados da retirada. Presente apenas em pedidos para retirada. properties: mode: type: string enum: - DEFAULT takeoutDateTime: type: string format: date-time indoor: type: object description: Dados do consumo no local. Presente apenas em pedidos `INDOOR`. properties: mode: type: string description: >- `DEFAULT` para consumo no local sem mesa/comanda, `TAB` para pedidos em comanda e `PLACE` para pedidos em mesa. enum: - DEFAULT - PLACE - TAB indoorDateTime: type: string format: date-time place: type: string placeName: type: string placeId: type: string tab: type: string tabId: type: string format: uuid tabName: type: string tabCode: type: string sendDelivered: type: boolean description: >- A loja é responsável pelo evento DELIVERED (sem operador logístico externo). sendPreparing: type: boolean description: A loja deve enviar o evento PREPARING. sendPickedUp: type: boolean description: A loja é responsável pelo evento PICKED_UP (pedidos para retirada). sendTracking: type: boolean description: A loja deve enviar atualizações de rastreamento. extraInfo: type: string description: Observação geral do pedido. Omitida quando vazia. money: type: object description: Valor monetário. required: - value - currency properties: value: type: number description: Valor, com até 4 casas decimais. example: 39.9 currency: type: string description: Moeda (código ISO 4217). enum: - BRL orderOption: type: object description: Complemento escolhido em um item do pedido. properties: id: type: string format: uuid index: type: integer description: Posição do complemento na lista. name: type: string externalCode: type: string description: Código externo do complemento. Omitido quando vazio. unit: type: string description: Unidade de medida. Sempre `UN`. enum: - UN quantity: type: integer unitPrice: $ref: '#/components/schemas/money' totalPrice: $ref: '#/components/schemas/money' orderOptionGroup: type: object description: >- Grupo de complementos de um item do pedido (views `optionGroups`/`groupOptions`). properties: id: type: string format: uuid name: type: string externalCode: type: string description: Código externo do grupo. Omitido quando vazio. totalPrice: $ref: '#/components/schemas/money' options: type: array items: $ref: '#/components/schemas/orderOption' loyaltyBlock: type: object description: >- Presente no pedido apenas para aplicativos cujo programa de fidelidade o cliente aderiu. Cada aplicativo recebe somente o bloco do seu próprio programa. O bloco identifica o cliente no operador e informa o que foi resgatado neste pedido. Ele não traz nenhum valor calculado pela plataforma: as regras de acúmulo pertencem ao operador, que escolhe sua própria base a partir do `total` do pedido (por exemplo, `itemsPrice` menos `discount`, se frete e taxas não devem acumular). O bloco descreve o pedido como ele está no momento da leitura, não um instante do seu histórico. Um aplicativo que recebe um evento CONCLUDED consulta o pedido e faz o acúmulo; um que recebe um evento CANCELLED estorna o acúmulo que havia concedido para aquele pedido. Quando um resgate está REVERSED, o saldo voltou para o cliente, que portanto pagou esse valor por outros meios — mas os totais do pedido continuam mostrando o desconto que ele havia financiado. Some `redemption.amount.value` de volta a qualquer base derivada dos totais do pedido. Um pedido que nunca teve resgate não traz a chave `redemption`. required: - accountId - programId properties: accountId: type: string description: Identificador da conta do cliente no operador. programId: type: string description: Identificador do programa no operador. redemption: type: object description: >- O resgate debitado neste pedido, presente somente na entrega para o aplicativo que foi debitado. CONFIRMED significa que o resgate vale: o desconto que ele financia está dentro de `total.discount` do pedido. REVERSED significa que o saldo foi devolvido ao cliente. required: - externalId - status - amount properties: externalId: type: string description: >- Identificador do resgate gerado pelo operador quando o débito foi criado. status: type: string enum: - CONFIRMED - REVERSED amount: $ref: '#/components/schemas/money' address: type: object description: Endereço. properties: country: type: string description: Sigla do país. example: BR state: type: string description: Sigla do estado. example: SP city: type: string example: São Paulo district: type: string description: Bairro. example: Moema street: type: string description: Logradouro. example: Avenida Ibirapuera number: type: string example: '100' complement: type: string description: Complemento. Omitido quando vazio. example: Bloco 2, apto 31 reference: type: string description: Ponto de referência. Omitido quando vazio. example: Casa amarela postalCode: type: string description: CEP. example: 04029-000 formattedAddress: type: string description: Endereço completo formatado. coordinates: type: object properties: latitude: type: number example: -23.54809 longitude: type: number example: -46.63638 Error: type: object required: - title - status properties: status: type: string description: Código HTTP da resposta, como string. example: '404' title: description: >- Descrição do problema. Em erros de validação pode vir como objeto (campo → lista de mensagens) ou como lista. oneOf: - type: string - type: object - type: array items: type: string example: Record not found UnauthorizedError: type: object properties: title: type: string example: Unauthorized status: type: integer example: 401 responses: BadRequestCursor: description: Os cursores `next` e `previous` foram informados juntos. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Token ausente, inválido, expirado ou revogado. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' NotFound: description: Recurso não encontrado (ou loja não autorizada para o aplicativo). content: application/json: schema: $ref: '#/components/schemas/Error' example: status: '404' title: Record not found NotAcceptable: description: Parâmetros de filtro inválidos. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Token de acesso opaco emitido pela API de autenticação (`POST /authentication/v1/oauth/token`). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.