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

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

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), 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 (ou 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

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:

GET/api/v1/sellers/orders/{id}/possible-statuses

POST/api/v1/sellers/orders/{id}/status

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

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.

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

{
  "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. A partir daí: emitir documento (fiscal), gerar etiqueta (logística), despachar.

Para onde ir agora