Crear orden de compra

{
  "supplier_id": "sup_01...",
  "store_id": "str_principal_01...",
  "expected_delivery_at": "2026-08-14T10:00:00-05:00",
  "idempotency_key": "0d4f1c9a-7c33-4d6e-9f2a-1b8e5a6c0d21",
  "lines": [
    {
      "item_id": "itm_pollo_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": "0991234560001",
  "external_reference": "MOV-2026-00342",
  "external_user_id": "erp-usuario-42",
  "lines": [
    {
      "supplier_sku": "SKU-POLLO-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-14T15:00:00.000Z",
    "external_reference": null,
    "lines": [
      {
        "id": "pol_01...",
        "item_id": "itm_pollo_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": "0991234560001", "count": 3 }
  }
}

{
  "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-05:00",
  "idempotency_key": "0d4f1c9a-7c33-4d6e-9f2a-1b8e5a6c0d21",
  "lines": [
    {
      "item_id": "itm_pollo_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": "0991234560001",
  "external_reference": "MOV-2026-00342",
  "external_user_id": "erp-usuario-42",
  "lines": [
    {
      "supplier_sku": "SKU-POLLO-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-14T15:00:00.000Z",
    "external_reference": null,
    "lines": [
      {
        "id": "pol_01...",
        "item_id": "itm_pollo_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": "0991234560001", "count": 3 }
  }
}

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

requerido

API key de BOH con scope inventory:write.

string

requerido

UUID del vendor.

string

UUID del proveedor. Se requiere supplier_id o external_supplier_id.

string

ID externo del proveedor.

string

UUID del establecimiento receptor. Exactamente uno de store_id, external_store_id o store_tax_id debe ser enviado.

string

Identificador cruzado del establecimiento. Mutuamente exclusivo con store_id y store_tax_id.

string

Identificador fiscal del establecimiento (RUC, CNPJ, CUIT, NIT…). Devuelve 422 si varios establecimientos activos comparten el mismo valor — usa store_id o external_store_id para desambiguar. Mutuamente exclusivo con store_id y external_store_id.

string

UUID de la agenda de recepción a la que pertenece la orden (opcional).

string

Clasificación libre de la orden (máx. 64 chars).

string

Timestamp ISO 8601 del cierre del pedido.

string

Timestamp ISO 8601 de la entrega esperada.

string

Referencia documental del cliente (ej. código de movimiento del ERP, máx. 256 chars). Se guarda para búsqueda y filtrado en el listado. No es clave de deduplicación — para eso usa idempotency_key.

string

Notas libres (máx. 1024 chars).

object

Datos adicionales libres.

boolean

Con true, cada artículo de línea debe existir en el catálogo del proveedor.

object[]

Líneas iniciales (opcional — puedes agregarlas después con action=add-lines).

Mostrar campos de línea

string

UUID del artículo. Exactamente uno de item_id, external_item_id o supplier_sku debe ser enviado.

string

ID externo del artículo, resuelto en el servidor. Al usarlo, base_unit_id pasa a ser opcional.

string

SKU del proveedor (sin distinguir mayúsculas, máx. 128 chars). Se resuelve contra el catálogo del proveedor de la orden. base_unit_id se deriva automáticamente.

number

requerido

Cantidad pedida en la unidad de entrada.

number

Cantidad en la unidad base del artículo. Requerida salvo que envíes unit_code o item_unit_id — en ambos casos el servidor la deriva como qty × factor_to_base. Si la envías de todos modos, debe coincidir con el valor derivado (tolerancia 0.001) o la petición falla con purchase_order_qty_base_mismatch (422).

string

UUID de la unidad base. Requerido salvo que uses external_item_id o supplier_sku.

number

Factor de conversión de la unidad de entrada a la base.

string

UUID de una unidad de artículo existente. El servidor deriva qty_base desde el factor_to_base de la unidad — no necesitas conocer el factor de conversión. Devuelve item_unit_not_found (404) si la unidad no resuelve y omitiste qty_base. Mutuamente exclusivo con unit_code y unit_label.

string

Resuelve la unidad de compra por su código de integración (sin distinguir mayúsculas). Mutuamente exclusivo con item_unit_id y unit_label.

string

Etiqueta libre de unidad (ej. "costal"), se guarda cuando no hay item_unit_id.

boolean

Con true y unit_label presente, guarda una nueva unidad PURCHASE en el artículo para reutilizarla.

number

Costo por unidad (≥ 0).

number

Informativo: monto de impuestos de la línea.

number

Informativo: monto de flete / entrega.

number

Informativo: monto total declarado.

number

Informativo: monto de comisión / markup.

string

Notas de línea (máx. 512 chars).

object

Datos adicionales por línea.

string

Identificador de usuario del llamador para auditoría. Opcional al crear; requerido en close.

string

Clave de idempotencia (máx. 255 chars). Repetir la misma clave devuelve la orden existente con HTTP 200 en lugar de crear un duplicado.

{
  "supplier_id": "sup_01...",
  "store_id": "str_principal_01...",
  "expected_delivery_at": "2026-08-14T10:00:00-05:00",
  "idempotency_key": "0d4f1c9a-7c33-4d6e-9f2a-1b8e5a6c0d21",
  "lines": [
    {
      "item_id": "itm_pollo_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": "0991234560001",
  "external_reference": "MOV-2026-00342",
  "external_user_id": "erp-usuario-42",
  "lines": [
    {
      "supplier_sku": "SKU-POLLO-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-14T15:00:00.000Z",
    "external_reference": null,
    "lines": [
      {
        "id": "pol_01...",
        "item_id": "itm_pollo_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": "0991234560001", "count": 3 }
  }
}

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

Descripción general

Identidad

Establecimientos

Proveedores

Artículos de catálogo

Sincronización de catálogo

Recetas

Recepciones de mercancía

Conteos de inventario

Eventos de merma

Transferencias

Lotes de producción

Seguimiento

Niveles de reorden

Pedido sugerido

Órdenes de compra

Líneas de OC

Webhooks

Crear orden de compra