Zé Seller Public API (1.0)

Download OpenAPI specification:Download

URL: https://seller-public-api.ze.delivery/docs License: Apache 2.0

Está API tem como objetivo, disponibilizar as informações dos nossos parceiros, tais como pedidos, catalogo de produtos entre outros

Authentication

API Authentication

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.

query Parameters

grant_type required	string Example: grant_type=client_credentials Deverá sempre ser utilizado `client_credentials`
scope required	string Example: scope=orders/read Atualmente temos somente o `orders/read` como escopo possível.

Request Body schema: application/x-www-form-urlencoded

client_id required	string O id do cliente.
client_secret required	string A secret do cliente.

Merchants

Sobre Merchants

Os endpoints do grupo Merchants da Seller Public API tratam do estabelecimento (PDV / seller) no Zé Delivery: consulta de informações operacionais e cadastrais, acompanhamento de KPIs operacionais e abertura e fechamento da loja (disponibilidade operacional do ponto). Complementam o grupo Products, que cobre catálogo e disponibilidade de itens; aqui o foco é a operação do PDV como estabelecimento, não a gestão SKU a SKU.

Quando usar os endpoints Merchants ?

Quando precisar do status e metadados do estabelecimento (disponibilidade, informações básicas, indicadores resumo como portfólio ideal, conforme o contrato da resposta).
Quando precisar consultar KPIs operacionais consolidados do PDV por período, granularidade e data de referência para dashboards, monitoramento ou automações.
Quando for necessário abrir ou fechar o PDV na plataforma, com motivo quando o fechamento exigir justificativa.

Quando não usar os endpoints Merchants ?

Para alterar disponibilidade de produtos ou SKUs específicos — use os endpoints do grupo Products (por exemplo disponibilidade de item).
Para detalhes de pedidos ou ciclo de pedido — use Orders e, para acompanhamento de eventos, Events.
Para histórico de pedidos finalizados — use Orders.
Para repasses, incentivos e pagamentos — use Financials.

Como os endpoints de Merchants se relacionam

As rotas são independentes: você pode consultar dados ou KPIs do merchant e alterar a disponibilidade da loja conforme a necessidade do seu fluxo, sem ordem fixa obrigatória entre elas.

flowchart TD
  G["GET /merchants/{merchantId} — informações do estabelecimento"]
  K["GET /merchants/{merchantId}/kpis — KPIs operacionais"]
  A["POST /merchants/{merchantId}/availability — abrir ou fechar a loja"]

Make merchant availability

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

path Parameters

merchantId

required

string

Example: 1234

O id do estabelecimento

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

operation required	string Enum: "CLOSED" "AVAILABLE" Closed para fechar estabelecimento, e avaiable para abrir
reasons	string Razao pela qual esta realizando operaçao. Campo obrigatorio quando for operação closed

Responses

Request samples

Payload

Content type

application/json

{"operation": "AVAILABLE",
"reasons": "INTERNET"
}

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Get merchant information

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

path Parameters

merchantId

required

string

Example: 1234

O id do estabelecimento

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Responses

Response samples

Content type

application/json

{"status": "AVAILABLE",
"basicInfo": {"idealPortfolio": {"totalProducts": 0,
"totalActiveProducts": 0,
"activeProductsPercentage": 0
}
}
}

Get Merchant KPIs

Objetivo

Permitir que o integrador consulte, de forma programática, os principais KPIs operacionais de um PDV (seller) para utilização em dashboards próprios, monitoramento de performance e automações. O endpoint fornece métricas consolidadas por período (granularidade) e data de referência, retornando indicadores estruturados por grupo.

Quando usar

Utilize este endpoint somente quando: O integrador precisar consultar KPIs consolidados de um PDV específico. For necessário alimentar dashboards externos ou sistemas próprios com métricas de desempenho do seller. Houver necessidade de analisar métricas agregadas por período (MONTH, WEEK, DAY ou HOUR).

Quando NÃO usar

Este endpoint não deve ser utilizado para: Consultar detalhes de pedidos individuais (use endpoints de Orders). Criar, atualizar ou enviar dados de performance. Substituir endpoints de catálogo, estoque ou operações transacionais.

Importante

Este endpoint é somente leitura (read-only). O acesso exige autenticação OAuth2 (client_credentials) e permissionamento específico para leitura de KPIs. O retorno é consolidado por PDV e por período — não há detalhamento por pedido. A granularidade e a data de referência são obrigatórias e impactam diretamente o cálculo das métricas. O integrador deve respeitar o rate limit configurado para a aplicação. O endpoint faz parte da Seller Public API (catálogo padrão) e não está relacionado a catálogo externo, marketplace ou integrações de parceiro customizadas.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: GET /merchants/{merchantId}/kpis
  API-->>Parceiro: 200 com KPIs agregados por período

path Parameters

merchantId

required

string

Example: 1234

O id do estabelecimento

query Parameters

granularity	string Enum: "HOUR" "DAY" "WEEK" "MONTH" A granularidade dos KPIs a serem retornados.
referenceDate	string <date> Example: referenceDate=2026-03-06 Data de referência para os KPIs (formato ISO 8601: YYYY-MM-DD).

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Responses

Response samples

Content type

application/json

{"kpis": {"general": {"validOrders": {"type": "INTEGER",
"value": "26"
},
"fillRate": {"type": "PERCENTAGE",
"value": "92.86"
},
"promoSellerActivationRate": {"type": "PERCENTAGE",
"value": "4.08"
},
"merchantAvailabilityRate": {"type": "PERCENTAGE",
"value": "98.5"
},
"tenMinutesDeliveryReleaseRate": {"type": "PERCENTAGE",
"value": "72.73"
},
"deliveryTrackingAccuracyRate": {"type": "PERCENTAGE",
"value": "90.91"
},
"thirtyFiveMinutesDeliveryAccurateRate": {"type": "PERCENTAGE",
"value": "90.0"
},
"deliveryOrderAggroupmentRate3More": {"type": "PERCENTAGE",
"value": "12.3"
},
"orderRating": {"type": "FLOAT",
"value": "5.0"
},
"idealPortfolioRate": {"type": "PERCENTAGE",
"value": "35.37"
}
},
"turbo": {"validTurboOrders": {"type": "INTEGER",
"value": "4"
},
"turboOrderRating": {"type": "FLOAT",
"value": "5.0"
},
"turboFillRate": {"type": "PERCENTAGE",
"value": "100.0"
},
"turboTrackingAccuracyRate": {"type": "PERCENTAGE",
"value": "100.0"
},
"fiveMinutesTurboDeliveryReleaseRate": {"type": "PERCENTAGE",
"value": "25.0"
},
"fifteenMinutesTurboAccurateRate": {"type": "PERCENTAGE",
"value": "75.0"
}
},
"updatedDate": "2026-03-06T18:54:53.887Z"
}
}

Products

Sobre Products

Os endpoints do grupo Products da Seller Public API cobrem a gestão de catálogo e oferta no Zé Delivery em dois eixos: rotas padrão (disponibilidade, criação e atualização de itens, oferta/preço do item, promoções em lote e listagem paginada do menu) e rotas /external-catalog, restritas a SKUs exclusivos do parceiro em verticais específicas (disponibilidade de produto e de options, preços de SKU e de option, e upsert em lote do catálogo externo). Todas as rotas exigem autenticação. Endpoints de catálogo externo não substituem o catálogo oficial da plataforma.

Quando usar os endpoints Products ?

Quando for necessário ligar ou desligar disponibilidade de SKU no PDV (catálogo gerenciado pelo parceiro, conforme escopo) ou, no catálogo externo, de produtos ou options (variantes/toppings) criados pela integração.
Quando precisar criar ou atualizar itens de produto por estabelecimento, ajustar oferta (preço/desconto) de um item ou fazer upsert em lote de itens ou promoções para vários merchants.
Quando for preciso listar itens do menu de um merchant com paginação e filtro por identificadores externos.
Quando a integração usar catálogo externo: sincronização em lote de SKUs, atualização de preço de produto ou de option por externalCode, conforme contrato da vertical.

Quando não usar os endpoints Products ?

Para pedidos (consulta, confirmação, cancelamento) — use o grupo Orders e, para sincronização de mudanças, Events.
Para abrir ou fechar o estabelecimento (PDV) — use Merchants (availability do merchant), não a disponibilidade de produto individual.
Para obter ou renovar token — use Authentication (client_credentials).
Para SKUs do catálogo padrão do Zé ou fluxos fora do escopo acordado — não use rotas de catálogo externo nem operações de item sem autorização explícita.

Como os endpoints de Products se relacionam

No fluxo padrão, costuma-se consultar o menu (GET), criar ou atualizar itens (POST/PUT por merchant), ajustar disponibilidade ou oferta quando aplicável, e usar upsert em lote ou promos para sincronização ampla. No catálogo externo, o fluxo típico é upsert do catálogo em lote, seguido de ajustes pontuais de preço e disponibilidade de produtos e options.

flowchart TB
  subgraph padrao["Catálogo padrão / parceiro"]
    direction TB
    M["GET /merchants/{merchantId}/menu/items — listar menu"]
    A["POST /merchants/{merchantId}/products/availability — on/off SKU"]
    C["POST /merchants/{merchantId}/products/items — criar item"]
    U["PUT /merchants/{merchantId}/products/items — atualizar item"]
    O["POST /merchants/{merchantId}/products/itemOffer — oferta/preço"]
    B["PUT /merchants/products/items — upsert em lote"]
    P["PUT /merchants/products/promos — promoções em lote"]
    M --> A --> C --> U --> O --> B --> P
  end

flowchart TB
  subgraph ext["Catálogo externo"]
    direction TB
    E1["PUT /external-catalog/catalog/products — upsert em lote"]
    E2["POST /external-catalog/merchants/{merchantId}/products/availability — disponibilidade SKU"]
    E3["POST /external-catalog/merchants/{merchantId}/options/availability — disponibilidade option"]
    E4["PUT /external-catalog/merchants/{merchantId}/products/{externalCode}/price — preço SKU"]
    E5["PUT /external-catalog/merchants/{merchantId}/options/{externalCode}/price — preço option"]
    E1 --> E2 --> E3 --> E4 --> E5
  end

Em ambos os quadros, a cadeia vertical é ordem sugerida de leitura, não sequência obrigatória de chamadas: use apenas os endpoints necessários ao seu fluxo (por exemplo, criar/atualizar item, disponibilidade e oferta podem ser chamados conforme a operação; em lote, upsert de itens e promos são independentes entre si quando aplicável).

Create product item

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

path Parameters

merchantId

required

string

Example: 1234

O id do estabelecimento

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

externalProductId	string Identificador do produto no sistema de origem (plataforma parceira).
name	string Nome do produto.
description	string Descrição do produto.
	Array of objects Lista de URLs de imagens do produto.
	object Informações de preço do produto. Regra de oferta: se value e originalValue forem iguais, não há oferta (preço cheio). Se forem diferentes, há oferta: o valor do desconto é ( originalValue − value ) e o percentual de desconto é esse valor dividido por originalValue, multiplicado por 100. O exemplo abaixo ilustra preço cheio (value = originalValue).
category	string Código ou slug da categoria do produto no catálogo.
tags	Array of strings Tags do produto.

Responses

Request samples

Payload

Content type

application/json

{"productId": "1234",
"externalProductId": "1234",
"name": "Nome do Produto",
"description": "Descrição do produto",
"category": "categoria",
"price": {"value": 29.9,
"originalValue": 39.9,
"currency": "BRL"
},
"images": [{"image": "https://exemplo.com/imagem.jpg",
"description": "Imagem principal"
}
],
"tags": ["tag1",
"tag2"
]
}

Response samples

Content type

application/json

{ }

Update product item

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

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

path Parameters

merchantId

required

string

Example: 1234

O id do estabelecimento

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

productId	integer O identificador do produto na plataforma Zé Delivery.
externalProductId	string Identificador do produto no sistema de origem (plataforma parceira).
name required	string Nome do produto.
description required	string Descrição do produto.
	Array of objects Lista de URLs de imagens do produto.
	object Informações de preço do produto. Regra de oferta: se value e originalValue forem iguais, não há oferta (preço cheio). Se forem diferentes, há oferta: o valor do desconto é ( originalValue − value ) e o percentual de desconto é esse valor dividido por originalValue, multiplicado por 100. O exemplo abaixo ilustra preço cheio (value = originalValue).
category required	string Código ou slug da categoria do produto no catálogo.
tags	Array of strings Tags do produto.

Responses

Request samples

Payload

Content type

application/json

{"productId": "1234",
"externalProductId": "1234",
"name": "Nome do Produto",
"description": "Descrição do produto",
"category": "categoria",
"price": {"value": 29.9,
"originalValue": 39.9,
"currency": "BRL"
},
"images": [{"image": "https://exemplo.com/imagem.jpg",
"description": "Imagem principal",
"order": 1
}
],
"tags": ["tag1",
"tag2"
]
}

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Upsert product items

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

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

required

Array of objects

Responses

Request samples

Payload

Content type

application/json

{"items": [{"merchantId": "string",
"productId": "string",
"externalProductId": "string",
"isAvailable": true,
"isFavorite": true
}
]
}

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Update product promotions

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

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

Array ()

One of

Any of

merchantId	string O id do estabelecimento
productId required	string O id do produto
externalProductId	string O id do produto externo
isEnabled required	boolean Value: true Define se a promoção está ativa ou não
percentage required	number [ 0 .. 100 ] Percentual de desconto da promoção
scheduleType required	string Enum: "ALWAYS" "WEEKDAYS" "WEEKENDS" "SUPER_FRIDAY" Tipo de agendamento da promoção

Responses

Request samples

Payload

Content type

application/json

Example

[{"merchantId": "1234",
"productId": "5678",
"isEnabled": true,
"percentage": 15.5,
"scheduleType": "ALWAYS"
}
]

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Update product availability

Objetivo

Atualizar disponibilidade (on/off) de um SKU do estabelecimento (produto ou externalProductId).

Quando usar

Quando o parceiro precisa marcar um produto específico como disponível ou indisponível no PDV.

Quando NÃO usar

Para atualizar produtos do catálogo padrão do Zé (aplicável somente a SKUs gerenciados pelo parceiro quando apropriado).

Importante

Body aceita productId (integer) ou externalProductId (string) e available boolean. Requer Authorization. Retorna 200 com objeto de confirmação.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: POST /merchants/{merchantId}/products/availability
  API-->>Parceiro: 200 com confirmação

path Parameters

merchantId

required

string

Example: 1234

O id do estabelecimento

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

productId	integer O identificador do produto na plataforma Zé Delivery.
externalProductId	string O identificador do produto em plataforma de terceiros.
available	boolean A disponibilidade do produto

Responses

Request samples

Payload

Content type

application/json

{"productId": "1234",
"externalProductId": "1234",
"available": true
}

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Get merchant items

Objetivo

Buscar itens do menu de um estabelecimento (paginação e filtro por externalProductIds).

Quando usar

Para listar produtos expostos de um merchant (paginação via page e pageSize).

Quando NÃO usar

Não usar para modificar itens; para detalhes completos do produto usar endpoints de produto.

Importante

Requer Authorization. pageSize tem limites (min=5, max=30) e page padrão = 1 segundo Swagger. Schema de resposta: merchantItemsResponse.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: GET /merchants/{merchantId}/menu/items
  API-->>Parceiro: 200 com itens paginados

path Parameters

merchantId

required

string

Example: 1234

O id do estabelecimento

query Parameters

page	number Default: 1 O número da página
pageSize	number [ 5 .. 30 ] Default: 5 O número de itens por página
externalProductIds	string Example: externalProductIds=12345,54321 Os ids externos dos itens. Retorna todos se não for informado.

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Responses

Response samples

Content type

application/json

{"currentPage": 0,
"totalPages": 0,
"totalItems": 0,
"pageSize": 0,
"items": [{"productId": 0,
"externalProductId": "string",
"name": "string",
"description": "string",
"status": "AVAILABLE",
"image": {"URL": "string"
},
"ean": "string",
"isFavorite": true,
"isPortfolioIdeal": true,
"brand": {"id": "string",
"name": "string"
},
"categories": [{"id": "string",
"name": "string"
}
],
"priceDetails": {"price": 0,
"discount": {"endsAt": "string",
"id": "string",
"startsAt": "string",
"values": [{"value": 0,
"finalUnitPrice": 0,
"minQuantity": 0,
"maxQuantity": 0,
"valueType": "FIXED_AMOUNT"
}
]
},
"sellerDiscount": {"active": true,
"percentageValues": [0
],
"current": {"createdAt": "string",
"discountPercentageValue": 0,
"id": "string",
"scheduleType": "ALWAYS",
"active": true,
"reason": "string",
"updatedAt": "string",
"username": "string"
}
},
"takeRateSeller": {"active": true,
"feeAmount": 0,
"feePercentage": 0,
"netPrice": 0
}
}
}
]
}

Update item offer

Objetivo

Atualizar/definir oferta (price/discount) de um item no estabelecimento.

Quando usar

Aplicar preço ou promoção em um item específico do merchant (price + originalValue).

Quando NÃO usar

Para alterar o catálogo global do Zé ou preços de SKUs do catálogo padrão (sem acordo).

Importante

Requer merchantId e price com value e originalValue (value > 0, originalValue ≥ value). Requer Authorization. Retorna 202 quando processado.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: POST /merchants/{merchantId}/products/itemOffer
  API-->>Parceiro: 202 quando aceito

path Parameters

merchantId

required

string

Example: 1234

O id do estabelecimento

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

productId	string O identificador do produto na plataforma Zé Delivery.
externalProductId	string Identificador do produto no sistema de origem (plataforma parceira).
required	object Informações de preço do produto. Regra de oferta: se value e originalValue forem iguais, não há oferta (preço cheio). Se forem diferentes, há oferta: o valor do desconto é ( originalValue − value ) e o percentual de desconto é esse valor dividido por originalValue, multiplicado por 100. O exemplo abaixo ilustra preço cheio (value = originalValue).

Responses

Request samples

Payload

Content type

application/json

{"productId": "1234",
"externalProductId": "1234",
"price": {"value": 29.9,
"originalValue": 39.9
}
}

Response samples

Content type

application/json

{ }

Update external catalog product availability

Objetivo

Atualizar a disponibilidade (on/off) de SKUs exclusivos criados pelo parceiro, destinados a uma vertical específica dentro do Zé Delivery.

Quando usar

Utilize este endpoint somente quando:

O SKU foi criado pelo parceiro via integração.
O SKU não existe no catálogo padrão do Zé.
O produto será consumido exclusivamente dentro da vertical associada a esta integração.

Quando NÃO usar

Este endpoint não deve ser utilizado para:

Produtos do catálogo padrão do Zé.
SKUs ABI já existentes na base.
Atualizações de disponibilidade de produtos padrão do marketplace.
Fluxos genéricos de catálogo.

Importante

Este é um endpoint específico para catálogos externos/parceiros. Ele não substitui nem altera o comportamento do catálogo oficial do Zé Delivery.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: POST /external-catalog/merchants/{merchantId}/products/availability
  API-->>Parceiro: 200 em caso de sucesso

path Parameters

merchantId

required

string

Example: 1234

O id do estabelecimento

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

productId	string O identificador do produto na plataforma Zé Delivery.
externalCode	string O código externo do produto na plataforma parceira.
available	boolean Indica se o produto está disponível.

Responses

Request samples

Payload

Content type

application/json

{"productId": "1234",
"externalCode": "1234",
"available": true
}

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Update external catalog option price

Objetivo

Atualizar o preço de uma option (variante/topping) pertencente a um SKU exclusivo do catálogo externo, identificado por externalCode.

Quando usar

Utilize este endpoint somente quando:

A option (variante) pertence a um SKU criado via integração externa.
O parceiro precisa ajustar preços de variantes/toppings gerenciadas no catálogo externo.

Quando NÃO usar

Este endpoint não deve ser utilizado para:

Atualizar preços de produtos do catálogo padrão do Zé.
Atualizações de pricing em SKUs ABI já cadastrados.
Atualizações massivas do marketplace fora do escopo do catálogo externo.

Importante

Método: PUT. Path: /external-catalog/merchants/{merchantId}/options/{externalCode}/price. Autenticação: header Authorization: Bearer <token> obrigatório. Parâmetros: merchantId (path); externalCode (path) — identificador da option no catálogo do parceiro. Body (application/json): objeto price com campos mínimos: value (number) — preço atual (obrigatório). originalValue (number) — preço original (obrigatório quando aplicável). currency (string) — ex.: BRL (recomendado). Respostas comuns: 202 Accepted (processamento assíncrono), 400, 401, 403, 404, 422, 500. Observações: alteração aplica-se somente à option identificada por externalCode; validar se a option existe no catálogo externo antes de enviar.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: PUT /external-catalog/merchants/{merchantId}/options/{externalCode}/price
  API-->>Parceiro: 202 ou código de erro conforme validação

path Parameters

merchantId required	string Example: 1234 O id do estabelecimento
externalCode required	string Example: 1234 O código externo do produto (option) a ser atualizado, definido pelo parceiro e único dentro do catálogo externo.

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

price

number

O preço final do produto

Responses

Request samples

Payload

Content type

application/json

{"price": 29.9
}

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Update external catalog product price

Objetivo

Atualizar o preço de venda de um SKU exclusivo criado pelo parceiro, identificado por externalCode.

Quando usar

Utilize este endpoint somente quando:

O SKU foi criado via integração externa e não existe no catálogo oficial do Zé.
For necessário ajustar o preço de venda do SKU em produção.

Quando NÃO usar

Este endpoint não deve ser utilizado para:

Atualizar preços de SKUs do catálogo padrão do Zé.
Alterar preços de itens que são compartilhados entre verticais sem autorização.

Importante

Método: PUT. Path: /external-catalog/merchants/{merchantId}/products/{externalCode}/price. Autenticação: header Authorization: Bearer <token> obrigatório. Parâmetros: merchantId (path); externalCode (path) — identificador do SKU no sistema do parceiro. Body (application/json): objeto price com campos mínimos: value (number) — preço final cobrado. originalValue (number) — preço original (sem desconto), quando aplicável. currency (string) — ex.: BRL. Respostas: 202 Accepted (assíncrono) ou 200/4xx/5xx conforme validação/erro. Observações: payload deve obedecer às regras de preço (ex.: value > 0; se originalValue informado calcule desconto conforme regra local). Garantir que o externalCode aponta para um SKU gerenciado pelo parceiro.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: PUT /external-catalog/merchants/{merchantId}/products/{externalCode}/price
  API-->>Parceiro: 202 ou resposta conforme validação

path Parameters

merchantId required	string Example: 1234 O id do estabelecimento
externalCode required	string Example: 1234 O código externo do produto a ser atualizado, definido pelo parceiro e único dentro do catálogo externo.

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

price	number Preço final (valor cobrado). Com oferta, é o valor já com desconto; sem oferta, coincide com originalValue. Deve ser > 0.
fullPrice	number Preço original (sem desconto). Igual a price quando não há oferta. Deve ser > 0.

Responses

Request samples

Payload

Content type

application/json

{"price": 29.9,
"fullPrice": 39.9
}

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Upsert external catalog products

Objetivo

Realizar upsert (criação/atualização em lote) do catálogo exclusivo do parceiro — sincronização em lote de SKUs destinados à vertical da integração.

Quando usar

Utilize este endpoint somente quando:

For necessário fazer onboarding inicial do catálogo exclusivo do parceiro.
Realizar sincronizações periódicas de muitos SKUs (bulk) criados pelo parceiro.
O catálogo enviado refere-se exclusivamente a produtos que não existem no catálogo oficial do Zé.

Quando NÃO usar

Este endpoint não deve ser utilizado para:

Criar ou atualizar produtos do catálogo padrão do Zé.
Sincronizações de SKUs que já pertençam ao marketplace padrão ou que sejam compartilhados entre verticais.
Operações unitárias frequentes (usar endpoints unitários para updates single-item).

Importante

Método: PUT. Path: /external-catalog/catalog/products. Autenticação: header Authorization: Bearer <token> obrigatório. Body (application/json): array de objetos produto (bulk). Para cada produto, seguir o schema do catálogo externo (identificadores externalProductId/externalCode, name, description, price, images, options, etc.). Respostas: normalmente 202 Accepted (processamento assíncrono); 400, 401, 403, 422 por item ou geral; 500 para erro servidor. Observações técnicas: Endpoint é assíncrono — processamento em background; cada item pode ter validações individuais que resultem em erros parciais. Monitorar mensagens/erros de retorno/reporting. Respeitar limites operacionais (tamanho de payload/rate limits) definidos por contrato técnico — validar antes de enviar lotes muito grandes. Mantém isolamento por vertical: não cria nem altera o catálogo oficial do Zé.

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

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

merchantId	string O id do estabelecimento
brandId	integer O id da marca do produto
externalProductId	string Identificador do produto no sistema de origem (plataforma parceira).
title	string Nome do produto.
description	string Descrição do produto.
	Array of objects Lista de URLs de imagens do produto.
	object Informações de preço do produto. Regra de oferta: se value e originalValue forem iguais, não há oferta (preço cheio). Se forem diferentes, há oferta: o valor do desconto é ( originalValue − value ) e o percentual de desconto é esse valor dividido por originalValue, multiplicado por 100. O exemplo abaixo ilustra preço cheio (value = originalValue).
category	string Código ou slug da categoria do produto no catálogo
tags	Array of strings Tags do produto
	Array of objects Default: []

Responses

Request samples

Payload

Content type

application/json

{"merchantId": "1234",
"brandId": 5678,
"externalProductId": "12345",
"title": "Nome do Produto",
"description": "Descrição do produto",
"category": "categoria",
"price": {"value": 29.9,
"originalValue": 39.9,
"currency": "BRL"
},
"images": [{"image": "https://exemplo.com/imagem.jpg",
"description": "Imagem principal"
}
],
"tags": ["tag1",
"tag2"
],
"optionGroups": [{"externalOptionGroupId": "1234",
"name": "Nome da opção",
"description": "Descrição da opção",
"maxPermitted": 2,
"minPermitted": 1,
"presentationType": "SELECT",
"active": true,
"index": 0,
"options": [{"externalOptionId": "1234",
"description": "Opção 1",
"maxPermitted": 1,
"price": 5,
"active": true,
"index": 0,
"isAvailable": true
},
{"externalOptionId": "5678",
"description": "Opção 2",
"maxPermitted": 1,
"price": 10,
"active": true,
"index": 1,
"isAvailable": true
}
]
}
]
}

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Update external catalog option availability

Objetivo

Controlar a disponibilidade granular (on/off) de options (variantes/toppings) de SKUs exclusivos do parceiro.

Quando usar

Utilize este endpoint somente quando:

For necessário marcar uma option como disponível ou indisponível para um merchant específico.
A option pertence a um SKU gerenciado no catálogo externo.

Quando NÃO usar

Este endpoint não deve ser utilizado para:

Controlar availability de opções que pertencem a produtos do catálogo padrão do Zé.
Controlar options em escala global fora do escopo da vertical de integração.

Importante

Método: POST. Path: /external-catalog/merchants/{merchantId}/options/availability. Autenticação: header Authorization: Bearer <token> obrigatório. Parâmetros: merchantId (path). Body (application/json): objeto com externalOptionCode ou identificador equivalente e available boolean. Respostas: 200 OK em caso de sucesso; 400, 401, 403, 404, 422, 500 conforme validações/erros. Observações: alteração afeta somente a option no contexto do merchant e da vertical; validar existência da option no catálogo externo antes de executar.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: POST /external-catalog/merchants/{merchantId}/options/availability
  API-->>Parceiro: 200 em caso de sucesso

path Parameters

merchantId

required

string

Example: 1234

O id do estabelecimento

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

optionId	string O identificador da opção na plataforma Zé Delivery.
available	boolean Indica se a opção está disponível.

Responses

Request samples

Payload

Content type

application/json

{"optionId": "1234",
"available": true
}

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Events

Sobre Events

Os endpoints do grupo Events da Seller Public API expõem o fluxo de sincronização assíncrona de mudanças de status de pedidos no Zé Delivery por meio de consultas periódicas (polling) e de confirmação de consumo (ack) dos eventos já processados. É voltado a parceiros que precisam acompanhar o ciclo dos pedidos sem depender de webhook.

Quando usar os endpoints Events ?

Quando for necessário consumir valores de status e eventos retornados pela API (CREATED, CONFIRMED, EDITED, READY_FOR_PICKUP, DISPATCHED, CANCELLED e CONCLUDED).
Quando o modelo de integração do parceiro for polling em vez de webhook.

Eventos de pedido

Os eventos de pedido representam mudanças relevantes no ciclo de vida do pedido e são retornados em eventType. Para obter os detalhes e o estado atual do pedido, consulte a orderURL recebida no evento ou GET /orders/{orderNumber}.

Valor retornado pela API	Descrição	Validade por tipo de pedido
`CREATED`	Pedido realizado e inserido na fila de aceite do PDV; também pode ter sido transferido ao PDV atual após rejeição de outro PDV.	`DELIVERY`, `TURBO`, `TAKEOUT`
`CONFIRMED`	Confirmação de que o PDV aceitou o pedido.	`DELIVERY`, `TURBO`, `TAKEOUT`
`EDITED`	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.	`DELIVERY`, `TURBO`, `TAKEOUT`
`READY_FOR_PICKUP`	O pedido já foi coletado pela pessoa entregadora. Atualmente, o Zé Delivery não possui um status que represente “pronto para coleta”	`DELIVERY`, `TURBO`
`DISPATCHED`	A pessoa entregadora iniciou a rota para o endereço de entrega.	`DELIVERY`, `TURBO`
`CANCELLED`	Pedido cancelado por cliente, pessoa entregadora, PDV, time interno do Zé Delivery ou expiração (conforme regras operacionais)	`DELIVERY`, `TURBO`, `TAKEOUT`
`CONCLUDED`	Pedido entregue com sucesso.	`DELIVERY`, `TURBO`, `TAKEOUT`

Como os endpoints de Events se relacionam

O fluxo típico é consultar eventos pendentes, processar cada evento na sua aplicação e confirmar o consumo para que esses eventos não voltem nas próximas consultas.

flowchart LR
  P["GET /events:polling — lista eventos pendentes"] --> B["Sua aplicação processa cada evento"]
  B --> A["POST /events/acknowledgment - Sua aplicação confirma que processou o evento"]
  A --> P

Events polling

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

query Parameters

eventType

Array of strings (OrderStatusEnum)

Items Enum: "CREATED" "CONFIRMED" "EDITED" "READY_FOR_PICKUP" "DISPATCHED" "CANCELLED" "CONCLUDED"

Example: eventType=CREATED

Status dos eventos do pedido

header Parameters

x-polling-merchants required	array Example: 123,1234 Os ids dos estabelecimentos requirido.
Authorization required	string token de autenticação para acessar o recurso

Responses

Response samples

Content type

application/json

[{"eventId": "3e7224ac-bec0-4fe1-88d1-6348c8149c44",
"orderId": 123456789,
"orderURL": "https://seller-public-api.ze.delivery/orders/123456789",
"eventType": "CREATED",
"sourceAppId": "",
"createdAt": "2021-09-15T19:51:57.851343",
"mocked": true
}
]

Events acknowledgment

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)

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

Array ()

id	string O número do evento na plataforma
orderId	number O número do pedido na plataforma
eventType	string (OrderStatusEnum) Enum: "CREATED" "CONFIRMED" "EDITED" "READY_FOR_PICKUP" "DISPATCHED" "CANCELLED" "CONCLUDED" Valores de status e eventos retornados pela API: CREATED indica pedido realizado e na fila de aceite do PDV, inclusive quando transferido de outro PDV; CONFIRMED, aceite pelo PDV; 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; READY_FOR_PICKUP, o pedido já foi coletado pela pessoa entregadora. Atualmente, o Zé Delivery não possui um status que represente pronto para coleta; DISPATCHED, pessoa entregadora em rota; CANCELLED, pedido cancelado por cliente, pessoa entregadora, PDV, time interno do Zé Delivery ou expiração (conforme regras operacionais); e CONCLUDED, entrega concluída. CREATED, CONFIRMED, EDITED, CANCELLED e CONCLUDED são válidos para DELIVERY, TURBO e TAKEOUT; READY_FOR_PICKUP e DISPATCHED, para DELIVERY e TURBO.

Responses

Request samples

Payload

Content type

application/json

[{"id": "3e7224ac-bec0-4fe1-88d1-6348c8149c44",
"orderId": 123456789,
"eventType": "CREATED"
}
]

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Webhook — POST recebido na sua URL

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

header Parameters

X-App-Signature required	string Example: sha256=a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456 é a assinatura de integridade da requisição: calculada com SHA-256 sobre o timestamp e o payload bruto do JSON recebidos no corpo da requisição, usando como segredo o valor `hash` obtido na criação do webhook via `PATCH /webhooks`. O cabeçalho costuma seguir o padrão `sha256=<digest_hexadecimal>`.
X-App-Timestamp required	number Example: 1714857600 Timestamp da requisição em segundos (Unix timestamp). Utilize para validar o `X-App-Signature`.
Content-Type required	string Value: "application/json" Tipo de mídia do corpo.

Request Body schema: application/json

clientId required	string <uuid> Identificador do cliente OAuth na plataforma.
eventType required	string (WebhookSubscriptionType) Value: "ORDER_EVENTS" Tipo de inscrição do webhook.
correlationId required	string Identificador de correlação da entrega (rastreabilidade entre tentativas e logs).
	object Carga útil específica do tipo de notificação. Para `ORDER_EVENTS`, contém o evento de pedido.

Responses

Request samples

Payload

Content type

application/json

{"clientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"eventType": "ORDER_EVENTS",
"correlationId": "9f2e4c1a-8b7d-4e6f-9a0b-1c2d3e4f5a6b",
"data": {"eventId": "3e7224ac-bec0-4fe1-88d1-6348c8149c44",
"eventType": "CONFIRMED",
"orderId": 123456789,
"createdAt": "2021-09-15T19:51:57.851343Z",
"merchantId": "merchant-uuid"
}
}

Webhooks

Sobre Webhooks

Os endpoints do grupo Webhooks permitem consultar e criar/atualizar a configuração de entrega de eventos para a URL do seu sistema.

Configurações

Quando active está habilitado, o Zé passa a enviar eventos para a URL que o voce configurou; com active desabilitado, não há envio para esse endpoint.

Além de active habilitado, é necessário definir quais eventos você deseja receber. Use o PATCH /webhooks e configure os eventos no campo subscribedEvents.

Política de resposta HTTP, retries e acknowledgment

Em caso de entrega bem-sucedida — ou seja, enviamos o evento para a URL configurada e ela retornou sucesso —, o evento é tratado como consumido, então é feito o acknowledgment e deixa de aparecer no polling do grupo Events.

Abaixo estão os casos que seguimos em cada status de resposta que veio da sua API:

Qualquer status 2xx é interpretado como processamento com sucesso; nesse caso fazemos o ack do evento (ele não volta no polling).
Se a sua URL responder 404, não realizamos novas tentativas de envio: consideramos que a rota não existe no endpoint configurado.
Para qualquer outro status de erro (resposta que não seja 2xx e que não seja esse caso de 404), realizamos até 3 tentativas de entrega.

Validação de autenticidade do evento

Nas requisições HTTP para a sua API são enviados os headers X-App-Signature e X-App-Timestamp.

O X-App-Timestamp é o instante do envio em segundos (timestamp Unix), útil por exemplo para limitar janelas de replay no seu lado.

O X-App-Signature é a assinatura de integridade da requisição: calculada com SHA-256 sobre o timestamp e o payload bruto do JSON recebidos no corpo da requisição, usando como segredo o valor hash obtido na criação do webhook via PATCH /webhooks. O cabeçalho costuma seguir o padrão sha256=<digest_hexadecimal>.

Para validar, reproduza o digest com o timestamp + corpo bruto ({timestamp}.{body}) e o mesmo segredo hash, compare com o valor em X-App-Signature (após o prefixo sha256=) e só então processe o evento.

Quando usar os endpoints Webhooks?

Quando quiser receber notificações em tempo real na sua própria URL em vez de depender só de consultas periódicas.
Para ativar ou pausar o envio (active), alterar a URL ou ajustar os tipos de evento (subscribedEvents no PATCH; na resposta e na listagem, subscriptions).
Para obter a configuração atual (incluindo hash para validação de assinatura), use a listagem.

Como os endpoints de Webhooks se relacionam

O fluxo típico é definir ou atualizar a configuração com PATCH /webhooks e, quando necessário, consultar o estado com GET /webhooks. Após a primeira criação, guarde o hash retornado para validar o cabeçalho X-App-Signature nas entregas.

flowchart TD
  D["POST na sua URL quando active = true"]
  D --> R{"Status HTTP?"}
  R -->|2xx| A["Ack — evento some do polling"]
  R -->|404| N["Sem retry — rota inexistente"]
  R -->|Outro erro| T["Até 3 tentativas de envio"]

Configurar webhook

Objetivo

Registrar ou atualizar a configuração de webhook do cliente autenticado na Seller Public API: URL de entrega dos eventos, se o webhook está ativo e quais categorias de eventos o parceiro deseja receber.

Quando usar

Quando o parceiro optar por notificações enviadas pela plataforma para um endpoint próprio em substituição ao fluxo de polling.

Quando NÃO usar

Não usar apenas para ler a configuração atual — para isso utilize GET /webhooks. Este endpoint não entrega a fila de eventos; ele apenas persiste a política de entrega (URL, ativo, inscrições).

Importante

Cada credencial de cliente mantém uma única configuração de webhook (comportamento de upsert). Na primeira criação, a resposta inclui o campo hash (segredo em hexadecimal) usado para validar entregas no seu endpoint; nas atualizações seguintes, o hash não é devolvido no corpo — armazene o segredo com segurança na primeira resposta bem-sucedida. O campo endpoint é obrigatório e deve ser uma URI válida. É necessário header Authorization com token válido para a API.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: PATCH /webhooks
  API-->>Parceiro: 200 — configuração persistida

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

endpoint required	string <uri> URL que receberá as notificações do webhook.
active	boolean Indica se o webhook está ativo. Se omitido, o padrão no registro é `false`.
subscribedEvents	Array of strings (WebhookSubscriptionType) Items Value: "ORDER_EVENTS" Lista de tipos de eventos inscritos. Se omitido, a lista fica vazia.

Responses

Request samples

Payload

Content type

application/json

{"endpoint": "https://partner.com/webhook",
"active": true,
"subscribedEvents": ["ORDER_EVENTS"
]
}

Response samples

Content type

application/json

{"clientId": "5e505642-9024-474d-9434-e5a44f505cc5",
"hash": "string",
"endpoint": "http://example.com",
"active": true,
"subscriptions": ["ORDER_EVENTS"
]
}

Listar webhook do cliente

Objetivo

Consultar a configuração de webhook associada ao cliente autenticado na Seller Public API.

Quando usar

Para exibir ou auditar URL, estado ativo/inativo e inscrições de eventos em painéis ou ferramentas internas. Para confirmar se já existe webhook cadastrado antes de um PATCH /webhooks, ou para recuperar o hash quando a configuração já existia e o segredo ainda é o mesmo persistido na plataforma.

Quando NÃO usar

Não lista eventos como no GET - events:polling. Para criar ou alterar as configurações do webhook, use PATCH /webhooks.

Importante

Se não houver registro, a resposta é um array vazio. Quando há configuração, a API retorna um array com exatamente um objeto contendo identificação do cliente, segredo, endpoint, indicador de ativo e lista de inscrições. Requer header Authorization com token válido.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: GET /webhooks
  API-->>Parceiro: 200 — array com 0 ou 1 item

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Responses

Response samples

Content type

application/json

[{"clientId": "5e505642-9024-474d-9434-e5a44f505cc5",
"hash": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6ab",
"endpoint": "http://example.com",
"active": true,
"subscriptions": ["ORDER_EVENTS"
]
}
]

Orders

Sobre Orders

Os endpoints do grupo Orders da Seller Public API concentram o ciclo de vida operacional de um pedido no Zé Delivery: consulta dos detalhes a partir do número do pedido na plataforma, confirmação de aceite pelo estabelecimento ou parceiro e solicitação de cancelamento ou rejeição com código de motivo. Quando habilitados para a sua integração, entram ainda a edição e a restauração de itens após a confirmação. Todas as rotas exigem autenticação e referenciam o pedido pelo identificador na plataforma.

Quando usar os endpoints Orders ?

Quando for necessário consultar estado e dados completos de um pedido para o qual você já possui o número válido na plataforma.
Quando o estabelecimento precisar aceitar o pedido ou solicitar cancelamento ou rejeição com código adequado ao status e às regras de negócio.
Quando, após a confirmação, for preciso ajustar itens (remoção ou substituição) ou restaurar a composição anterior do pedido, conforme disponibilidade da rota para o seu caso.

Quando não usar os endpoints Orders ?

Para sincronizar mudanças de status ou evitar consultas repetidas em massa como se fosse fila de trabalho — use o grupo Events (polling e confirmação de consumo dos eventos).
Para catálogo, preço ou disponibilidade de produtos — use Products e Merchants quando aplicável.
Para obter ou renovar token — use Authentication (client_credentials).

Como os endpoints de Orders se relacionam

O fluxo típico é consultar o pedido, confirmar ou solicitar cancelamento. Depois da confirmação, quando aplicável, seguem passos opcionais de atualização de itens e restauração.

flowchart TD
  G["GET /orders/{orderNumber} — detalhes do pedido"] --> D{"Decisão do parceiro"}
  D -->|Aceitar| C["POST /orders/{orderNumber}/confirm — aceite do pedido"]
  D -->|Rejeitar ou solicitar cancelamento| R["POST /orders/{orderNumber}/requestCancellation — solicitação com motivo"]
  C --> I{"Ajustar itens?"}
  I -->|Sim| U["PUT /orders/{orderNumber}/items — atualização de itens"]
  U --> Z{"Desfazer edição?"}
  Z -->|Sim| S["POST /orders/{orderNumber}/restore — restaurar composição"]
  I -->|Não| N["Seguir operação / logística"]

Detalhes do pedido

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.

Valor retornado pela API	Descrição	Validade por tipo de pedido
`CREATED`	Pedido realizado e na fila de aceite do PDV; também pode ter sido transferido após rejeição de outro PDV.	`DELIVERY`, `TURBO`, `TAKEOUT`
`CONFIRMED`	Pedido aceito pelo PDV.	`DELIVERY`, `TURBO`, `TAKEOUT`
`EDITED`	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.	`DELIVERY`, `TURBO`, `TAKEOUT`
`READY_FOR_PICKUP`	O pedido já foi coletado pela pessoa entregadora. Atualmente, o Zé Delivery não possui um status que represente “pronto para coleta”	`DELIVERY`, `TURBO`
`DISPATCHED`	Pessoa entregadora iniciou a rota para o endereço de entrega.	`DELIVERY`, `TURBO`
`CANCELLED`	Pedido cancelado por cliente, pessoa entregadora, PDV, time interno do Zé Delivery ou expiração (conforme regras operacionais)	`DELIVERY`, `TURBO`, `TAKEOUT`
`CONCLUDED`	Pedido entregue com sucesso.	`DELIVERY`, `TURBO`, `TAKEOUT`

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

path Parameters

orderNumber

required

string >= 9

Example: 123456789

O número do pedido na plataforma Zé Delivery

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Responses

Response samples

Content type

application/json

{"displayId": "123457890",
"status": "CREATED",
"type": "DELIVERY",
"salesChannel": "DEFAULT",
"createdAt": "2021-09-15T19:51:57.851343",
"orderTiming": "INSTANT",
"merchant": {"id": 12345
},
"items": [{"id": 12345,
"index": 3,
"name": "Refrigerante de Limão 2L",
"externalCode": "12345",
"category": {"id": 0
},
"unit": "UNIT",
"quantity": 1,
"hasLimitedPromotion": false,
"unitPrice": {"value": 10,
"currency": "R$"
},
"totalPrice": {"value": 10,
"currency": "R$"
}
}
],
"otherFees": [{"name": "Frete",
"type": "DELIVERY_FEE",
"receivedBy": "MERCHANT",
"price": {"value": 10,
"currency": "R$"
},
"observation": "string"
}
],
"discounts": [{"amount": {"value": 10,
"currency": "R$"
},
"target": "CART"
}
],
"coupon": {"total": 0,
"code": "string",
"description": "string"
},
"total": {"itemsPrice": {"value": 10,
"currency": "R$"
},
"otherFees": {"value": 10,
"currency": "R$"
},
"discount": {"value": 10,
"currency": "R$"
},
"orderAmount": {"value": 10,
"currency": "R$"
},
"change": {"value": 10,
"currency": "R$"
}
},
"payments": {"methods": [{"value": 10,
"currency": "R$",
"type": "PENDING",
"method": "CASH"
}
]
},
"customer": {"phone": {"number": "5511912345678"
},
"name": "Maria",
"documentNumber": "12345678901",
"email": "email@email.com"
},
"delivery": {"deliveredBy": "MERCHANT",
"pickupCode": "",
"deliveryAddress": {"country": "Brazil",
"streetName": "Rua Estados Unidos",
"formattedAddress": "Rua Estados Unidos, 99 - São Paulo - SP",
"streetNumber": "99",
"city": "São Paulo",
"postalCode": "01234578",
"coordinates": {"latitude": -41.485,
"longitude": -39.485
},
"neighborhood": "Jardim das Orquídeas",
"state": "SP",
"complement": "AP 123"
},
"schedule": {"scheduledDateTimeStart": "2021-09-15T19:51:57.851343",
"scheduledDateTimeEnd": "2021-09-15T19:51:57.851343"
},
"returnDate": "30/03/2026"
},
"takeout": {"mode": "`DEFAULT`",
"takeoutDateTime": "2021-09-15T19:51:57.851343"
},
"serviceFee": {"total": 5,
"isHeavyBag": true
},
"extraInfo": "Trazer bem gelada",
"observations": "Substituir por item similar",
"statusHistory": [{"createdAt": "2021-09-15T19:51:57.851343",
"status": "CREATED"
}
]
}

Confirmar 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

path Parameters

orderNumber

required

string >= 9

Example: 123456789

O número do pedido na plataforma Zé Delivery

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

reason	string Campo livre para informações sobre a confirmação do pedido
orderExternalCode	string Código externo do pedido que pode ser usada como referência
createdAt	string Data e hora da criação do pedido
preparationTime	number Indica o tempo de preparação do pedido em minutos

Responses

Request samples

Payload

Content type

application/json

{"reason": "string",
"orderExternalCode": "string",
"createdAt": "2021-09-15T19:51:57.851343",
"preparationTime": 0
}

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Solicitar cancelamento do pedido

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

path Parameters

orderNumber

required

string >= 9

Example: 123456789

O número do pedido na plataforma Zé Delivery

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

code

string

Enum: "SYSTEMIC_ISSUES" "DUPLICATE_APPLICATION" "UNAVAILABLE_ITEM" "RESTAURANT_WITHOUT_DELIVERY_PERSON" "ORDER_OUTSIDE_THE_DELIVERY_AREA" "BLOCKED_CUSTOMER" "INTERNAL_DIFFICULTIES_OF_THE_RESTAURANT" "RISK_AREA" "DELIVERY_PROBLEM"

Os códigos de razão de cancelamento, SYSTEMIC_ISSUES para problemas sistêmicos, DUPLICATE_APPLICATION para pedidos duplicados, UNAVAILABLE_ITEM para itens indisponíveis, RESTAURANT_WITHOUT_DELIVERY_PERSON para estabelecimento sem entregador, ORDER_OUTSIDE_THE_DELIVERY_AREA para pedidos fora da área de entrega, BLOCKED_CUSTOMER para clientes bloqueados, INTERNAL_DIFFICULTIES_OF_THE_RESTAURANT para dificuldades internas do estabelecimento, RISK_AREA para áreas de risco e DELIVERY_PROBLEM para problemas de entrega. Atenção, o cancelamento pode desencadear diferentes fluxos dependendo do status atual do pedido. Caso o pedido já tenha sido confirmado, apenas os seguintes códigos serão aceitos: UNAVAILABLE_ITEM, ORDER_OUTSIDE_THE_DELIVERY_AREA, INTERNAL_DIFFICULTIES_OF_THE_RESTAURANT e DELIVERY_PROBLEM. Caso o pedido não tenha sido confirmado, apenas os seguintes códigos serão aceitos: INTERNAL_DIFFICULTIES_OF_THE_RESTAURANT, UNAVAILABLE_ITEM e RESTAURANT_WITHOUT_DELIVERY_PERSON.

Responses

Request samples

Payload

Content type

application/json

{"code": "UNAVAILABLE_ITEM"
}

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Histórico de pedidos finalizados do estabelecimento

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.

Valor retornado pela API	Descrição	Validade por tipo de pedido
`CREATED`	Pedido realizado e na fila de aceite do PDV; também pode ter sido transferido após rejeição de outro PDV.	`DELIVERY`, `TURBO`, `TAKEOUT`
`CONFIRMED`	Pedido aceito pelo PDV.	`DELIVERY`, `TURBO`, `TAKEOUT`
`EDITED`	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.	`DELIVERY`, `TURBO`, `TAKEOUT`
`READY_FOR_PICKUP`	O pedido já foi coletado pela pessoa entregadora. Atualmente, o Zé Delivery não possui um status que represente “pronto para coleta”	`DELIVERY`, `TURBO`
`DISPATCHED`	Pessoa entregadora iniciou a rota para o endereço de entrega.	`DELIVERY`, `TURBO`
`CANCELLED`	Pedido cancelado por cliente, pessoa entregadora, PDV, time interno do Zé Delivery ou expiração (conforme regras operacionais)	`DELIVERY`, `TURBO`, `TAKEOUT`
`CONCLUDED`	Pedido entregue com sucesso.	`DELIVERY`, `TURBO`, `TAKEOUT`

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

path Parameters

merchantId

required

string

Example: 1234

O id do estabelecimento

query Parameters

startDate	string <date-time> Example: startDate=2026-04-01T00:00:00.000Z Data inicial do período de consulta no formato ISO 8601 (UTC). Quando não informada, é considerada 30 dias antes de `endDate`. Não pode ser anterior a 6 meses contados a partir da data atual.
endDate	string <date-time> Example: endDate=2026-05-01T00:00:00.000Z Data final do período de consulta no formato ISO 8601 (UTC). Quando não informada, é considerada a data/hora atual. Deve ser maior ou igual a `startDate`, e o intervalo entre `startDate` e `endDate` não pode exceder 3 meses por consulta.
page	integer >= 1 Default: 1 O número da página, iniciando em 1.
pageSize	integer [ 1 .. 50 ] Default: 20 O número de itens por página.
sort	string Enum: "asc" "desc" Ordenação dos pedidos pela data de criação. `asc` para ordem crescente e `desc` para ordem decrescente.

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Responses

Response samples

Content type

application/json

{"page": 1,
"pageSize": 20,
"hasNext": true,
"items": [{"number": "123457890",
"date": "2026-04-15T19:51:57.851Z",
"customerName": "João Silva",
"status": "CREATED",
"deliveryType": "DELIVERY",
"payment": {"type": "CASH",
"category": "PENDING"
},
"total": 89.9,
"subTotal": 79.9,
"discount": 5,
"discountDescription": "PROMO10",
"shippingFee": 7.9,
"extraContribution": 4.5,
"rating": {"value": 5,
"description": "Atendimento ótimo",
"reasons": ["FAST_DELIVERY"
]
},
"customerComment": "Sem cebola, por favor.",
"items": [{"name": "Cerveja Brahma 600ml",
"quantity": 2,
"unitPrice": 9.9,
"subTotal": 19.8
}
],
"statusHistory": [{"status": "CREATED",
"date": "2026-04-15T20:01:11.000Z",
"description": "Pedido aceito pelo estabelecimento.",
"reasons": ["OUT_OF_RANGE"
]
}
]
}
]
}

Restaurar pedido editado

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

path Parameters

orderNumber

required

string >= 9

Example: 123456789

O número do pedido na plataforma Zé Delivery

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Responses

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Atualizar itens do pedido

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

path Parameters

orderNumber

required

string >= 9

Example: 123456789

O número do pedido na plataforma Zé Delivery

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

	Array of objects (UpdateOrderItem) <= 30 items Lista de itens a serem removidos do pedido.
	Array of objects <= 30 items Lista de substituições de itens do pedido.

Responses

Request samples

Payload

Content type

application/json

{"removedItems": [{"productId": "12345",
"externalProductId": "ext-12345",
"quantity": 2,
"hasLimitedPromotion": false
}
],
"replacedItems": [{"currentItem": {"productId": "12345",
"externalProductId": "ext-12345",
"quantity": 2,
"hasLimitedPromotion": false
},
"newItem": {"productId": "12345",
"externalProductId": "ext-12345",
"quantity": 2
}
}
]
}

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Logistics

Sobre Logistics

Os endpoints do grupo Logistics da Seller Public API concentram o ciclo de vida operacional da entrega de um pedido no Zé Delivery: consulta dos detalhes de entrega, rastreamento passo a passo do entregador (coleta no PDV, início de rota, chegada ao destino e finalização), validação do código de entrega e cancelamento pelo entregador quando a entrega não puder ser concluída. Todas as rotas exigem autenticação e referenciam o pedido pelo identificador na plataforma.

Quando usar os endpoints Logistics ?

Quando for necessário consultar dados operacionais da entrega de um pedido, incluindo entregador, pickupCode e endereço de destino.
Quando o sistema de logística precisar reportar cada etapa da jornada do entregador: coleta no PDV, início de rota, chegada ao endereço do cliente e conclusão da entrega.
Quando for necessário validar o código de entrega (deliveryCode) apresentado no momento da retirada ou entrega.
Quando o entregador não conseguir completar a entrega e precisar solicitar o cancelamento com o motivo apropriado.

Quando não usar os endpoints Logistics ?

Para aceitar, rejeitar ou cancelar pedidos administrativamente — use o grupo Orders (/orders/{orderNumber}/confirm, /requestCancellation, /cancel).
Para sincronizar eventos de status de pedido ou substituir polling de fila — use o grupo Events.
Para consultar ou alterar catálogo, preços ou disponibilidade de produtos — use Products e Merchants.
Para obter ou renovar token — use Authentication (client_credentials).

Como os endpoints de Logistics se relacionam

O fluxo típico começa com a consulta dos detalhes de entrega, que fornece o pickupCode necessário para a coleta no PDV. Em seguida, o entregador coleta o pedido, inicia a rota, sinaliza chegada ao destino e valida o código de entrega. Por fim, finaliza a entrega com sucesso ou cancela por motivo operacional.

flowchart TD
  G["GET /logistics/delivery/{orderNumber} — detalhes da entrega"] --> P["POST /logistics/orderPicked/{orderNumber} — pedido coletado no PDV"]
  P --> SR["POST /logistics/startRoute/{orderNumber} — início de rota"]
  SR --> A["POST /logistics/arrived/{orderNumber} — chegada ao destino"]
  A --> VC["POST /logistics/validateCode/{orderNumber} — validar deliveryCode"]
  VC --> D{"Entrega concluída?"}
  D -->|Sim| F["POST /logistics/finishDelivery/{orderNumber} — finalizar entrega"]
  D -->|Não, problema operacional| C["POST /logistics/cancel/{orderNumber} — cancelamento pelo entregador"]

Delivery details

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)

path Parameters

orderNumber

required

string >= 9

Example: 123456789

O número do pedido na plataforma Zé Delivery

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Responses

Response samples

Content type

application/json

{"orderDisplayId": "123457890",
"customerName": "Maria",
"deliveryMan": {"email": "Maria@ze.delivery"
},
"merchant": {"id": "Maria@ze.delivery"
},
"deliveryPrice": {"price": {"value": 10,
"currency": "R$"
}
}
}

Order Picked

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

path Parameters

orderNumber

required

string >= 9

Example: 123456789

O número do pedido na plataforma Zé Delivery

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

required

string

E-mail do entregador

Responses

Request samples

Payload

Content type

application/json

{"email": "string"
}

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Start Route Order

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

path Parameters

orderNumber

required

string >= 9

Example: 123456789

O número do pedido na plataforma Zé Delivery

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

required

string

E-mail do entregador

Responses

Request samples

Payload

Content type

application/json

{"email": "string"
}

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Arrived Order

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

path Parameters

orderNumber

required

string >= 9

Example: 123456789

O número do pedido na plataforma Zé Delivery

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

required

string

E-mail do entregador

Responses

Request samples

Payload

Content type

application/json

{"email": "string"
}

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Validate Code

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

path Parameters

orderNumber

required

string >= 9

Example: 123456789

O número do pedido na plataforma Zé Delivery

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

deliveryCode

required

string

O código de entrega do pedido

Responses

Request samples

Payload

Content type

application/json

{"deliveryCode": "0406"
}

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Finish Route

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

path Parameters

orderNumber

required

string >= 9

Example: 123456789

O número do pedido na plataforma Zé Delivery

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

email required	string E-mail do entregador
lat	number Latitude da posição do entregador
long	number Longitude da posição do entregador

Responses

Request samples

Payload

Content type

application/json

{"email": "string",
"lat": 0,
"long": 0
}

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Delivery Order Cancel

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

path Parameters

orderNumber

required

string >= 9

Example: 123456789

O número do pedido na plataforma Zé Delivery

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

email required	string E-mail do entregador
reason required	string Enum: "SYSTEMIC_ISSUES" "RISK_AREA" "NOT_FOUND" "PAYMENT_ISSUE" "INCORRECT" "OTHERS" Os códigos de razão de cancelamento, `SYSTEMIC_ISSUES` para problemas sistêmicos, `RISK_AREA` para áreas de risco, `NOT_FOUND` para destinatário não encontrado, `PAYMENT_ISSUE` para problemas no pagamento, `INCORRECT` para pedidos incorretos e `OTHERS` para motivos não mapeados.

Responses

Request samples

Payload

Content type

application/json

{"email": "string",
"reason": "RISK_AREA"
}

Response samples

Content type

application/json

{"code": "string",
"title": "string",
"type": "string",
"messages": ["string"
]
}

Financials

Sobre Financials

O módulo Financials da Seller Public API reúne as informações necessárias para que parceiros integradores construam experiências financeiras para os pontos de venda do Zé Delivery, possibilitando a conciliação financeira e previsões de recebimento dos PDVs.

Os endpoints desse módulo permitem consultar dois grupos diferentes de informações:

Reembolso: valores adicionais ou deduções calculados pelo Zé de acordo com o que é ofertado na relação entre o Zé e cada PDV, como ajustes por pedido, incentivos operacionais e pagamentos manuais.
Pagamentos Online: operações financeiras referente a pedidos realizados pelo consumidor por meio de pagamento online - via Cartão cadastrado ou Pix gerado no app do Zé Delivery

Esses grupos não são excludentes, se complementam.

Como o dinheiro circula

O fluxo depende da forma de pagamento do pedido.

Pagamento na entrega

Quando o cliente paga na entrega, o valor principal do pedido é recebido:

fisicamente pelo PDV ou pessoa entregadora
ou pelo adquirente (maquininha/POS) contratado pelo próprio PDV.

Nesse caso, o Zé não é resposável pela transferência do valor principal, mas cada pedido pode gerar ajustes financeiros calculados:

markup;
diferenças de frete;
cupons e descontos;
taxas e comissões;

Etapa	Fluxo do pagamento na entrega
1	O cliente realiza o pedido.
2	O pedido é entregue.
3	O cliente paga diretamente ao PDV ou ao adquirente contratado pelo PDV.
4	O Zé calcula os ajustes financeiros aplicáveis.
5	Os ajustes entram na apuração semanal de ajustes.

Pagamento Online

Quando o cliente paga online, o pagamento é processado por um adquirente contratado pelo Zé. O valor principal do pedido segue o fluxo financeiro desse adquirente até ser transferido ao PDV, respeitando o plano de repasse contratado pelo PDV: a rotina financeira do adquirente, as datas previstas para as operações e eventuais estornos.

As previsões, entradas e saídas relacionadas ao valor principal do pedido cujo pagamento tenha passado pela adquirência online contratada pelo Zé são consultadas no endpoint de Operações de Pagamentos Online.

Mesmo em um pedido pago online, ainda podem existir reembolsos calculados pelo Zé. Por isso, a consulta das operações de Pagamento Online não substitui os três endpoints de Reembolso.

Etapa	Fluxo do Pagamento Online
1	O cliente realiza e paga o pedido online.
2	O adquirente processa o pagamento.
3	O pedido é entregue.
5	O valor principal é transferido conforme o plano de repasse e a rotina financeira aplicável.
6	Separadamente, os ajustes do pedido entram na apuração semanal de ajustes.

Incentivos e Pagamentos Manuais

Independente da forma de pagamento, o cálculo de Incentivos Operacionais e inclusão de exceções financeiras também acontecem semanalmente.

O cálculo dos repasses financeiros do Zé

Reembolsos

Os três endpoints de Reembolso apresentam partes diferentes de uma mesma apuração financeira, e trabalham por regime de competência. Eles apresentam dados apurados em relação a semanas ISO anteriores já encerradas.

Semanalmente, o motor de reembolso calcula a operação do PDV na semana anterior:

Reembolsos por pedido da semana anterior + incentivos operacionais da semana anterior + pagamentos manuais da semana anterior = resultado do reembolso a ser pago na semana atual

Se o resultado for positivo, o PDV recebe o pagamento da semana anterior na semana atual
Se o resultado for zero ou negativo, o valor do pagamento de reembolso daquela semana é zerado

Os dados de Reembolso fornecidos na API podem sofrer variações até o momento do pagamento em si. Isso pode ocorrer por falhas nas transferências bancárias, ou outros motivos de exceção que não foram previamente cobertos. Caso haja dúvidas, orientamos o PDV a entrar em contato com o suporte do Zé

Essas possíveis falhas não são informadas nos endpoints de Reembolso. Não há dados bancários reais de tentativas de transferência

Os dados calculados para a semana competência nunca são alterados

Todos os pedidos do Zé Delivery estão elegíveis à análise de Reembolso.

Pagamentos Online

As operações de Pagamentos Online informam pagamentos do valor principal do pedido em regime de caixa, tanto previsões quanto valores realizado.

É importante ressaltar que as previsões de pagamento fornecidas pelos adquirentes do Zé podem sofrer alterações dado ao calendário de dias úteis do sistema financeiro nacional. Fins de semana e feriados podem impactar o pagamento real.

O valor principal dos pedidos pagos online segue o plano de repasse combinado entre PDV e Zé, o que define:

as datas associadas às operações (vendas, estornos, parcelamentos, etc);
cobranças de taxas gerais de cada adquirente

Por isso, um mesmo PDV pode receber uma ou mais transferências de Pagamentos Online durante uma mesma semana, com competências de semanas variadas anteriores.

Somente operações de pedidos pagos via app do Zé são informadas nesse grupo de dados.

Fluxo geral

A visão de Competência dos Reembolsos + a visão de Caixa dos Pagamentos Online definem as movimentações financeiras que um PDV tem direito a receber do Zé Delivery. Demais transações de valores principais realizadas fora do aplicativo (dinheiro, maquininha/POS) não estão contempladas nestas visões.

Para os dados disponíveis, sugerimos o agrupamento semanal desses dados.

%%{init: {"themeVariables": {"fontFamily": "Roboto, sans-serif", "fontSize": "13px"}, "flowchart": {"htmlLabels": false, "curve": "basis", "nodeSpacing": 42, "rankSpacing": 38, "padding": 12}}}%%
flowchart TB
    pedido(["Pedido realizado<br/>no Zé"]) --> forma("Forma de<br/>pagamento")
    forma -->|Na entrega| entrega("Pagamento<br/>na entrega")
    forma -->|Online| online("Pagamento<br/>Online")

    entrega --> recebimento["PDV, pessoa entregadora ou<br/>adquirente recebe o valor<br/>do pedido"]
    recebimento --> ajustes("Zé calcula<br/>eventuais ajustes")

    online --> adquirente["Adquirente contratado pelo Zé<br/>processa o pagamento"]
    online --> ajustes
    adquirente --> transferencia["Valor é previsto e/ou transferido<br/>conforme o fluxo financeiro<br/>do adquirente"]
    transferencia --> operacoes("Endpoint de Operações<br/>de Pagamentos Online")
    ajustes --> endpoints("Endpoints de<br/>Reembolso")

    classDef start fill:#F3F6FA,stroke:#BBC9D5,stroke-width:1px,color:#34434F;
    classDef decision fill:#EAF3FB,stroke:#9ABDD7,stroke-width:1px,color:#285572;
    classDef delivery fill:#FDEBDD,stroke:#DFA87F,stroke-width:1px,color:#844A28;
    classDef deliveryDetail fill:#FFF6EF,stroke:#EACBB3,stroke-width:1px,color:#844A28;
    classDef online fill:#DDEFFC,stroke:#7DB5DB,stroke-width:1px,color:#17547B;
    classDef onlineDetail fill:#F0F8FE,stroke:#B5D6EA,stroke-width:1px,color:#17547B;
    classDef reimbursement fill:#E3F3E7,stroke:#88BA94,stroke-width:1px,color:#276141;

    linkStyle default stroke:#B9C3CA,stroke-width:1px;
    linkStyle 1 stroke:#DFA87F,stroke-width:1.5px;
    linkStyle 2 stroke:#7DB5DB,stroke-width:1.5px;
    linkStyle 4 stroke:#88BA94,stroke-width:1.5px;
    linkStyle 6 stroke:#88BA94,stroke-width:1.5px;

    class pedido start;
    class forma decision;
    class entrega delivery;
    class recebimento deliveryDetail;
    class online,operacoes online;
    class adquirente,transferencia onlineDetail;
    class ajustes,endpoints reimbursement;

Exemplos

Pedido feito no valor de R$ 100,00 - Pagamento em Dinheiro na entrega - 1 único pedido na semana

Pedido é feito no Zé
Pessoa Entregadora leva o pedido até o endereço de entrega
Pessoa Entregadora recebe o valor principal de R$ 100,00 do cliente e volta para a loja
R$ 100,00 entra no caixa do PDV
No fechamento da semana, o motor de ajustes de reembolsos realiza os cálculos
- do pedido (markup de produtos Ambev, diferença do frete acordado, cupons aplicados, descontos do Zé, taxas e descontos adicionais)
- de incentivos operacionais
- e inclui os lançamentos manuais no cálculo
O valor de reembolso calculado é de R$ 20,00

Supondo que o PDV só teve 1 pedido na semana anterior, recebimentos totais:

R$ 100,00 do valor do pedido no retorno da pessoa entregadora
R$ 20,00 de reembolso na semana seguinte ao pedido

Total: R$ 120,00 ^** (desconsiderando variação de valor de dinheiro no tempo)

Pedido feito no valor de R$ 100,00 - Pagamento em Cartão de crédito na entrega, processado pelo adquirente do PDV - 1 único pedido na semana

Pedido é feito no Zé
Pessoa Entregadora leva o pedido até o endereço de entrega
Pessoa Entregadora cobra o valor principal de R$ 100,00 do cliente pela maquininha, e volta para a loja
Dependendo do plano do PDV com a adquirente:
- Os R$ 100,00 tem incidência de taxas. Nesse exemplo, taxas de R$ 2,00, então o valor principal do pedido cai para R$ 98,00
- E o prazo para liberação do dinheiro pode variar. Nesse exemplo, vamos considerar 7 dias para recebimento
No fechamento da semana, o motor de ajustes de reembolsos realiza os cálculos
- do pedido (markup de produtos Ambev, diferença do frete acordado, cupons aplicados, descontos do Zé, taxas e descontos adicionais)
- de incentivos operacionais
- e inclui os lançamentos manuais no cálculo
O valor de reembolso calculado é de R$ 20,00

Supondo que o PDV só teve 1 pedido na semana anterior, recebimentos totais:

R$ 98,00 recebidos 7 dias após a data do pagamento
R$ 20,00 de reembolso

Total: R$ 118,00 ^** (desconsiderando variação de valor de dinheiro no tempo)

Pedido feito no valor de R$ 100,00 - Pagamento Online no app do Zé, em Cartão de crédito - 1 único pedido na semana

Pedido é feito no Zé
Pessoa Entregadora leva o pedido até o endereço de entrega, e entrega sem cobrar nada
Dependendo do plano do PDV com o Zé:
- Os R$ 100,00 tem incidência de taxas. Nesse exemplo, taxas de R$ 2,00, então o valor principal do pedido cai para R$ 98,00
- E o prazo para liberação do dinheiro pode variar. Nesse exemplo, vamos considerar 7 dias^* para recebimento
No fechamento da semana, o motor de ajustes de reembolsos realiza os cálculos
- do pedido (markup de produtos Ambev, diferença do frete acordado, cupons aplicados, descontos do Zé, taxas e descontos adicionais)
- de incentivos operacionais
- e inclui os lançamentos manuais no cálculo
O valor de reembolso calculado é de R$ 20,00

Supondo que o PDV só teve 1 pedido na semana anterior, recebimentos totais:

R$ 98,00 recebidos 7 dias^* após a data do pagamento
R$ 20,00 de reembolso

Total: R$ 118,00 ^** (desconsiderando variação de valor de dinheiro no tempo)

^* É importante ressaltar que as previsões de pagamento fornecidas pelos adquirentes do Zé podem sofrer alterações dado ao calendário de dias úteis do sistema financeiro nacional. Fins de semana e feriados podem impactar o pagamento real.

^** Os dados de Reembolso fornecidos na API podem sofrer variações até o momento do pagamento em si. Isso pode ocorrer por falhas nas transferências bancárias, ou outros motivos de exceção que não foram previamente cobertos. Caso haja dúvidas, orientamos o PDV a entrar em contato com o suporte do Zé

Fluxo recomendado de leitura dos dados para conciliação financeira

Consulte os pedidos finalizados no endpoint GET Orders History.
Consulte o endpoint de Operações de Pagamentos Online para:
- conciliar a entrada financeira de vendas passadas pagas online (pagas via app do Zé Delivery)
- verificar planejamento de recebimento futuro de vendas pagas online (pagas via app do Zé Delivery)
Consulte os Reembolsos para verificar o cálculo semanal relativo a todos os pedidos do PDV no Zé Delivery

Operações de Pagamentos Online

Objetivo

Permitir que o integrador consulte as operações financeiras relacionadas aos pagamentos realizados online (via app do Zé) para um estabelecimento. Cada registro representa uma operação financeira.

Fluxo dos pagamentos online: pagamento pelo app, conta bolsão, estornos e liquidação interna ou externa.

Credit:

Representam recebíveis através da calendarização dos pagamentos e estornos que serão feitos para a conta de adquirente do PDV. Fornecem dados de conciliação passada e previsão estimada de pagamentos futuros. Regras nos adquirentes podem mudar, ou previsões podem não ser corretamente informadas em todos os casos, para todos os adquirentes

Possuem pedidos vinculados. Em via de regra, mudanças no pedido (como edição, mudanças na forma de pagamento, status, etc) impactam nas operações financeiras relativas a ele. Podem ocorrer exceções.

Refund

Representam o estorno realizado na conta bolsão de cada adquirente, ou da remoção de previsões futuras

Estornos podem acontecer por inúmeros motivos, de forma parcial ou total ao valor de cada pedido, inclusive para casos limites em que pedidos são quase que imediatamente cancelados ou desconsiderados após o pagamento

Transfer:

representam as tentativas de transferência bancária final, da conta adquirente para contas fora da adquirente (do PDV ou “externa”)

Não possuem pedidos vinculados. Nem todo valor ou desconto que compõem uma transferência são relativos a pedido. Parte de um desconto pode ser, por exemplo, uma taxa de recebimento aos finais de semana cobrada pela adquirente, contratada pelo PDV

Para mais informações do fluxo financeiro do Zé, veja:

A Introdução ao módulo Financial
A FAQ de Pagamentos Online para PDVs: Pagamento Online | Portal do Parceiro.
A FAQ de Reembolsos para PDVs: Pagamento | Portal do Parceiro.

Quando usar

Use este endpoint quando for necessário:

consultar operações relacionadas ao valor principal de Pagamentos Online;
consultar operações previstas ou realizadas, com ou sem vínculo a um número de pedido;
alimentar processos de conciliação em ERPs;
comparar previsões com recebimentos realizados;
investigar divergências financeiras de um PDV.

Quando não usar

Não use este endpoint para:

obter uma conciliação pronta;
calcular automaticamente o saldo final do PDV;
consultar exclusivamente ajustes de markup, frete, cupom ou comissão;
consultar incentivos operacionais;
consultar pagamentos manuais;
obter o plano de repasse contratado;
consultar detalhes operacionais completos de um pedido.

Filtros

A consulta exige a identificação do estabelecimento no caminho da requisição. Os demais parâmetros são opcionais e devem ser enviados na query string.

GET /merchants/{merchantId}/financials/payments-reports

Identificação do estabelecimento

Parâmetro	Local	Obrigatório	Tipo	Descrição
`merchantId`	Path	Sim	string	Identificador do estabelecimento cujas operações financeiras serão consultadas. O token utilizado deve possuir acesso ao estabelecimento informado.

Exemplo:

GET /merchants/32/financials/payments-reports

Se o token não possuir acesso ao merchantId, a API retorna 403 Forbidden.

Filtros opcionais

Quando mais de um filtro é informado, a operação precisa atender a todos eles simultaneamente.

Parâmetro	Tipo	Valores ou formato	Descrição
`operationStartDate`	data	`YYYY-MM-DD`	Data inicial da operação financeira. Deve ser enviada com `operationEndDate`.
`operationEndDate`	data	`YYYY-MM-DD`	Data final da operação financeira. Deve ser enviada com `operationStartDate`.
`orderStartDate`	data	`YYYY-MM-DD`	Data inicial de criação do pedido. Deve ser enviada com `orderEndDate`.
`orderEndDate`	data	`YYYY-MM-DD`	Data final de criação do pedido. Deve ser enviada com `orderStartDate`.
`payoutStartDate`	data	`YYYY-MM-DD`	Data inicial prevista para o repasse. Deve ser enviada com `payoutEndDate`.
`payoutEndDate`	data	`YYYY-MM-DD`	Data final prevista para o repasse. Deve ser enviada com `payoutStartDate`.
`orderNumber`	string	—	Número do pedido associado à operação.
`status`	string	`credit`, `externalCredit`, `refund`, `projected`	Classificação financeira da operação. Não corresponde ao status do pedido.
`operationType`	string	`credit`, `refund`, `transfer`	Tipo da operação financeira.
`paymentMethod`	string	`creditCard`, `nupay`, `pix`, `transfer`	Método de pagamento da operação.
`liquidationType`	string	`internal`, `external`	Tipo da liquidação. É especialmente útil em operações de transferência.
`provider`	string ou lista	Ex.: Pagarme, Tuna	Provider responsável pela operação. Pode ser enviado uma vez, repetido ou como lista separada por vírgula.
`pageSize`	inteiro	De 1 a 100	Quantidade máxima de registros por página. O padrão é 30.
`cursor`	string	Valor opaco	Identificador utilizado para consultar a próxima página.

Como funcionam os períodos

Os três períodos são independentes e consultam campos diferentes:

orderStartDate e orderEndDate filtram a data de criação do pedido, apresentada em order.createdAt;
operationStartDate e operationEndDate filtram a data da operação financeira, apresentada em operation.date;
payoutStartDate e payoutEndDate filtram a data prevista para o repasse, apresentada em payment.expectedPayoutAt.

Por isso, consultar o mesmo intervalo nos três pares pode produzir resultados diferentes. Um filtro por data da operação, por exemplo, não considera a data de criação do pedido nem a data prevista para o repasse.

As datas devem ser informadas no formato YYYY-MM-DD, considerando o calendário de Brasília (-03:00). O início e o fim são inclusivos. Assim, o período abaixo considera os dias 1 e 2 de agosto por completo:

GET /merchants/32/financials/payments-reports
    ?operationStartDate=2026-08-01
    &operationEndDate=2026-08-02

Cada período deve seguir estas regras:

as datas inicial e final devem ser enviadas juntas;
a data inicial não pode ser posterior à data final;
o intervalo pode ter no máximo 90 dias, contando as datas inicial e final;
a data final deve ser anterior à data atual.

Quando nenhum dos três períodos é informado, a API consulta automaticamente os últimos 90 dias encerrados no dia anterior, utilizando a data da operação como referência.

Caso mais de um período seja enviado, todos serão aplicados simultaneamente. No exemplo abaixo, somente serão retornados registros cuja data da operação e data prevista de repasse estejam dentro dos respectivos intervalos:

GET /merchants/32/financials/payments-reports
    ?operationStartDate=2026-08-01
    &operationEndDate=2026-08-20
    &payoutStartDate=2026-08-02
    &payoutEndDate=2026-08-22

Quando o campo usado pelo filtro não existe no registro, esse registro não é retornado. Por exemplo, operações sem dados do pedido não aparecem em uma consulta que utiliza orderStartDate e orderEndDate.

Valores aceitos pelos filtros

Status

O filtro status classifica as operações apresentadas no relatório. Ele não representa o status do pedido e não deve ser interpretado isoladamente como confirmação de que o valor chegou à conta bancária do estabelecimento.

Status	Descrição
`credit`	Operação financeira realizada ou confirmada, excluindo estornos. Conforme o tipo da operação, pode representar um crédito ou uma transferência liquidada.
`externalCredit`	Crédito destinado à liquidação externa, quando o recebível é direcionado a uma instituição financeira em razão de uma cessão ou garantia de recebíveis.
`refund`	Estorno financeiro total ou parcial. Um mesmo pedido pode gerar mais de um estorno, inclusive em datas diferentes.
`projected`	Operação prevista, cuja liquidação ainda está pendente. A data e o valor são estimativas e podem sofrer alterações.

Para interpretar o estado detalhado de uma operação, considere também:

operation.type: natureza da movimentação;
operation.sourceStatus: status recebido do provedor;
liquidation.status: situação da liquidação;
liquidation.type: destino interno ou externo da liquidação.

O status financeiro também não deve ser confundido com order.status, que representa a situação operacional do pedido.

Exemplo:

GET /merchants/32/financials/payments-reports?status=credit

Tipo de operação

O filtro operationType aceita:

credit
refund
transfer

Operações do tipo transfer não possuem um pedido associado.

Exemplo:

GET /merchants/32/financials/payments-reports
    ?operationType=transfer
    &liquidationType=internal

Método de pagamento

O filtro paymentMethod aceita:

creditCard
nupay
pix
transfer

Exemplo:

GET /merchants/32/financials/payments-reports?paymentMethod=pix

Tipo de liquidação

O filtro liquidationType aceita:

internal
external

Provider

O filtro provider pode ser enviado de três maneiras.

Valor único:

GET /merchants/32/financials/payments-reports?provider=Pagarme

Parâmetro repetido:

GET /merchants/32/financials/payments-reports
    ?provider=Pagarme
    &provider=Tuna

Lista separada por vírgula:

GET /merchants/32/financials/payments-reports?provider=Pagarme,Tuna

Quando mais de um provider é informado, são retornados registros pertencentes a qualquer um deles. Recomenda-se usar a grafia documentada para cada provider.

Exemplo com filtros combinados

GET /merchants/32/financials/payments-reports
    ?operationStartDate=2026-08-01
    &operationEndDate=2026-08-20
    &operationType=transfer
    &liquidationType=external
    &provider=Pagarme
    &pageSize=50

Nesse exemplo, cada registro precisa atender simultaneamente ao período da operação, ao tipo de operação, ao tipo de liquidação e ao provider informados.

Como interpretar o retorno

Operação como registro principal

Cada item de operations representa uma operação financeira, não um pedido. Um mesmo pedido pode originar várias operações, e algumas operações podem não possuir vínculo com um pedido disponível na origem.

O diagrama abaixo apresenta uma forma simplificada de interpretar as operações financeiras. Ele é ilustrativo e não representa todas as combinações possíveis entre operation.type, status, payment, order e liquidation.

A leitura deve ser feita de forma progressiva:

Identificar o que aconteceu em operation.type.
Analisar o estado financeiro em status.
Verificar o estado e o destino da liquidação em liquidation.status e liquidation.type.
Considerar o provider responsável pelo processamento.

Os campos devem ser analisados em conjunto. Eles podem apresentar null quando a informação não for fornecida pela origem ou não se aplicar à operação.

%%{init: {"themeVariables": {"fontFamily": "Roboto, sans-serif", "fontSize": "13px"}, "flowchart": {"htmlLabels": false, "curve": "basis", "nodeSpacing": 40, "rankSpacing": 36, "padding": 12}}}%%
flowchart TB
    START(["Uma linha do relatório<br/>representa uma operação<br/>financeira"])

    START --> TYPE("1. O que aconteceu?<br/>operation.type")

    TYPE -->|credit| CREDIT("CRÉDITO<br/>Um valor a receber ou já<br/>realizado")
    TYPE -->|refund| REFUND("ESTORNO<br/>Devolução total ou parcial<br/>de um pagamento")
    TYPE -->|transfer| TRANSFER("TRANSFERÊNCIA<br/>Tentativa de retirar o saldo<br/>da adquirente")

    CREDIT --> CREDIT_NORMAL["Normalmente:<br/>• possui pedido<br/>• método: creditCard,<br/>  nupay ou pix"]

    REFUND --> REFUND_NORMAL["Normalmente:<br/>• possui pedido<br/>• mantém o método do<br/>  pagamento original"]

    TRANSFER --> TRANSFER_NORMAL["Normalmente:<br/>• não possui pedido<br/>• método: transfer<br/>• pode consolidar vários<br/>  recebíveis"]

    CREDIT_NORMAL --> NEXT
    REFUND_NORMAL --> NEXT
    TRANSFER_NORMAL --> NEXT

    NEXT(["Depois de identificar o tipo,<br/>leia as outras dimensões da<br/>operação"])

    NEXT --> STATUS_TITLE("2. Em que estado está?<br/>status")
    NEXT --> LIQUIDATION_TITLE("3. Como está a liquidação?<br/>liquidation.status<br/>liquidation.type")
    NEXT --> PROVIDER_TITLE("4. Quem processou?<br/>provider")

    STATUS_TITLE --> STATUS["projected = previsto<br/>credit = realizado ou confirmado<br/>refund = estornado<br/>externalCredit = destinado ao<br/>fluxo externo"]

    LIQUIDATION_TITLE --> LIQUIDATION["status:<br/>liquidated = concluída<br/>pending_liquidation = pendente<br/>liquidation_failed = falhou<br/>liquidation_reversed = revertida<br/>null = informação indisponível<br/><br/>type:<br/>internal = fluxo normal do PDV<br/>external = instituição financeira<br/>null = informação indisponível"]

    PROVIDER_TITLE --> PROVIDER["Exemplos atuais:<br/>tuna ou pagarme"]

    classDef start fill:#F3F6FA,stroke:#BBC9D5,stroke-width:1px,color:#34434F;
    classDef question fill:#EAF3FB,stroke:#9ABDD7,stroke-width:1px,color:#285572;
    classDef credit fill:#DDEFFC,stroke:#7DB5DB,stroke-width:1px,color:#17547B;
    classDef creditDetail fill:#F0F8FE,stroke:#B5D6EA,stroke-width:1px,color:#34434F;
    classDef refund fill:#FDEBDD,stroke:#DFA87F,stroke-width:1px,color:#844A28;
    classDef refundDetail fill:#FFF6EF,stroke:#EACBB3,stroke-width:1px,color:#34434F;
    classDef transfer fill:#E3F3E7,stroke:#88BA94,stroke-width:1px,color:#276141;
    classDef transferDetail fill:#F1FAF3,stroke:#BEDBC6,stroke-width:1px,color:#34434F;
    classDef detail fill:#F6F8FA,stroke:#CAD5DE,stroke-width:1px,color:#34434F;
    classDef next fill:#EAF3FB,stroke:#9ABDD7,stroke-width:1px,color:#285572;

    linkStyle default stroke:#B9C3CA,stroke-width:1px;
    linkStyle 1 stroke:#7DB5DB,stroke-width:1.5px;
    linkStyle 2 stroke:#DFA87F,stroke-width:1.5px;
    linkStyle 3 stroke:#88BA94,stroke-width:1.5px;

    class START start;
    class TYPE,STATUS_TITLE,LIQUIDATION_TITLE,PROVIDER_TITLE question;
    class CREDIT credit;
    class REFUND refund;
    class TRANSFER transfer;
    class CREDIT_NORMAL creditDetail;
    class REFUND_NORMAL refundDetail;
    class TRANSFER_NORMAL transferDetail;
    class STATUS,LIQUIDATION,PROVIDER detail;
    class NEXT next;

Cobertura temporal

Retenção histórica dos dados: Sugerimos limitar as consultas a 12 meses no passado do momento da consulta, para qualquer filtro de período. Períodos mais antigos podem ter dados ausentes.
Período máximo por chamada: Todos os filtros de período utilizados devem ter um limite de intervalo de 90 dias
Horizonte de estimativas futuras: Não há limitações de períodos futuros a serem consultados. Se há dados de previsões no futuro, eles serão retornados

Envelope e paginação

A resposta contém o estabelecimento consultado, as operações da página atual e os dados de paginação:

Campo	Tipo	Significado
`merchantId`	string	Estabelecimento autorizado e consultado.
`operations`	array	Operações financeiras da página atual.
`pageInfo.pageSize`	integer	Limite utilizado na consulta.
`pageInfo.totalItems`	integer	Total de registros para os filtros aplicados.
`pageInfo.hasNextPage`	boolean	Indica se existe uma próxima página.
`pageInfo.nextCursor`	string \| `null`	Cursor da próxima página ou `null` quando não houver mais resultados.

Como paginar

Na primeira requisição, não envie cursor. O parâmetro pageSize é opcional, aceita valores entre 1 e 100 e possui valor padrão 30.

Quando hasNextPage for true, envie o valor de nextCursor no parâmetro cursor:

GET /merchants/32/financials/payments-reports
    ?operationStartDate=2026-08-01
    &operationEndDate=2026-08-31
    &pageSize=30
    &cursor=CURSOR_OPACO

Ao consultar a próxima página, mantenha o mesmo merchantId, os mesmos filtros e o mesmo pageSize. Alterá-los interrompe a continuidade da consulta.

O cursor é opaco: não deve ser decodificado, alterado ou construído pelo consumidor.

A API não retorna currentPage, pois a paginação por cursor não permite calcular um número de página confiável.

Retornar para uma página anterior

O contrato oferece apenas nextCursor; não existe previousCursor. Para permitir a navegação de volta, a aplicação deve manter temporariamente os cursores utilizados:

a primeira página é acessada sem cursor;
a segunda utiliza o nextCursor da primeira;
a terceira utiliza o nextCursor da segunda;
para voltar, reutilize o cursor que abriu a página desejada.

Os cursores devem ser mantidos somente durante a navegação atual.

Resultado sem dados

Uma consulta válida sem operações retorna 200 OK:

{
  "merchantId": "32",
  "operations": [],
  "pageInfo": {
    "pageSize": 30,
    "totalItems": 0,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Uma coleção vazia não retorna 404 Not Found.

Descrição dos campos

Operação

Campo	Tipo	Obrigatório	Significado
`operations.id`	string	Sim	Identificador único da operação financeira
`operations.status`	`credit` \| `externalCredit` \| `refund` \| `projected` \| `null`	Sim	Classificação financeira pública da operação, como crédito, crédito externo, estorno ou projeção. Não representa o status operacional do pedido, nem espelham status brutos das adquirentes.
`operations.createdAt`	date-time string \| `null`	Sim	Criação do registro financeiro na base do Zé Delivery. Para verificar a data de criação do registro no adquirente, confira `operation.date`
`operations.updatedAt`	date-time string \| `null`	Sim	Última atualização do registro financeiro na base do Zé Delivery
`operations.provider`	string \| `null`	Sim	Provedor (Adquirente) responsável pelo processamento
`operations.anticipationPlan`	string \| `null`	Sim	Plano de antecipação associado ao seller no momento da geração da operação financeira
`operations.financial`	object	Sim	Valores da movimentação, não o total do pedido
`operations.order`	object	Não	Pedido relacionado. Ausente quando não houver vínculo de pedido disponível para a operação (normalmente Transfers)
`operations.payment`	object	Sim	Contexto do pagamento ou transferência
`operations.operation`	object	Sim	Natureza e data da movimentação
`operations.liquidation`	object	Sim	Contexto da liquidação ou repasse

Money

Campo	Tipo	Significado
`value`	number	Valor decimal em unidades da moeda, com o sinal original preservado.
`currency`	literal BRL	Moeda ISO 4217.

financial

Campo	Tipo	Obrigatório	Significado
`financial.grossAmount`	Money \| `null`	Sim	Valor bruto da operação
`financial.feeAmount`	Money \| `null`	Sim	Taxas relacionadas a operação, cobradas do PDV
`financial.netAmount`	Money \| `null`	Sim	Valor líquido da operação após desconto de taxas ( `financial.grossAmount` - `financial.feeAmount` )

order

Campo público	Tipo	Obrigatório	Significado
`order.number`	string \| `null`	Sim	Número do pedido apresentado ao estabelecimento
`order.status`	string \| `null`	Sim	Status operacional do pedido; não é status financeiro
`order.createdAt`	date-time string \| `null`	Sim	Criação do pedido
`order.updatedAt`	date-time string \| `null`	Sim	Última atualização do pedido
`order.isEdited`	boolean	Sim	Indica se o pedido teve seus itens editados (funcionalidade “Edição de pedidos”)
`order.amount`	Money \| `null`	Sim	Valor original do pedido
`order.editedAt`	date-time string \| `null`	Sim	Momento da edição financeira (funcionalidade “Edição de pedidos”)
`order.editedAmount`	Money \| `null`	Sim	Valor do pedido após a “Edição de pedidos”

payment

Campo público	Tipo	Obrigatório	Significado
`payment.method`	ENUM aberto string \| `null`	Sim	Meio de pagamento normalizado
`payment.expectedPayoutAt`	date-time string \| `null`	Sim	Data prevista informada pela adquirente para disponibilização ou repasse do valor. Pode sofrer alteração por dias não úteis, mudança de plano, antecipação, falha de transferência ou reprocessamento. Não deve ser interpretada isoladamente como confirmação de recebimento bancário.
`payment.amount`	Money \| `null`	Sim	Valor integral do pagamento
`payment.refundedAmount`	Money \| `null`	Sim	Valor estornado
`payment.refundType`	partial \| total \| `null`	Sim	Indica `refund` parcial ou total
`payment.methodDetails`	string \| `null`	Sim	Descrição complementar recebida da origem
`payment.cardBrand`	string \| `null`	Sim	Bandeira, quando aplicável
`payment.installmentNumber`	integer \| `null`	Sim	Parcela relacionada ao registro
`payment.installments`	integer \| `null`	Sim	Número total de parcelas

operation

Campo público	Tipo	Obrigatório	Significado
`operation.type`	`credit` \| `refund` \| `transfer` \| `null`	Sim	Natureza da movimentação
`operation.description`	string \| `null`	Sim	Classificação mais específica da origem
`operation.sourceStatus`	string \| `null`	Sim	Estado bruto da operação na adquirente / `provider`
`operation.date`	date-time string \| `null`	Sim	Data da criação da operação na base do `provider`

liquidation

Campo público	Tipo	Obrigatório	Significado
`liquidation.status`	string \| `null`	Sim	Estado da liquidação
`liquidation.type`	string \| `null`	Sim	Tipo do fluxo de liquidação. Pode ser `internal` (para a conta do PDV), `external` (para uma instituição financeira) ou `null` (falha na disponibilização do dado) Em uma liquidação externa, uma parcela é indivisível: ela é direcionada integralmente à instituição financeira ou integralmente ao banco do PDV. Parcelas diferentes do mesmo pedido podem seguir para destinos diferentes.
`liquidation.createdAt`	date-time string \| `null`	Sim	Criação do registro de liquidação
`liquidation.updatedAt`	date-time string \| `null`	Sim	Última atualização da liquidação
`liquidation.date`	date-time string \| `null`	Sim	Data da liquidação quando fornecida
`liquidation.bank`	object \| `null`	Sim	Banco relacionado ao repasse (quando disponível)
`liquidation.bank.code`	string \| `null`	Sim	Código bancário (quando disponível)
`liquidation.bank.name`	string \| `null`	Sim	Nome do banco (quando disponível)
`liquidation.product`	string \| `null`	Sim	Produto financeiro associado (quando disponível)

ENUMs e significados

Campo	Significado	Valores públicos
`status`	Como a operação está classificada financeiramente?	`credit`, `externalCredit`, `refund`, `projected`
`operationType`	Qual movimentação financeira foi registrada?	`credit`, `refund`, `transfer`
`paymentMethod`	Qual meio está associado à operação?	`creditCard`, `nupay`, `pix`, `transfer`
`liquidationType`	Por qual fluxo ocorreu a liquidação?	`internal`, `external`

Significados:

credit: entrada ou recebível de pagamento;
externalCredit: crédito com liquidação externa;
refund: estorno de pagamento;
projected: operação prevista, ainda não confirmada como liquidada;
transfer: movimentação da conta da adquirente para outra conta;
internal: liquidação tratada no fluxo interno conhecido pelo Zé;
external: recebível direcionado a uma instituição financeira em razão de cessão de recebíveis ou garantia contratada pelo PDV.

Exemplos de payload

Previsão de pagamento

Representa um recebimento previsto, ainda não liquidado. A data e os valores são estimativas e podem mudar até a liquidação.

operation.type: credit
status: projected
liquidation.status: pendingLiquidation
payment.expectedPayoutAt: data da previsão em que o pagamento será efetivado

{
  "merchantId": "32",
  "operations": [
    {
      "id": "eb523507-6844-4f13-a6f0-c910e7dd5479",
      "status": "projected",
      "createdAt": "2026-08-10T16:15:00.000-03:00",
      "updatedAt": "2026-08-10T16:15:00.000-03:00",
      "provider": "tuna",
      "anticipationPlan": "D+30",
      "financial": {
        "grossAmount": {
          "value": 80,
          "currency": "BRL"
        },
        "feeAmount": {
          "value": 1.48,
          "currency": "BRL"
        },
        "netAmount": {
          "value": 78.52,
          "currency": "BRL"
        }
      },
      "order": {
        "number": "234567890",
        "status": "Delivered",
        "createdAt": "2026-08-10T16:10:00.000-03:00",
        "updatedAt": "2026-08-10T16:45:00.000-03:00",
        "isEdited": false,
        "amount": {
          "value": 80,
          "currency": "BRL"
        },
        "editedAt": null,
        "editedAmount": null
      },
      "payment": {
        "method": "nupay",
        "expectedPayoutAt": "2026-09-09T18:00:00.000-03:00",
        "amount": {
          "value": 80,
          "currency": "BRL"
        },
        "refundedAmount": null,
        "refundType": null,
        "methodDetails": "Nupay Credito",
        "cardBrand": null,
        "installmentNumber": 1,
        "installments": 1
      },
      "operation": {
        "type": "credit",
        "description": "credit",
        "sourceStatus": "scheduled",
        "date": "2026-08-10T16:15:00.000-03:00"
      },
      "liquidation": {
        "status": "pendingLiquidation",
        "type": "internal",
        "createdAt": "2026-08-10T16:15:00.000-03:00",
        "updatedAt": "2026-08-10T16:15:00.000-03:00",
        "date": null,
        "bank": null,
        "product": "nupay"
      }
    }
  ],
  "pageInfo": {
    "pageSize": 1,
    "totalItems": 1,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Estorno parcial de uma previsão

Representa o estorno parcialmente realizado de uma operação financeira prévia. Normalmente, a edição realizada de um pedido, ou cancelamento de parte de um pedido

operation.type: refund
status: refund
financial.grossAmount: O valor absoluto é diferente do pagamento efetuado pelo client, relativo ao valor original na order (payment.amount.value)
payment.refundType: partial

{
  "merchantId": "32",
  "operations": [
    {
      "id": "d7ed2243-3a3c-7b58-ada4-4379d475fae0",
      "status": "refund",
      "createdAt": "2026-07-19T22:02:47.000-03:00",
      "updatedAt": "2026-07-20T07:26:15.000-03:00",
      "provider": "tuna",
      "anticipationPlan": "D+30",
      "financial": {
        "grossAmount": {
          "value": -6.28,
          "currency": "BRL"
        },
        "feeAmount": {
          "value": -0.12,
          "currency": "BRL"
        },
        "netAmount": {
          "value": -6.16,
          "currency": "BRL"
        }
      },
      "order": {
        "number": "930566718",
        "status": "Delivered",
        "createdAt": "2026-07-19T19:02:48.000-03:00",
        "updatedAt": "2026-07-19T19:34:05.000-03:00",
        "isEdited": true,
        "amount": {
          "value": 32.45,
          "currency": "BRL"
        },
        "editedAt": "2026-07-19T22:09:08.000-03:00",
        "editedAmount": {
          "value": 32.45,
          "currency": "BRL"
        }
      },
      "payment": {
        "method": "nupay",
        "expectedPayoutAt": "2026-07-19T21:00:00.000-03:00",
        "amount": {
          "value": 38.74,
          "currency": "BRL"
        },
        "refundedAmount": {
          "value": 6.28,
          "currency": "BRL"
        },
        "refundType": "partial",
        "methodDetails": "Nupay Debito",
        "cardBrand": null,
        "installmentNumber": 1,
        "installments": 1
      },
      "operation": {
        "type": "refund",
        "description": "credit_refund",
        "sourceStatus": "scheduled",
        "date": "2026-07-18T21:00:00.000-03:00"
      },
      "liquidation": {
        "status": "liquidated",
        "type": "internal",
        "createdAt": "2026-07-19T22:02:47.000-03:00",
        "updatedAt": "2026-07-20T07:26:15.000-03:00",
        "date": null,
        "bank": {
          "code": "033",
          "name": "BCO SANTANDER (BRASIL) S.A."
        },
        "product": "nupay"
      }
    }
  ],
  "pageInfo": {
    "pageSize": 30,
    "totalItems": 1,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Estorno total de uma previsão

Representa o estorno integral de um pagamento. Um mesmo pedido pode gerar mais de uma operação financeira, inclusive em datas diferentes.

operation.type: refund
status: refund
financial.grossAmount: O valor absoluto é igual ao do pagamento efetuado pelo client, relativo ao valor o original na order (payment.amount.value)
payment.refundType: total ou null

{
  "merchantId": "32",
  "operations": [
    {
      "id": "8ac67cc3-d887-44cb-b002-9556409e39be",
      "status": "refund",
      "createdAt": "2026-08-15T11:20:00.000-03:00",
      "updatedAt": "2026-08-15T11:25:00.000-03:00",
      "provider": "pagarme",
      "anticipationPlan": "D+7",
      "financial": {
        "grossAmount": {
          "value": -100,
          "currency": "BRL"
        },
        "feeAmount": {
          "value": 0,
          "currency": "BRL"
        },
        "netAmount": {
          "value": 0,
          "currency": "BRL"
        }
      },
      "order": {
        "number": "123456789",
        "status": "Delivered",
        "createdAt": "2026-08-01T14:25:00.000-03:00",
        "updatedAt": "2026-08-15T11:15:00.000-03:00",
        "isEdited": false,
        "amount": {
          "value": 100,
          "currency": "BRL"
        },
        "editedAt": null,
        "editedAmount": null
      },
      "payment": {
        "method": "pix",
        "expectedPayoutAt": "2026-08-08T18:00:00.000-03:00",
        "amount": {
          "value": 100,
          "currency": "BRL"
        },
        "refundedAmount": {
          "value": 100,
          "currency": "BRL"
        },
        "refundType": null,
        "methodDetails": "Pix",
        "cardBrand": null,
        "installmentNumber": 1,
        "installments": 1
      },
      "operation": {
        "type": "refund",
        "description": "credit_refund",
        "sourceStatus": "paid",
        "date": "2026-08-15T11:20:00.000-03:00"
      },
      "liquidation": {
        "status": null,
        "type": null,
        "createdAt": null,
        "updatedAt": null,
        "date": null,
        "bank": null,
        "product": null
      }
    }
  ],
  "pageInfo": {
    "pageSize": 1,
    "totalItems": 1,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Atualização de uma Previsão após Liquidação “Interna”

Quando uma Transfer é realizada, e a previsão de um pagamento é pago, a operação relativa a previsão é atualizada.

operation.type: credit
status: credit
liquidation.status: liquidated
liquidation.type: internal

{
  "merchantId": "32",
  "operations": [
    {
      "id": "51b83624-77ed-4f80-9666-a753414cb620",
      "status": "credit",
      "createdAt": "2026-08-01T14:30:00.000-03:00",
      "updatedAt": "2026-08-08T18:05:00.000-03:00",
      "provider": "pagarme",
      "anticipationPlan": "D+7",
      "financial": {
        "grossAmount": {
          "value": 100,
          "currency": "BRL"
        },
        "feeAmount": {
          "value": 2,
          "currency": "BRL"
        },
        "netAmount": {
          "value": 98,
          "currency": "BRL"
        }
      },
      "order": {
        "number": "123456789",
        "status": "Delivered",
        "createdAt": "2026-08-01T14:25:00.000-03:00",
        "updatedAt": "2026-08-01T15:10:00.000-03:00",
        "isEdited": false,
        "amount": {
          "value": 100,
          "currency": "BRL"
        },
        "editedAt": null,
        "editedAmount": null
      },
      "payment": {
        "method": "creditCard",
        "expectedPayoutAt": "2026-08-08T18:00:00.000-03:00",
        "amount": {
          "value": 100,
          "currency": "BRL"
        },
        "refundedAmount": null,
        "refundType": null,
        "methodDetails": "Crédito à Vista",
        "cardBrand": "visa",
        "installmentNumber": 1,
        "installments": 1
      },
      "operation": {
        "type": "credit",
        "description": "credit",
        "sourceStatus": "paid",
        "date": "2026-08-08T18:05:00.000-03:00"
      },
      "liquidation": {
        "status": "liquidated",
        "type": "internal",
        "createdAt": "2026-08-01T14:30:00.000-03:00",
        "updatedAt": "2026-08-08T18:05:00.000-03:00",
        "date": null,
        "bank": null,
        "product": "anticipation"
      }
    }
  ],
  "pageInfo": {
    "pageSize": 1,
    "totalItems": 1,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Atualização de uma Previsão após Liquidação “Interna” - Dados de liquidation ausentes

Existem casos em que a atualização de um pagamento é efetuado, mas a adquirente não atualiza corretamente a base do Zé Delivery. Tendem a ser casos de exceção.

operation.type: credit
status: credit
Dados de liquidation estão null

{
  "merchantId": "32",
  "operations": [
    {
      "id": "cde53648-10e7-9404-d945-fa29e9b09690",
      "status": "credit",
      "createdAt": "2026-07-18T18:26:45.000-03:00",
      "updatedAt": "2026-07-18T18:29:58.000-03:00",
      "provider": "pagarme",
      "anticipationPlan": "D+30",
      "financial": {
        "grossAmount": {
          "value": 97.86,
          "currency": "BRL"
        },
        "feeAmount": {
          "value": 1.22,
          "currency": "BRL"
        },
        "netAmount": {
          "value": 96.64,
          "currency": "BRL"
        }
      },
      "order": {
        "number": "601850223",
        "status": "Expired",
        "createdAt": "2026-07-18T18:26:46.000-03:00",
        "updatedAt": "2026-07-18T18:29:55.000-03:00",
        "isEdited": false,
        "amount": {
          "value": 97.86,
          "currency": "BRL"
        },
        "editedAt": null,
        "editedAmount": null
      },
      "payment": {
        "method": "pix",
        "expectedPayoutAt": "2026-07-17T18:00:00.000-03:00",
        "amount": {
          "value": 97.86,
          "currency": "BRL"
        },
        "refundedAmount": null,
        "refundType": null,
        "methodDetails": "Pix",
        "cardBrand": null,
        "installmentNumber": 1,
        "installments": 1
      },
      "operation": {
        "type": "credit",
        "description": "credit",
        "sourceStatus": "paid",
        "date": "2026-07-18T18:27:29.600-03:00"
      },
      "liquidation": {
        "status": null,
        "type": null,
        "createdAt": null,
        "updatedAt": null,
        "date": null,
        "bank": null,
        "product": null
      }
    }
  ],
  "pageInfo": {
    "pageSize": 30,
    "totalItems": 1,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Atualização de uma Previsão após Liquidação “Externa”

A atualização, mas para quando a previsão foi paga para um agente financeiro externo

operation.type: credit
status: credit
liquidation.status: liquidated
liquidation.type: external

{
  "merchantId": "32",
  "operations": [
    {
      "id": "51b83624-77ed-4f80-9666-a753414cb620",
      "status": "credit",
      "createdAt": "2026-08-01T14:30:00.000-03:00",
      "updatedAt": "2026-08-08T18:05:00.000-03:00",
      "provider": "pagarme",
      "anticipationPlan": "D+7",
      "financial": {
        "grossAmount": {
          "value": 100,
          "currency": "BRL"
        },
        "feeAmount": {
          "value": 2,
          "currency": "BRL"
        },
        "netAmount": {
          "value": 98,
          "currency": "BRL"
        }
      },
      "order": {
        "number": "123456789",
        "status": "Delivered",
        "createdAt": "2026-08-01T14:25:00.000-03:00",
        "updatedAt": "2026-08-01T15:10:00.000-03:00",
        "isEdited": false,
        "amount": {
          "value": 100,
          "currency": "BRL"
        },
        "editedAt": null,
        "editedAmount": null
      },
      "payment": {
        "method": "creditCard",
        "expectedPayoutAt": "2026-08-08T18:00:00.000-03:00",
        "amount": {
          "value": 100,
          "currency": "BRL"
        },
        "refundedAmount": null,
        "refundType": null,
        "methodDetails": "Crédito à Vista",
        "cardBrand": "visa",
        "installmentNumber": 1,
        "installments": 1
      },
      "operation": {
        "type": "credit",
        "description": "credit",
        "sourceStatus": "paid",
        "date": "2026-08-08T18:05:00.000-03:00"
      },
      "liquidation": {
        "status": "liquidated",
        "type": "external",
        "createdAt": "2026-08-01T14:30:00.000-03:00",
        "updatedAt": "2026-08-08T18:05:00.000-03:00",
        "date": null,
        "bank": null,
        "product": "anticipation"
      }
    }
  ],
  "pageInfo": {
    "pageSize": 1,
    "totalItems": 1,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Transferência (Liquidação) “Interna”

Representa a saída do saldo mantido na adquirente para a conta bancária cadastrada pelo PDV.

operation.type: transfer
payment.method: transfer. Todos os outros campos de payment estarão vazios
status: credit
liquidation.status: liquidated
liquidation.type: internal

{
  "merchantId": "32",
  "operations": [
    {
      "id": "ad541973-e962-43fa-8182-ebbe55c400af",
      "status": "credit",
      "createdAt": null,
      "updatedAt": null,
      "provider": "tuna",
      "anticipationPlan": null,
      "financial": {
        "grossAmount": {
          "value": -98,
          "currency": "BRL"
        },
        "feeAmount": null,
        "netAmount": {
          "value": -98,
          "currency": "BRL"
        }
      },
      "payment": {
        "method": "transfer",
        "expectedPayoutAt": null,
        "amount": null,
        "refundedAmount": null,
        "refundType": null,
        "methodDetails": null,
        "cardBrand": null,
        "installmentNumber": null,
        "installments": null
      },
      "operation": {
        "type": "transfer",
        "description": null,
        "sourceStatus": "payout_status=4",
        "date": "2026-08-09T10:00:00.000-03:00"
      },
      "liquidation": {
        "status": "liquidated",
        "type": "internal",
        "createdAt": null,
        "updatedAt": null,
        "date": null,
        "bank": {
          "code": "033",
          "name": "BCO SANTANDER (BRASIL) S.A."
        },
        "product": "nupay"
      }
    }
  ],
  "pageInfo": {
    "pageSize": 1,
    "totalItems": 1,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Transferência (Liquidação) “Externa”

Representa a saída do saldo da adquirente para uma instituição financeira que possui direito sobre os recebíveis do PDV.

operation.type: transfer
payment.method: transfer. Todos os outros campos de payment estarão vazios
status: externalCredit
liquidation.status: liquidated
liquidation.type: external

{
  "merchantId": "32",
  "operations": [
    {
      "id": "74e498b3-fe36-4b71-b131-89e02e25aa06",
      "status": "externalCredit",
      "createdAt": null,
      "updatedAt": null,
      "provider": "pagarme",
      "anticipationPlan": null,
      "financial": {
        "grossAmount": {
          "value": -150,
          "currency": "BRL"
        },
        "feeAmount": null,
        "netAmount": {
          "value": -150,
          "currency": "BRL"
        }
      },
      "payment": {
        "method": "transfer",
        "expectedPayoutAt": null,
        "amount": null,
        "refundedAmount": null,
        "refundType": null,
        "methodDetails": null,
        "cardBrand": null,
        "installmentNumber": null,
        "installments": null
      },
      "operation": {
        "type": "transfer",
        "description": null,
        "sourceStatus": "success",
        "date": "2026-08-20T18:00:00.000-03:00"
      },
      "liquidation": {
        "status": "liquidated",
        "type": "external",
        "createdAt": null,
        "updatedAt": null,
        "date": null,
        "bank": {
          "code": "197",
          "name": "STONE INSTITUIÇÃO DE PAGAMENTO S.A."
        },
        "product": "anticipation"
      }
    }
  ],
  "pageInfo": {
    "pageSize": 1,
    "totalItems": 1,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Resultado sem operações

Uma consulta válida sem registros retorna 200 OK com uma coleção vazia. Não retorna 404 Not Found.

{
  "merchantId": "32",
  "operations": [],
  "pageInfo": {
    "pageSize": 30,
    "totalItems": 0,
    "hasNextPage": false,
    "nextCursor": null
  }
}

Comportamentos, cuidados e limitações

O endpoint retorna operações financeiras, não o histórico completo de pedidos. Um pedido somente aparece quando existe uma operação financeira associada e o vínculo está disponível na origem. Um pedido pode aparecer em várias operações.
Pedidos cancelados, recusados ou não aceitos podem aparecer. O status operacional do pedido não elimina uma entrada, um estorno ou outra movimentação financeira já produzida.
Não deduplicar operações por order.number. Registros com o mesmo pedido não são necessariamente duplicados.
Cada parcela pode ser retornada separadamente. Parcelas podem possuir valores, taxas, datas previstas e destinos de liquidação diferentes.
Não some indiscriminadamente todas as operações. Previsões, créditos realizados, transferências e estornos podem representar etapas diferentes do mesmo fluxo financeiro
Uma transferência consolida diversos recebíveis e movimentos. Por isso, ela não possui necessariamente relação direta com um único pedido. Não infira a composição de uma transferência. Coincidência de valor ou data não comprova que determinados pedidos fazem parte dela.
order.amount, payment.amount e financial.netAmount representam conceitos diferentes. Eles não precisam possuir o mesmo valor e não deve ser inferida uma fórmula entre eles sem considerar o tipo da operação e a regra do provider.
null não significa zero. O valor pode não ter sido informado pela origem ou não ser aplicável àquela operação.
Uma operação com status projected representa uma previsão. Ela ainda não comprova liquidação ou recebimento e pode mudar antes da realização. payment.expectedPayoutAt não confirma o recebimento. O campo representa uma data prevista ou informada pela origem, não necessariamente a data em que o dinheiro chegou à conta bancária do PDV.
operation.sourceStatus=paid não comprova o crédito na conta bancária final. O status indica como a origem classificou o pagamento ou a operação e deve ser interpretado junto com os dados de liquidação.
Datas e valores previstos podem mudar. Dias não úteis, antecipação, mudança de plano, falhas e reprocessamentos podem produzir diferenças entre previsão e realização.
Estornos podem ser representados de maneiras diferentes. Antes da liquidação, determinados fluxos podem corrigir o valor futuro; depois da liquidação, pode ser criada uma nova operação negativa. Um pedido pode possuir vários estornos. Edições e correções posteriores podem gerar movimentações diferentes, em datas diferentes. Os motivos detalhados de estorno ainda não estão disponíveis.
Falhas e retentativas podem produzir novas operações. Uma nova tentativa de transferência não deve ser tratada como atualização ou duplicação automática da anterior. O retorno bancário de uma transferência com falha ainda não está contemplado. O histórico completo das tentativas também não está disponível atualmente.
Liquidação externa significa que um recebível foi direcionado a uma instituição financeira. Isso pode ocorrer em razão de cessão ou garantia de recebíveis contratada pelo PDV. Os detalhes desse contrato não são fornecidos pelo endpoint. liquidation.bank e liquidation.product são retornados somente quando disponíveis na origem.
Uma parcela não é dividida na liquidação externa. Ela segue integralmente para a instituição financeira ou integralmente para o fluxo normal do PDV; parcelas diferentes podem seguir destinos diferentes.
Algumas informações dependem do tipo e da origem da operação. liquidation.bank e payment.cardBrand podem ser null, enquanto order pode não estar presente.

path Parameters

merchantId

required

string

Example: 32

Identificador do estabelecimento cujas operações financeiras serão consultadas. O token utilizado deve possuir acesso ao estabelecimento informado.

query Parameters

operationStartDate	string <date> Data inicial da operação financeira. Deve ser enviada com operationEndDate.
operationEndDate	string <date> Data final da operação financeira. Deve ser enviada com operationStartDate.
orderStartDate	string <date> Data inicial de criação do pedido. Deve ser enviada com orderEndDate.
orderEndDate	string <date> Data final de criação do pedido. Deve ser enviada com orderStartDate.
payoutStartDate	string <date> Data inicial prevista para o repasse. Deve ser enviada com payoutEndDate.
payoutEndDate	string <date> Data final prevista para o repasse. Deve ser enviada com payoutStartDate.
orderNumber	string Número do pedido associado à operação.
status	string Enum: "credit" "externalCredit" "refund" "projected" Classificação financeira da operação. Não corresponde ao status do pedido.
operationType	string Enum: "credit" "refund" "transfer" Tipo da operação financeira.
paymentMethod	string Enum: "creditCard" "nupay" "pix" "transfer" Método de pagamento da operação.
liquidationType	string Enum: "internal" "external" Tipo da liquidação. É especialmente útil em operações de transferência.
provider	Array of strings Provider responsável pela operação. Pode ser enviado uma vez, repetido ou como lista separada por vírgula.
pageSize	integer [ 1 .. 100 ] Default: 30 Quantidade máxima de registros por página. O padrão é 30.
cursor	string Identificador utilizado para consultar a próxima página.

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Responses

Response samples

Content type

application/json

{"merchantId": "32",
"operations": [{"id": "eb523507-6844-4f13-a6f0-c910e7dd5479",
"status": "projected",
"createdAt": "2026-08-10T16:15:00.000-03:00",
"updatedAt": "2026-08-10T16:15:00.000-03:00",
"provider": "tuna",
"anticipationPlan": "D+30",
"financial": {"grossAmount": {"value": 80,
"currency": "BRL"
},
"feeAmount": {"value": 1.48,
"currency": "BRL"
},
"netAmount": {"value": 78.52,
"currency": "BRL"
}
},
"order": {"number": "234567890",
"status": "Delivered",
"createdAt": "2026-08-10T16:10:00.000-03:00",
"updatedAt": "2026-08-10T16:45:00.000-03:00",
"isEdited": false,
"amount": {"value": 80,
"currency": "BRL"
},
"editedAt": null,
"editedAmount": null
},
"payment": {"method": "nupay",
"expectedPayoutAt": "2026-09-09T18:00:00.000-03:00",
"amount": {"value": 80,
"currency": "BRL"
},
"refundedAmount": null,
"refundType": null,
"methodDetails": "Nupay Credito",
"cardBrand": null,
"installmentNumber": 1,
"installments": 1
},
"operation": {"type": "credit",
"description": "credit",
"sourceStatus": "scheduled",
"date": "2026-08-10T16:15:00.000-03:00"
},
"liquidation": {"status": "pendingLiquidation",
"type": "internal",
"createdAt": "2026-08-10T16:15:00.000-03:00",
"updatedAt": "2026-08-10T16:15:00.000-03:00",
"date": null,
"bank": null,
"product": "nupay"
}
}
],
"pageInfo": {"pageSize": 1,
"totalItems": 1,
"hasNextPage": false,
"nextCursor": null
}
}

Reembolso - Cálculo por pedido

Objetivo

Essa consulta faz parte das consultas de Reembolso. Ela traz o valor calculado para cada “ajuste financeiro” realizado em cada pedido, em regime de competência da semana.

Esses são os itens calculados semanalmente para cada pedido, retornados por esse endpoint:

Markup: markup na venda de produtos Ambev.
Frete: diferença entre os valores de entrega negociado com o estabelecimento e os pagos pelo cliente, incluindo taxas adicionais.
Cupons e Descontos: valores de cupons e descontos aplicados nos pedidos.
Taxas e Comissões: cobranças de plataforma e marketplace.

Semanalmente, o motor de reembolso calcula a operação do PDV na semana anterior:

Reembolsos por pedido da semana anterior + incentivos operacionais da semana anterior + pagamentos manuais da semana anterior = resultado do reembolso a ser pago na semana atual

Se o resultado for positivo, o PDV recebe o pagamento da semana aterior na semana atual
Se o resultado for zero ou negativo, o valor do pagamento de reembolso daquela semana é zerado

Use esse endpoint junto com os outros endpoints de reembolso para calcular os reembolsos semanais. Para mais informações do fluxo financeiro do Zé, veja:

A Introdução ao módulo Financial
A FAQ de Pagamentos Online para PDVs: Pagamento Online | Portal do Parceiro.
A FAQ de Reembolsos para PDVs: Pagamento | Portal do Parceiro.

Quando usar

Utilize este endpoint quando:

For necessário consultar resumos de repasse por pedido de um estabelecimento.
Houver um merchantId válido ao qual o parceiro tenha acesso.
O período de consulta estiver definido por startDate e endDate, ambos no formato YYYY-MM-DD.
For desejável paginar os resultados usando page e pageSize.
For necessário filtrar a consulta por um pedido específico, desde que ele pertença ao período financeiro informado.
O objetivo for apoiar conciliação financeira na granularidade do pedido.

Quando NÃO usar

Este endpoint não deve ser utilizado para:

Consultar detalhes completos de um pedido específico.
Acompanhar o ciclo de vida operacional do pedido em tempo real.
Criar, atualizar, cancelar ou restaurar pedidos.
Obter a visão financeira completa do seller.
Detalhar a memória de cálculo de cada componente financeiro.

Importante

Requer header Authorization: Bearer <token> e o parceiro deve ter permissão sobre o merchantId consultado.

Os campos startDate e endDate são obrigatórios e devem ser enviados no formato YYYY-MM-DD, por exemplo 2026-05-18. Valores com horário completo, como 2026-05-18T00:00:00.000Z, não fazem parte do contrato deste endpoint.

Como o período é interpretado:

A API usa startDate e endDate para descobrir quais semanas ISO fazem parte do intervalo informado.
Uma semana ISO começa na segunda-feira e termina no domingo.
Não é possível consultar a semana atual enquanto ela ainda estiver em andamento; somente semanas ISO já fechadas são aceitas.
O período deve estar dentro do mesmo ano e pode cobrir, no máximo, as últimas 5 semanas ISO fechadas.
Como a busca é feita por semana ISO, a API consulta as semanas inteiras selecionadas. Por isso, a resposta pode trazer pedidos pertencentes a essas semanas mesmo quando a data do pedido estiver fora do recorte literal de startDate e endDate.

Exemplo: startDate=2026-05-18 e endDate=2026-05-24 selecionam a semana ISO 21 de 2026. Já startDate=2026-05-01 e endDate=2026-05-31 selecionam as semanas ISO 18 a 22 de 2026.

Na resposta, cada pedido traz extensions.financialDetails.isoWeek e extensions.financialDetails.isoYear, indicando a semana financeira usada como referência para aquele resumo.

O filtro orderNumber é opcional. Quando informado, ele restringe a busca ao pedido enviado dentro das semanas ISO selecionadas por startDate e endDate. Se o pedido não pertencer ao período financeiro informado, ele não será retornado.

Este endpoint só traz informações financeiras atreladas ao pedido e expõe os valores finais resumidos de cada componente. Ele não representa a visão financeira completa do seller e não detalha a memória de cálculo de cada valor.

Paginação:

page é opcional, inicia em 1 e usa 1 como valor padrão.
pageSize é opcional, usa 100 como valor padrão e aceita valores entre 1 e 200.
O campo pageInfo.hasNextPage indica se há mais páginas disponíveis.

Valores monetários são retornados como objetos com value e currency. Para este endpoint, a moeda retornada é BRL.

Componentes financeiros retornados:

MARKUP: markup na venda de produtos Ambev.
DELIVERY_FEE: frete; diferença entre os valores de entrega negociado com o estabelecimento e os pagos pelo cliente, incluindo taxas adicionais.
discounts: valor restituído do cupom utilizado no pedido.
SAMPLING_GIFTS: valor de produtos vendidos a preço simbólico no Zé para experimentação do cliente.
MARKETPLACE_DISCOUNT: restituição de promoção aplicada automaticamente pelo Zé nos produtos.
TAKE_RATE: comissão aplicada na venda de produtos marketplace.
SERVICE_FEE: percentual cobrado sobre o valor do pedido, conforme contrato com o estabelecimento.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: GET summaries com merchantId, startDate, endDate e paginação
  API->>API: Seleciona semanas ISO fechadas
  API-->>Parceiro: 200 com orders, pageInfo e financialDetails
  Parceiro->>API: GET summaries com page=N+1
  API-->>Parceiro: 200 com próxima página, se existir

path Parameters

merchantId

required

string

Example: 1234

O id do estabelecimento

query Parameters

startDate required	string <date> Example: startDate=2026-05-18 Data inicial do período financeiro no formato YYYY-MM-DD. A API usa `startDate` e `endDate` para selecionar semanas ISO completas; somente semanas ISO já fechadas podem ser consultadas.
endDate required	string <date> Example: endDate=2026-05-24 Data final do período financeiro no formato YYYY-MM-DD. Deve estar no mesmo ano de `startDate`; o período pode cobrir, no máximo, as últimas 5 semanas ISO fechadas.
page	integer >= 1 Default: 1 O numero da pagina, iniciando em 1.
pageSize	integer [ 1 .. 200 ] Default: 100 O numero de itens por pagina.
orderNumber	string Example: orderNumber=123456789 Número do pedido para filtrar a consulta dentro do período financeiro informado.

header Parameters

Authorization

required

string

token de autenticacao para acessar o recurso

Responses

Response samples

Content type

application/json

{"merchantId": "12345",
"startDate": "2026-05-23",
"endDate": "2026-06-04",
"orders": [{"displayId": "877379758",
"createdAt": "2026-05-18T19:30:57",
"total": {"otherFees": {"value": 0,
"currency": "BRL"
},
"discount": {"value": 0,
"currency": "BRL"
},
"orderReimbursement": {"value": 0,
"currency": "BRL"
}
},
"otherFees": [{"type": "DELIVERY_FEE",
"price": {"value": 0,
"currency": "BRL"
}
},
{"type": "SERVICE_FEE",
"price": {"value": 0,
"currency": "BRL"
}
},
{"type": "MARKETPLACE_DISCOUNT",
"price": {"value": 0,
"currency": "BRL"
}
},
{"type": "SAMPLING_GIFTS",
"price": {"value": 0,
"currency": "BRL"
}
},
{"type": "MARKUP",
"price": {"value": 0,
"currency": "BRL"
}
},
{"type": "TAKE_RATE",
"price": {"value": 0,
"currency": "BRL"
}
}
],
"discounts": [{"description": "COUPON",
"amount": {"value": 0,
"currency": "BRL"
}
}
],
"extensions": {"financialDetails": {"isoWeek": 21,
"isoYear": 2026
}
}
}
],
"pageInfo": {"currentPage": 1,
"pageSize": 1,
"totalItems": 2,
"hasNextPage": true
}
}

Reembolso - Incentivos operacionais

Objetivo

Essa consulta faz parte das consultas de Reembolso. Ela retorna o valor de incentivos operacionais calculados para o PDV na semana de competência.

Incentivos operacionais são valores pagos ao PDV semanalmente, com base no atingimento das metas de indicadores previstos no Termo Geral de Contratação. A resposta traz os valores consolidados da semana consultada, incluindo:

Valor por pedido válido: valor de incentivo considerado para cada pedido válido na semana.
Pedidos válidos: quantidade de pedidos considerados no cálculo do incentivo.
Valor total: soma final do incentivo operacional apurado para a semana.

Semanalmente, o motor de reembolso calcula a operação do PDV na semana anterior:

Reembolsos por pedido da semana anterior + incentivos operacionais da semana anterior + pagamentos manuais da semana anterior = resultado do reembolso a ser pago na semana atual

Se o resultado for positivo, o PDV recebe o pagamento da semana aterior na semana atual
Se o resultado for zero ou negativo, o valor do pagamento de reembolso daquela semana é zerado

Use esse endpoint junto com os outros endpoints de reembolso para calcular os reembolsos semanais. Para mais informações do fluxo financeiro do Zé, veja:

A Introdução ao módulo Financial
A FAQ de Pagamentos Online para PDVs: Pagamento Online | Portal do Parceiro.
A FAQ de Reembolsos para PDVs: Pagamento | Portal do Parceiro.

Quando usar

Utilize este endpoint quando:

For necessário consultar o resumo semanal de incentivos operacionais de um estabelecimento.
Houver um merchantId válido ao qual o parceiro tenha acesso.
A semana financeira estiver definida por isoYear e isoWeek.
O objetivo for apoiar conciliação financeira de incentivos operacionais semanais.
A consulta precisar validar o valor por pedido válido, a quantidade de pedidos válidos e o total repassado na semana.

Quando NÃO usar

Este endpoint não deve ser utilizado para:

Consultar repasses financeiros calculados pedido a pedido; para isso, use GET /merchants/{merchantId}/reimbursements/orders/summaries.
Consultar detalhes completos de um pedido específico.
Acompanhar o ciclo de vida operacional do pedido em tempo real.
Criar, atualizar, cancelar ou restaurar pedidos.
Obter a visão financeira completa do seller.
Detalhar a memória de cálculo, metas, elegibilidade ou regras internas da campanha de incentivo.
Consultar várias semanas em uma única chamada.
Consultar KPIs operacionais. Para isso, use o endpoint de KPIs GET /merchants/{merchantId}/kpis.

Importante

Requer header Authorization: Bearer <token> e o parceiro deve ter permissão sobre o merchantId consultado.

Os campos isoYear e isoWeek são obrigatórios:

isoYear deve ser um número inteiro positivo, por exemplo 2026.
isoWeek deve ser um número inteiro entre 1 e 53.
A combinação de isoYear e isoWeek deve representar uma semana ISO existente. Alguns anos não possuem semana ISO 53.

Uma semana ISO começa na segunda-feira e termina no domingo. Este endpoint consulta uma única semana por chamada; ele não aceita startDate, endDate, paginação ou filtro por pedido.

Janela de consulta:

Na segunda-feira e na terça-feira, a semana imediatamente anterior ainda não fica disponível. A API permite consultar as 4 semanas ISO fechadas anteriores a ela.
De quarta-feira a domingo, a API permite consultar as últimas 5 semanas ISO fechadas antes da semana atual, começando pela semana ISO imediatamente anterior.
A semana atual nunca fica disponível enquanto ainda está em andamento.
Quando a semana informada está fora da janela liberada, a API retorna 404 Not Found.

Exemplo: em uma quarta-feira da semana ISO 22 de 2026, é possível consultar as semanas ISO 21, 20, 19, 18 e 17. Em uma segunda-feira ou terça-feira da semana ISO 22 de 2026, é possível consultar as semanas ISO 20, 19, 18 e 17; a semana ISO 21 ainda não está liberada.

Quando não houver resumo de incentivo operacional para o estabelecimento e a semana informados, a API também retorna 404 Not Found.

Valores monetários são retornados como objetos com value e currency. Para este endpoint, a moeda retornada é BRL.

Campos retornados:

operationalIncentives: lista com o resumo consolidado de incentivos operacionais da semana consultada.
amountPerOrder.value: valor de incentivo por pedido válido.
amountPerOrder.currency: moeda do valor por pedido válido.
totalAmount.value: valor total do incentivo operacional repassado na semana.
totalAmount.currency: moeda do valor total.
validOrders: quantidade de pedidos válidos considerados no cálculo.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  participant Financeiro as Motor financeiro
  Parceiro->>API: GET operational-incentives com merchantId, isoYear e isoWeek
  API->>API: Valida permissao e janela de semana ISO
  API->>Financeiro: Consulta resumo de incentivo da semana
  Financeiro-->>API: total, valor por pedido e pedidos validos
  API-->>Parceiro: 200 com operationalIncentives

path Parameters

merchantId

required

string

Example: 1234

O id do estabelecimento

query Parameters

isoYear required	integer >= 1 Example: isoYear=2026 Ano ISO da semana financeira consultada. Deve ser um número inteiro positivo.
isoWeek required	integer [ 1 .. 53 ] Example: isoWeek=21 Semana financeira no padrão ISO. Deve ser um número inteiro entre 1 e 53 e existir no ano ISO informado em `isoYear`.

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Responses

Response samples

Content type

application/json

{"operationalIncentives": [{"amountPerOrder": {"value": 2.5,
"currency": "BRL"
},
"totalAmount": {"value": 250,
"currency": "BRL"
},
"validOrders": 100
}
]
}

Reembolso - Lista de pagamentos manuais

Objetivo

Essa consulta faz parte das consultas de Reembolso. Ela retorna os pagamentos manuais lançados para um estabelecimento em um período financeiro.

"Pagamentos manuais" são ajustes e correções aplicadas à restituição financeira de PDVs. Podem ser relativos a incentivos sazonais (como Páscoa, Carnaval e Natal), correções retroativas de pagamentos, adicionais de frete em períodos específicos e outras questões pontuais não automatizadas. Esses ajustes podem ser positivos (adicionando valor à restituição) ou negativos (realizando deduções), a depender da natureza do ajuste.

A resposta traz a lista de ajustes lançados com competência financeria nas semanas ISO consultadas. Semanas sem lançamentos também são preservadas na resposta com entries: [].

Semanalmente, o motor de reembolso calcula a operação do PDV na semana anterior:

Reembolsos por pedido da semana anterior + incentivos operacionais da semana anterior + pagamentos manuais da semana anterior = resultado do reembolso a ser pago na semana atual

Se o resultado for positivo, o PDV recebe o pagamento da semana aterior na semana atual
Se o resultado for zero ou negativo, o valor do pagamento de reembolso daquela semana é zerado

Use esse endpoint junto com os outros endpoints de reembolso para calcular os reembolsos semanais. Para mais informações do fluxo financeiro do Zé, veja:

A Introdução ao módulo Financial
A FAQ de Pagamentos Online para PDVs: Pagamento Online | Portal do Parceiro.
A FAQ de Reembolsos para PDVs: Pagamento | Portal do Parceiro.

Quando usar

Utilize este endpoint quando:

For necessário consultar lançamentos financeiros manuais de um estabelecimento.
Houver um merchantId válido ao qual o parceiro tenha acesso.
O período de consulta estiver definido por startDate e endDate, ambos no formato YYYY-MM-DD.
O período estiver dentro das últimas 5 semanas ISO fechadas.
For desejável paginar os lançamentos retornados usando page e pageSize.
O objetivo for apoiar conciliação financeira semanal de ajustes manuais do PDV.

Quando NÃO usar

Este endpoint não deve ser utilizado para:

Consultar repasses financeiros calculados pedido a pedido; para isso, use GET /merchants/{merchantId}/reimbursements/orders/summaries.
Consultar incentivos operacionais semanais; para isso, use GET /merchants/{merchantId}/reports/operational-incentives.
Consultar detalhes completos de um pedido específico.
Acompanhar o ciclo de vida operacional do pedido em tempo real.
Criar, atualizar, cancelar ou restaurar pedidos.
Obter a visão financeira completa do seller.
Consultar a semana atual enquanto ela ainda está em andamento.
Consultar mais de 5 semanas ISO em uma única chamada.
Consultar períodos que gerem semanas ISO em anos diferentes.

Importante

Requer header Authorization: Bearer <token> e o parceiro deve ter permissão sobre o merchantId consultado.

Os campos startDate e endDate são obrigatórios e devem ser enviados no formato YYYY-MM-DD, por exemplo 2026-06-08. Valores com horário completo, como 2026-06-08T00:00:00.000Z, não fazem parte do contrato deste endpoint.

Como o período é interpretado:

A API usa startDate e endDate para descobrir quais semanas ISO fazem parte do intervalo informado.
Uma semana ISO começa na segunda-feira e termina no domingo.
A semana atual nunca fica disponível enquanto ainda está em andamento.
A semana imediatamente anterior à data da consulta é a semana mais recente permitida.
O período pode cobrir, no máximo, as últimas 5 semanas ISO fechadas.
O período informado deve gerar semanas ISO pertencentes a um único ano ISO.
Como a busca é feita por semana ISO, a API consulta as semanas inteiras selecionadas.

Exemplo: startDate=2026-06-08 e endDate=2026-06-25 selecionam as semanas ISO 24, 25 e 26 de 2026. A resposta traz isoYear no topo e cada grupo semanal em manualPaymentWeeks.

Paginação:

page é opcional, inicia em 1 e usa 1 como valor padrão.
pageSize é opcional, usa 100 como valor padrão e aceita valores entre 1 e 200.
O campo pageInfo.hasNextPage indica se há mais páginas disponíveis.

Valores monetários são retornados como objetos com value e currency. Para este endpoint, a moeda retornada é BRL.

Campos retornados:

merchantId: estabelecimento consultado.
startDate: data inicial consultada.
endDate: data final consultada.
isoYear: ano ISO das semanas financeiras retornadas.
manualPaymentWeeks: lista de semanas ISO consultadas.
manualPaymentWeeks[].isoWeek: semana financeira no padrão ISO.
manualPaymentWeeks[].entries: lançamentos manuais daquela semana. Pode ser uma lista vazia.
entries[].description: descrição do lançamento manual.
entries[].type: tipo do lançamento manual retornado pela API.
entries[].amount: valor monetário do lançamento manual.
pageInfo: informações de paginação da consulta.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  participant Financeiro as Motor financeiro
  Parceiro->>API: GET manual-payments com merchantId, startDate, endDate e paginação
  API->>API: Valida permissao e janela das semanas ISO fechadas
  API->>Financeiro: Consulta lançamentos manuais por ano ISO e semanas
  Financeiro-->>API: semanas com lançamentos manuais
  API-->>Parceiro: 200 com manualPaymentWeeks e pageInfo

path Parameters

merchantId

required

string

Example: 1234

O id do estabelecimento

query Parameters

startDate required	string <date> Example: startDate=2026-06-08 Data inicial do período financeiro no formato YYYY-MM-DD. A API usa `startDate` e `endDate` para selecionar semanas ISO completas; somente semanas ISO já fechadas podem ser consultadas.
endDate required	string <date> Example: endDate=2026-06-25 Data final do período financeiro no formato YYYY-MM-DD. Deve gerar semanas ISO no mesmo ano de `startDate`; o período pode cobrir, no máximo, as últimas 5 semanas ISO fechadas.
page	integer >= 1 Default: 1 O número da página, iniciando em 1.
pageSize	integer >= 1 Default: 100 O número de itens por página.

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Responses

Response samples

Content type

application/json

{"merchantId": "32",
"startDate": "2026-06-08",
"endDate": "2026-06-25",
"isoYear": 2026,
"manualPaymentWeeks": [{"isoWeek": 24,
"entries": [{"description": "DESCRICAO_DO_PAGAMENTO",
"type": "DISCOUNT",
"amount": {"value": 2500,
"currency": "BRL"
}
},
{"description": "DESCRICAO_DO_PAGAMENTO",
"type": "MARKUP",
"amount": {"value": 1500.5,
"currency": "BRL"
}
}
]
},
{"isoWeek": 25,
"entries": [ ]
}
],
"pageInfo": {"currentPage": 1,
"pageSize": 100,
"totalItems": 2,
"hasNextPage": false
}
}

Homologation

Sobre Homologation

Os endpoints do grupo Homologation ajudam você a validar a sua integração antes de entrar em produção. Com eles, é possível gerar pedidos de teste e simular os eventos que a sua integração receberia em situações reais do dia a dia. Dessa forma, você testa de ponta a ponta como o seu sistema recebe e trata cada evento.

Disponibilidade

Os endpoints deste grupo funcionam somente no ambiente de desenvolvimento (release):

https://seller-public-api.release.ze.delivery

Eles não estão disponíveis em produção.

Quando usar os endpoints de homologação

Para verificar se a sua integração recebe os eventos de pedido, tanto por polling quanto por webhook.
Para testar cenários difíceis de reproduzir com pedidos reais, como entregas e cancelamentos diversos.
Para repetir os testes quantas vezes forem necessárias durante o desenvolvimento.

Quando NÃO usar

Para operar pedidos reais: utilize os grupos Orders e Events em Produção.

Como a homologação se relaciona com os demais grupos

A simulação usa os mesmos canais que você já utiliza na integração:

Events: os eventos simulados aparecem no polling com o campo adicional mocked: true.
Webhooks: se o seu webhook estiver ativo e inscrito em eventos de pedido, os eventos simulados também são enviados para a sua URL.
Orders: o pedido teste pode ser consultado em GET /orders/{orderNumber} enviando o header mocked: true.

Passo a passo sugerido

Autentique-se com as credenciais do ambiente de desenvolvimento (POST /auth).
(Opcional) Configure e ative o seu webhook (PATCH /webhooks) para receber os eventos em tempo real.
Escolha o cenário que deseja testar e chame POST /flows/v1/homologation/create-order-scenario.
Confira se a sua integração recebeu os eventos esperados, pelo webhook ou pelo polling (GET /events:polling).
Consulte os detalhes do pedido teste em GET /orders/{orderNumber} com o header mocked: true.

flowchart TD
  A["POST /auth"] --> B["PATCH /webhooks (opcional)"]
  B --> C["POST /flows/v1/homologation/create-order-scenario"]
  C --> D{"Como você recebe eventos?"}
  D -->|Webhook ativo| E["Eventos chegam na sua URL"]
  D -->|Polling| F["GET /events:polling"]
  E --> G["GET /orders/{orderNumber} com mocked: true"]
  F --> G

Criar cenário de pedido para homologação

Objetivo

Permitir que o parceiro homologue a sua integração de forma autônoma. Ao chamar este endpoint, a Zé Seller Public API cria um pedido teste para a loja vinculada às suas credenciais e simula a sequência de eventos do cenário escolhido, exatamente como eles chegariam em uma operação real.

Assim, você consegue validar se o seu sistema (PDV, ERP ou plataforma de integração) recebe e trata corretamente cada situação do ciclo de vida de um pedido.

O tempo de disparo dos eventos é predefinido para testes, podendo levar entre 30 e 60 segundos para o disparo. Eles não refletem o tempo da operação real do Zé.

Quando usar

Utilize este endpoint durante a fase de homologação, sempre que quiser testar como a sua integração reage a um cenário específico. Basta informar qual cenário deseja simular:

created_order — Pedido criado

O pedido é criado e a sua integração recebe somente o evento de pedido criado (CREATED). Útil para validar a recepção de novos pedidos.

order_expired_by_timeout — Pedido expirado por falta de aceite

Simula um pedido que não foi aceito dentro do prazo. A sequência é:

O cliente realiza o pedido.
A sua integração recebe o evento de pedido criado (CREATED).
O pedido não recebe nenhuma confirmação (nem por API, nem pelo painel do PDV (Seu Zé))
Como o pedido não foi aceito a tempo, a sua integração recebe o evento de pedido expirado, que chega como cancelamento (CANCELLED).

Na operação real, o prazo de confirmação de um pedido pode variar de 2 a 12 minutos após o pedido cair para um PDV, dependendo de fatores de seleção do Zé. Na simulação, essa diferença segue o intervalo padrão informado

Quando NÃO usar

Em produção: este endpoint está disponível somente no ambiente de desenvolvimento (release) e não funciona em produção. Só é possível gerar pedidos teste, e não representam uma venda.
Para testar ações sobre o pedido (como confirmar ou cancelar): nesta versão, apenas os eventos do cenário são simulados.

Importante

Ambiente: utilize apenas o servidor de desenvolvimento (https://seller-public-api.release.ze.delivery).
Autenticação: a chamada usa o mesmo token das demais requisições; a loja do pedido é identificada a partir das suas credenciais. É necessário ter ao menos uma loja ativa vinculada a elas.
Pedido teste: o pedido é criado em uma base exclusiva de testes. Para consultá-lo em GET /orders/{orderNumber}, envie o header mocked: true, usando o número do pedido retornado na resposta.
Polling: os eventos simulados aparecem em GET /events:polling como os demais, com o campo adicional mocked: true.
Webhook: os eventos também são enviados para a URL configurada no seu webhook, desde que ele esteja ativo e inscrito em eventos de pedido (ORDER_EVENTS). Veja o grupo Webhooks.
Expiração: nos cenários de expiração, o encerramento do pedido é comunicado pelo evento CANCELLED, da mesma forma que acontece em produção.

sequenceDiagram
  participant Parceiro as Seu sistema
  participant API as Zé Seller Public API
  Parceiro->>API: POST /flows/v1/homologation/create-order-scenario
  API-->>Parceiro: simulação concluída + número do pedido fictício
  API-)Parceiro: eventos do cenário via webhook (se ativo)
  Parceiro->>API: GET /events:polling
  API-->>Parceiro: eventos do cenário (mocked: true)
  Parceiro->>API: GET /orders/{orderNumber} com header mocked: true
  API-->>Parceiro: detalhes do pedido fictício

flowchart LR
  subgraph criado [created_order]
    C1[CREATED]
  end
  subgraph inatividade [order_expired_by_merchant_inactivity]
    I1[CREATED] --> I2[CONFIRMED] --> I3["CANCELLED (expirado)"]
  end
  subgraph timeout [order_expired_by_timeout]
    T1[CREATED] --> T2["CANCELLED (expirado)"]
  end

header Parameters

Authorization

required

string

token de autenticação para acessar o recurso

Request Body schema: application/json

scenarioId

required

string

Enum: "created_order" "order_expired_by_timeout"

Cenário que será simulado.

created_order: pedido criado; envia o evento CREATED.
order_expired_by_timeout: pedido criado, aceito e depois expirado por inatividade; envia os eventos CREATED, CONFIRMED e CANCELLED.
order_expired_by_timeout: pedido criado e não aceito dentro do prazo; envia os eventos CREATED e CANCELLED.

Responses

Request samples

Payload

Content type

application/json

{"scenarioId": "order_expired_by_timeout"
}

Response samples

Content type

application/json

{"flowId": "3f1c2a7e-9b4d-4e2a-8c1f-6d5e4b3a2c10",
"status": "COMPLETED",
"orderId": 123456789
}

Changelog

2026-11-03

Endpoint(s) impactado(s): GET /orders/{orderNumber}
Tipo de mudança: Melhoria
Descrição: A documentação pública da consulta de pedido inclui a nova modalidade de entrega ECONOMY no campo type, correspondente a entrega “sem pressa” com prazo de até duas horas, além das modalidades já documentadas.
🔹 Antes vs Depois
Antes:

{
  "type": "DELIVERY"
}

Depois:

{
  "type": "ECONOMY"
}

🔹 Impacto para parceiros: Ajuste opcional — integrações podem reconhecer e exibir a modalidade ECONOMY a partir do campo type, considerando sua descrição e prazo de entrega.

Endpoint(s) impactado(s): GET /merchants/{merchantId}/orders/history
Tipo de mudança: Melhoria
Descrição: A documentação pública do histórico de pedidos finalizados inclui a nova modalidade de entrega ECONOMY no campo deliveryType de cada registro, correspondente a entrega “sem pressa” com prazo de até duas horas.
🔹 Antes vs Depois
Antes:

{
  "deliveryType": "DELIVERY"
}

Depois:

{
  "deliveryType": "ECONOMY"
}

🔹 Impacto para parceiros: Ajuste opcional — integrações podem reconhecer, exibir e filtrar a modalidade ECONOMY a partir do campo deliveryType de cada item no histórico de pedidos.

2026-10-20

Endpoint(s) impactado(s): GET /orders/{orderNumber}
Tipo de mudança: Melhoria
Descrição: A consulta de pedido passa a documentar em otherFees a contribuição extra feita pelo cliente e destinada ao PDV, com o novo valor optional_extra_contribution em type. O campo observation contém uma observação adicional e aparece quando necessário.
🔹 Antes vs Depois
Antes: O contrato de otherFees descrevia apenas taxas do tipo DELIVERY_FEE e não incluía o campo observation.

{
  "otherFees": [
    {
      "name": "string",
      "type": "DELIVERY_FEE",
      "receivedBy": "MERCHANT",
      "price": {
        "value": 0,
        "currency": "string"
      }
    }
  ]
}

Depois: O contrato também descreve a contribuição extra feita pelo cliente e destinada ao PDV. O campo observation aparece quando necessário.

{
  "otherFees": [
    {
      "name": "string",
      "type": "optional_extra_contribution",
      "receivedBy": "MERCHANT",
      "price": {
        "value": 0,
        "currency": "string"
      },
      "observation": "string"
    }
  ]
}

🔹 Impacto para parceiros: Ajuste opcional — integrações podem reconhecer o novo tipo de taxa como contribuição extra feita pelo cliente e destinada ao PDV, além de consumir a observação adicional quando presente.

2026-10-15

Endpoint(s) impactado(s): POST /flows/v1/homologation/create-order-scenario
Tipo de mudança: Nova feature
Descrição: A documentação pública passa a incluir o endpoint de homologação que cria um pedido teste e simula a sequência de eventos do cenário informado (scenarioId), para validação da integração. O recurso está disponível somente no ambiente de desenvolvimento (release).
🔹 Antes vs Depois
Antes: A especificação pública não descrevia a rota de criação de cenários de pedido para homologação nem o contrato de requisição e resposta.
Depois:

{
  "flowId": "string",
  "status": "string",
  "orderId": 0
}

🔹 Impacto para parceiros: Ajuste opcional — parceiros em fase de homologação podem utilizar o endpoint documentado para simular cenários de pedido no ambiente de desenvolvimento; não há alteração em contratos de produção.

Endpoint(s) impactado(s): GET /merchants/{merchantId}/orders/history
Tipo de mudança: Melhoria
Descrição: A documentação pública do histórico de pedidos finalizados passa a descrever o campo extraContribution em cada registro retornado, indicando o valor total da contribuição extra feita pelo cliente e destinada ao PDV.
🔹 Antes vs Depois
Antes:

{
  "number": "string",
  "date": "string",
  "customerName": "string",
  "status": "CREATED",
  "deliveryType": "DELIVERY",
  "payment": {
    "type": "CASH",
    "category": "PENDING"
  },
  "total": 0,
  "subTotal": 0,
  "discount": 0,
  "discountDescription": "string",
  "shippingFee": 0,
  "rating": {
    "value": 0,
    "description": "string",
    "reasons": [
      "string"
    ]
  },
  "customerComment": "string",
  "items": [
    {
      "name": "string",
      "quantity": 0,
      "unitPrice": 0,
      "subTotal": 0
    }
  ],
  "statusHistory": [
    {
      "status": "CREATED",
      "date": "string",
      "description": "string",
      "reasons": [
        "string"
      ]
    }
  ]
}

Depois:

{
  "number": "string",
  "date": "string",
  "customerName": "string",
  "status": "CREATED",
  "deliveryType": "DELIVERY",
  "payment": {
    "type": "CASH",
    "category": "PENDING"
  },
  "total": 0,
  "subTotal": 0,
  "discount": 0,
  "discountDescription": "string",
  "shippingFee": 0,
  "extraContribution": 0,
  "rating": {
    "value": 0,
    "description": "string",
    "reasons": [
      "string"
    ]
  },
  "customerComment": "string",
  "items": [
    {
      "name": "string",
      "quantity": 0,
      "unitPrice": 0,
      "subTotal": 0
    }
  ],
  "statusHistory": [
    {
      "status": "CREATED",
      "date": "string",
      "description": "string",
      "reasons": [
        "string"
      ]
    }
  ]
}

🔹 Impacto para parceiros: Ajuste opcional — a propriedade extraContribution passa a constar no contrato publicado de cada pedido no histórico; integrações existentes não precisam de alteração, mas podem consumir o campo para exibir o valor da contribuição extra do cliente destinada ao PDV.

2026-10-08

Tipo de mudança: Melhoria
Descrição: A documentação pública reorganiza o conteúdo de KPIs do estabelecimento: o material passa a ficar agrupado na seção Merchants (Estabelecimentos), em vez de aparecer em outra área da navegação, para facilitar a localização por quem integra operações de loja.
🔹 Antes vs Depois
Antes: As orientações e referências sobre KPIs de merchant não estavam organizadas sob a seção de estabelecimentos na documentação.
Depois: O conteúdo de KPIs do estabelecimento fica disponível na seção Merchants, alinhado ao restante da documentação de estabelecimento.
🔹 Impacto para parceiros: Nenhum impacto — não há alteração em endpoints, autenticação ou payloads; apenas reorganização da documentação no portal.

Tipo de mudança: Melhoria
Descrição: A seção da documentação antes identificada como Reports passa a se chamar Financials, refletindo melhor o escopo dos relatórios e fluxos financeiros descritos para parceiros.
🔹 Antes vs Depois
Antes: A navegação e os títulos da documentação usavam o nome Reports para o bloco de relatórios financeiros.
Depois: O mesmo conteúdo e endpoints documentados passam a ser apresentados sob o nome Financials.
🔹 Impacto para parceiros: Nenhum impacto — não há mudança de rotas, verbos HTTP nem de contratos; apenas o nome da seção na documentação.

Endpoint(s) impactado(s): GET /merchants/{merchantId}/financials/payments-reports
Tipo de mudança: Nova feature
Descrição: A API pública passa a documentar a consulta paginada das operações financeiras de pagamentos online de um estabelecimento, incluindo créditos, estornos e transferências. A navegação da seção Financials também foi reorganizada e ganhou orientações para integração e conciliação.
🔹 Antes vs Depois
Antes: A especificação pública não incluía a rota para consultar operações de pagamentos online nem descrevia seus filtros e sua resposta.
Depois:

{
  "merchantId": "string",
  "operations": [
    {
      "id": "string",
      "status": "credit",
      "createdAt": "string",
      "updatedAt": "string",
      "provider": "string",
      "anticipationPlan": "string",
      "financial": {
        "grossAmount": {
          "value": 0,
          "currency": "BRL"
        },
        "feeAmount": {
          "value": 0,
          "currency": "BRL"
        },
        "netAmount": {
          "value": 0,
          "currency": "BRL"
        }
      },
      "order": {
        "number": "string",
        "status": "string",
        "createdAt": "string",
        "updatedAt": "string",
        "isEdited": true,
        "amount": {
          "value": 0,
          "currency": "BRL"
        },
        "editedAt": "string",
        "editedAmount": {
          "value": 0,
          "currency": "BRL"
        }
      },
      "payment": {
        "method": "string",
        "expectedPayoutAt": "string",
        "amount": {
          "value": 0,
          "currency": "BRL"
        },
        "refundedAmount": {
          "value": 0,
          "currency": "BRL"
        },
        "refundType": "partial",
        "methodDetails": "string",
        "cardBrand": "string",
        "installmentNumber": 0,
        "installments": 0
      },
      "operation": {
        "type": "credit",
        "description": "string",
        "sourceStatus": "string",
        "date": "string"
      },
      "liquidation": {
        "status": "string",
        "type": "internal",
        "createdAt": "string",
        "updatedAt": "string",
        "date": "string",
        "bank": {
          "code": "string",
          "name": "string"
        },
        "product": "string"
      }
    }
  ],
  "pageInfo": {
    "pageSize": 0,
    "totalItems": 0,
    "hasNextPage": true,
    "nextCursor": "string"
  }
}

🔹 Impacto para parceiros: Ajuste opcional — integradores podem passar a consultar o novo endpoint para conciliar pagamentos online. As integrações existentes não precisam ser alteradas.

2026-08-24

Endpoint(s) impactado(s): GET /orders/{orderNumber}
Tipo de mudança: Melhoria
Descrição: A documentação pública do endpoint de consulta de pedido passa a descrever as informações necessárias para edição de itens: a preferência do cliente em observations (valores Substituir por item similar ou Cancelar o item.) e o identificador de categoria em items[].category.id, necessário para substituir um item em falta por outro da mesma categoria.
🔹 Antes vs Depois
Antes: A documentação do retorno de pedido não detalhava como interpretar observations nem o uso de items[].category.id no fluxo de edição de itens.
Depois: A documentação passa a explicar os valores possíveis de observations e como utilizar items[].category.id ao substituir itens em falta por outro da mesma categoria.
🔹 Impacto para parceiros: Nenhum impacto — não há alteração no contrato de requisição ou resposta; apenas documentação adicional sobre campos já presentes no esquema.

2026-07-28

Endpoint(s) impactado(s): GET /merchants/{merchantId}/menu/items
Tipo de mudança: Melhoria
Descrição: Revertida a alteração de documentação do endpoint de listagem paginada de itens do cardápio: as referências ao prefixo /v2 foram removidas e o caminho documentado volta a ser GET /merchants/{merchantId}/menu/items.
🔹 Antes vs Depois
Antes: Documentado como GET /v2/merchants/{merchantId}/menu/items (com o prefixo /v2).
Depois: Documentação revertida para GET /merchants/{merchantId}/menu/items, sem o prefixo /v2.
🔹 Impacto para parceiros: Nenhum impacto — não há alteração no contrato de requisição ou resposta; apenas a documentação do caminho foi corrigida para refletir o endereço real do endpoint.

2026-07-15

Endpoint(s) impactado(s): GET /merchants/{merchantId}/reports/manual-payments
Tipo de mudança: Nova feature
Descrição: A documentação pública da API passa a incluir o endpoint de pagamentos manuais, com detalhes de rota, parâmetros e estrutura de resposta para uso por parceiros. O endpoint permite consultar, de forma paginada, os pagamentos manuais lançados para um estabelecimento em um período financeiro, agrupados por semana ISO.
🔹 Antes vs Depois
Antes: O endpoint de pagamentos manuais não estava documentado na especificação pública da API.
Depois:

{
  "merchantId": "string",
  "startDate": "string",
  "endDate": "string",
  "isoYear": 0,
  "manualPaymentWeeks": [
    {
      "isoWeek": 0,
      "entries": [
        {
          "description": "string",
          "type": "string",
          "amount": {
            "value": 0,
            "currency": "BRL"
          }
        }
      ]
    }
  ],
  "pageInfo": {
    "currentPage": 0,
    "pageSize": 0,
    "totalItems": 0,
    "hasNextPage": true
  }
}

🔹 Impacto para parceiros: Ajuste opcional — parceiros que precisam consultar pagamentos manuais lançados para o estabelecimento podem agora utilizar o endpoint documentado; não há alteração em contratos existentes.

2026-07-14

Endpoint(s) impactado(s): GET /v2/merchants/{merchantId}/menu/items
Tipo de mudança: Melhoria
Descrição: Corrigida a documentação do endpoint de listagem paginada de itens do cardápio para incluir o prefixo /v2. O endpoint e seu contrato de requisição e resposta não foram alterados.
🔹 Antes vs Depois
Antes: Documentado como GET /merchants/{merchantId}/menu/items (sem o prefixo /v2).
Depois: Documentação corrigida para GET /v2/merchants/{merchantId}/menu/items, refletindo o caminho real do endpoint.
🔹 Impacto para parceiros: Nenhum impacto — não há alteração no contrato de requisição ou resposta; apenas a documentação do caminho foi corrigida.

2026-06-22

Endpoint(s) impactado(s): GET /merchants/{merchantId}/reports/operational-incentives
Tipo de mudança: Nova feature
Descrição: A documentação pública da API passa a incluir o endpoint de incentivos operacionais, com detalhes de rota, parâmetros e estrutura de resposta para uso por parceiros.
🔹 Antes vs Depois
Antes: O endpoint de incentivos operacionais não estava documentado na especificação pública da API.
Depois:

{
  "operationalIncentives": [
    {
      "amountPerOrder": {
        "value": 0,
        "currency": "BRL"
      },
      "totalAmount": {
        "value": 0,
        "currency": "BRL"
      },
      "validOrders": 0
    }
  ]
}

🔹 Impacto para parceiros: Ajuste opcional — parceiros que precisam consultar dados de incentivos operacionais podem agora utilizar o endpoint documentado; não há alteração em contratos existentes.

2026-06-16

Endpoint(s) impactado(s): GET /merchants/{merchantId}/reimbursements/orders/summaries
Tipo de mudança: Nova feature
Descrição: A documentação pública da API passa a incluir o endpoint de resumos de pedidos para reembolso, com detalhes de rota, parâmetros e estrutura de resposta para uso por parceiros.
🔹 Antes vs Depois
Antes: O endpoint de resumos de pedidos para reembolso não estava documentado na especificação pública da API.
Depois:

{
  "merchantId": "string",
  "startDate": "string",
  "endDate": "string",
  "orders": [
    {
      "displayId": "string",
      "createdAt": "string",
      "total": {
        "otherFees": {
          "value": 0,
          "currency": "BRL"
        },
        "discount": {
          "value": 0,
          "currency": "BRL"
        },
        "orderReimbursement": {
          "value": 0,
          "currency": "BRL"
        }
      },
      "otherFees": [
        {
          "type": "DELIVERY_FEE",
          "price": {
            "value": 0,
            "currency": "BRL"
          }
        }
      ],
      "discounts": [
        {
          "description": "string",
          "amount": {
            "value": 0,
            "currency": "BRL"
          }
        }
      ],
      "extensions": {
        "financialDetails": {
          "isoWeek": 0,
          "isoYear": 0
        }
      }
    }
  ],
  "pageInfo": {
    "currentPage": 0,
    "pageSize": 0,
    "totalItems": 0,
    "hasNextPage": true
  }
}

🔹 Impacto para parceiros: Ajuste opcional — parceiros que precisam consultar resumos financeiros de pedidos para fins de reembolso podem agora utilizar o endpoint documentado; não há alteração em contratos existentes.

2026-05-28

Endpoint(s) impactado(s): GET /orders/{orderNumber} PUT /orders/{orderNumber}/items
Tipo de mudança: Nova feature
Descrição: O campo hasLimitedPromotion passa a integrar o esquema de itens do pedido: na resposta de consulta de pedido (GET /orders/{orderNumber}), cada item do array items pode indicar se possui promoção limitada por quantidade; no payload de atualização de itens (PUT /orders/{orderNumber}/items), o campo hasLimitedPromotion pode ser enviado em removedItems para identificar itens com esse tipo de promoção.
🔹 Antes vs Depois
Antes:

{
  "id": 0,
  "index": 0,
  "name": "string",
  "externalCode": "string",
  "category": {
    "id": 0
  },
  "unit": "UNIT",
  "quantity": 0,
  "unitPrice": {
    "value": 0,
    "currency": "string"
  },
  "totalPrice": {
    "value": 0,
    "currency": "string"
  }
}

Depois:

{
  "id": 0,
  "index": 0,
  "name": "string",
  "externalCode": "string",
  "category": {
    "id": 0
  },
  "unit": "UNIT",
  "quantity": 0,
  "hasLimitedPromotion": true,
  "unitPrice": {
    "value": 0,
    "currency": "string"
  },
  "totalPrice": {
    "value": 0,
    "currency": "string"
  }
}

🔹 Impacto para parceiros: Ajuste opcional — o campo hasLimitedPromotion passa a estar disponível em cada item retornado por GET /orders/{orderNumber} e pode ser informado nos itens de removedItems em PUT /orders/{orderNumber}/items; integrações existentes não precisam de alteração, mas podem consumir ou enviar o novo campo para identificar e tratar promoções limitadas por quantidade.

2026-05-05

Endpoint(s) impactado(s): GET /merchants/{merchantId}/orders/history
Tipo de mudança: Nova feature
Descrição: A documentação pública da API passa a incluir o endpoint de histórico de pedidos finalizados do estabelecimento, com detalhes de rota, parâmetros e estrutura de resposta para uso por parceiros.
🔹 Antes vs Depois
Antes: O endpoint de histórico de pedidos não estava documentado na especificação pública da API.
Depois:

{
  "page": 0,
  "pageSize": 0,
  "hasNext": true,
  "items": [
    {
      "number": "string",
      "date": "string",
      "customerName": "string",
      "status": "CREATED",
      "deliveryType": "DELIVERY",
      "payment": {
        "type": "CASH",
        "category": "PENDING"
      },
      "total": 0,
      "subTotal": 0,
      "discount": 0,
      "discountDescription": "string",
      "shippingFee": 0,
      "rating": {
        "value": 0,
        "description": "string",
        "reasons": [
          "string"
        ]
      },
      "customerComment": "string",
      "items": [
        {
          "name": "string",
          "quantity": 0,
          "unitPrice": 0,
          "subTotal": 0
        }
      ],
      "statusHistory": [
        {
          "status": "CREATED",
          "date": "string",
          "description": "string",
          "reasons": [
            "string"
          ]
        }
      ]
    }
  ]
}

🔹 Impacto para parceiros: Ajuste opcional — parceiros que precisam consultar o histórico de pedidos finalizados de um estabelecimento podem agora utilizar o endpoint documentado; não há alteração em contratos existentes.

2026-05-04

Endpoint(s) impactado(s): GET /merchants/{merchantId}/menu/items
Tipo de mudança: Nova feature
Descrição: O payload de resposta da listagem paginada de itens do cardápio passa a incluir a propriedade isPortfolioIdeal, indicando se o item é considerado ideal para o portfólio do parceiro.
🔹 Antes vs Depois
Antes:

{
  "productId": 0,
  "externalProductId": "string",
  "name": "string",
  "description": "string",
  "status": "AVAILABLE",
  "image": {
    "URL": "string"
  },
  "ean": "string",
  "isFavorite": true,
  "brand": {
    "id": "string",
    "name": "string"
  },
  "categories": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "priceDetails": {
    "price": 0,
    "discount": {
      "endsAt": "string",
      "id": "string",
      "startsAt": "string",
      "values": [
        {
          "value": 0,
          "finalUnitPrice": 0,
          "minQuantity": 0,
          "maxQuantity": 0,
          "valueType": "FIXED_AMOUNT"
        }
      ]
    },
    "sellerDiscount": {
      "active": true,
      "percentageValues": [
        0
      ],
      "current": {
        "createdAt": "string",
        "discountPercentageValue": 0,
        "id": "string",
        "scheduleType": "ALWAYS",
        "active": true,
        "reason": "string",
        "updatedAt": "string",
        "username": "string"
      }
    },
    "takeRateSeller": {
      "active": true,
      "feeAmount": 0,
      "feePercentage": 0,
      "netPrice": 0
    }
  }
}

Depois:

{
  "productId": 0,
  "externalProductId": "string",
  "name": "string",
  "description": "string",
  "status": "AVAILABLE",
  "image": {
    "URL": "string"
  },
  "ean": "string",
  "isFavorite": true,
  "isPortfolioIdeal": true,
  "brand": {
    "id": "string",
    "name": "string"
  },
  "categories": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "priceDetails": {
    "price": 0,
    "discount": {
      "endsAt": "string",
      "id": "string",
      "startsAt": "string",
      "values": [
        {
          "value": 0,
          "finalUnitPrice": 0,
          "minQuantity": 0,
          "maxQuantity": 0,
          "valueType": "FIXED_AMOUNT"
        }
      ]
    },
    "sellerDiscount": {
      "active": true,
      "percentageValues": [
        0
      ],
      "current": {
        "createdAt": "string",
        "discountPercentageValue": 0,
        "id": "string",
        "scheduleType": "ALWAYS",
        "active": true,
        "reason": "string",
        "updatedAt": "string",
        "username": "string"
      }
    },
    "takeRateSeller": {
      "active": true,
      "feeAmount": 0,
      "feePercentage": 0,
      "netPrice": 0
    }
  }
}

🔹 Impacto para parceiros: Ajuste opcional — a propriedade isPortfolioIdeal passa a estar disponível em cada item retornado; integrações existentes não precisam de alteração, mas podem consumir o novo campo para sinalizar recomendações de portfólio.

Endpoint(s) impactado(s): GET /webhooks PATCH /webhooks
Tipo de mudança: Nova feature
Descrição: A documentação pública da API passa a incluir os endpoints de gerenciamento de webhooks, permitindo que parceiros consultem e configurem a URL de destino dos eventos de pedido.
🔹 Antes vs Depois
Antes: Endpoints não documentados na especificação pública.
Depois:

[
  {
    "clientId": "string",
    "hash": "string",
    "endpoint": "string",
    "active": true,
    "subscriptions": [
      "ORDER_EVENTS"
    ]
  }
]

🔹 Impacto para parceiros: Ajuste opcional — parceiros que desejam receber eventos de pedido via webhook podem agora consultar (GET /webhooks) e configurar (PATCH /webhooks) o endpoint de destino conforme o contrato publicado.

2026-04-23

Tipo de mudança: Nova feature
Descrição: A documentação pública passa a oferecer o fluxo Quero integrar com o Zé: nova opção na navegação do portal que abre um modal com formulário para manifestação de interesse em integrar com o Zé Delivery.
🔹 Antes vs Depois
Antes: No portal da documentação da API não existia um caminho dedicado para quem deseja iniciar o processo de integração.
Depois: Passa a existir uma entrada explícita no menu da documentação que abre, em modal, o formulário de interesse em integração.
🔹 Impacto para parceiros: Nenhum impacto — não há alteração em endpoints, autenticação ou payloads; apenas conteúdo e experiência complementares na documentação.

2026-04-16

Tipo de mudança: Melhoria
Descrição: A documentação pública da API passa a incluir uma seção de perguntas frequentes (FAQ), com respostas às dúvidas mais comuns de integração.
🔹 Antes vs Depois
Antes: Não havia FAQ publicado junto à documentação da API.
Depois: Passa a existir material de FAQ acessível na documentação, alinhado às dúvidas recorrentes de quem integra.
🔹 Impacto para parceiros: Nenhum impacto — não há mudança de rotas, verbos HTTP nem de contratos de request ou response; apenas documentação adicional.

2026-04-06

Endpoint(s) impactado(s): GET /merchants/{merchantId}/menu/items
Tipo de mudança: Breaking change
Descrição: Na listagem paginada de itens do cardápio, quando a resposta incluir o objeto current em priceDetails.sellerDiscount, o contrato público passa a exigir a propriedade scheduleType, com valores definidos pelo enum publicado no esquema.
🔹 Antes vs Depois
Antes:

{
  "current": {
    "createdAt": "string",
    "discountPercentageValue": 0,
    "id": "string",
    "active": true,
    "reason": "string",
    "updatedAt": "string",
    "username": "string"
  }
}

Depois:

{
  "current": {
    "createdAt": "string",
    "discountPercentageValue": 0,
    "id": "string",
    "scheduleType": "ALWAYS",
    "active": true,
    "reason": "string",
    "updatedAt": "string",
    "username": "string"
  }
}

🔹 Impacto para parceiros: Ajuste obrigatório — quem consome priceDetails.sellerDiscount.current precisa aceitar de forma estável a chave scheduleType e interpretar os valores enumerados conforme o contrato, sempre que current estiver presente.
Breaking change (se aplicável): Integrações que fixam o conjunto de campos de current, ignoram propriedades desconhecidas ou falham ao deserializar chaves novas podem quebrar ao receber scheduleType. Atualize leitura ou validação da resposta para tratar scheduleType como parte de current, conforme o esquema publicado.

FAQ

Visão geral

O que é a Seller Public API do Zé Delivery?

A Seller Public API é a interface oficial que permite que parceiros integrem seus sistemas ao Zé Delivery, possibilitando operações como:

Recebimento e gestão de pedidos
Atualização de catálogo (produtos, preços, disponibilidade)
Integração logística
Consulta de eventos e status
Gestão de lojas

Ela foi projetada para suportar múltiplos modelos de negócio e integrações escaláveis.

Quem pode se integrar com o Zé Delivery?

Empresas que possuam, obrigatoriamente:

Sistema próprio (OMS, WMS, ERP, marketplace, etc.)
Capacidade técnica de integração via API, a ser validada pelo time técnico do Zé Delivery
Acordo comercial com o Zé Delivery

Por onde começar

Como iniciar uma integração com o Zé Delivery?

O processo segue estas etapas:

Aprovação da integração pelo time comercial do Zé
Pré-onboarding — validação técnica pelo time técnico do Zé
Kickoff técnico — liberação de credenciais em ambiente de testes
Desenvolvimento e teste da integração — pelo integrador, conforme a documentação, em ambiente de testes
Homologação e aprovação dos testes — pelo time técnico do Zé
Liberação de credenciais em produção
Go-live controlado — alinhado com o time comercial do Zé
Rollout — alinhado com o time comercial do Zé

Existe ambiente de testes?

Sim. URLs base:

Development: https://seller-public-api.release.ze.delivery
Production: https://seller-public-api.ze.delivery

Preciso falar com o time do Zé para integrar?

Sim. É necessário alinhamento com o time comercial para aprovação da integração. Se aprovado, o time comercial direciona o contato do time técnico para o início das atividades.

Sobre a API

Como obtenho minhas credenciais?

As credenciais em ambiente de teste e de produção são fornecidas pelo time técnico do Zé durante o onboarding.

Como funciona a autenticação?

A Seller Public API utiliza OAuth2 no fluxo client_credentials.

Para se autenticar:

Envie client_id e client_secret para o endpoint /auth
A API retornará um access_token
Utilize esse token nas próximas requisições

👉 O token precisa ser gerado apenas uma vez e possui validade de 24 horas. Nesse período, não é necessário autenticar novamente a cada requisição.

Quando o token expirar:

Chame novamente o endpoint /auth
Gere um novo access_token
Continue utilizando a API normalmente

Boas práticas:

Armazene (cache) o token no seu sistema
Evite gerar token a cada requisição
Monitore o tempo de expiração (expire_in)

Erros comuns:

401 Unauthorized — token inválido ou expirado

Como funciona o processo de homologação da integração?

O parceiro recebe credenciais de ambiente de desenvolvimento (dev)
Realiza a integração com os endpoints liberados para o seu escopo
Executa os testes de integração de forma independente
Quando estiver pronto, agenda uma validação com o time do Zé
Durante a validação, são realizados testes em conjunto (em tempo real)

Se aprovado:

O time técnico do Zé comunica o time comercial sobre a homologação
Após aprovação do comercial, são liberadas as credenciais de produção

👉 Esse processo reforça qualidade, segurança e estabilidade antes do go-live.

Quais são os tipos de resposta da API (sync vs async)?

A API trabalha com dois tipos de resposta:

Síncrona (sync)

Retorno imediato da operação
Status HTTP típico: 200 OK

Assíncrona (async)

A requisição é aceita para processamento e finalizada posteriormente
Status HTTP típico: 202 Accepted

👉 Em fluxos assíncronos, acompanhe o processamento via eventos (polling).

Como funciona o catálogo no Zé Delivery?

Existem dois modelos:

Catálogo padrão do Zé (fluxo padrão)

Catálogo interno, gerenciado pelo Zé Delivery
Utilizado na maioria das integrações

Catálogo externo do parceiro (em validação)

O parceiro pode criar e gerenciar o próprio catálogo via API
Usado em integrações específicas (ex.: novas verticais ou modelos de negócio)

👉 O uso de catálogo externo depende de validação e alinhamento com o time do Zé.

Por que não tenho acesso a todos os endpoints?

A API segue o princípio de least privilege: você só acessa os endpoints necessários, conforme o escopo de integração alinhado com o time do Zé Delivery.

Posso solicitar novos acessos?

Sim, mediante alinhamento com os times comercial e técnico do Zé.

Monitoramento

Como monitorar minha integração?

Recomenda-se acompanhamento diário, com alertas para instabilidade ou erros, observando:

Taxa de erro
Latência
Volume de requisições
Status de pedidos

Existe uma status page da API do Zé Delivery?

Atualmente não disponibilizamos uma status page pública para acompanhamento da disponibilidade da API.

👉 Estamos evoluindo essa frente; futuramente será disponibilizada uma status page para parceiros, com visibilidade sobre:

Disponibilidade dos serviços
Incidentes em andamento
Histórico de indisponibilidades

Essa evolução faz parte da melhoria de observabilidade e transparência da API para o ecossistema de parceiros.

Como fico sabendo de mudanças na API?

Hoje: via Changelog nesta documentação.
Futuro: versionamento e alertas automáticos.