Skip to main content
Três rotas escrevem no catálogo. Elas recebem os mesmos objetos e validam os campos da mesma forma. O que muda é o que acontece com objetos novos e com os objetos que você não enviou.

Update

Mudanças pontuais: preço, status, tempo de entrega, abrir e fechar a loja.

Upsert

Cadastrar e alterar objetos sem mexer no resto do catálogo.

Force

Carga inicial ou reescrita completa. Remove o que não vier.

Qual usar

Primeira carga

Use o force com o catálogo completo, ou o upsert tipo a tipo, na ordem OPTION, OPTION_GROUP, CATEGORY e ITEM.

Produto novo ou alterado

Use o upsert só com os objetos que mudaram.

Preço, estoque e status do dia a dia

Use o update com o id e só os campos que mudaram. Se o objeto não existir na loja, a chamada falha em vez de criar um objeto incompleto.

Reconciliação completa

Use o force quando o seu sistema for a fonte da verdade e você quiser apagar da DeliveryVip o que não existe mais nele.

Comportamento comum

A resposta 204 No Content só chega depois que o catálogo foi gravado. Tudo roda numa única transação: se qualquer objeto falhar, nada é gravado e a resposta é 422 com o motivo. Corrija o objeto e reenvie a chamada inteira.A única parte assíncrona são as imagens, baixadas depois da resposta.
Em update e upsert, um objeto que já existe recebe só os campos presentes no JSON. Um campo ausente mantém o valor atual. Campos fora da estrutura documentada são rejeitados com 422.
categoryId, optionIds, optionGroupId e optionId precisam apontar para objetos que já existem na loja. Senão, a chamada falha com uma mensagem como categoryId '...' not available in merchant.No update e no upsert, envie um tipo por vez, nesta ordem: OPTION, OPTION_GROUP, CATEGORY e ITEM. No force, a ordem é resolvida para você: serviços, opções, grupos, categorias, produtos e formas de pagamento são gravados nessa sequência.
IDs repetidos dentro de um mesmo objeto são removidos antes de gravar: optionIds de um grupo, modifiers de um produto (pelo id) e optionGroups de um modificador (pelo optionGroupId).Não repita o mesmo objeto na lista principal (updatedObjects, upsertObjects ou as listas do force): a chamada pode falhar com 422.

Formato dos campos

O ID é seu e precisa ser único. Gere um UUID novo no seu sistema para cada objeto. Não reaproveite UUIDs de outra plataforma ou de catálogos antigos: se o UUID já pertencer a outra loja na DeliveryVip, o objeto é ignorado sem erro, nem criado nem alterado.

Regras de preço do modificador

O campo rule de um modificador define como o preço das opções escolhidas entra no produto. Para as opções A = 10, B = 15 e C = 20: minPermitted e maxPermitted limitam quantas opções o cliente escolhe:
  • Envie os dois juntos. Enviar só um deles gera erro.
  • Os dois são inteiros maiores ou iguais a 0, e minPermitted não pode ser maior que maxPermitted.
  • minPermitted igual a 0 torna o modificador opcional.
  • maxPermitted igual a 0 significa sem limite. Nesse caso, minPermitted também precisa ser 0.

Imagens

Produtos (ITEM) e opções (OPTION) aceitam image com url e checksum. A imagem é baixada depois da resposta, em segundo plano:
  • Se o checksum for igual ao da imagem atual, o download é ignorado. Envie sempre o checksum real do arquivo para não baixar a mesma imagem de novo.
  • A url precisa ser https://, pública e responder 2xx direto: redirecionamentos não são seguidos.
  • Formatos aceitos: PNG, JPEG, GIF, WebP e SVG.
  • O download tem limite de 5 segundos para conectar e 10 segundos no total.
  • Se o download falhar, a imagem é descartada sem aviso e a anterior continua. Confira o checksum no GET da loja para saber se a troca aconteceu.
O checksum é o MD5 do arquivo, em Base64.

Respostas e erros

Os erros 422 trazem o motivo em title. Quando há mais de um erro de estrutura, eles vêm separados por |.
422 Unprocessable Content