logo
Documentation Powered by ReDoc

Zé Seller Public API (1.0)

Download OpenAPI specification:Download

URL: https://seller-public-api.ze.delivery 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.

Orders

Order details

Com este método é possível, recuperar os detalhes do pedido, dado o seu número na plataforma Zé Delivery. Atenção: as informações sensíveis do cliente não estarão disponíveis para todos os parceiros pois dependem de alinhamentos legais entre o Zé Delivery e o Parceiro.

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",
  • "createdAt": "2021-09-15T19:51:57.851343",
  • "merchant": {
    },
  • "items": [
    ],
  • "otherFees": [
    ],
  • "discounts": [
    ],
  • "total": {
    },
  • "payments": {
    },
  • "customer": {
    },
  • "delivery": {
    },
  • "takeout": {
    },
  • "serviceFee": {
    },
  • "extraInfo": "Trazer bem gelada",
  • "statusHistory": [
    ]
}

Order confirm

Com este método é possível aceitar um pedido, dado o número 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

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

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": [
    ]
}

Order cancellation

Com este método é possível solicitar, dado o número do pedido, que este seja cancelado ou rejeitado

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

Content type
application/json
{
  • "code": "UNAVAILABLE_ITEM"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "title": "string",
  • "type": "string",
  • "messages": [
    ]
}

Order cancel

Com este método é possível cancelar um pedido em qualquer status, dado o número do pedido na plataforma Zé Delivery

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
required
string
Enum: "POC_STOCKOUT" "OPER_ISSUES" "OTHERS" "DELIVERY_ISSUE" "WRONG_ADDRESS" "LATE_ORDER" "OTHER"

Código da razão de cancelamento. Os códigos aceitos são: POC_STOCKOUT para falta de estoque, OPER_ISSUES para problemas de operação, DELIVERY_ISSUE para problemas na entregga, WRONG_ADDRESS para endereço errado, LATE_ORDER para pedido atrasado, OTHER e OTHERS

Responses

Request samples

Content type
application/json
{
  • "code": "POC_STOCKOUT"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "title": "string",
  • "type": "string",
  • "messages": [
    ]
}

Restore an edited order

Com este método é possível restaurar um pedido editado para a versão original, dado o número do pedido. Apenas pedidos com status 'CONFIRMED' podem ser restaurados.

path Parameters
orderNumber
required
string
Example: 1234

O número do pedido

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": [
    ]
}

Update order items

Com este método é possível editar os itens de um pedido, removendo ou substituindo itens. Apenas pedidos com status 'CONFIRMED' podem ser editados. É necessário enviar pelo menos um dos campos: removedItems ou replacedItems.

path Parameters
orderNumber
required
string
Example: 1234

O número do pedido

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

Content type
application/json
{
  • "removedItems": [
    ],
  • "replacedItems": [
    ]
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "title": "string",
  • "type": "string",
  • "messages": [
    ]
}

Events

Events polling

Com este método é possível, recuperar os eventos dos pedidos, desde em andamento até concluído.

query Parameters
eventType
Array of strings (OrderStatusEnum)
Items Enum: "CREATED" "CONFIRMED" "DISPATCHED" "CANCELLED" "CONCLUDED" "EDITED"
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
[]

Events acknowledgment

Com este método é possível, remover os eventos que já foram consumidos, desta forma eles não retornarão mais na rota de 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" "DISPATCHED" "CANCELLED" "CONCLUDED" "EDITED"

Os status possíveis do pedido, CREATED para quando o pedido é realizado, CONFIRMED para quando um pedido foi aceito por um estabelecimento, DISPATCHED para quando um pedido é despachado para uma pessoa entregadora, CANCELLED para quando há algum tipo de cancelamento, CONCLUDED para quando um pedido é entregue e EDITED para quando um pedido é editado.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": "string",
  • "title": "string",
  • "type": "string",
  • "messages": [
    ]
}

Merchants

Make merchant availability

Com este método é possível abrir e fechar loja, dado o id do estabelecimento e razao.

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

Content type
application/json
{
  • "operation": "AVAILABLE",
  • "reasons": "INTERNET"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "title": "string",
  • "type": "string",
  • "messages": [
    ]
}

Get merchant information

Com este método é possível recuperar os detalhes 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": {
    }
}

Get Merchant KPIs

Esse metodo permite 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.

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": {
    }
}

Products

Create product item

Com este método é possível criar um item de produto de um estabelecimento, dado o id do estabelecimento e um identificador do produto.

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

Content type
application/json
{
  • "productId": "1234",
  • "externalProductId": "1234",
  • "name": "Nome do Produto",
  • "description": "Descrição do produto",
  • "category": "categoria",
  • "price": {
    },
  • "images": [],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{ }

Update product item

Com este método é possível é atualizar um item de produto de um estabelecimento dado o id do estabelecimento e um identificador do produto.

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

Content type
application/json
{
  • "productId": "1234",
  • "externalProductId": "1234",
  • "name": "Nome do Produto",
  • "description": "Descrição do produto",
  • "category": "categoria",
  • "price": {
    },
  • "images": [],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "title": "string",
  • "type": "string",
  • "messages": [
    ]
}

Upsert product items

Com este método é possível atualizar ou criar itens de produto, dado um array de itens.

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

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "title": "string",
  • "type": "string",
  • "messages": [
    ]
}

Update product promotions

Com este método é possível atualizar as promoções de produtos para diversos estabelecimentos.

header Parameters
Authorization
required
string

token de autenticação para acessar o recurso

Request Body schema: application/json
Array ()
One of
isEnabled
boolean
Value: true

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": "string",
  • "title": "string",
  • "type": "string",
  • "messages": [
    ]
}

Update product availability

Com este método é possível, atualizar a disponibilidade de um produto, dado o id do estabelecimento e um identificador do produto.

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

Content type
application/json
{
  • "productId": "1234",
  • "externalProductId": "1234",
  • "available": true
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "title": "string",
  • "type": "string",
  • "messages": [
    ]
}

Get merchant items

Com este método é possível recuperar os itens do menu do estabelecimento

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": [
    ]
}

Update item offer

Com este método é possível atualizar a oferta do item (preço, etc.) de um estabelecimento, dado o id do estabelecimento e um identificador do produto.

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

Content type
application/json
{
  • "productId": "1234",
  • "externalProductId": "1234",
  • "price": {
    }
}

Response samples

Content type
application/json
{ }

Logistics

Delivery details

Com este método é possível, recuperar os detalhes de entrega do pedido, dado o seu número na plataforma Zé Delivery.

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": {
    },
  • "merchant": {
    },
  • "deliveryPrice": {
    }
}

Order Picked

Com este método é possível informar que o entregador pegou o 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

Request Body schema: application/json
email
required
string

E-mail do entregador

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "title": "string",
  • "type": "string",
  • "messages": [
    ]
}

Start Route Order

Com este método é possível informar coleta de pedido pelo entregador e o início da entrega

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

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "title": "string",
  • "type": "string",
  • "messages": [
    ]
}

Arrived Order

Com este método é possível informar que o pedido chegou ao destino

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

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "title": "string",
  • "type": "string",
  • "messages": [
    ]
}

Validate Code

Com este método é possível validar o código de entrega 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

Request Body schema: application/json
deliveryCode
required
string

O código de entrega do pedido

Responses

Request samples

Content type
application/json
{
  • "deliveryCode": "0406"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "title": "string",
  • "type": "string",
  • "messages": [
    ]
}

Finish Route

Com este método o pedido informado será finalizado e dado 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

Content type
application/json
{
  • "email": "string",
  • "lat": 0,
  • "long": 0
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "title": "string",
  • "type": "string",
  • "messages": [
    ]
}

Delivery Order Cancel

Com este método é possível que o entregador cancele o 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

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

Content type
application/json
{
  • "email": "string",
  • "reason": "RISK_AREA"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "title": "string",
  • "type": "string",
  • "messages": [
    ]
}