# Visão geral
Como sua loja recebe pedidos, avança pelos estados do ciclo de vida, e onde estão as outras peças do quebra-cabeça (fiscal, etiquetas, devoluções, industrialização).
> Este guia é o **mapa**. Cada tema tem um guide próprio com o passo a passo aprofundado:
>
> - [Industrialização](/guia/pedidos-industrializacao), para o workflow `production`.
> - [Fiscal](/guia/pedidos-fiscal): NF-e, Declaração de Conteúdo, XML.
> - [Logística](/guia/pedidos-logistica): shipments e etiquetas.
> - [Devoluções](/guia/devolucoes): RMA encaminhada ao seller.
---
## Conceitos
O objeto que `GET /orders/{id}` devolve, de relance — campos principais (vários trazem um par `*_label` em pt-BR para exibir):
```jsonc
{
"order_number": "ORD-000123", // ← identificador público do pedido
"checkout_group_id": "01K8PB1QA…", // agrupa pedidos do mesmo checkout
"store": {…}, // loja responsável
"customer": {…}, // comprador
"type": "standard", // tipo do pedido (+ type_label)
"channel": "marketplace", // canal de venda (+ channel_label)
"workflow_type": "standard", // ← workflow: standard | production (industrialização)
"status": "paid", // ← estado atual (+ status_label, status_color)
"totals": {…}, // produtos, frete, descontos, total
"items": [{…}], // linhas do pedido
"applied_benefits": [{…}], // cupons/descontos aplicados
"invoices": [{…}], // documentos fiscais (ver Fiscal)
"shipping": {…}, // transportadora e frete (ver Logística)
"delivery_method": "shipping", // shipping | pickup (+ delivery_method_label)
"is_production_order": false, // true quando workflow_type=production
"payment_method": "pix", // forma de pagamento (+ payment_method_label)
"payment_url": "https://…", // link de pagamento (canais direct/store_seller; null fora de waiting_payment)
"payment_link_target": "store", // onde o link abre: platform | store
"created_at": "2026-04-26T14:32:11Z",
"updated_at": "2026-04-26T14:35:42Z"
}
```
> Campos que não se aplicam ao pedido vêm `null` (ex.: `picked_up_at` sem retirada, `payment_expires_at` após o pagamento). Trate a ausência como "não se aplica", não como erro.
---
## Fluxos de pedido
Cada pedido segue um **workflow** — o trilho de estados entre o pagamento e a conclusão, definido pelo `workflow_type`. O dia a dia da loja muda conforme o trilho, e cada um tem um guia próprio com o passo a passo:
- [Entrega](/guia/pedidos-entrega): o fluxo padrão, com envio por transportadora.
- [Retirada](/guia/pedidos-retirada): cliente paga online e busca no balcão.
- [Sob encomenda](/guia/pedidos-sob-encomenda): pré-venda e espera por reposição de estoque.
- [Industrialização](/guia/pedidos-industrializacao): produto que passa pela fábrica antes de embalar.
---
## Como pensar num pedido
Um pedido é o **estado** de uma compra, desde o pagamento confirmado até a entrega (ou cancelamento). Quem dirige o estado é o seller, chamando a API conforme o pedido caminha.
Três ideias fixam tudo:
**1. `order_number` é o identificador.** Em toda rota onde aparece `{id}`, é o `order_number` (ex.: `ORD-000123`). É público, estável e visível ao cliente.
**2. Toda transição passa por uma única rota.** `POST /orders/{id}/status` muda o estado, e o que muda de uma transição para outra é só o valor de `status` (mais um `data`, quando o estado pedir). Você não vai encontrar um endpoint para cada ação — nada de `/cancel`, `/ship` ou `/deliver` por conta própria. Isso é de propósito: em vez de te obrigar a conhecer dezenas de rotas, juntamos tudo numa só. Você aprende uma rota e conduz o pedido do início ao fim com ela.
**3. Você não precisa decorar o que pode chamar.** A rota `GET /orders/{id}/possible-statuses` já devolve, para o estado atual do pedido, **quais transições são válidas** e **qual o payload de cada uma** (`payload_schema`). Se você só lê essa rota e age sobre o que ela devolve, não tem como mandar um `status` inválido.
### O ciclo padrão (`workflow_type=standard`)
```mermaid
stateDiagram-v2
direction LR
[*] --> paid
paid --> preparing
paid --> ready_to_ship: pular
preparação
preparing --> ready_to_ship
preparing --> shipped: envio
direto
ready_to_ship --> shipped
shipped --> delivered
delivered --> [*]
```
Esse é o caminho da maioria dos pedidos. Outros `workflow_type` (production, in_store_pickup, pre_order, backorder, collective) **inserem etapas** antes ou dentro desse fluxo, mas no fim caem no mesmo `delivered`.
### Conceitos que aparecem em vários lugares
**`workflow_type`** define o "perfil" do pedido e o conjunto de transições aceitas. Os valores possíveis são `standard`, `production`, `in_store_pickup`, `pre_order`, `backorder` e `collective`. Você não escolhe o workflow: ele é definido no momento da criação do pedido, pela natureza do produto (sob encomenda, retirada na loja, pré-venda etc.).
**Operações assíncronas.** Algumas ações disparam jobs em background e retornam **202 Accepted** imediatamente. Isso acontece em três lugares: emissão de Declaração de Conteúdo, registro de NF-e com XML (gera DANFE em background) e geração de etiquetas. Em todos, o padrão é: dispara, faz polling, consome o resultado.
**Downloads via S3 assinado.** PDFs (DANFE, declaração, etiqueta) **não são servidos pela API**. Ela devolve uma URL S3 com assinatura, válida por **15 minutos**. Se expirar, você chama a rota de download de novo, que gera uma nova URL.
---
## Anatomia de um pedido
Quando você busca um pedido com `GET /orders/{id}`, recebe um objeto grande. Não precisa entender campo a campo de uma vez — agrupando por função, ele fica simples. A **listagem** (`GET /orders`) traz um subconjunto enxuto desses campos; o **detalhe** traz tudo.
| Bloco | Campos principais | Para que serve |
|---|---|---|
| **Identificação** | `order_number`, `checkout_group_id` | `order_number` é o ID público (o `{id}` das rotas). `checkout_group_id` agrupa pedidos nascidos do mesmo checkout — um carrinho com itens de várias lojas vira **um pedido por loja**, todos com o mesmo `checkout_group_id`. |
| **Quem** | `customer`, `store`, `sales_agent`, `physical_store` | Cliente, loja, e — quando a venda passou por um agente ou balcão — o agente de vendas e a loja física. Cada um vem como objeto (`{ id, name, ... }`) e também como `*_id`/`*_uid` solto. |
| **Classificação** | `type`, `channel`, `workflow_type`, `status` | O "perfil" do pedido: o tipo, o canal de origem, o [workflow](#conceitos-que-aparecem-em-varios-lugares) e o estado atual. Todos vêm com `_label` em pt-BR; `status` traz também `status_color`. |
| **Itens** | `items[]`, `items_count`, `lines_count`, `items_preview` | `items[]` é o detalhe linha a linha (produto, variação, `quantity`, `prices`, `net_value`). `items_count` soma as quantidades, `lines_count` conta as linhas, e `items_preview` traz os 3 primeiros com thumbnail — pronto para um card de listagem. |
| **Dinheiro** | `totals`, `payment_method`, `payment_status`, `payment_expires_at`, `applied_benefits` | `totals` resume `{ products, shipping, discounts, order }`. Forma e situação do pagamento vêm com `_label`. `applied_benefits` lista cupons/descontos. O extrato completo (splits, comissões) está na rota [`/financial`](#financeiro). |
| **Entrega** | `delivery_method`, `shipping`, `picked_up_at` | Método de entrega e a opção de frete escolhida (`carrier_name`, `display_name`, prazo). Rastreio consolidado fica em [`/tracking`](#tracking-de-entrega); etiquetas, no guia de [logística](/guia/pedidos-logistica). |
| **Fiscal** | `invoices[]` | Resumo dos documentos fiscais (`type`, `status`, `invoice_number`, `pdf_url`). O fluxo completo está no guia [fiscal](/guia/pedidos-fiscal). |
| **Operacional** | `notes`, `metadata`, `occurrences`, `created_at`, `updated_at` | Anotação interna da loja, metadados livres, ocorrências/SLA ligadas ao pedido, e os timestamps. |
Duas convenções valem para o objeto inteiro:
**Campos `*_label` e `*_color` já vêm prontos.** Todo enum do pedido (status, canal, tipo, workflow, pagamento) chega com o valor cru **e** o rótulo em pt-BR — e cor, onde faz sentido. Você nunca precisa traduzir esses valores no front: use o `_label` direto. Os valores possíveis (para popular filtros e badges) vêm da rota [`/enums`](/reference/pedidos#tag/enums-de-pedido/GET/api/v1/sellers/orders/enums).
**Campos são condicionais.** Vários campos só aparecem no contexto em que fazem sentido — `payment_expires_at` só quando o pedido aguarda pagamento, `pickup_address` só em retirada na loja, e assim por diante. Trate a **ausência** de um campo como "não se aplica a este pedido", não como erro.
---
## Encontrando pedidos
Tem duas formas: **listar com filtros** (visão operacional) ou **olhar números agregados** (visão gerencial).
### Listagem com filtros
GET/api/v1/sellers/orders
Esta é a rota que o painel do seller chama no dia a dia. Sem filtros, devolve todos os pedidos da loja (paginados, mais novo primeiro).
Quando você está montando uma fila de trabalho, normalmente combina um filtro de **status** (`paid`, `preparing`, `shipped`...) com um filtro de **data** (`date_from`, `date_to`). Os filtros mais usados:
| Para… | Use |
|---|---|
| Pedidos pendentes de preparação | `?status=paid,preparing` (CSV aceito) |
| Pedidos enviados aguardando entrega | `?status=shipped` |
| Busca por nº de pedido ou nome de cliente | `?search=ORD-0001` ou `?search=João` |
| Pedidos de um cliente específico | `?customer_id=01K8PB2RCUST00001A2B3C4D5E` |
| Pedidos de um canal | `?channel=marketplace` (CSV aceito) |
| Pedidos sob encomenda | `?workflow=production` |
| Pedidos com um item específico | `?item_id=ITM-0551` |
| Janela de datas | `?date_from=2026-04-01&date_to=2026-04-30` |
| Ordenação | `?sort=-created_at` (`-` = desc) |
`limit` controla a paginação (default 20). A resposta vem em `data[]` com `meta` para paginação. **Os campos completos do pedido na listagem são um subconjunto enxuto**; para o detalhe completo use a rota individual abaixo.
> **Valores aceitos nos filtros (`status`, `channel`, `type`, `workflow`, métodos de pagamento…)** não precisam ser hardcodados. A rota [`GET /api/v1/sellers/orders/enums`](/reference/pedidos#tag/enums-de-pedido/GET/api/v1/sellers/orders/enums) devolve **todos** os enums do pedido (`value` + `label` pt-BR, com `color` onde faz sentido) num só request — use para popular dropdowns e badges. Para os status **agrupados por workflow**, há também a rota pública [`GET /api/global/enums/order/status`](/reference/pedidos#tag/enums-de-pedido/GET/api/global/enums/order/status).
### Visão agregada
GET/api/v1/sellers/orders/summary
KPIs fixos **do dia atual**: quantos pedidos chegaram, receita, ticket médio, contadores por status (preparing, ready_to_ship, shipped, delivered_today) e por canal. Independe dos filtros da listagem: é sempre o panorama global da loja. Use para cabeçalho de dashboard.
GET/api/v1/sellers/orders/dashboard
Estatísticas consolidadas **num período configurável** (`days`, default 30): gráfico de evolução diária (vendidos, pendentes, cancelados), totais do período, comparativo com o período anterior de mesma duração, e lista dos pedidos mais recentes. Use para tela de "Visão geral" do seller.
### Pedido individual
GET/api/v1/sellers/orders/{id}
Payload completo: itens, cliente, snapshot de endereço, totais, splits financeiros (resumo), fiscais (`invoices[]`), anotações, metadata de envio (carrier, opção escolhida). É o que a tela de detalhe do pedido consome.
---
## Avançando o pedido
Esta é a parte central. O fluxo correto, **sempre**, é:
```mermaid
sequenceDiagram
autonumber
participant I as Integrador
participant A as API
I->>A: GET /orders/{id}/possible-statuses
A-->>I: { next_actions: [ { target_status, payload_schema }, ... ] }
Note over I: escolhe a próxima ação
I->>A: POST /orders/{id}/status
{ status, data? }
A-->>I: 200 + pedido atualizado
```
### Próximos passos válidos
GET/api/v1/sellers/orders/{id}/possible-statuses
Devolve, para o status atual do pedido, as transições válidas. Cada item de `next_actions` traz:
- `action`: slug semântico (ex.: `mark-preparing`, `cancel`, `start-production`).
- `target_status`: o valor a enviar em `status` na rota única.
- `label`: texto pronto para botão/UI.
- `payload_schema`: JSONSchema do `data` aceito. `null` quando a transição não exige payload.
Exemplo (pedido em `paid`, workflow `standard`):
```json
{
"data": {
"current_status": "paid",
"workflow_type": "standard",
"next_actions": [
{
"action": "mark-preparing",
"target_status": "preparing",
"label": "Iniciar preparação",
"payload_schema": null
},
{
"action": "cancel",
"target_status": "cancelled",
"label": "Cancelar pedido",
"payload_schema": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 500
}
}
}
}
]
}
}
```
> **Padrão de UI recomendado:** renderize um botão por `next_action`, com label = `next_action.label`. Quando clicado, monte `data` a partir do `payload_schema` (se houver) e chame a rota única.
### A rota única de status
POST/api/v1/sellers/orders/{id}/status
```http
POST /api/v1/sellers/orders/ORD-000123/status
Content-Type: application/json
{ "status": "preparing" }
```
Cenários comuns:
```jsonc
// iniciar preparação (workflow standard)
{
"status": "preparing"
}
// marcar enviado com rastreio
{
"status": "shipped",
"data": {
"tracking_code": "BR123456789BR"
}
}
// cancelar com motivo
{
"status": "cancelled",
"data": {
"reason": "Cliente solicitou cancelamento."
}
}
```
**O que pode dar errado:**
| Erro | Quando acontece | Como tratar |
|---|---|---|
| `422 VALIDATION_ERROR` (transição) | `status` enviado não está em `next_actions` do estado atual. `errors.status` vem com `"Transição inválida: não é possível ir de X para Y"`. | Refaça `GET /possible-statuses`. O pedido provavelmente já avançou (concorrência) ou seu cache está velho. |
| `422 VALIDATION_ERROR` (payload) | Payload em `data` não bate com `payload_schema` (campo faltando, tipo errado, max ultrapassado). | Olhe o `errors` da resposta, que vem por campo. |
| `404` | `order_number` não existe **ou** não pertence à sua loja. | Cheque o ID. Pedido de outra loja aparece como 404 (não 403) por motivos de privacidade. |
### Referência rápida: payloads por status
Você normalmente **não precisa** desta tabela, porque `possible-statuses` já entrega o `payload_schema` por transição. Está aqui só para debug rápido.
| `status` | `data` | obrigatório? |
|---|---|---|
| `preparing` | (nenhum) | não se aplica |
| `ready_to_ship` | (nenhum) | não se aplica |
| `shipped` | `{ tracking_code? }` (string, máx 100) | opcional |
| `delivered` | (nenhum) | não se aplica |
| `cancelled` | `{ reason? }` (string, máx 500) | opcional |
| `production_started` | `{ estimated_days? }` (integer) | opcional |
| `awaiting_materials` | `{ materials? }` (array de strings) | opcional |
| `production_in_progress` | (nenhum) | não se aplica |
| `production_finished` | (nenhum) | não se aplica |
| `ready_for_pickup` | (nenhum) | não se aplica |
| `picked_up` | `{ confirmation_code }` (string, máx 50) | **obrigatório** |
| `pickup_expired` | (nenhum) | não se aplica |
| `available` | (nenhum) | não se aplica |
| `restocked` | (nenhum) | não se aplica |
---
## Cancelamento
Cancelar costuma ser a primeira coisa que as pessoas procuram como rota própria — e ela não existe de propósito. Não há `DELETE /orders/{id}` nem `/cancel`: cancelar é uma transição de status como qualquer outra, igual a marcar enviado ou entregue. Você usa a mesma rota de sempre, mandando `status: cancelled` — mas só **enquanto o pedido não entrou em preparação/produção**. A partir daí, o cancelamento sai das suas mãos: é a operação da plataforma que cancela. E há estados sem saída nenhuma: `delivered`, `cancelled`, `completed` e `payment_expired` (já `pickup_expired` não é terminal — ele ainda transiciona para `cancelled`).
```json
{
"status": "cancelled",
"data": {
"reason": "Sem estoque para entregar no prazo."
}
}
```
`reason` é opcional, fica no histórico (`GET /orders/{id}/events`) e pode aparecer para o cliente. O `possible-statuses` indica quando essa ação está disponível para o estado atual.
---
## Acompanhando o pedido
Três rotas auxiliares que **não mudam estado**, só leem dados para telas/relatórios.
### Tracking de entrega
GET/api/v1/sellers/orders/{id}/tracking
Visão **consolidada** de rastreio: status atual, `tracking_code`, `tracking_url` pública (se disponível), `estimated_delivery_at`, `delivered_at`, `picked_up_at`. É o "onde está meu pedido", perfeito para uma tela simples de acompanhamento.
### Histórico granular (eventos)
GET/api/v1/sellers/orders/{id}/events
Linha do tempo completa do pedido: cada mudança de status, anotação ou ação fiscal vira um evento. Cada evento traz quem fez (`author_type`, `author_name`) e contexto (`metadata`). É o que você quer para uma timeline detalhada ou para auditoria.
### Financeiro
GET/api/v1/sellers/orders/{id}/financial
Splits de receita (quem recebe quanto: seller, marketplace, sales agent), audit de comissão por item, e benefícios aplicados (cupons, descontos, regras absorvidas pelo marketplace). Use para tela de "extrato do pedido" ou para conferir o repasse esperado.
### Anotações internas
PUT/api/v1/sellers/orders/{id}/notes
`notes` é texto livre da loja sobre o pedido, **não aparece para o cliente**. Útil para deixar lembretes ("ligar antes de despachar", "embalagem para presente", "cliente vai retirar quarta"). Envia o texto inteiro a cada chamada (não é append) ou `null` para limpar.
---
## Outros workflows resumidos
A maior parte dos pedidos é `standard`, mas a loja pode receber outros tipos. Aqui um resumo; cada um tem peculiaridades que merecem leitura aprofundada.
### `production`: sob encomenda
Pedido que **passa pela fábrica antes de embalar**: tecido, móveis sob medida, brindes personalizados. Em vez de pular para `preparing`, o seller informa início, eventual espera por insumos, fabricação e conclusão. Quando a produção termina, o pedido entra no trilho padrão (`preparing` → `ready_to_ship` → ...).
→ **Detalhe completo em [Pedidos: industrialização](/guia/pedidos-industrializacao).**
### `in_store_pickup`: retirada na loja
Cliente paga online e vai buscar no balcão. O pedido segue o trilho normal até `preparing` — é ali que o caminho bifurca, porque `delivery_method=pickup`: em vez de `ready_to_ship`, o próximo passo é `ready_for_pickup`. Quando o cliente aparece, o seller confirma com um código de retirada. Ao confirmar `picked_up`, o pedido vira `delivered` automaticamente; não chame `delivered` em seguida.
```mermaid
stateDiagram-v2
direction LR
[*] --> paid
paid --> preparing
preparing --> ready_for_pickup
ready_for_pickup --> picked_up: código
confirmado
ready_for_pickup --> pickup_expired
picked_up --> delivered: automático
```
| Ação | Body |
|---|---|
| Iniciar preparação | `{ "status": "preparing" }` |
| Pronto para retirada | `{ "status": "ready_for_pickup" }` |
| Confirmar retirada | `{ "status": "picked_up", "data": { "confirmation_code": "A1B2C3" } }` |
| Retirada expirada | `{ "status": "pickup_expired" }` |
### `pre_order` e `backorder`
Espelhados. Um aguarda o produto chegar ao estoque pela primeira vez (`pre_order` → `available`), o outro aguarda reposição (`backorder` → `restocked`). Quando o seller libera, o pedido entra no fluxo padrão a partir de `paid`.
```mermaid
flowchart LR
A(["pre_order
awaiting_availability"]) -- "status: available" --> P["paid"]
B(["backorder
awaiting_restock"]) -- "status: restocked" --> P
P --> S["Workflow standard"]
```
### `collective`: compra coletiva
Pedido vinculado a uma campanha de compra coletiva. Fica em `awaiting_campaign_conclusion` até a campanha encerrar; o sistema decide automaticamente se o pedido prossegue ou é cancelado. O seller só atua a partir de `preparing` em diante; não há transições manuais antes disso.
---
## Para onde ir agora
| Você precisa… | Vá para |
|---|---|
| Emitir NF-e, Declaração ou DANFE | [Pedidos: fiscal](/guia/pedidos-fiscal) |
| Gerar e baixar etiquetas | [Pedidos: logística](/guia/pedidos-logistica) |
| Tratar uma devolução | [Devoluções](/guia/devolucoes) |
| Pedidos sob encomenda | [Pedidos: industrialização](/guia/pedidos-industrializacao) |
| Schemas e códigos de erro | [Referência da API](/reference/pedidos) |