# Criar pedido de produção

> Escopo: pedidos:escrever (quem criou a chave precisa de producao.planejar). valor_centavos só é aceito se quem criou a chave tiver custos.ver ou…

URL: https://precificador3d.com.br/docs/api/referencia/criar-pedido-producao

`POST https://api.precificador3d.com.br/v1/pedidos-producao`

Escopo: `pedidos:escrever` (quem criou a chave precisa de `producao.planejar`). `valor_centavos` só é aceito se quem criou a chave tiver `custos.ver` ou `producao.receber` e a chave tiver `produtos:custos`. Item avulso só em pedido de cliente. Pedido ligado a cotação fica para a v2. Operação de escrita com custo 5.

Escopo: `pedidos:escrever`.

## Parâmetros

| Nome | Onde | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | sim | Chave única da operação, guardada por 24 h junto com o hash do corpo, o status e o id
criado (sem corpo nem resposta). Repetir com o mesmo corpo devolve o mesmo status e o
recurso relido pelo id. A mesma chave com outro corpo responde `422 idempotencia_conflito`.
 (até 64 caracteres) |

## Corpo (application/json)

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `tipo` | string | sim | Valores: `cliente`, `estoque`. |
| `cliente_nome` | string | não | Obrigatório em pedido de cliente. (até 120 caracteres) |
| `prazo` | string (date) | não | Obrigatório em pedido de cliente. |
| `valor_centavos` | integer | não | Só aceito com permissão de valor (ver a descrição da operação). (de 0 a 100000000000) |
| `prioridade` | string | não | (padrão "normal") Valores: `normal`, `urgente`. |
| `observacao` | string | não | (até 500 caracteres) |
| `itens` | array de object | sim | (1 a 100 itens) |

```json
{
  "tipo": "cliente",
  "cliente_nome": "Ana Lima",
  "prazo": "2026-10-20",
  "prioridade": "normal",
  "observacao": "Pedido ERP 5521",
  "itens": [
    {
      "produto_id": "5a6b7c8d-9e0f-4a1b-2c3d-4e5f6a7b8c9d",
      "variacao_id": "6b7c8d9e-0f1a-4b2c-3d4e-5f6a7b8c9d0e",
      "quantidade": 200
    },
    {
      "avulso": {
        "nome": "Suporte de celular personalizado"
      },
      "quantidade": 1
    }
  ]
}
```

## Resposta 201

Pedido criado.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | string (uuid) | sim |  |
| `codigo` | string | sim |  |
| `tipo` | string | sim | Valores: `cliente`, `estoque`. |
| `origem` | string | sim | Valores: `cotacao`, `manual`, `repor`, `api`. |
| `cotacao_id` | string (uuid) \| null | sim |  |
| `cliente_nome` | string \| null | sim | null em pedido para estoque e depois da anonimização (LGPD). |
| `prazo` | string (date) \| null | sim |  |
| `prioridade` | string | sim | Valores: `normal`, `urgente`. |
| `situacao` | string | sim | Valores: `aberto`, `em_producao`, `finalizado`, `cancelado`. |
| `pagamento_situacao` | string \| null | sim | Valores: `nao_pago`, `sinal_pago`, `pago`, `null`. |
| `itens` | array de object | sim |  |
| `itens[].id` | string (uuid) | sim |  |
| `itens[].tipo` | string | sim | Valores: `catalogo`, `cotacao`, `avulso`. |
| `itens[].produto_id` | string (uuid) \| null | sim |  |
| `itens[].variacao_id` | string (uuid) \| null | sim |  |
| `itens[].nome` | string | sim |  |
| `itens[].quantidade` | integer | sim |  |
| `itens[].situacao` | string | sim | Valores: `ativo`, `finalizado`, `retirado`. |
| `itens[].etapa` | string \| null | sim | Nome da etapa atual do item. |
| `criado_em` | string (date-time) | sim |  |
| `atualizado_em` | string (date-time) | sim |  |
| `finalizado_em` | string (date-time) \| null | sim |  |
| `valor_centavos` | integer | não | [custos] Valor do pedido de cliente. (de 0 a 100000000000) |

```json
{
  "id": "a0b1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d",
  "codigo": "OP-0107",
  "tipo": "cliente",
  "origem": "api",
  "cotacao_id": null,
  "cliente_nome": "Ana Lima",
  "prazo": "2026-10-20",
  "prioridade": "normal",
  "situacao": "aberto",
  "pagamento_situacao": "nao_pago",
  "itens": [
    {
      "id": "e4f5a6b7-c8d9-4e0f-1a2b-3c4d5e6f7a8b",
      "tipo": "catalogo",
      "produto_id": "5a6b7c8d-9e0f-4a1b-2c3d-4e5f6a7b8c9d",
      "variacao_id": "6b7c8d9e-0f1a-4b2c-3d4e-5f6a7b8c9d0e",
      "nome": "Chaveiro Dragão · Azul",
      "quantidade": 200,
      "situacao": "ativo",
      "etapa": "Fila"
    }
  ],
  "criado_em": "2026-10-05T10:00:00-03:00",
  "atualizado_em": "2026-10-05T10:00:00-03:00",
  "finalizado_em": null
}
```

## Outras respostas

- **400** (`dados_invalidos`): Dados, filtro, cursor ou cabeçalho inválido.
- **401** (`nao_autenticado`): Chave ausente, malformada, desconhecida, revogada ou expirada (a resposta é a mesma para todos os casos).
- **403** (`escopo_insuficiente`): Escopo insuficiente, conta bloqueada, módulo desligado ou chave suspensa.
- **408** (`tempo_esgotado`): O corpo do POST não chegou inteiro em 5 s.
- **409** (`idempotencia_em_andamento`): Requisição com a mesma Idempotency-Key ainda em andamento.
- **413** (`corpo_grande_demais`): Corpo acima de 64 KB.
- **415** (`tipo_nao_suportado`): Só `application/json`.
- **422** (`saldo_insuficiente`): Regra de negócio recusou (referência de outra conta ou inexistente, saldo insuficiente, quantidade fora do mínimo ou múltiplo) ou a Idempotency-Key já foi usada com outro corpo (`idempotencia_conflito`).
- **429** (`limite_excedido`): Limite de uso excedido (rajada, minuto, mês ou requisições simultâneas).
- **500** (`erro_interno`): Erro interno. O detalhe fica no log, ligado ao requisicao_id.
- **503** (`indisponivel`): API desligada, sob pressão (disjuntor aberto) ou no limite global da plataforma.

## Exemplos

**cURL**

```bash
curl -X POST "https://api.precificador3d.com.br/v1/pedidos-producao" \
  -H "Authorization: Bearer $PC3D_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data '{
  "tipo": "cliente",
  "cliente_nome": "Ana Lima",
  "prazo": "2026-10-20",
  "prioridade": "normal",
  "observacao": "Pedido ERP 5521",
  "itens": [
    {
      "produto_id": "5a6b7c8d-9e0f-4a1b-2c3d-4e5f6a7b8c9d",
      "variacao_id": "6b7c8d9e-0f1a-4b2c-3d4e-5f6a7b8c9d0e",
      "quantidade": 200
    },
    {
      "avulso": {
        "nome": "Suporte de celular personalizado"
      },
      "quantidade": 1
    }
  ]
}'
```

**JavaScript**

```js
const resposta = await fetch('https://api.precificador3d.com.br/v1/pedidos-producao', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PC3D_CHAVE}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "tipo": "cliente",
    "cliente_nome": "Ana Lima",
    "prazo": "2026-10-20",
    "prioridade": "normal",
    "observacao": "Pedido ERP 5521",
    "itens": [
      {
        "produto_id": "5a6b7c8d-9e0f-4a1b-2c3d-4e5f6a7b8c9d",
        "variacao_id": "6b7c8d9e-0f1a-4b2c-3d4e-5f6a7b8c9d0e",
        "quantidade": 200
      },
      {
        "avulso": {
          "nome": "Suporte de celular personalizado"
        },
        "quantidade": 1
      }
    ]
  }),
});
if (!resposta.ok) {
  const erro = await resposta.json(); // application/problem+json
  throw new Error(`${erro.codigo}: ${erro.detail} (${erro.requisicao_id})`);
}
const dados = await resposta.json();
```

**Python**

```python
import os
import uuid

import requests

resposta = requests.post(
    "https://api.precificador3d.com.br/v1/pedidos-producao",
    headers={
        "Authorization": f"Bearer {os.environ['PC3D_CHAVE']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "tipo": "cliente",
        "cliente_nome": "Ana Lima",
        "prazo": "2026-10-20",
        "prioridade": "normal",
        "observacao": "Pedido ERP 5521",
        "itens": [
            {
                "produto_id": "5a6b7c8d-9e0f-4a1b-2c3d-4e5f6a7b8c9d",
                "variacao_id": "6b7c8d9e-0f1a-4b2c-3d4e-5f6a7b8c9d0e",
                "quantidade": 200,
            },
            {
                "avulso": {
                    "nome": "Suporte de celular personalizado",
                },
                "quantidade": 1,
            },
        ],
    },
    timeout=10,
)
resposta.raise_for_status()
dados = resposta.json()
```