Criar ou atualizar objetos (upsert)

POST /merchant/v3/{merchantId}/merchantUpsert cria os objetos cujo id ainda não existe na loja e altera os que já existem. Objetos que você não enviar ficam como estão. É a rota para cadastrar produtos, opções e categorias e para manter o catálogo em dia, um tipo por chamada.

Como o upsert pode criar objetos, ele exige mais campos que o update: name em todos os tipos com id, e menu, price e categoryId em ITEM. As regras de formato, imagens e erros comuns às três rotas estão em Ações.

Gere um UUID novo para cada objeto no seu sistema. O id enviado vira o ID do objeto na DeliveryVip. Não reaproveite UUIDs de outras plataformas ou de catálogos antigos: se o UUID já pertencer a outra loja, o objeto é ignorado sem erro. Use UUID em minúsculas, versão 1 a 5 (por exemplo, v4).

Corpo da requisição

string

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

string

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

object[]

Objetos a criar ou alterar, no formato do entityType (veja abaixo). Obrigatório e não pode ser vazio quando houver entityType.

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

Ordem do cadastro

Um objeto só pode apontar para outro que já existe. Na primeira carga, envie um tipo por chamada nesta ordem:

OPTION

As opções individuais, como sabores e bordas.

OPTION_GROUP

Os grupos, com optionIds apontando para as opções do passo anterior.

Requisição

Cadastrar uma categoria:

curl --request POST 'https://api.deliveryvip.com.br/merchant/v3/{merchantId}/merchantUpsert' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "entityType": "CATEGORY",
    "upsertObjects": [
      { "id": "44b34740-e8a1-44ea-8ef1-c0b896877df3", "index": 1, "name": "Pizzas", "status": "AVAILABLE" }
    ]
  }'

const response = await fetch(
  `https://api.deliveryvip.com.br/merchant/v3/${merchantId}/merchantUpsert`,
  {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      entityType: 'CATEGORY',
      upsertObjects: [
        { id: '44b34740-e8a1-44ea-8ef1-c0b896877df3', index: 1, name: 'Pizzas', status: 'AVAILABLE' },
      ],
    }),
  },
)
if (response.status !== 204) console.error(await response.json())

response = requests.post(
    f"https://api.deliveryvip.com.br/merchant/v3/{merchant_id}/merchantUpsert",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "entityType": "CATEGORY",
        "upsertObjects": [
            {"id": "44b34740-e8a1-44ea-8ef1-c0b896877df3", "index": 1, "name": "Pizzas", "status": "AVAILABLE"},
        ],
    },
)
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 um objeto que já existe, só os campos enviados são alterados. Opções, grupos, categorias e produtos removidos por um force voltam ao catálogo se forem enviados de novo com o mesmo id.

SERVICE

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

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

PAYMENT_METHOD

uuid

obrigatório

ID da forma de pagamento.

string

obrigatório

Nome exibido ao cliente.

string

obrigatório

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",
  "upsertObjects": [
    {
      "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

obrigatório

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",
  "upsertObjects": [
    {
      "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",
      "name": "Americana",
      "description": "Molho de tomate, mussarela, frango com barbecue, azeitona preta e orégano.",
      "externalCode": "147",
      "status": "AVAILABLE"
    }
  ]
}

OPTION_GROUP

uuid

obrigatório

ID do grupo de opções.

string

obrigatório

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",
  "upsertObjects": [
    {
      "id": "a0f77d73-e8eb-434a-924e-d63883657288",
      "name": "Bordas",
      "externalCode": "2",
      "status": "AVAILABLE",
      "optionIds": [
        "1591c35a-6286-41c2-b6af-d3ccf64d8363",
        "50e6c17f-41c6-41c0-bc3a-37fcea6dd500"
      ]
    },
    {
      "id": "65a751bd-f12e-4f4e-8f54-808a85016379",
      "name": "Bordas Vulcão",
      "status": "AVAILABLE",
      "optionIds": [
        "27462198-2676-4d7f-8956-a9474ee2b273",
        "3433e107-2f8f-48d5-88ab-c27d79b40627",
        "435d68dc-2e1f-48e2-9d5b-f667c62a474b",
        "6ca94f9e-87c6-4369-b6bd-fa208d0c0f71"
      ]
    }
  ]
}

ITEM

uuid

obrigatório

ID do produto.

string

obrigatório

Nome do produto.

uuid

obrigatório

Categoria do produto. Precisa existir na loja.

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

object

obrigatório

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.

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.

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

"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: trocar os modificadores de um produto

{
  "entityType": "ITEM",
  "upsertObjects": [
    {
      "id": "98e0ca6b-0e2d-4b3a-beba-ef48ab05c6d0",
      "name": "Sorvete",
      "categoryId": "44b34740-e8a1-44ea-8ef1-c0b896877df3",
      "menu": ["DELIVERY", "TAKEOUT"],
      "price": { "value": 12.0, "originalValue": 12.0, "currency": "BRL" },
      "modifiers": [
        {
          "id": "2488c7a1-0706-409d-bb69-d248f4c81358",
          "name": "Escolha a cobertura",
          "rule": "ADDITION",
          "minPermitted": 0,
          "maxPermitted": 2,
          "optionGroups": [
            { "optionGroupId": "a0f77d73-e8eb-434a-924e-d63883657288", "index": 1 }
          ]
        }
      ]
    }
  ]
}

O produto passa a ter só esse modificador. Para tirar todos, envie "modifiers": [].

Exemplo completo de ITEM

{
  "merchantStatus": "AVAILABLE",
  "entityType": "ITEM",
  "upsertObjects": [
    {
      "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

Ordem do cadastro

Requisição

Objetos por entityType

SERVICE

PAYMENT_METHOD

OPTION

OPTION_GROUP

CATEGORY

ITEM

Próximos passos

Update

Force

​Corpo da requisição

​Ordem do cadastro

​Requisição

​Objetos por entityType

​SERVICE

​PAYMENT_METHOD

​OPTION

​OPTION_GROUP

​CATEGORY

​ITEM

​Próximos passos

Update

Force

Corpo da requisição

Ordem do cadastro

Requisição

Objetos por entityType

SERVICE

PAYMENT_METHOD

OPTION

OPTION_GROUP

CATEGORY

ITEM

Próximos passos