> ## 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": "<eventId>"}] (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.

# Atualizar objetos (update)

> Altere campos de objetos que já existem, abra ou feche a loja e mude os tempos de entrega e retirada.

`POST /merchant/v3/{merchantId}/merchantUpdate` altera objetos que **já existem** na loja. Só o `id` é obrigatório: envie o identificador e os campos que mudaram. É a rota para o dia a dia, como trocar preço, pausar um produto em falta ou abrir e fechar a loja.

> [!NOTE]
>
> Se um `id` enviado não existir na loja, a chamada inteira falha com `422` e nada é gravado. Para criar objetos, use o [upsert](/docs/guides/merchant/catalog-and-services/actions/upsert.md). As regras de formato, imagens e erros comuns às três rotas estão em [Ações](/docs/guides/merchant/catalog-and-services/actions.md).

## Corpo da requisição

**merchantStatus** `string`

`AVAILABLE` abre a loja, `UNAVAILABLE` fecha. Obrigatório quando não houver `entityType`.

**entityType** `string`

Tipo dos objetos em `updatedObjects`: `SERVICE`, `PAYMENT_METHOD`, `OPTION`, `OPTION_GROUP`, `CATEGORY` ou `ITEM`. Um tipo por chamada.

**updatedObjects** `object[]`

Objetos a alterar, no formato do `entityType` ([veja abaixo](#objetos-por-entitytype)). Obrigatório e não pode ser vazio quando houver `entityType`.

Combine os campos conforme o que você precisa:

| Você envia | Efeito |
| - | - |
| Só `merchantStatus` | Abre ou fecha a loja. |
| `entityType` + `updatedObjects` | Altera só os objetos enviados. |
| Os três | Faz as duas coisas na mesma chamada. |

## Requisição

Pausar um produto em falta e corrigir o preço de outro:

```bash cURL theme={null}
curl --request POST 'https://api.deliveryvip.com.br/merchant/v3/{merchantId}/merchantUpdate' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "entityType": "ITEM",
    "updatedObjects": [
      { "id": "8cd0cfb4-3288-4345-bcc6-37e78fb42221", "status": "UNAVAILABLE" },
      {
        "id": "89bef249-bdce-4d2a-b949-f71bcd91e2f5",
        "price": { "value": 79.9, "originalValue": 85.0, "currency": "BRL" }
      }
    ]
  }'
```

```js Node.js theme={null}
const response = await fetch(
  `https://api.deliveryvip.com.br/merchant/v3/${merchantId}/merchantUpdate`,
  {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      entityType: 'ITEM',
      updatedObjects: [
        { id: '8cd0cfb4-3288-4345-bcc6-37e78fb42221', status: 'UNAVAILABLE' },
        {
          id: '89bef249-bdce-4d2a-b949-f71bcd91e2f5',
          price: { value: 79.9, originalValue: 85.0, currency: 'BRL' },
        },
      ],
    }),
  },
)
if (response.status !== 204) console.error(await response.json())
```

```python Python theme={null}
response = requests.post(
    f"https://api.deliveryvip.com.br/merchant/v3/{merchant_id}/merchantUpdate",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "entityType": "ITEM",
        "updatedObjects": [
            {"id": "8cd0cfb4-3288-4345-bcc6-37e78fb42221", "status": "UNAVAILABLE"},
            {
                "id": "89bef249-bdce-4d2a-b949-f71bcd91e2f5",
                "price": {"value": 79.9, "originalValue": 85.0, "currency": "BRL"},
            },
        ],
    },
)
if response.status_code != 204:
    print(response.json())
```

A resposta de sucesso é `204 No Content`, sem corpo. Veja os [erros possíveis](/docs/guides/merchant/catalog-and-services/actions.md#respostas-e-erros).

## Objetos por entityType

Em todos os tipos, só os campos enviados são alterados.

### SERVICE

Disponibilidade e tempo dos serviços de entrega e retirada.

**serviceType** `string` *required*

`DELIVERY` (entrega) ou `TAKEOUT` (retirada).

**serviceTime** `integer` *required*

Tempo do serviço, em minutos.

**status** `string`

`AVAILABLE` ativa o serviço, `UNAVAILABLE` desativa. Sem o campo, a disponibilidade atual é mantida.

> [accordion] Exemplo: abrir a loja e mudar os tempos
>
> ```json theme={null}
> {
>   "merchantStatus": "AVAILABLE",
>   "entityType": "SERVICE",
>   "updatedObjects": [
>     { "status": "AVAILABLE", "serviceType": "DELIVERY", "serviceTime": 40 },
>     { "status": "AVAILABLE", "serviceType": "TAKEOUT", "serviceTime": 40 }
>   ]
> }
> ```

### PAYMENT\_METHOD

**id** `uuid` *required*

ID da forma de pagamento.

**name** `string`

Nome exibido ao cliente.

**mode** `string`

`CASH`, `CREDIT`, `DEBIT`, `PIX`, `MEAL_VOUCHER`, `FOOD_VOUCHER` ou `OTHER`.

**index** `integer`

Posição na lista, a partir de `1`.

**externalCode** `string`

Código no seu sistema.

**status** `string`

`AVAILABLE` ou `UNAVAILABLE`.

> [accordion] Exemplo
>
> ```json theme={null}
> {
>   "entityType": "PAYMENT_METHOD",
>   "updatedObjects": [
>     {
>       "id": "44b34740-e8a1-44ea-8ef1-c0b896877df3",
>       "index": 1,
>       "name": "Visa - Crédito",
>       "mode": "CREDIT",
>       "status": "AVAILABLE",
>       "externalCode": "VISA_CREDIT"
>     },
>     {
>       "id": "2a8d8227-663b-464a-8afe-b44a214c82f2",
>       "index": 2,
>       "name": "Visa - Débito",
>       "mode": "DEBIT",
>       "status": "AVAILABLE",
>       "externalCode": "VISA_DEBIT"
>     }
>   ]
> }
> ```

### OPTION

**id** `uuid` *required*

ID da opção.

**name** `string`

Nome da opção.

**description** `string`

Descrição da opção.

**externalCode** `string`

Código no seu sistema.

**status** `string`

`AVAILABLE` ou `UNAVAILABLE`.

**image** `object`

Imagem da opção. Veja as [regras de imagem](/docs/guides/merchant/catalog-and-services/actions.md#imagens).

**propriedades**

**url** `string` *required*

Endereço `https://` da imagem.

**checksum** `string` *required*

MD5 do arquivo em Base64.

> [accordion] Exemplo
>
> ```json theme={null}
> {
>   "entityType": "OPTION",
>   "updatedObjects": [
>     {
>       "id": "fce12ae5-0b64-458f-9794-b1580fb9bd26",
>       "name": "Alemanha",
>       "description": "Molho de tomate, mussarela, requeijão, bacon picado, cebola e orégano.",
>       "externalCode": "152",
>       "status": "AVAILABLE",
>       "image": {
>         "url": "https://storage.com/alemanha.jpg",
>         "checksum": "3sQ1rVvGw0T7bH2pYk9xNw=="
>       }
>     },
>     {
>       "id": "e3080d59-6e2a-478b-b63e-8b78679444f2",
>       "status": "UNAVAILABLE"
>     }
>   ]
> }
> ```

### OPTION\_GROUP

**id** `uuid` *required*

ID do grupo de opções.

**name** `string`

Nome do grupo.

**externalCode** `string`

Código no seu sistema.

**status** `string`

`AVAILABLE` ou `UNAVAILABLE`.

**optionIds** `uuid[]`

Lista **completa** das opções do grupo. Substitui a lista atual. Todas as opções precisam existir na loja.

> [!NOTE]
>
> Um grupo pode ser usado por vários produtos. Mudar `optionIds` muda as opções do grupo em **todos** os modificadores que o usam. Um array vazio (`"optionIds": []`) remove todas as opções do grupo. Sem o campo, as opções atuais são mantidas.

> [accordion] Exemplo
>
> ```json theme={null}
> {
>   "entityType": "OPTION_GROUP",
>   "updatedObjects": [
>     {
>       "id": "a0f77d73-e8eb-434a-924e-d63883657288",
>       "name": "Bordas",
>       "externalCode": "2",
>       "status": "AVAILABLE",
>       "optionIds": [
>         "1591c35a-6286-41c2-b6af-d3ccf64d8363",
>         "50e6c17f-41c6-41c0-bc3a-37fcea6dd500"
>       ]
>     },
>     {
>       "id": "98e0ca6b-0e2d-4b3a-beba-ef48ab05c6d0",
>       "name": "Novo grupo de coberturas",
>       "optionIds": []
>     }
>   ]
> }
> ```
>
> O segundo objeto renomeia o grupo e remove todas as opções dele.

### CATEGORY

**id** `uuid` *required*

ID da categoria.

**name** `string`

Nome da categoria.

**index** `integer`

Posição no cardápio, a partir de `1`.

**description** `string`

Descrição da categoria.

**externalCode** `string`

Código no seu sistema.

**status** `string`

`AVAILABLE` ou `UNAVAILABLE`.

> [accordion] Exemplo
>
> ```json theme={null}
> {
>   "entityType": "CATEGORY",
>   "updatedObjects": [
>     { "id": "44b34740-e8a1-44ea-8ef1-c0b896877df3", "index": 1, "name": "Promoções", "status": "AVAILABLE" },
>     { "id": "2a8d8227-663b-464a-8afe-b44a214c82f2", "index": 2, "name": "Entradas", "status": "AVAILABLE" }
>   ]
> }
> ```

### ITEM

**id** `uuid` *required*

ID do produto.

**name** `string`

Nome do produto.

**categoryId** `uuid`

Categoria do produto. Precisa existir na loja.

**index** `integer`

Posição dentro da categoria, a partir de `1`.

**description** `string`

Descrição do produto.

**externalCode** `string`

Código no seu sistema.

**status** `string`

`AVAILABLE` ou `UNAVAILABLE`.

**ean** `string`

Código de barras EAN.

**menu** `string[]`

Onde o produto é vendido: `DELIVERY`, `TAKEOUT` e `INDOOR`. A lista substitui a atual: um tipo que não vier deixa de valer. `DELIVERY_TAKEOUT` ainda é aceito por retrocompatibilidade e vira `DELIVERY` + `TAKEOUT`. Prefira os tipos individuais.

**price** `object`

**propriedades**

**value** `number` *required*

Preço atual.

**originalValue** `number` *required*

Preço original. Quando `value` é menor que `originalValue`, o produto aparece **em promoção**: por exemplo, `value` 80.0 e `originalValue` 100.0.

**currency** `string` *required*

Sempre `BRL`.

**image** `object`

`url` (`https://`) e `checksum` da imagem, como em `OPTION`. Veja as [regras de imagem](/docs/guides/merchant/catalog-and-services/actions.md#imagens).

**modifiers** `object[]`

Lista **completa** de modificadores do produto. Substitui a atual.

**propriedades**

**id** `uuid` *required*

ID do modificador.

**name** `string` *required*

Pergunta exibida ao cliente, por exemplo "Escolha os sabores".

**index** `integer`

Posição no produto, a partir de `1`.

**externalCode** `string`

Código no seu sistema.

**status** `string`

`AVAILABLE` ou `UNAVAILABLE`.

**rule** `string`

`ADDITION`, `APPORTIONMENT` ou `HIGHEST`. Veja as [regras de preço](/docs/guides/merchant/catalog-and-services/actions.md#regras-de-preço-do-modificador).

**minPermitted** `integer`

Mínimo de opções. Envie junto com `maxPermitted`.

**maxPermitted** `integer`

Máximo de opções. `0` significa sem limite.

**optionGroups** `object[]`

Lista **completa** de grupos de opções do modificador. Substitui a atual.

**propriedades**

**optionGroupId** `uuid` *required*

ID de um grupo de opções que já existe na loja.

**index** `integer`

Posição do grupo no modificador, a partir de `1`.

**options** `object[]`

Preço, posição e status de opções do grupo **neste modificador**.

**propriedades**

**optionId** `uuid` *required*

ID da opção.

**index** `integer`

Posição da opção, a partir de `1`.

**status** `string`

`AVAILABLE` ou `UNAVAILABLE`.

**price** `object`

`value`, `originalValue` e `currency` (`BRL`), todos obrigatórios. O preço cobrado é o `value`.

> [accordion] Como os modificadores são gravados
>
> * O produto precisa existir, mas os modificadores dentro dele são **criados ou atualizados**: um modificador com `id` novo é criado. Por isso `name` é obrigatório no modificador mesmo no update.
> * `"modifiers": []` remove todos os modificadores do produto. Um modificador que existia e não veio na lista é **apagado**. Sem o campo `modifiers`, os modificadores atuais são mantidos.
> * `"optionGroups": []` remove todos os grupos do modificador. Sem o campo, os grupos atuais são mantidos.
> * Todas as opções do grupo entram no modificador automaticamente. A lista `options` só ajusta preço, posição e status de cada uma. Uma opção que não faz parte do grupo é ignorada.

> [accordion] Exemplo: remover todos os modificadores de um produto
>
> ```json theme={null}
> {
>   "entityType": "ITEM",
>   "updatedObjects": [
>     { "id": "98e0ca6b-0e2d-4b3a-beba-ef48ab05c6d0", "modifiers": [] }
>   ]
> }
> ```

> [accordion] Exemplo: trocar os grupos de um modificador
>
> ```json theme={null}
> {
>   "entityType": "ITEM",
>   "updatedObjects": [
>     {
>       "id": "98e0ca6b-0e2d-4b3a-beba-ef48ab05c6d0",
>       "modifiers": [
>         {
>           "id": "2488c7a1-0706-409d-bb69-d248f4c81358",
>           "name": "Escolha a cobertura",
>           "optionGroups": [
>             { "optionGroupId": "a0f77d73-e8eb-434a-924e-d63883657288", "index": 1 }
>           ]
>         }
>       ]
>     }
>   ]
> }
> ```
>
> O produto passa a ter só esse modificador, e o modificador passa a ter só esse grupo. Para tirar todos os grupos, envie `"optionGroups": []`.

> [accordion] Exemplo completo de ITEM
>
> ```json theme={null}
> {
>   "merchantStatus": "AVAILABLE",
>   "entityType": "ITEM",
>   "updatedObjects": [
>     {
>       "id": "8cd0cfb4-3288-4345-bcc6-37e78fb42221",
>       "index": 1,
>       "name": "Água Mineral sem Gás 500ml",
>       "description": "500ml",
>       "externalCode": "6",
>       "status": "AVAILABLE",
>       "menu": ["DELIVERY", "TAKEOUT"],
>       "price": { "value": 4.5, "originalValue": 4.5, "currency": "BRL" },
>       "categoryId": "9d68e128-ac01-4627-a8f9-064f44da3d8f",
>       "image": {
>         "url": "https://storage.com/image.jpg",
>         "checksum": "ZwfVoHMiCU7FgxzoSfC4Vg=="
>       }
>     },
>     {
>       "id": "89bef249-bdce-4d2a-b949-f71bcd91e2f5",
>       "index": 2,
>       "name": "Pizza Gigante",
>       "description": "Pizza Gigante",
>       "externalCode": "104",
>       "status": "UNAVAILABLE",
>       "menu": ["DELIVERY", "TAKEOUT"],
>       "price": { "value": 85.0, "originalValue": 85.0, "currency": "BRL" },
>       "categoryId": "44b34740-e8a1-44ea-8ef1-c0b896877df3",
>       "image": {
>         "url": "https://storage.com/image.jpg",
>         "checksum": "8UhRfj73ostwpfgzHWD47Q=="
>       },
>       "modifiers": [
>         {
>           "id": "03670695-aaa7-4f9c-95f2-12803a7ec9a3",
>           "index": 1,
>           "name": "Escolha os Sabores da sua Pizza",
>           "status": "AVAILABLE",
>           "rule": "HIGHEST",
>           "minPermitted": 1,
>           "maxPermitted": 4,
>           "externalCode": "123",
>           "optionGroups": [
>             {
>               "optionGroupId": "ba13187c-8bd8-4b3a-a506-8a129485b701",
>               "index": 1,
>               "options": [
>                 {
>                   "optionId": "635899c6-1d99-47d7-864e-e7413c3837f3",
>                   "index": 64,
>                   "status": "AVAILABLE",
>                   "price": { "value": 0.0, "originalValue": 0.0, "currency": "BRL" }
>                 },
>                 {
>                   "optionId": "abaae840-3c34-448a-8637-a7ee1f8048e7",
>                   "index": 85,
>                   "status": "AVAILABLE",
>                   "price": { "value": 0.0, "originalValue": 0.0, "currency": "BRL" }
>                 }
>               ]
>             },
>             {
>               "optionGroupId": "1915b8cf-d419-446b-90fd-612e11778c61",
>               "index": 2,
>               "options": [
>                 {
>                   "optionId": "874f6327-22e8-4190-8003-8ef1e74f3068",
>                   "index": 172,
>                   "status": "AVAILABLE",
>                   "price": { "value": 0.0, "originalValue": 0.0, "currency": "BRL" }
>                 },
>                 {
>                   "optionId": "14c32301-b84d-4f7f-b8b8-9d6410cf66a0",
>                   "index": 504,
>                   "status": "AVAILABLE",
>                   "price": { "value": 0.0, "originalValue": 0.0, "currency": "BRL" }
>                 }
>               ]
>             }
>           ]
>         }
>       ]
>     }
>   ]
> }
> ```

## Próximos passos

> [card] [Upsert](/docs/guides/merchant/catalog-and-services/actions/upsert.md)
>
> Crie objetos novos no catálogo.

> [card] [Regras comuns e erros](/docs/guides/merchant/catalog-and-services/actions.md)
>
> Formato dos campos, imagens e mensagens de erro.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.