> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fire.rest/llms.txt
> Use this file to discover all available pages before exploring further.
# Criar pedido de compra
> Cria um novo pedido de compra em estado DRAFT, opcionalmente com linhas iniciais.
API key do BOH com escopo `inventory:write`.
UUID do vendor.
UUID do fornecedor.
ID externo do fornecedor.
UUID do estabelecimento receptor. Exatamente um de `store_id`, `external_store_id` ou `store_tax_id` deve ser enviado.
Identificador externo do estabelecimento. Mutuamente exclusivo com `store_id` e `store_tax_id`.
Identificador fiscal do estabelecimento (RUC, CNPJ, CUIT, NIT…). Retorna `422` se vários estabelecimentos ativos compartilham o mesmo valor — use `store_id` ou `external_store_id` para desambiguar. Mutuamente exclusivo com `store_id` e `external_store_id`.
UUID da agenda de recebimento à qual o pedido pertence (opcional).
Classificação livre do pedido (máx. 64 chars).
Timestamp ISO 8601 do fechamento do pedido.
Timestamp ISO 8601 da entrega esperada.
Referência documental do cliente (ex. código de movimento do ERP, máx. 256 chars). Armazenada para busca e filtro na listagem. Não é chave de deduplicação — para isso use `idempotency_key`.
Notas livres (máx. 1024 chars).
Dados adicionais livres.
Com `true`, cada item de linha deve existir no catálogo do fornecedor.
Linhas iniciais (opcional — você pode adicioná-las depois com `action=add-lines`).
UUID do item. Exatamente um de `item_id`, `external_item_id` ou `supplier_sku` deve ser enviado.
ID externo do item, resolvido no servidor. Ao usá-lo, `base_unit_id` passa a ser opcional.
SKU do fornecedor (sem diferenciar maiúsculas, máx. 128 chars). Resolvido contra o catálogo do fornecedor do pedido. `base_unit_id` é derivado automaticamente.
Quantidade pedida na unidade de entrada.
Quantidade na unidade base do item. Obrigatória exceto se você enviar `unit_code` ou `item_unit_id` — em ambos os casos o servidor a deriva como `qty × factor_to_base`. Se enviada mesmo assim, deve coincidir com o valor derivado (tolerância 0.001) ou a requisição falha com `purchase_order_qty_base_mismatch` (422).
UUID da unidade base. Obrigatório exceto se usar `external_item_id` ou `supplier_sku`.
Fator de conversão da unidade de entrada para a base.
UUID de uma unidade de item existente. O servidor deriva `qty_base` a partir do `factor_to_base` da unidade — você não precisa conhecer o fator de conversão. Retorna `item_unit_not_found` (404) se a unidade não resolver e `qty_base` foi omitido. Mutuamente exclusivo com `unit_code` e `unit_label`.
Resolve a unidade de compra pelo código de integração (sem diferenciar maiúsculas). Mutuamente exclusivo com `item_unit_id` e `unit_label`.
Rótulo livre de unidade (ex. `"saco"`), armazenado quando não há `item_unit_id`.
Com `true` e `unit_label` presente, salva uma nova unidade PURCHASE no item para reutilização.
Custo por unidade (≥ 0).
Informativo: valor de impostos da linha.
Informativo: valor de frete / entrega.
Informativo: valor total declarado.
Informativo: valor de comissão / markup.
Notas da linha (máx. 512 chars).
Dados adicionais por linha.
Identificador do usuário chamador para auditoria. Opcional na criação; obrigatório no `close`.
Chave de idempotência (máx. 255 chars). Repetir a mesma chave retorna o pedido existente com HTTP 200 em vez de criar um duplicado.
```json Com UUIDs internos theme={null}
{
"supplier_id": "sup_01...",
"store_id": "str_principal_01...",
"expected_delivery_at": "2026-08-14T10:00:00-03:00",
"idempotency_key": "0d4f1c9a-7c33-4d6e-9f2a-1b8e5a6c0d21",
"lines": [
{
"item_id": "itm_frango_01...",
"qty": 10,
"qty_base": 10000,
"base_unit_id": "unit_g_01...",
"unit_to_base_factor": 1000,
"unit_label": "kg",
"unit_cost": 4.5
}
]
}
```
```json Totalmente externo (sem UUIDs internos) theme={null}
{
"external_supplier_id": "RUC-001234567",
"store_tax_id": "12.345.678/0001-90",
"external_reference": "MOV-2026-00342",
"external_user_id": "erp-usuario-42",
"lines": [
{
"supplier_sku": "SKU-FRANGO-001",
"qty": 10,
"unit_code": "kg",
"total_amount": 55.0
}
]
}
```
```json 201 theme={null}
{
"purchase_order": {
"id": "po_01...",
"status": "DRAFT",
"supplier_id": "sup_01...",
"store_id": "str_principal_01...",
"expected_delivery_at": "2026-08-14T13:00:00.000Z",
"external_reference": null,
"lines": [
{
"id": "pol_01...",
"item_id": "itm_frango_01...",
"qty": 10,
"qty_base": 10000,
"base_unit_id": "unit_g_01...",
"unit_label": "kg",
"unit_cost": 4.5
}
]
}
}
```
```json 404 (fornecedor não encontrado) theme={null}
{
"error": {
"kind": "supplier_not_found",
"message": "Supplier not found"
}
}
```
```json 404 (estabelecimento não encontrado por external_store_id) theme={null}
{
"error": {
"kind": "purchase_order_store_external_id_not_found",
"message": "No active store matches the provided external_store_id"
}
}
```
```json 404 (estabelecimento não encontrado por store_tax_id) theme={null}
{
"error": {
"kind": "purchase_order_store_tax_id_not_found",
"message": "No active store matches the provided store_tax_id"
}
}
```
```json 422 (store_tax_id ambíguo) theme={null}
{
"error": {
"kind": "purchase_order_store_tax_id_ambiguous",
"message": "Multiple active stores share the same tax_id — use store_id or external_store_id to disambiguate",
"details": { "tax_id": "12.345.678/0001-90", "count": 2 }
}
}
```
```json 422 (qty_base não confere) theme={null}
{
"error": {
"kind": "purchase_order_qty_base_mismatch",
"message": "Client-provided qty_base does not match the server-derived value"
}
}
```
```json 404 (unidade de item não encontrada) theme={null}
{
"error": {
"kind": "item_unit_not_found",
"message": "item_unit_id does not resolve to an active unit and qty_base was omitted"
}
}
```