Industrialização

A industrialização é para o produto que passa pela fábrica antes de ser embalado: sob encomenda, personalização, móveis sob medida, brindes corporativos, tecido. Como não existe nada pronto pra embalar logo após o pagamento, o pedido não pula direto para preparing: ganha os estados de produção que faltam entre o pagamento e o envio. É o workflow production.

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 ou similar. Como no fluxo padrão, toda mudança de status passa pela rota única: consulte possible-statuses e envie a mudança em /status. A única exceção é o fechamento da produção, que não é uma mudança de status e tem rotas próprias.

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 precisa ser um inteiro maior ou igual a 1. Valores 0, negativos, fracionados ou em texto devolvem 422 em errors.estimated_days e o pedido não transiciona. Para dizer "sem estimativa", omita o campo em vez de mandar 0.

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 a pausa. A mudança de status entra no histórico do pedido (GET /orders/{id}/events) e explica ao SAC por que o prazo esticou.

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

materials[] é opcional e a chamada funciona igual sem ele: { "status": "awaiting_materials" } registra a pausa do mesmo jeito.

Hoje a lista de materiais não é armazenada. A API aceita o campo (ele está no payload_schema da transição), mas o conteúdo não é persistido nem devolvido depois. Se a sua operação precisa dessa lista, guarde-a do seu lado, ou registre o texto nas anotações do pedido.

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.
• Gera e baixa etiquetas.
• Marca shipped com tracking_code, depois delivered.

Fechamento da produção

A fábrica nem sempre fecha na quantidade pedida: o tecido rende menos, uma peça sai fora do padrão, o cliente aceita 92 das 100 camisetas. Quando o pedido foi vendido em Condição Especial — entrada paga no checkout e saldo cobrado depois da produção — esse saldo tem que sair pelo que foi produzido de verdade, não pelo que foi pedido.

É o que essas duas rotas fazem. Não são mudança de status: elas acertam quantidade, desconto, comissão e totais do pedido, e é esse acerto que a cobrança do saldo usa.

Quando se aplica

As quatro condições valem juntas:

Não precisa testar as quatro por conta própria: chame a prévia e leia can_confirm. Quando vier false, o motivo está em blocking_reason, em português, pronto para exibir.

O pedido em Condição Especial traz os campos do saldo no detalhe:

{
  "payment_condition": "installment_plan",
  "down_payment_percentage": 30,       // % da entrada, já paga no checkout
  "down_payment_amount": 699.00,       // valor da entrada
  "remaining_production_amount": 1631.00 // saldo a cobrar, antes do acerto
}

1. Prévia

Mande o produzido por item e veja o pedido recalculado, sem gravar nada:

POST /api/v1/sellers/orders/ORD-000123/workflow/production-closing/preview

{
  "items": [
    { "order_item_id": "01KS3PRH2M…", "quantity_produced": 92 }
  ]
}

O order_item_id é o id do item no detalhe do pedido. Sem items no corpo, a prévia assume produção integral — o retrato de "nada mudou", bom para conferir os totais antes de mexer em quantidade.

{
  "data": {
    "can_confirm": true,
    "blocking_reason": null,
    "already_closed": false,
    "items": [
      {
        "order_item_id": "01KS3PRH2M…",
        "product_name": "Camiseta personalizada — algodão 30.1",
        "quantity_ordered": 100,
        "quantity_produced": 92,
        "quantity_final": 92,      // arredondado para inteiro, piso em zero
        "difference": -8,
        "total_before": 2500.00,
        "total_after": 2300.00
      }
    ],
    "totals": {
      "total_products_after": 2300.00,
      "total_discounts_after": 230.00,  // desconto acompanha a linha, na mesma proporção
      "total_shipping": 80.00,          // frete não é recalculado
      "total_order_after": 2150.00
    },
    "payment_condition": {
      "down_payment_amount": 699.00,    // a entrada não muda
      "remaining_before": 1631.00,
      "remaining_after": 1451.00        // é este valor que será cobrado
    }
  }
}

Estas duas rotas respondem fora do envelope padrão: o corpo é { "data": { … } }, sem success nem message_code.

2. Confirmar

POST /api/v1/sellers/orders/ORD-000123/workflow/production-closing/confirm

{
  "items": [
    { "order_item_id": "01KS3PRH2M…", "quantity_produced": 92 }
  ],
  "note": "Sobrou tecido para 92 peças; cliente aprovou o corte."
}

Aqui o items é obrigatório. Mande a lista completa: item omitido conta como produzido zero e sai do pedido. O note (até 2000 caracteres) fica no histórico.

A resposta é 201 com a mesma prévia, agora com already_closed: true e os totais finais.

Cuidados

O fechamento é único e não tem volta. Uma segunda confirmação devolve 422 com A produção deste pedido já foi fechada. Não existe rota para desfazer: se errou a quantidade, é caso de suporte.

can_confirm continua true depois de fechar. Ele só olha as condições do pedido, que continuam valendo. Quem responde "já fechou" é o already_closed — use esse campo como guarda antes de oferecer o botão de confirmar.

Produzir a mais também vale.quantity_produced maior que o pedido é aceito: a diferença fica positiva e o saldo sobe. A quantidade é arredondada para inteiro (92.5 vira 93) e valor negativo vira zero.

O frete não entra no acerto.total_shipping fica como estava; só produtos e descontos são recalculados.

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. Ú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. A lista de materiais não aparece para ele (nem é guardada pela API). Por isso estimated_days e a passagem para production_in_progress são importantes: mostram progresso ao cliente.