Pedidos

Endpoints de /api2/order para listagem com paginação determinística, consulta detalhada por ID ou increment_id e operações administrativas: cancel, hold e unhold. Esta página é a porta de entrada da família de pedidos — a partir daqui, navegue para Faturas, Expedições, Estornos e Histórico.

REST JSON Bearer Token Novo em 2026

Visão geral

A família /api2/order consolida o ciclo de vida do pedido na Plataforma Yep — da consulta inicial ao estorno final. Esta página cobre o recurso raiz Orders; os demais recursos têm página própria.

200

Limit máximoPor página em qualquer listagem.

Limit padrãoQuando limit é omitido ou inválido.

Operações admin.list, get, cancel, hold, unhold.

opt

Metadadostotal, last_page, has_next sob include_pagination=1.

FaturasListar, consultar, faturar (total/parcial) e reenviar e-mail. ExpediçõesCriar shipment com rastreio, adicionar tracks e reenviar e-mail. EstornosCredit memo a partir de invoice ou pedido, online ou offline. HistóricoListar histórico, criar comentário e mudar status do pedido.

Regras gerais da família

Convenções comuns a todos os endpoints de pedidos. Base URL nos exemplos: /api2. Endpoints protegidos exigem Authorization: Bearer {{token}} e Content-Type: application/json nos verbos POST.

Listagens aceitam filtros por query string ou por JSON body. Quando o mesmo campo existir nos dois lugares, o valor da query string prevalece.
Paginação padrão: page=1, limit=20. Limite máximo: 200. Também são aceitos page_size, per_page e pageSize.
Datas devem usar YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS. Datas inválidas retornam 400.
Ordenação: use sort e direction (asc ou desc). Campos aceitos variam por recurso.
Em endpoints operacionais que aceitam items, cada item deve usar order_item_id ou sku e uma quantidade positiva em qty.
Erros seguem o padrão {"error": "mensagem"}.

Status HTTP

Status	Uso
`200`	Consulta ou atualização concluída.
`201`	Criação de invoice, shipment, rastreio, histórico ou credit memo concluída.
`400`	Parâmetro inválido, JSON inválido ou ambiguidade na operação.
`401`	Token ausente ou inválido.
`404`	Pedido, invoice, shipment ou credit memo não encontrado.
`409`	Conflito de gravação, duplicidade ou deadlock tratado pelo helper do módulo.
`503`	Recurso temporariamente indisponível por lock wait ou contenção no banco.
`500`	Erro inesperado tratado pelo helper do módulo.

GET/api2/order

Listar pedidos com filtros e paginação determinística.

ListagemFiltros

page Opcional

Página atual. Padrão 1.

limit Opcional

Quantidade de registros por página. Padrão 20, máximo 200.

include_pagination Opcional

Quando 1, retorna total, last_page e has_next.

status Opcional

Status único, lista separada por vírgula ou array no body. Ex.: pending,processing.

state Opcional

State único, lista separada por vírgula ou array no body.

increment_id Opcional

Número incremental. Valor único retorna o pedido detalhado; lista por vírgula ou array funciona como filtro de listagem.

customer_id Opcional

ID do cliente.

customer_email / email Opcional

E-mail do cliente. A comparação ignora maiúsculas/minúsculas.

store_id Opcional

ID da loja, para resultado determinístico em ambientes multi-store.

created_from / created_to Opcional

Intervalo de criação. Aliases aceitos: created_at_from, created_at_to, from, to.

updated_from / updated_to Opcional

Intervalo de atualização. Aliases aceitos: updated_at_from, updated_at_to.

sort, direction Opcional

Campos aceitos: entity_id, created_at, updated_at, increment_id, grand_total.

Exemplo — query string

GET /api2/order?page=1&limit=50&status=pending,processing&include_pagination=1&sort=created_at&direction=desc
Authorization: Bearer {{token}}

Exemplo — JSON body

{
  "page": 1,
  "limit": 50,
  "include_pagination": 1,
  "status": ["pending", "processing"],
  "customer_email": "cliente@example.com",
  "created_from": "2026-01-01",
  "created_to": "2026-12-31",
  "sort": "created_at",
  "direction": "desc"
}

Resposta — exemplo

{
  "success": true,
  "page": 1,
  "limit": 50,
  "total": 137,
  "last_page": 3,
  "has_next": true,
  "orders": [
    {
      "order_id": 123,
      "increment_id": "100000123",
      "status": "processing",
      "state": "processing",
      "grand_total": 459.90,
      "customer_id": 34,
      "customer_email": "cliente@example.com",
      "omnichat_sales_person_id": "seller-123",
      "omnichat_sales_person_name": "Nome do vendedor",
      "created_at": "2026-04-22 14:33:10",
      "updated_at": "2026-04-23 09:11:02"
    }
  ]
}

Quando a integração Omnichat estiver ativa na loja, pedidos com origem Omnichat incluem omnichat_sales_person_id e omnichat_sales_person_name. Para pedidos sem vínculo Omnichat, os campos retornam null.

GET/api2/order

Obter pedido individual por id ou increment_id. A resposta usa a chave order (singular).

GET /api2/order?id=123
Authorization: Bearer {{token}}

GET /api2/order?increment_id=100000123
Authorization: Bearer {{token}}

Existe alias plural /api2/orders que aceita os mesmos parâmetros.

POST/api2/order/cancel

Cancela o pedido seguindo as regras nativas da Yep. Quando canCancel() retornar falso, a API devolve 400.

POST /api2/order/cancel
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_increment_id": "100000123",
  "comment": "Cancelado pela integração."
}

Também aceita order_id em vez de order_increment_id.

POST/api2/order/hold

Coloca o pedido em hold quando canHold() permitir.

POST /api2/order/hold
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_id": 123,
  "comment": "Pedido em análise."
}

POST/api2/order/unhold

Remove o hold quando canUnhold() permitir.

POST /api2/order/unhold
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_id": 123,
  "comment": "Análise concluída."
}

Formas de uso suportadas

Combinações testadas e homologadas para o recurso Orders.

Listar pedidos abertosGET /api2/order?status=pending,processing&include_pagination=1

Pedido por númeroGET /api2/order?increment_id=100000123

Pedido por IDGET /api2/order?id=123

Listar com sincronização incrementalGET /api2/order?updated_from=2026-04-01&sort=updated_at&direction=asc

Cancelar pedidoPOST /api2/order/cancel

Colocar em holdPOST /api2/order/hold

Remover holdPOST /api2/order/unhold

Recomendações para integração

Boas práticas consolidadas para integrações com ERP, OMS, CRM e marketplaces que sincronizam pedidos com a Plataforma Yep.

Evitar

Misturar order_id e order_increment_id no mesmo payload — escolha um identificador por requisição.
Forçar cancel/hold/unhold sem checar o estado atual — a Yep retorna 400 quando a transição não é permitida.
Depender de ordenação implícita entre páginas — sempre informe sort e direction.

Dica de sincronização incremental

Para integrações OMS/ERP, combine updated_from + limit=100 + include_pagination=1 + sort=updated_at&direction=asc. Você obtém um delta determinístico, com critério de parada confiável e ordenação previsível para retomar a partir de um checkpoint.

Erros comuns

Status	Exemplo de body	Quando ocorre
`400`	`{"error": "Invalid date format"}`	Datas fora do formato `YYYY-MM-DD` ou `YYYY-MM-DD HH:MM:SS`.
`400`	`{"error": "Order cannot be canceled"}`	`canCancel()`, `canHold()` ou `canUnhold()` retornaram falso para o estado atual do pedido.
`401`	`{"error": "Unauthorized"}`	`Authorization` ausente ou token expirado.
`404`	`{"error": "Order not found"}`	`order_id` ou `increment_id` inexistente.
`503`	`{"error": "Resource temporarily unavailable"}`	Lock wait ou contenção transitória — repetir após backoff.