Criar pedido de compra

{
  "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
    }
  ]
}

{
  "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
    }
  ]
}

{
  "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
      }
    ]
  }
}

{
  "error": {
    "kind": "supplier_not_found",
    "message": "Supplier not found"
  }
}

{
  "error": {
    "kind": "purchase_order_store_external_id_not_found",
    "message": "No active store matches the provided external_store_id"
  }
}

{
  "error": {
    "kind": "purchase_order_store_tax_id_not_found",
    "message": "No active store matches the provided store_tax_id"
  }
}

{
  "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 }
  }
}

{
  "error": {
    "kind": "purchase_order_qty_base_mismatch",
    "message": "Client-provided qty_base does not match the server-derived value"
  }
}

{
  "error": {
    "kind": "item_unit_not_found",
    "message": "item_unit_id does not resolve to an active unit and qty_base was omitted"
  }
}

POST

api

public

vendors

{vendorId}

procurement

orders

{
  "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
    }
  ]
}

{
  "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
    }
  ]
}

{
  "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
      }
    ]
  }
}

{
  "error": {
    "kind": "supplier_not_found",
    "message": "Supplier not found"
  }
}

{
  "error": {
    "kind": "purchase_order_store_external_id_not_found",
    "message": "No active store matches the provided external_store_id"
  }
}

{
  "error": {
    "kind": "purchase_order_store_tax_id_not_found",
    "message": "No active store matches the provided store_tax_id"
  }
}

{
  "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 }
  }
}

{
  "error": {
    "kind": "purchase_order_qty_base_mismatch",
    "message": "Client-provided qty_base does not match the server-derived value"
  }
}

{
  "error": {
    "kind": "item_unit_not_found",
    "message": "item_unit_id does not resolve to an active unit and qty_base was omitted"
  }
}

string

obrigatório

API key do BOH com escopo inventory:write.

string

obrigatório

UUID do vendor.

string

UUID do fornecedor.

string

ID externo do fornecedor.

string

UUID do estabelecimento receptor. Exatamente um de store_id, external_store_id ou store_tax_id deve ser enviado.

string

Identificador externo do estabelecimento. Mutuamente exclusivo com store_id e store_tax_id.

string

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.

string

UUID da agenda de recebimento à qual o pedido pertence (opcional).

string

Classificação livre do pedido (máx. 64 chars).

string

Timestamp ISO 8601 do fechamento do pedido.

string

Timestamp ISO 8601 da entrega esperada.

string

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.

string

Notas livres (máx. 1024 chars).

object

Dados adicionais livres.

boolean

Com true, cada item de linha deve existir no catálogo do fornecedor.

object[]

Linhas iniciais (opcional — você pode adicioná-las depois com action=add-lines).

Mostrar campos da linha

string

UUID do item. Exatamente um de item_id, external_item_id ou supplier_sku deve ser enviado.

string

ID externo do item, resolvido no servidor. Ao usá-lo, base_unit_id passa a ser opcional.

string

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.

number

obrigatório

Quantidade pedida na unidade de entrada.

number

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).

string

UUID da unidade base. Obrigatório exceto se usar external_item_id ou supplier_sku.

number

Fator de conversão da unidade de entrada para a base.

string

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.

string

Resolve a unidade de compra pelo código de integração (sem diferenciar maiúsculas). Mutuamente exclusivo com item_unit_id e unit_label.

string

Rótulo livre de unidade (ex. "saco"), armazenado quando não há item_unit_id.

boolean

Com true e unit_label presente, salva uma nova unidade PURCHASE no item para reutilização.

number

Custo por unidade (≥ 0).

number

Informativo: valor de impostos da linha.

number

Informativo: valor de frete / entrega.

number

Informativo: valor total declarado.

number

Informativo: valor de comissão / markup.

string

Notas da linha (máx. 512 chars).

object

Dados adicionais por linha.

string

Identificador do usuário chamador para auditoria. Opcional na criação; obrigatório no close.

string

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.

{
  "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
    }
  ]
}

{
  "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
    }
  ]
}

{
  "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
      }
    ]
  }
}

{
  "error": {
    "kind": "supplier_not_found",
    "message": "Supplier not found"
  }
}

{
  "error": {
    "kind": "purchase_order_store_external_id_not_found",
    "message": "No active store matches the provided external_store_id"
  }
}

{
  "error": {
    "kind": "purchase_order_store_tax_id_not_found",
    "message": "No active store matches the provided store_tax_id"
  }
}

{
  "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 }
  }
}

{
  "error": {
    "kind": "purchase_order_qty_base_mismatch",
    "message": "Client-provided qty_base does not match the server-derived value"
  }
}

{
  "error": {
    "kind": "item_unit_not_found",
    "message": "item_unit_id does not resolve to an active unit and qty_base was omitted"
  }
}

Visão geral

Identidade

Estabelecimentos

Fornecedores

Itens do catálogo

Sincronização de catálogo

Receitas

Recebimentos de mercadoria

Contagens de estoque

Eventos de perda

Transferências

Lotes de produção

Rastreamento

Níveis de reposição

Pedido sugerido

Pedidos de compra

Linhas de PC

Webhooks

Criar pedido de compra