# Entrega

Workflow `standard` com `delivery_method=shipping`: a venda comum, que termina com um pacote saindo da loja e chegando na casa do cliente. É o caminho da grande maioria dos pedidos — e a base sobre a qual os outros workflows se encaixam.

> Pré-requisitos: leia primeiro [Pedidos: visão geral](/guia/pedidos). Os conceitos de `possible-statuses`, rota única `/status` e `workflow_type` valem aqui também.

---

## Quando um pedido cai aqui

Todo pedido nasce com dois eixos definidos na criação — você não escolhe nenhum deles depois:

- **`workflow_type`** é o perfil comercial. Sem natureza especial (fabricação, espera de estoque, campanha), o pedido é `standard`.
- **`delivery_method`** é o eixo de fulfillment: `shipping` (envio) ou `pickup` (retirada presencial).

Este guia cobre a combinação mais comum: `standard` + `shipping`. Se o cliente escolheu retirar na loja, o começo é igual, mas o caminho bifurca depois de `preparing` — veja [Pedidos: retirada](/guia/pedidos-retirada).

```jsonc
{
  "order_number": "ORD-000123",   // identificador público do pedido
  "workflow_type": "standard",    // ← perfil padrão
  "delivery_method": "shipping",  // ← termina com envio
  "status": "paid",               // pagamento confirmado, sua vez
  "shipping": {…}                 // frete escolhido no checkout
}
```

Os valores possíveis dos dois eixos (e de todos os outros enums do pedido) vêm de <a class="api-route" href="/reference/pedidos#tag/enums-de-pedido/GET/api/v1/sellers/orders/enums"><span class="api-method api-method-get">GET</span><span class="api-path">/api/v1/sellers/orders/enums</span></a>. Para os status já agrupados por workflow, use a rota pública <a class="api-route" href="/reference/pedidos#tag/enums-de-pedido/GET/api/global/enums/order/status"><span class="api-method api-method-get">GET</span><span class="api-path">/api/global/enums/order/status</span></a>.

---

## O caminho

```mermaid
stateDiagram-v2
    direction LR
    [*] --> paid
    paid --> preparing
    preparing --> ready_to_ship
    preparing --> shipped: envio<br/>direto
    ready_to_ship --> shipped
    shipped --> delivered
    delivered --> [*]
```

Sua fila de entrada é a listagem filtrada por pedidos pagos:

```http
GET /api/v1/sellers/orders?status=paid,preparing&sort=-created_at
```

E o avanço, como sempre, é o par `possible-statuses` + rota única:

<a class="api-route" href="/reference/pedidos#tag/pedidos/GET/api/v1/sellers/orders/{id}/possible-statuses"><span class="api-method api-method-get">GET</span><span class="api-path">/api/v1/sellers/orders/{id}/possible-statuses</span></a>

<a class="api-route" href="/reference/pedidos#tag/pedidos/POST/api/v1/sellers/orders/{id}/status"><span class="api-method api-method-post">POST</span><span class="api-path">/api/v1/sellers/orders/{id}/status</span></a>

## Etapa a etapa

| Status | O que significa | Sua ação | Próximo |
|---|---|---|---|
| `paid` | Pagamento confirmado. Dados do comprador liberados (`customer_data_released=true`). | `{ "status": "preparing" }` quando começar a separar/embalar. | `preparing` |
| `preparing` | Pedido sendo embalado. **Aqui abre a janela fiscal**: emita a NF-e ou Declaração ([fiscal](/guia/pedidos-fiscal)) e gere as etiquetas ([logística](/guia/pedidos-logistica)). | `{ "status": "ready_to_ship" }` com o pacote fechado e documento emitido. | `ready_to_ship` |
| `ready_to_ship` | Aguardando coleta ou postagem. | `{ "status": "shipped", "data": { "tracking_code": "BR…" } }` quando o pacote sair. | `shipped` |
| `shipped` | Em trânsito com a transportadora. | `{ "status": "delivered" }` quando o cliente receber — **se** a entrega for operada por você (ver abaixo). | `delivered` |
| `delivered` | Entregue. Estado terminal. | Nada. | — |

O `tracking_code` em `shipped` é opcional (string, máx 100), mas alimenta a tela de acompanhamento do cliente e a rota <a class="api-route" href="/reference/pedidos#tag/pedidos/GET/api/v1/sellers/orders/{id}/tracking"><span class="api-method api-method-get">GET</span><span class="api-path">/api/v1/sellers/orders/{id}/tracking</span></a> — informe sempre que tiver.

---

## Pontos de atenção

### O gate fiscal trava o despacho

Mercadoria não sai sem documento fiscal. As transições para `ready_to_ship` e `shipped` **recusam com 422** (campo `fiscal` no erro) se o pedido não tiver uma NF-e ou Declaração de Conteúdo emitida:

```json
{
  "errors": {
    "fiscal": ["É necessário emitir uma NF-e ou Declaração de Conteúdo antes de despachar o pedido."]
  }
}
```

Por isso a ordem prática dentro de `preparing` é: emitir documento → gerar etiqueta → marcar `ready_to_ship`. O passo a passo da emissão está em [Pedidos: fiscal](/guia/pedidos-fiscal).

> A máquina de estados aceita pular de `paid` direto para `ready_to_ship`, mas na prática o atalho raramente serve: a emissão fiscal só abre a partir de `preparing`, e sem documento o gate barra a transição. Passe por `preparing`.

### Partes do fluxo podem andar sozinhas

Não assuma que você é o único a mover o pedido — releia `possible-statuses` antes de cada ação em vez de confiar num estado em cache:

- **`paid` → `preparing` automático**: lojas com preparação automática habilitada pela plataforma têm esse passo dado pelo sistema assim que o pagamento confirma.
- **`ready_to_ship` → `shipped` automático**: quando o shipment é rastreado pela plataforma e entra em trânsito, o pedido é marcado como enviado sem você chamar nada.
- **`shipped` → `delivered` automático**: idem quando a transportadora confirma a entrega.

Cada mudança fica registrada em `GET /orders/{id}/events`, com `author_type` dizendo quem fez (você, o sistema, o admin).

### Quem pode confirmar `delivered`

Depende de quem opera a entrega:

| Situação | Confirmação |
|---|---|
| Frete com transportadora própria do seller, ou entrega manual sem transportadora | **Você**, via `{ "status": "delivered" }`. |
| Frete com transportadora da plataforma | **Automática/da operação.** Sua chamada manual recusa com 422. |
| Entrega com motorista da plataforma em andamento | Confirmação vem do app do motorista; manual só depois que ele concluir ou registrar falha. |

### Prazos viram ocorrências

Pedido pago tem SLA: documento fiscal e preparação têm prazos configurados pela plataforma, e estourar gera [ocorrência](/guia/ocorrencias) ligada ao pedido. Não deixe pedidos parados em `paid`.

---

## Cancelamento

A janela do seller é **curta**: só enquanto o pedido não entrou em preparação. Em `paid` você ainda pode:

```json
{
  "status": "cancelled",
  "data": { "reason": "Sem estoque para entregar no prazo." }
}
```

A partir de `preparing` (inclusive), o cancelamento é exclusivo da operação da plataforma — a API recusa com 422 e o `possible-statuses` **já nem lista** a opção `cancel` para você. Se precisar cancelar um pedido em preparação ou despachado, abra o caso com o suporte da plataforma.

`delivered` é terminal: depois dele, o caminho para desfazer a venda é a [devolução](/guia/devolucoes), não o cancelamento.

---

## Emissão fiscal

A elegibilidade abre em `preparing` e segue valendo em `ready_to_ship`, `shipped` e `delivered`. Em `paid` a API fiscal recusa com 422 ("o pedido precisa estar em preparação"). Ou seja:

```mermaid
flowchart LR
    A["paid<br/>(fiscal bloqueado)"] --> B["preparing<br/>(fiscal liberado ✓)"]
    B --> C["ready_to_ship → shipped → delivered<br/>(fiscal segue liberado)"]
```

Emitiu tarde demais? Sem problema — dá para registrar a NF-e mesmo com o pedido já `delivered` (caso clássico: corrigir documento depois da entrega). O fluxo completo de emissão, polling e download está em [Pedidos: fiscal](/guia/pedidos-fiscal).

---

## Para onde ir agora

| Você precisa… | Vá para |
|---|---|
| Emitir NF-e ou Declaração | [Pedidos: fiscal](/guia/pedidos-fiscal) |
| Gerar e baixar etiquetas | [Pedidos: logística](/guia/pedidos-logistica) |
| Pedido com retirada na loja | [Pedidos: retirada](/guia/pedidos-retirada) |
| Pedido aguardando reposição de estoque | [Pedidos: sob encomenda](/guia/pedidos-sob-encomenda) |
| Produto fabricado sob demanda | [Pedidos: industrialização](/guia/pedidos-industrializacao) |