# Sob encomenda

Workflow `backorder`: venda **sem estoque disponível**. O cliente paga, e o pedido fica estacionado aguardando a mercadoria chegar — quando você **abastece o estoque do SKU**, a plataforma detecta e retoma o pedido sozinha. Se a sua integração só conhece o fluxo padrão, esses pedidos parecem "travados depois do pago"; este guia explica essa espera e como ela se destrava.

> 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

Pedido sob encomenda nasce de venda B2B (pedido direto, proposta de representante) sobre produto que **permite venda sem estoque** — e só quando a plataforma tem o recurso habilitado. Você reconhece pelo `workflow_type`:

```jsonc
{
  "order_number": "ORD-000789",       // identificador público do pedido
  "workflow_type": "backorder",       // ← sob encomenda (label "Sob Encomenda")
  "status": "awaiting_restock",       // ← a espera: "Aguardando Reposição"
  "channel": "direct",                // canal de origem da venda
  "delivery_method": "shipping"       // a entrega segue o eixo normal depois
}
```

Existe um workflow espelho, `pre_order` (pré-venda): em vez de aguardar *reposição* (`awaiting_restock → restocked`), aguarda a *primeira disponibilidade* (`awaiting_availability → available`). A mecânica é idêntica; este guia usa o backorder como referência.

---

## O caminho

```mermaid
stateDiagram-v2
    direction LR
    [*] --> paid
    paid --> awaiting_restock: automático
    awaiting_restock --> restocked: estoque abastecido<br/>(automático)
    restocked --> paid: retomada<br/>(automático)
    state "preparing → … → delivered" as trilho
    paid --> trilho
```

Em palavras: o pagamento confirma (`paid`), o **sistema move sozinho** o pedido para `awaiting_restock`, e ali ele fica — fora das filas de preparação — até a mercadoria chegar. Quando você **abastece o estoque do SKU** (o mesmo `POST /api/products/{id}/stocks` de sempre — veja [Produtos · Estoque](/guia/produtos-estoque)), a plataforma detecta a reposição, marca o pedido como `restocked`, **debita a quantidade vendida do saldo** e o devolve ao trilho padrão a partir de `paid` — dali ele segue como qualquer [entrega](/guia/pedidos-entrega) (ou [retirada](/guia/pedidos-retirada), se for o caso).

> Pedidos esperando o mesmo SKU retomam **do mais antigo para o mais novo**, e cada um só sai da espera quando **todos** os seus itens têm saldo disponível.

## Etapa a etapa

| Status | O que significa | Sua ação | Próximo |
|---|---|---|---|
| `paid` (relance) | Pagamento confirmou. Estado de passagem: um job em background move o pedido em seguida. | Nada — não tente `preparing` aqui. | `awaiting_restock` (automático) |
| `awaiting_restock` | **A espera.** Pedido aguardando a mercadoria chegar ao seu estoque. | Provisione a mercadoria e, quando ela chegar, **dê entrada no estoque** (`POST /api/products/{id}/stocks` com `increment`). | `restocked` (automático) |
| `restocked` | Estoque reposto; marco registrado na timeline. | Nada — a quantidade vendida é debitada e o pedido retoma sozinho. | `paid`, e daí `preparing → …` |
| `preparing` em diante | Pedido voltou ao fluxo comum. | Igual ao guia de [entrega](/guia/pedidos-entrega): fiscal, etiqueta, envio. | — |

Existe também o destravamento **manual**, para quando você quer forçar a retomada sem dar entrada no estoque (ex.: a mercadoria chegou mas o ajuste de saldo vem depois). É a dupla de sempre:

<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>

```http
POST /api/v1/sellers/orders/ORD-000789/status
Content-Type: application/json

{ "status": "restocked" }
```

Mesmo no manual, a retomada completa acontece: o pedido passa por `restocked`, o saldo disponível é debitado (sem nunca ficar negativo) e ele volta pra `paid`.

---

## Como a integração percebe a espera

Quatro sinais, do mais direto ao mais sutil:

**1. O campo `status` é `awaiting_restock`.** Com `status_label` "Aguardando Reposição". O pedido não vai aparecer nos seus filtros de fila de preparação (`?status=paid,preparing`) — e isso é correto, não é um pedido perdido.

**2. A listagem filtra por workflow.** Sua fila de provisionamento é:

```http
GET /api/v1/sellers/orders?workflow=backorder&status=awaiting_restock&sort=created_at
```

(Ordenado do mais antigo para o mais novo: quem espera há mais tempo provisiona primeiro.)

**3. O `possible-statuses` só oferece duas saídas.** Em `awaiting_restock`, as `next_actions` são `mark-restocked` (→ `restocked`) e `cancel` (→ `cancelled`). Nada de `preparing`: se sua integração renderiza um botão por ação, ela já mostra o fluxo certo sem código especial.

```json
{
  "data": {
    "current_status": "awaiting_restock",
    "workflow_type": "backorder",
    "next_actions": [
      { "action": "mark-restocked", "target_status": "restocked", "label": "Reposto", "payload_schema": null },
      { "action": "cancel", "target_status": "cancelled", "label": "Cancelado", "payload_schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 } } } }
    ]
  }
}
```

**4. A timeline conta a história.** `GET /orders/{id}/events` registra o `paid → awaiting_restock` com autoria do sistema e, na retomada, o `awaiting_restock → restocked → paid` — com autoria "Sistema (reposição de estoque)" quando veio do abastecimento, ou a sua quando foi forçada manualmente.

---

## Pontos de atenção

**O pulo para `awaiting_restock` é assíncrono.** Logo após o webhook de pagamento, o pedido pode aparecer por alguns instantes como `paid` — e nessa janela curta o `possible-statuses` ainda oferece `preparing`, porque o sistema não estacionou o pedido. Não morda a isca: num pedido `workflow_type=backorder`, não dispare a esteira de preparação no primeiro `paid`. Espere o estado assentar em `awaiting_restock`; o produto, por definição, ainda não está no estoque.

**Os dados do comprador ficam visíveis durante a espera.** O pedido sob encomenda só estaciona **depois** do pagamento confirmado, então `customer_data_released` vem `true` e o PII do comprador (nome, endereço, documento) aparece normalmente em `awaiting_restock` e `restocked` — você pode planejar a entrega enquanto provisiona. O que continua bloqueado nesse período é a emissão fiscal (abaixo).

**O débito de estoque acontece na retomada.** A venda sob encomenda não reserva saldo (não havia saldo). Quando o pedido retoma (`restocked → paid`), a quantidade vendida é debitada dos seus locais — por isso a entrada de estoque vem primeiro. Na retomada manual sem saldo suficiente, o sistema debita o que houver (sem negativar) e registra a diferença em log.

**A reposição deve ser verdade.** O cliente já pagou e vê a linha do tempo do pedido ("Reposto" é um marco visível). Forçar a retomada sem ter a mercadoria só transfere o atraso para a etapa de preparação — onde os prazos de SLA da plataforma passam a contar.

---

## Cancelamento

Aqui o seller tem **mais** janela que nos outros fluxos: a espera inteira é pré-operacional, então `cancelled` está disponível tanto em `awaiting_restock` quanto em `restocked` — útil quando o fornecedor falha de vez:

```json
{
  "status": "cancelled",
  "data": { "reason": "Produto descontinuado pelo fornecedor, sem previsão de reposição." }
}
```

O estorno ao cliente segue o pipeline normal de cancelamento. A janela fecha no lugar de sempre: quando o pedido retoma o trilho e entra em `preparing`, cancelar vira assunto da operação da plataforma.

---

## Emissão fiscal

**Nada durante a espera.** `awaiting_restock` e `restocked` (e o `paid` de passagem) estão fora da janela fiscal — a API de emissão recusa com 422. A elegibilidade abre quando o pedido retoma o trilho e chega em `preparing`, exatamente como no fluxo de [entrega](/guia/pedidos-entrega). A partir daí: emitir documento ([fiscal](/guia/pedidos-fiscal)), gerar etiqueta ([logística](/guia/pedidos-logistica)), despachar.

---

## Para onde ir agora

| Você precisa… | Vá para |
|---|---|
| O trilho padrão pós-reposição | [Pedidos: entrega](/guia/pedidos-entrega) |
| Pedido que será retirado na loja | [Pedidos: retirada](/guia/pedidos-retirada) |
| Produto fabricado sob demanda (outro tipo de espera) | [Pedidos: industrialização](/guia/pedidos-industrializacao) |
| Emitir NF-e ou Declaração | [Pedidos: fiscal](/guia/pedidos-fiscal) |