{
"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"
}
}
Órdenes de compra
Crear orden de compra
Crea una nueva orden de compra en estado DRAFT, opcionalmente con líneas iniciales.
POST
/
api
/
v1
/
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
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"
}
}