Atualizar objetos (update)

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.

Se um id enviado não existir na loja, a chamada inteira falha com 422 e nada é gravado. Para criar objetos, use o upsert. As regras de formato, imagens e erros comuns às três rotas estão em Ações.

Corpo da requisição

string

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

string

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

object[]

Objetos a alterar, no formato do entityType (veja abaixo). 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:

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" }
      }
    ]
  }'

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())

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.

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.

string

obrigatório

DELIVERY (entrega) ou TAKEOUT (retirada).

integer

obrigatório

Tempo do serviço, em minutos.

string

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

Exemplo: abrir a loja e mudar os tempos

{
  "merchantStatus": "AVAILABLE",
  "entityType": "SERVICE",
  "updatedObjects": [
    { "status": "AVAILABLE", "serviceType": "DELIVERY", "serviceTime": 40 },
    { "status": "AVAILABLE", "serviceType": "TAKEOUT", "serviceTime": 40 }
  ]
}

PAYMENT_METHOD

uuid

obrigatório

ID da forma de pagamento.

string

Nome exibido ao cliente.

string

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

integer

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

string

Código no seu sistema.

string

AVAILABLE ou UNAVAILABLE.

Exemplo

{
  "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

uuid

obrigatório

ID da opção.

string

Nome da opção.

string

Descrição da opção.

string

Código no seu sistema.

string

AVAILABLE ou UNAVAILABLE.

object

Imagem da opção. Veja as regras de imagem.

Mostrar propriedades

string

obrigatório

Endereço https:// da imagem.

string

obrigatório

MD5 do arquivo em Base64.

Exemplo

{
  "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

uuid

obrigatório

ID do grupo de opções.

string

Nome do grupo.

string

Código no seu sistema.

string

AVAILABLE ou UNAVAILABLE.

uuid[]

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

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.

Exemplo

{
  "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.

ITEM

uuid

obrigatório

ID do produto.

string

Nome do produto.

uuid

Categoria do produto. Precisa existir na loja.

integer

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

string

Descrição do produto.

string

Código no seu sistema.

string

AVAILABLE ou UNAVAILABLE.

string

Código de barras EAN.

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.

object

Mostrar propriedades

number

obrigatório

Preço atual.

number

obrigatório

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

string

obrigatório

Sempre BRL.

object

url (https://) e checksum da imagem, como em OPTION. Veja as regras de imagem.

object[]

Lista completa de modificadores do produto. Substitui a atual.

Mostrar propriedades

uuid

obrigatório

ID do modificador.

string

obrigatório

Pergunta exibida ao cliente, por exemplo “Escolha os sabores”.

integer

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

string

Código no seu sistema.

string

AVAILABLE ou UNAVAILABLE.

string

ADDITION, APPORTIONMENT ou HIGHEST. Veja as regras de preço.

integer

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

integer

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

object[]

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

Mostrar propriedades

uuid

obrigatório

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

integer

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

object[]

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

Mostrar propriedades

uuid

obrigatório

ID da opção.

integer

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

string

AVAILABLE ou UNAVAILABLE.

object

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

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.

Exemplo: remover todos os modificadores de um produto

{
  "entityType": "ITEM",
  "updatedObjects": [
    { "id": "98e0ca6b-0e2d-4b3a-beba-ef48ab05c6d0", "modifiers": [] }
  ]
}

Exemplo: trocar os grupos de um modificador

{
  "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": [].

Exemplo completo de ITEM

{
  "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" }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Visão geral

Pedidos

Catálogo

Indoor

Descontos

Ferramentas

Referência

Corpo da requisição

Requisição

Objetos por entityType

SERVICE

PAYMENT_METHOD

OPTION

OPTION_GROUP

CATEGORY

ITEM

Próximos passos

Upsert

Regras comuns e erros

​Corpo da requisição

​Requisição

​Objetos por entityType

​SERVICE

​PAYMENT_METHOD

​OPTION

​OPTION_GROUP

​CATEGORY

​ITEM

​Próximos passos

Upsert

Regras comuns e erros

Corpo da requisição

Requisição

Objetos por entityType

SERVICE

PAYMENT_METHOD

OPTION

OPTION_GROUP

CATEGORY

ITEM

Próximos passos