# 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](/guia/pedidos). 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:

```mermaid
stateDiagram-v2
    direction LR
    [*] --> paid
    paid --> production_started
    production_started --> awaiting_materials: faltam<br/>insumos
    production_started --> production_in_progress
    awaiting_materials --> production_in_progress: insumos<br/>chegaram
    production_in_progress --> production_finished
    production_finished --> preparing
    production_finished --> ready_to_ship: pular<br/>preparing
```

| Estado | Significa |
|---|---|
| `production_started` | A fábrica recebeu o pedido. Equipe foi avisada, ordem de produção foi criada. |
| `awaiting_materials` | A produção pausou porque falta insumo. Comum quando o seller compra material sob demanda. |
| `production_in_progress` | Está sendo fabricado agora. |
| `production_finished` | Saiu da fábrica. A partir daqui o pedido entra no trilho padrão de envio (`preparing` ou direto `ready_to_ship`). |

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`):

```http
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.

```http
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?".

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

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

```json
{
  "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](/guia/pedidos-fiscal).
- Gera e baixa etiquetas: ver [Pedidos: logística](/guia/pedidos-logistica).
- Marca `shipped` com `tracking_code`, depois `delivered`.

---

## Cenários comuns

### "Recebi 3 pedidos sob encomenda hoje"

```http
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ê):

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

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

Quando o insumo chegar, retoma:

```json
{
  "status": "production_in_progress"
}
```

### "Terminei de produzir, vou embalar"

```json
{
  "status": "production_finished"
}
```

E em seguida o trilho normal:

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

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

```json
{
  "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](/guia/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.