Com este método, será possível realizar a autenticação na API utilizando protocolo OAuth2. Com isso retornará um access_token que irá dar permissão de acesso a API.

Objetivo

Expor valores de status e eventos de pedidos (CREATED, CONFIRMED, EDITED, READY_FOR_PICKUP, DISPATCHED, CANCELLED e CONCLUDED) via polling.

Quando usar

Para sincronização assíncrona de eventos: consumir mudanças de status de pedidos. Quando o parceiro não usa webhook e prefere polling.

Quando NÃO usar

Não usar para consultas ad-hoc de detalhes do pedido (chamar /orders/{orderNumber} para detalhes). Não usar sem informar x-polling-merchants header com os merchantIds.

Importante

Requer header x-polling-merchants (lista de merchant ids) e Authorization. Pode filtrar por eventType. Schema de resposta: array de EventPollingOutput.

eventType identifica a alteração ocorrida. Para obter o estado e os detalhes atuais do pedido, consulte a orderURL recebida no evento ou GET /orders/{orderNumber}. EDITED é um evento emitido quando uma alteração realizada diretamente pelo PDV é concluída com sucesso. EDITED não representa um status persistente nem uma mudança de etapa do pedido.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: GET /events:polling
  API-->>Parceiro: 200 — eventos ainda não confirmados

Objetivo

Acknowledge — notificar a API que eventos foram consumidos para que não sejam retornados novamente no polling.

Quando usar

Após consumir com sucesso eventos obtidos por GET /events:polling, envie ack com lista de EventAcknowledgementInput.

Quando NÃO usar

Não usar para sinalizar falha de processamento (ack indica consumo bem-sucedido).

Importante

Requer Authorization. Recebe array de objetos com id, orderId, eventType. Retorna 202 informando que vai ser processada a requisição.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Note over Parceiro,API: Após processar eventos obtidos em GET /events:polling
  Parceiro->>API: POST /events/acknowledgment
  API-->>Parceiro: 202 — requisição aceita (eventos não voltam no próximo polling)

Esta operação não existe na Zé Seller Public API como rota a ser chamada por você. Ela documenta a requisição HTTP que a plataforma envia para a URL cadastrada em PATCH /webhooks quando a inscrição inclui ORDER_EVENTS e há um evento a entregar.

Método e corpo: POST com Content-Type: application/json e corpo conforme o schema ao lado.

Resposta esperada: seu endpoint deve responder com código HTTP 2xx para indicar recebimento processado; outros códigos podem implicar políticas de retentativa conforme a plataforma (404 não há retentativa e para os demais erros há 3 tentativas).

Nota: o método publicado neste host (POST /callbacks/order-events-webhook) existe apenas para fins de documentação; não é o caminho que recebe o webhook — o caminho é o da sua própria URL configurada.

Nota: use os headers X-App-Signature e X-App-Timestamp para validar a requisição.

sequenceDiagram
  participant SPA as Zé Seller Public API
  participant API as Seu Sistema
  SPA->>API: POST https://seu.webhook.com
  Note right of API: Processa a requisição
  API-->>SPA: 200 Evento processado com sucesso

Objetivo

Recuperar detalhes de entrega de um pedido (nome do cliente, entregador, preços, pickupCode, endereço).

Quando usar

Utilize este endpoint somente quando:

• For necessário realizar consultas operacionais sobre rota e dados do entregador para execução da entrega.
• For preciso verificar o pickupCode para coleta do pedido no PDV.

Quando NÃO usar

Este endpoint não deve ser utilizado para:

• Alterar o status de entrega do pedido (use os endpoints POST do grupo Logistics).
• Obter dados completos do pedido além das informações de entrega (use GET /orders/{orderNumber}).

Importante

Requer header Authorization: Bearer <token>. Schema de resposta: DeliveryDetailsOutput.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: GET /logistics/delivery/{orderNumber}
  API-->>Parceiro: 200 com detalhes da entrega (entregador, pickupCode, endereço)

Objetivo

Informar que o entregador pegou o pedido no PDV (marcar pickup).

Quando usar

Utilize este endpoint somente quando:

• For necessário confirmar que o entregador recebeu fisicamente o pedido no ponto de venda.
• O body obrigatório com o email do entregador estiver disponível.

Quando NÃO usar

Este endpoint não deve ser utilizado para:

• Indicar chegada ao endereço do cliente ou entrega final — use /logistics/arrived/{orderNumber} ou /logistics/finishDelivery/{orderNumber}.
• Registrar outros eventos da jornada do entregador antes da coleta.

Importante

Requer header Authorization: Bearer <token>. Retorna 202 quando aceito para processamento. Schema do body: PickedOrderInput.

sequenceDiagram
  participant Entregador as Seu sistema (entregador)
  participant API as Zé Seller Public API
  Entregador->>API: POST /logistics/orderPicked/{orderNumber}
  Note right of API: Body: { email }
  API-->>Entregador: 202 Aceito para processamento

Objetivo

Informar início de rota/coleta pelo entregador (rota iniciada).

Quando usar

Utilize este endpoint somente quando:

• O entregador iniciar a rota de entrega após coletar o pedido no PDV.
• O body com o email do entregador estiver disponível.

Quando NÃO usar

Este endpoint não deve ser utilizado para:

• Sinalizar chegada ao endereço do cliente — use /logistics/arrived/{orderNumber}.
• Confirmar a entrega final — use /logistics/finishDelivery/{orderNumber}.

Importante

Requer header Authorization: Bearer <token>. Retorna 202 quando aceito para processamento. Schema do body: startRouteOrderInput.

sequenceDiagram
  participant Entregador as Seu sistema (entregador)
  participant API as Zé Seller Public API
  Entregador->>API: POST /logistics/startRoute/{orderNumber}
  Note right of API: Body: { email }
  API-->>Entregador: 202 Aceito para processamento

Objetivo

Informar que o pedido chegou ao destino (entregador chegou no endereço do cliente).

Quando usar

Utilize este endpoint somente quando:

• For necessário sinalizar a chegada do entregador ao endereço do cliente, antes da tentativa de entrega ou entrega final.
• O body com o email do entregador estiver disponível.

Quando NÃO usar

Este endpoint não deve ser utilizado para:

• Confirmar que a entrega foi concluída — use /logistics/finishDelivery/{orderNumber}.
• Registrar outros eventos anteriores da jornada (coleta, início de rota).

Importante

Requer header Authorization: Bearer <token>. Body com email do entregador é obrigatório. Retorna 202 quando aceito para processamento. Schema do body: ArrivedOrderInput.

sequenceDiagram
  participant Entregador as Seu sistema (entregador)
  participant API as Zé Seller Public API
  Entregador->>API: POST /logistics/arrived/{orderNumber}
  Note right of API: Body: { email }
  API-->>Entregador: 202 Aceito para processamento

Objetivo

Validar o código de entrega (deliveryCode) informado no momento da entrega ou retirada do pedido.

Quando usar

Utilize este endpoint somente quando:

• For necessário verificar se o deliveryCode informado pelo entregador ou cliente é válido para o pedido em questão.

Quando NÃO usar

Este endpoint não deve ser utilizado para:

• Autorização de pagamento ou verificação de identidade além da validação do código de entrega.
• Confirmar a conclusão da entrega — use /logistics/finishDelivery/{orderNumber} após validar o código.

Importante

Requer header Authorization: Bearer <token>. Body obrigatório com deliveryCode. Retorna 200 em caso de código válido. Schema do body: ValidateCodeInput.

sequenceDiagram
  participant Entregador as Seu sistema (entregador)
  participant API as Zé Seller Public API
  Entregador->>API: POST /logistics/validateCode/{orderNumber}
  Note right of API: Body: { deliveryCode }
  API-->>Entregador: 200 Código validado com sucesso

Objetivo

Marcar o pedido como entregue (finalizar rota e status do pedido).

Quando usar

Utilize este endpoint somente quando:

• A entrega foi concluída com sucesso pelo entregador.
• O body com o email do entregador estiver disponível; lat/long são opcionais para registro de geolocalização.

Quando NÃO usar

Este endpoint não deve ser utilizado para:

• Cancelar ou reverter o status de entrega — use /logistics/cancel/{orderNumber} para cancelamentos pelo entregador.
• Sinalizar etapas intermediárias (coleta, rota, chegada) — use os endpoints de evento correspondentes antes de finalizar.

Importante

Requer header Authorization: Bearer <token>. Retorna 202 quando aceito para processamento. Schema do body: OrderDeliveredInput.

sequenceDiagram
  participant Entregador as Seu sistema (entregador)
  participant API as Zé Seller Public API
  Entregador->>API: POST /logistics/finishDelivery/{orderNumber}
  Note right of API: Body: { email, lat?, long? }
  API-->>Entregador: 202 Pedido marcado como entregue

Objetivo

Permitir que o entregador solicite o cancelamento do pedido por motivos operacionais (ex.: NOT_FOUND, RISK_AREA).

Quando usar

Utilize este endpoint somente quando:

• O entregador não conseguir completar a entrega por motivos documentados no enum de razões disponível.

Quando NÃO usar

Este endpoint não deve ser utilizado para:

• Cancelamentos administrativos que não pertençam ao fluxo operacional da pessoa entregadora.
• Rejeição de pedido antes da confirmação pelo estabelecimento — use /orders/{orderNumber}/requestCancellation.

Importante

Requer header Authorization: Bearer <token>. Body obrigatório com email do entregador e reason (enum de motivos, ex.: NOT_FOUND, RISK_AREA).

sequenceDiagram
  participant Entregador as Seu sistema (entregador)
  participant API as Zé Seller Public API
  Entregador->>API: POST /logistics/cancel/{orderNumber}
  Note right of API: Body: { email, reason }
  API-->>Entregador: 202 Cancelamento aceito para processamento

Objetivo

Abrir ou fechar um estabelecimento (operational availability) no Zé.

Quando usar

Para operação de abertura (operation: AVAILABLE) ou fechamento (operation: CLOSED) do PDV com razão obrigatória quando CLOSED.

Quando NÃO usar

Não usar para alterar disponibilidade de produtos individuais (use products/availability).

Importante

Body com operation enum (AVAILABLE | CLOSED); reasons obrigatório quando CLOSED. Requer Authorization. Retornos: 200/422 conforme validação.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: POST /merchants/{merchantId}/availability
  API-->>Parceiro: 200 ou 422 conforme validação

Objetivo

Recuperar informações do estabelecimento (status, availability, basicInfo, idealPortfolio, etc).

Quando usar

Quando precisar do status operacional do PDV e metadados úteis para operação/decisões.

Quando NÃO usar

Não usar como substituto de integrações profundas de catálogo/WMS; dados são informativos.

Importante

Requer Authorization. Schema de resposta: MerchantInformationResponse. Campos como idealPortfolio fornecem métricas (totalProducts, totalActiveProducts).

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: GET /merchants/{merchantId}
  API-->>Parceiro: 200 com dados do estabelecimento

Objetivo

Recuperar os detalhes de um pedido a partir do seu número na plataforma Zé Delivery.

Quando usar

Utilize este endpoint somente quando:

• For necessário consultar o estado e dados completos de um pedido (items, total, merchant, delivery, customer — conforme permissões).
• Houver um orderNumber válido gerado pela plataforma.
• O parceiro tiver autorização para ver os dados sensíveis (aplicável somente se houver acordo legal).

Quando NÃO usar

Este endpoint não deve ser utilizado para:

• Polling massivo de listas de pedidos (usar events:polling para eventos).
• Recuperar pedidos não pertencentes ao escopo do parceiro sem autorização.
• Operações de escrita/alteração de pedido.

Importante

Informações para edição de pedidos

Quando disponíveis, os detalhes do pedido incluem informações que devem ser preservadas para permitir a edição de itens:

• observations: preferência do cliente para tratar itens que estejam em falta. O campo é opcional e não é retornado quando o cliente não informar uma preferência. Os valores possíveis são:
  • Substituir por item similar: indica que o item pode ser substituído por outro da mesma categoria. Nesse caso, utilize items[].category.id para garantir que o novo item pertença à mesma categoria.
  • Cancelar o item.: indica que o item em falta deve ser cancelado.
• items[].category.id: identificador da categoria do item. Esse campo deve ser utilizado no fluxo de substituição por item similar para garantir que o novo item pertença à mesma categoria.

Status e histórico do pedido

A resposta contém:

• status: o status mais recente do pedido.
• statusHistory: a lista cronológica de status e eventos registrados, com a data de cada ocorrência.

Os valores seguem os eventos documentados no grupo Events. Em especial, EDITED é um evento emitido quando uma alteração realizada diretamente pelo PDV é concluída com sucesso. EDITED não representa um status persistente nem uma mudança de etapa do pedido. Para acompanhar mudanças de forma assíncrona, consuma GET /events:polling ou configure webhooks.

Ao consultar um pedido, um mesmo produto pode aparecer na resposta em até duas linhas separadas, com o mesmo identificador e os mesmos dados. As únicas diferenças entre essas duas linhas são os campos de unitPrice, onde um possui um valor promocional (mais baixo) e outro não, e o campo hasLimitedPromotion, que indica se aquela parte do produto foi vendida com a promoção:

• hasLimitedPromotion = true: parte do produto vendida com preço promocional (ainda dentro da quantidade que tem desconto).
• hasLimitedPromotion = false: parte do produto vendida pelo preço normal, seja porque a quantidade comprada passou do limite da promoção, seja porque o produto não tinha promoção.

Por isso, ao processar a resposta, considere que a identificação única de uma linha de produto no pedido é a combinação identificador do produto + hasLimitedPromotion.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: GET /orders/{orderNumber}
  API-->>Parceiro: 200 com detalhes do pedido

Objetivo

Confirmar/aceitar um pedido no sistema do Zé (aceitação pelo estabelecimento/parceiro).

Quando usar

Utilize este endpoint somente quando:

• O estabelecimento/parceiro confirma que irá preparar o pedido.
• É necessário informar preparationTime, orderExternalCode ou createdAt adicionais (opcionais).

Quando NÃO usar

Este endpoint não deve ser utilizado para:

• Cancelar pedidos (usar /requestCancellation ou /cancel).
• Confirmar pedidos já confirmados sem validação (verificar status antes de confirmar).

Importante

Recurso idempotente a nível de negócio — confirmar sem checar status pode gerar rejeições; o endpoint retorna 202 quando a requisição é aceita para processamento. Requer Authorization header. Campos possíveis no body: preparationTime (minutos), orderExternalCode, createdAt. Validar formato createdAt ISO UTC se informado.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: GET /orders/{orderNumber}
  API-->>Parceiro: 200 com detalhes do pedido
  Parceiro->>API: POST /orders/{orderNumber}/confirm
  API-->>Parceiro: 202 aceite em processamento

Objetivo

Solicitar o cancelamento ou rejeição de um pedido, informando o código de motivo apropriado.

Quando usar

Utilize este endpoint somente quando:

• O estabelecimento não puder atender o pedido (ex.: UNAVAILABLE_ITEM, RESTAURANT_WITHOUT_DELIVERY_PERSON etc.).
• O pedido ainda estiver em status que permite requestCancellation conforme regras de negócio.

Quando NÃO usar

Este endpoint não deve ser utilizado para:

• Cancelamentos feitos por entregador (use endpoints de logística quando aplicável).
• Substituir o fluxo de cancelamento em massa sem observar regras por status do pedido.

Importante

Body requer um code dentre os códigos documentados (ex.: UNAVAILABLE_ITEM, SYSTEMIC_ISSUES, etc.). Ver regras: se pedido já confirmado, apenas alguns códigos são aceitos; se não confirmado, outros códigos são aceitos — seguir a enumeração do Swagger. Retorna 202 quando aceita para processamento; erros 422 podem indicar validações de negócio sobre o status atual do pedido. Requer Authorization header.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: POST /orders/{orderNumber}/requestCancellation
  API-->>Parceiro: 202 solicitação aceita para processamento

Objetivo

Consultar, de forma paginada, o histórico de pedidos finalizados de um estabelecimento (merchantId) em um determinado período. A resposta traz uma visão resumida de cada pedido — cliente, pagamento, valores, avaliação e histórico de status — adequada para construção de relatórios, dashboards e telas de consulta.

Quando usar

Utilize este endpoint somente quando:

• For necessário listar pedidos já finalizados de um estabelecimento (por exemplo, pedidos concluídos ou cancelados), dentro de um intervalo de datas.
• Houver um merchantId válido ao qual o parceiro tenha acesso.
• For desejável paginar os resultados (page, pageSize) e/ou ordená-los pela data de criação (sort).

Quando NÃO usar

Este endpoint não deve ser utilizado para:

• Consulta de pedidos em andamento (ainda não finalizados): eles não são retornados por este endpoint.
• Acompanhamento em tempo real do ciclo de vida de pedidos: utilizar events:polling em conjunto com getOrderByNumber.
• Recuperação de detalhes completos de um pedido específico (itens, taxas, descontos detalhados, cliente completo): utilizar getOrderByNumber.
• Operações de escrita ou alteração de pedidos (confirmar, cancelar, restaurar, atualizar itens).

Importante

Status e histórico

Cada item retornado possui:

• status: o status final mais recente do pedido, normalmente CONCLUDED ou CANCELLED.
• statusHistory: o histórico cronológico de status e eventos do pedido.

O histórico pode conter eventos intermediários, como CREATED, CONFIRMED, READY_FOR_PICKUP, DISPATCHED e EDITED. EDITED é um evento emitido quando uma alteração realizada diretamente pelo PDV é concluída com sucesso. EDITED não representa um status persistente nem uma mudança de etapa do pedido.

Requer header Authorization: Bearer <token> e o parceiro deve ter permissão sobre o merchantId consultado. Somente pedidos que já concluíram seu ciclo de vida (ex.: CONCLUDED e CANCELLED) são retornados — pedidos em andamento são omitidos do resultado.

Limites de período:

• startDate não pode ser anterior a 6 meses contados a partir da data atual.
• O intervalo entre startDate e endDate não pode exceder 3 meses por consulta.
• Para cobrir intervalos maiores, fracionar a consulta em múltiplas chamadas com janelas de até 3 meses, sempre dentro dos últimos 6 meses.

Quando startDate e endDate não forem informados, o período padrão é dos últimos 30 dias até o momento atual; quando informados, devem estar em ISO 8601 e endDate deve ser maior ou igual a startDate. O pageSize aceita valores entre 1 e 50 (padrão 20). O campo hasNext na resposta indica se há mais páginas a consultar. Dados sensíveis do cliente (ex.: nome) podem ser omitidos quando o parceiro não tiver permissão para acessá-los.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: GET /merchants/{merchantId}/orders/history?startDate&endDate&page&pageSize&sort
  API-->>Parceiro: 200 com página de pedidos finalizados
  Parceiro->>API: GET /merchants/{merchantId}/orders/history?page=N+1 (enquanto hasNext = true)
  API-->>Parceiro: 200 com próxima página

Objetivo

Reverter as alterações feitas nos itens de um pedido confirmado, restaurando a composição anteriormente vigente na plataforma, quando essa operação é suportada pelo estado atual do pedido.

Quando usar

Utilize este endpoint somente quando:

• Já tiver sido aplicada uma atualização de itens no pedido e for necessário desfazê-la.
• O pedido estiver em condições que permitem restauração segundo as regras de negócio expostas pela API.

Quando NÃO usar

Este endpoint não deve ser utilizado para:

• Substituir o cancelamento ou a solicitação de cancelamento quando o objetivo for encerrar o pedido.
• Corrigir dados que não dependem do fluxo de edição de itens (consulte os demais endpoints do grupo Orders).

Importante

Em geral, a restauração aplica-se a pedidos confirmados que tenham passado por edição de itens; se o pedido não estiver elegível, a API retorna erro de validação. Em caso de sucesso, a resposta segue o que está definido no contrato público deste recurso.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: PUT /orders/{orderNumber}/items
  API-->>Parceiro: resposta de sucesso conforme contrato
  Parceiro->>API: POST /orders/{orderNumber}/restore
  API-->>Parceiro: resposta de sucesso conforme contrato

Objetivo

Ajustar os itens de um pedido já confirmado, removendo produtos indisponíveis ou substituindo-os por alternativas equivalentes, sem alterar o restante do contrato público descrito no Swagger.

Quando usar

Utilize este endpoint somente quando:

• O pedido estiver em status que permite edição de itens após a confirmação pelo estabelecimento (conforme regras da plataforma).
• For necessário registrar remoções ou substituições antes da preparação ou da operação logística subsequente.

Quando NÃO usar

Este endpoint não deve ser utilizado para:

• Alterar pedidos que ainda não foram confirmados (o fluxo esperado é consulta, depois confirmação ou solicitação de cancelamento).
• Substituir o cancelamento do pedido quando a intenção for encerrar o pedido por completo (use os fluxos de cancelamento documentados no grupo Orders).

Importante

A alteração de itens só é aceita quando o pedido está no status CONFIRMED. Em qualquer outro status, a API recusa a chamada. Para desfazer mudanças e voltar à composição anterior do pedido, use o endpoint de restauração do pedido, no mesmo grupo Orders.

Um mesmo produto pode aparecer no pedido em até duas linhas separadas, com o mesmo identificador e os mesmos dados. As únicas diferenças entre essas duas linhas são os campos de unitPrice, onde um possui um valor promocional (mais baixo) e outro não, e o campo hasLimitedPromotion, que indica se aquela parte do produto foi vendida com a promoção:

• hasLimitedPromotion = true: parte do produto vendida com preço promocional (ainda dentro da quantidade que tem desconto).
• hasLimitedPromotion = false: parte do produto vendida pelo preço normal, seja porque a quantidade comprada passou do limite da promoção, seja porque o produto não tinha promoção.

Por isso, na edição de itens, o que identifica uma linha de produto de forma única é a combinação identificador do produto + hasLimitedPromotion. Ao remover quantidade ou substituir um item, envie o campo hasLimitedPromotion para a API saber em qual das duas linhas mexer. Se você não enviar esse campo, a API atua na linha com hasLimitedPromotion = false, caso ela exista.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: POST /orders/{orderNumber}/confirm
  API-->>Parceiro: 202 aceite em processamento
  Parceiro->>API: PUT /orders/{orderNumber}/items (pedido em CONFIRMED, hasLimitedPromotion por item)
  API-->>Parceiro: resposta de sucesso conforme contrato

Objetivo

Criar (POST) um item de produto para um estabelecimento (inclui price, images, category, tags).

Quando usar

POST: criar SKUs exclusivos do parceiro para o merchant (catálogo externo/partner-managed).

Quando NÃO usar

Não usar para criar SKUs que pertencem ao catálogo padrão do Zé sem autorização. Evitar duplicar productId vs externalProductId — a regra do Swagger indica que exatamente um dos identificadores é obrigatório.

Importante

Regras de validação: exatamente um de productId ou externalProductId deve ser enviado; se price informado, value e originalValue são obrigatórios; imagens têm image obrigatório. Requer Authorization. Respostas podem retornar 202 (async processing) ou erros 422/400.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: POST /merchants/{merchantId}/products/items
  API-->>Parceiro: 202 ou erro de validação

Objetivo

Atualizar (PUT) um item de produto para um estabelecimento (inclui price, images, category, tags).

Quando usar

PUT: atualizar metadados do item (nome, descrição, preço, imagens).

Quando NÃO usar

Não usar para alterar SKUs que pertencem ao catálogo padrão do Zé sem autorização. Evitar duplicar productId vs externalProductId — a regra do Swagger indica que exatamente um dos identificadores é obrigatório.

Importante

Regras de validação: exatamente um de productId ou externalProductId deve ser enviado; se price informado, value e originalValue são obrigatórios; imagens têm image obrigatório. Requer Authorization. Respostas podem retornar 202 (async processing) ou erros 422/400.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: PUT /merchants/{merchantId}/products/items
  API-->>Parceiro: 202 ou erro de validação

Objetivo

Upsert em lote (atualizar múltiplos produtos) — sincronização inicial ou periódica de catálogo parceiro.

Quando usar

Onboarding inicial de catálogo exclusivo do parceiro ou sincronização de muitos SKUs.

Quando NÃO usar

Para atualizações unitárias frequentes (usar endpoints unitários); não criar produtos no catálogo oficial do Zé.

Importante

Recurso assíncrono: retorna 202 para processamento; validações por item podem retornar 422. Requer Authorization. Limitações de tamanho de payload não documentadas explicitamente no Swagger — validar com infraestrutura antes de enviar grandes lotes.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: PUT /merchants/products/items
  API-->>Parceiro: 202 — processamento assíncrono

Objetivo

Atualizar promoções de produtos para múltiplos estabelecimentos em lote.

Quando usar

Aplicar/retirar campanhas/promos para vários merchants de uma só vez.

Quando NÃO usar

Para promoções que impactam catálogo padrão sem acordo; não usar para promoções ad-hoc sem campos obrigatórios.

Importante

Estrutura: array de ProductPromoInput. Regras: se isEnabled=true, percentage e scheduleType são obrigatórios, caso contrário não devem ser enviados. Deve ser usado productId ou externalProductId em ambos os casos. Requer Authorization. Retorna 202 quando aceito.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: PUT /merchants/products/promos
  API-->>Parceiro: 202 quando aceito