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 chamada é síncrona e tudo ou nada
A chamada é síncrona e tudo ou nada
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.Só os campos enviados são alterados
Só os campos enviados são alterados
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.Referências precisam existir antes
Referências precisam existir antes
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
IDs repetidos
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
Regras de preço do modificador
O camporule 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, eminPermittednão pode ser maior quemaxPermitted. minPermittedigual a0torna o modificador opcional.maxPermittedigual a0significa sem limite. Nesse caso,minPermittedtambém precisa ser0.
Imagens
Produtos (ITEM) e opções (OPTION) aceitam image com url e checksum. A imagem é baixada depois da resposta, em segundo plano:
- Se o
checksumfor 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
urlprecisa serhttps://, pública e responder2xxdireto: 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
checksumno GET da loja para saber se a troca aconteceu.
checksum é o MD5 do arquivo, em Base64.
Como calcular o checksum
Como calcular o checksum
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