Sob encomenda

Sob encomenda é a 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. É o workflow backorder.

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}/stock 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). Use as duas rotas de status, como em qualquer outro fluxo:

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", "required": ["reason"], "properties": { "reason": { "type": "string", "minLength": 10, "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. 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. reason é obrigatório (mínimo 10 caracteres):

{
  "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, gerar etiqueta, despachar.