> ## 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. # Criar ou atualizar entidades da loja > Cria ou atualiza (upsert) status e entidades da loja. O corpo pode ser enviado diretamente ou envolvido em `{"merchant": {...}}`. Este endpoint pode ser usado das seguintes formas: **1 - Enviado apenas com o campo `merchantStatus`:** abre ou fecha a loja. **2 - Enviado apenas com os campos `entityType` e `upsertObjects`:** cria ou atualiza somente os objetos enviados. > Quando o campo `entityType` é preenchido, o campo `upsertObjects` não pode estar vazio. **3 - Enviado com os campos `merchantStatus`, `entityType` e `upsertObjects`:** os cenários 1 e 2 acontecem simultaneamente. ## OpenAPI ````yaml https://app.deliveryvip.com.br/swaggers/merchant.yaml post /merchant/v3/{merchantId}/merchantUpsert 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}/merchantUpsert: post: tags: - Merchants summary: Criar ou atualizar entidades da loja description: >- Cria ou atualiza (upsert) status e entidades da loja. O corpo pode ser enviado diretamente ou envolvido em `{"merchant": {...}}`. Este endpoint pode ser usado das seguintes formas: **1 - Enviado apenas com o campo `merchantStatus`:** abre ou fecha a loja. **2 - Enviado apenas com os campos `entityType` e `upsertObjects`:** cria ou atualiza somente os objetos enviados. > Quando o campo `entityType` é preenchido, o campo `upsertObjects` não pode estar vazio. **3 - Enviado com os campos `merchantStatus`, `entityType` e `upsertObjects`:** os cenários 1 e 2 acontecem simultaneamente. parameters: - $ref: '#/components/parameters/merchantId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MerchantUpsert' responses: '204': description: Dados recebidos e processados com sucesso. Sem conteúdo na resposta. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/MalformedJson' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/CatalogUnprocessable' 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 schemas: MerchantUpsert: type: object discriminator: propertyName: entityType mapping: SERVICE: '#/components/schemas/ServiceUpsert' OPTION: '#/components/schemas/OptionUpsert' OPTION_GROUP: '#/components/schemas/OptionGroupUpsert' CATEGORY: '#/components/schemas/CategoryUpsert' ITEM: '#/components/schemas/ItemUpsert' PAYMENT_METHOD: '#/components/schemas/PaymentMethodUpsert' properties: merchantStatus: type: string description: Abre (`AVAILABLE`) ou fecha (`UNAVAILABLE`) a loja. enum: - AVAILABLE - UNAVAILABLE example: AVAILABLE entityType: type: string description: Tipo das entidades enviadas em `upsertObjects`. enum: - SERVICE - OPTION - OPTION_GROUP - CATEGORY - ITEM - PAYMENT_METHOD ServiceUpsert: description: Upsert de objetos `Service`. allOf: - $ref: '#/components/schemas/MerchantUpsert' - type: object properties: upsertObjects: description: Objetos `Service` a criar ou atualizar. type: array items: $ref: '#/components/schemas/Service' OptionUpsert: description: Upsert de objetos `Option`. allOf: - $ref: '#/components/schemas/MerchantUpsert' - type: object properties: upsertObjects: description: Objetos `Option` a criar ou atualizar. type: array items: $ref: '#/components/schemas/Option' OptionGroupUpsert: description: Upsert de objetos `OptionGroup`. allOf: - $ref: '#/components/schemas/MerchantUpsert' - type: object properties: upsertObjects: description: Objetos `OptionGroup` a criar ou atualizar. type: array items: $ref: '#/components/schemas/OptionGroup' CategoryUpsert: description: Upsert de objetos `Category`. allOf: - $ref: '#/components/schemas/MerchantUpsert' - type: object properties: upsertObjects: description: Objetos `Category` a criar ou atualizar. type: array items: $ref: '#/components/schemas/Category' ItemUpsert: description: Upsert de objetos `Item`. allOf: - $ref: '#/components/schemas/MerchantUpsert' - type: object properties: upsertObjects: description: Objetos `Item` a criar ou atualizar. type: array items: $ref: '#/components/schemas/Item' PaymentMethodUpsert: description: Upsert de objetos `PaymentMethod`. allOf: - $ref: '#/components/schemas/MerchantUpsert' - type: object properties: upsertObjects: description: Objetos `PaymentMethod` a criar ou atualizar. type: array items: $ref: '#/components/schemas/PaymentMethod' UnauthorizedError: type: object properties: title: type: string example: Unauthorized status: type: integer example: 401 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 Service: type: object title: Service required: - serviceType - serviceTime properties: status: type: string description: Indica se o serviço está disponível. enum: - AVAILABLE - UNAVAILABLE example: AVAILABLE serviceType: type: string description: |- Tipo de serviço oferecido: `DELIVERY` - pedidos entregues no endereço do cliente. `TAKEOUT` - pedidos retirados pelo cliente no estabelecimento. enum: - DELIVERY - TAKEOUT example: DELIVERY serviceTime: type: integer description: Tempo estimado do serviço, em minutos. example: 15 Option: type: object title: Option required: - id - name properties: id: type: string format: uuid description: Id do complemento. example: e5232f14-430c-4a94-8ff6-289d5a16a87a name: type: string description: Nome do complemento. example: Abacaxi description: type: string description: Descrição do complemento. example: Fatias de abacaxi fresco externalCode: type: string description: Código externo do complemento. status: type: string description: Indica se o complemento está disponível. enum: - AVAILABLE - UNAVAILABLE example: AVAILABLE image: $ref: '#/components/schemas/Image' OptionGroup: type: object title: Option Group required: - id - name properties: id: type: string format: uuid description: Id do grupo de complementos. example: fe67e551-f42f-499a-8afb-0ed893c71fa3 name: type: string description: Nome do grupo de complementos. maxLength: 150 example: Escolha o sabor da pizza externalCode: type: string description: Código externo (normalmente o código do grupo no sistema da loja). example: '12' status: type: string description: Indica se o grupo está disponível. enum: - AVAILABLE - UNAVAILABLE example: AVAILABLE optionIds: type: array description: Ids dos complementos (`Option`) que pertencem a este grupo. items: type: string format: uuid example: e5232f14-430c-4a94-8ff6-289d5a16a87a Category: type: object title: Category required: - id - name properties: id: type: string format: uuid description: Id da categoria. example: 92fad022-2c28-4239-a026-989f5b555cb7 index: type: integer description: Posição de exibição. example: 0 name: type: string description: Nome da categoria. maxLength: 150 example: Pizzas salgadas description: type: string description: Descrição da categoria. example: Sabores de pizzas salgadas. externalCode: type: string description: >- Código externo (normalmente o código da categoria no sistema da loja). example: '13' status: type: string description: Indica se a categoria está disponível. enum: - AVAILABLE - UNAVAILABLE example: AVAILABLE Item: type: object title: Item required: - id - name - menu - price - categoryId properties: id: type: string format: uuid description: Id do item. example: 732bd31e-77fc-47ee-88ee-a0437f97b198 index: type: integer description: Posição de exibição. example: 0 name: type: string description: Nome do item. maxLength: 150 example: Pizza de calabresa description: type: string description: Descrição do item. example: Calabresa fatiada, cebola e azeitonas. externalCode: type: string description: Código externo (normalmente o código do item no sistema da loja). example: '233467' status: type: string description: Indica se o item está disponível. enum: - AVAILABLE - UNAVAILABLE example: AVAILABLE ean: type: string description: Código EAN do produto. example: '7896005202074' menu: type: array items: type: string enum: - DELIVERY - TAKEOUT - DELIVERY_TAKEOUT - INDOOR description: >- Cardápios em que o item é vendido: `DELIVERY` - cardápio de entrega `TAKEOUT` - cardápio de retirada `DELIVERY_TAKEOUT` - alias legado, equivale a `DELIVERY` + `TAKEOUT` `INDOOR` - cardápio de consumo no local Na leitura, itens disponíveis para entrega e retirada trazem `DELIVERY_TAKEOUT` junto dos valores separados, por compatibilidade. price: $ref: '#/components/schemas/ItemPrice' categoryId: type: string format: uuid description: Id da categoria do item. example: 92fad022-2c28-4239-a026-989f5b555cb7 image: $ref: '#/components/schemas/Image' modifiers: type: array description: Etapas de personalização do item (por exemplo, escolha de sabores). items: type: object title: Modifier required: - id - name properties: id: type: string format: uuid description: Id da etapa. example: 732bd31e-77fc-47ee-88ee-a0437f97b198 index: type: integer description: Posição de exibição. example: 0 name: type: string maxLength: 150 example: Escolha os sabores externalCode: type: string description: Código externo da etapa. status: type: string description: Indica se a etapa está disponível. enum: - AVAILABLE - UNAVAILABLE example: AVAILABLE rule: type: string description: >- Regra de cálculo do preço dos complementos: `ADDITION` - soma os preços de todos os complementos escolhidos. `APPORTIONMENT` - soma os preços dos complementos escolhidos e divide pela quantidade escolhida. `HIGHEST` - considera o complemento de maior preço. enum: - ADDITION - APPORTIONMENT - HIGHEST example: ADDITION minPermitted: type: integer description: Quantidade mínima de complementos a escolher. example: 1 maxPermitted: type: integer description: >- Quantidade máxima de complementos a escolher (`0` = sem limite). example: 4 optionGroups: type: array items: type: object title: Option Group required: - optionGroupId properties: optionGroupId: type: string format: uuid description: Id do grupo de complementos. example: 732bd31e-77fc-47ee-88ee-a0437f97b198 index: type: integer description: Posição de exibição. example: 0 options: type: array items: type: object title: Option required: - optionId properties: optionId: type: string format: uuid description: Id do complemento. example: 732bd31e-77fc-47ee-88ee-a0437f97b198 index: type: integer description: Posição de exibição. example: 0 status: type: string description: >- Indica se o complemento está disponível neste item. enum: - AVAILABLE - UNAVAILABLE example: AVAILABLE price: $ref: '#/components/schemas/ItemPrice' PaymentMethod: type: object title: PaymentMethod required: - id - name - mode properties: id: type: string format: uuid description: Id da forma de pagamento. example: 92fad022-2c28-4239-a026-989f5b555cb7 index: type: integer description: Posição de exibição. example: 1 name: type: string description: Nome da forma de pagamento. maxLength: 150 example: Visa - Crédito externalCode: type: string description: >- Código externo (normalmente o código da forma de pagamento no sistema da loja). example: '13' status: type: string description: Indica se a forma de pagamento está disponível. enum: - AVAILABLE - UNAVAILABLE example: AVAILABLE mode: type: string description: Modalidade de pagamento. enum: - CASH - CREDIT - DEBIT - PIX - MEAL_VOUCHER - FOOD_VOUCHER - OTHER example: CASH Image: description: Imagem. type: object required: - url - checksum properties: url: type: string format: uri description: >- URL HTTPS da imagem. Baixe e armazene a imagem do seu lado: a URL pode deixar de ser válida depois de algum tempo. example: https://pizzariadapraca.com.br/imagem.jpg checksum: type: string description: Checksum do arquivo. Use para detectar mudanças na imagem. example: 96b41025 ItemPrice: type: object title: Item Price required: - value - originalValue - currency properties: value: type: number description: Preço atual. Até 4 casas decimais. example: 50 originalValue: type: number description: Preço original (antes de promoção). Até 4 casas decimais. example: 50 currency: type: string description: Moeda (código ISO 4217). enum: - BRL example: BRL responses: Unauthorized: description: Token ausente, inválido, expirado ou revogado. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' MalformedJson: description: >- O corpo da requisição não é um JSON válido, ou o token não tem o escopo `od.all` (sem corpo). content: application/json: schema: $ref: '#/components/schemas/Error' 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 CatalogUnprocessable: description: >- O corpo não respeita o schema (`title` traz a lista de erros), `entityType` não é permitido (`entity_type_unallowed`), a lista de objetos está vazia (`objects_empty`) ou houve erro ao gravar. 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.