Industrialização

Workflow production. Para produtos que passam pela fábrica antes de embalar: sob encomenda, personalização, móveis sob medida, brindes corporativos, tecido.

Pré-requisitos: leia primeiro Pedidos: visão geral. Os conceitos de possible-statuses, rota única /status e workflow_type valem aqui também.

Para que serve

No workflow padrão, o pedido vai de paid direto para preparing (embalar) e depois ready_to_ship (despachar). Não dá conta de produto que precisa ser feito.

Industrialização insere quatro estados antes do trilho de envio:

Quando a produção termina, o resto do ciclo é igual ao standard: emite documento fiscal, gera etiqueta, marca enviado, entregue.

Mesmo com os estados novos de produção, você não vai encontrar um endpoint para cada etapa — nada de /start-production, /finish-production e afins. É de propósito: assim como no fluxo padrão, tudo passa pela rota única de status. Você consulta os estados válidos em possible-statuses e envia a mudança em /status; o que muda de uma etapa para outra é só o status que você manda. Uma rota só, do começo ao fim da produção.

Fluxo passo a passo

1. Pedido entra como paid, workflow production

Você reconhece um pedido de industrialização lendo workflow_type no detalhe (ou filtrando a listagem por ?workflow=production):

GET /api/v1/sellers/orders?workflow=production&status=paid

A fábrica precisa saber que tem trabalho novo; esta é a fila de entrada.

2. Iniciar produção

Quando a equipe da fábrica vai pegar o pedido, marque início. Use production_started no lugar de preparing, pois preparing é para embalar produto pronto, não fabricar.

POST /api/v1/sellers/orders/ORD-000123/status
Content-Type: application/json

{
  "status": "production_started",
  "data": { "estimated_days": 7 }
}

estimated_days é opcional, mas fortemente recomendado: a plataforma usa esse número para calcular uma estimativa de entrega que o cliente vê na tela de acompanhamento. Sem ele, o cliente fica sem previsão para algo que demora.

3. (Opcional) Pausar por falta de materiais

Se a produção precisar parar porque faltou insumo, registre. Isso fica no histórico do pedido e ajuda no SAC quando o cliente pergunta "por que está demorando?".

{
  "status": "awaiting_materials",
  "data": { "materials": ["Tecido azul indigo 1.6m", "Zíper 20cm cor 4"] }
}

materials[] é opcional; você pode mandar apenas { "status": "awaiting_materials" } para registrar a pausa sem detalhar a lista.

Quando o insumo chegar, volte para production_in_progress:

{
  "status": "production_in_progress"
}

Pode ir direto de production_started para production_in_progress se não houver pausa por insumos.

4. Concluir produção

Quando o produto sai da fábrica e está pronto para embalar:

{
  "status": "production_finished"
}

A partir daqui, o pedido deixa o trilho de produção e entra no fluxo padrão. As próximas transições válidas (GET /possible-statuses) vão ser preparing (embalar) ou ready_to_ship (pular embalagem se já saiu pronto da fábrica).

5. Encaixar com o resto do ciclo

Depois de production_finished, o pedido se comporta exatamente como um standard em paid:

• Emite documento fiscal: ver Pedidos: fiscal.
• Gera e baixa etiquetas: ver Pedidos: logística.
• Marca shipped com tracking_code, depois delivered.

Cenários comuns

"Recebi 3 pedidos sob encomenda hoje"

GET /api/v1/sellers/orders?workflow=production&status=paid&sort=-created_at

Para cada pedido, dispare production_started com a estimativa real (não use um valor genérico, pois o cliente vê):

{
  "status": "production_started",
  "data": {
    "estimated_days": 5
  }
}

"A fábrica avisou que ficou sem o tecido X"

Pausa o pedido afetado registrando o que falta:

{
  "status": "awaiting_materials",
  "data": { "materials": ["Tecido X cor 7"] }
}

Quando o insumo chegar, retoma:

{
  "status": "production_in_progress"
}

"Terminei de produzir, vou embalar"

{
  "status": "production_finished"
}

E em seguida o trilho normal:

{
  "status": "preparing"
}

"Terminei de produzir e já vai direto pra transportadora (sem caixa interna)"

production_finished aceita pular preparing e ir direto para ready_to_ship. O possible-statuses mostra ambas as opções:

{
  "status": "ready_to_ship"
}

"Esse pedido vai dar muito trabalho, preciso cancelar"

Pela API, o cancelamento só está disponível antes de a produção começar (pedido ainda em paid). A partir de production_started, cancelar passa a ser com a operação da plataforma — acione o suporte. Se ainda está em paid:

{
  "status": "cancelled",
  "data": {
    "reason": "Insumo descontinuado pelo fornecedor."
  }
}

O reason vai para o histórico e pode aparecer no SAC do cliente.

Cuidados

Não use preparing no início. É comum a equipe estar acostumada com o fluxo padrão e marcar preparing quando o pedido chega — e um POST direto até passa, mas fura o fluxo de produção: o pedido pula os estados da fábrica e o cliente perde o acompanhamento. Tanto é desvio que preparing nem aparece em possible-statuses para pedidos de produção. A partir de paid, use production_started.

estimated_days muda a UX do cliente. Esse número alimenta a estimativa de prazo na tela do cliente. Ser otimista demais gera reclamação; prefira margem de segurança.

Dá para emitir documento fiscal já em production_finished? Sim — a elegibilidade fiscal abre em qualquer estado de produção (production_started, awaiting_materials, production_in_progress, production_finished), sem precisar avançar pra preparing (ver Pedidos: fiscal). Útil quando a nota precisa sair antes de o produto ficar pronto.

O cliente acompanha a produção? Sim. As mudanças de status de produção ficam visíveis para o cliente como linha do tempo do pedido, incluindo o awaiting_materials (sem revelar o materials[], que é interno). Por isso estimated_days e a passagem para production_in_progress são importantes: dão sinal de vida.