> ## 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.
# Crear orden de compra
> Crea una nueva orden de compra en estado DRAFT, opcionalmente con líneas iniciales.
API key de BOH con scope `inventory:write`.
UUID del vendor.
UUID del proveedor. Se requiere `supplier_id` o `external_supplier_id`.
ID externo del proveedor.
UUID del establecimiento receptor. Exactamente uno de `store_id`, `external_store_id` o `store_tax_id` debe ser enviado.
Identificador cruzado del establecimiento. Mutuamente exclusivo con `store_id` y `store_tax_id`.
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`.
UUID de la agenda de recepción a la que pertenece la orden (opcional).
Clasificación libre de la orden (máx. 64 chars).
Timestamp ISO 8601 del cierre del pedido.
Timestamp ISO 8601 de la entrega esperada.
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`.
Notas libres (máx. 1024 chars).
Datos adicionales libres.
Con `true`, cada artículo de línea debe existir en el catálogo del proveedor.
Líneas iniciales (opcional — puedes agregarlas después con `action=add-lines`).
UUID del artículo. Exactamente uno de `item_id`, `external_item_id` o `supplier_sku` debe ser enviado.
ID externo del artículo, resuelto en el servidor. Al usarlo, `base_unit_id` pasa a ser opcional.
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.
Cantidad pedida en la unidad de entrada.
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).
UUID de la unidad base. Requerido salvo que uses `external_item_id` o `supplier_sku`.
Factor de conversión de la unidad de entrada a la base.
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`.
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`.
Etiqueta libre de unidad (ej. `"costal"`), se guarda cuando no hay `item_unit_id`.
Con `true` y `unit_label` presente, guarda una nueva unidad PURCHASE en el artículo para reutilizarla.
Costo por unidad (≥ 0).
Informativo: monto de impuestos de la línea.
Informativo: monto de flete / entrega.
Informativo: monto total declarado.
Informativo: monto de comisión / markup.
Notas de línea (máx. 512 chars).
Datos adicionales por línea.
Identificador de usuario del llamador para auditoría. Opcional al crear; requerido en `close`.
Clave de idempotencia (máx. 255 chars). Repetir la misma clave devuelve la orden existente con HTTP 200 en lugar de crear un duplicado.
```json Con UUIDs internos theme={null}
{
"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
}
]
}
```
```json Totalmente externo (sin UUIDs internos) theme={null}
{
"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
}
]
}
```
```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-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
}
]
}
}
```
```json 404 theme={null}
{
"error": {
"kind": "supplier_not_found",
"message": "Supplier not found"
}
}
```
```json 404 (establecimiento no 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 (establecimiento no 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 ambiguo) 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": "0991234560001", "count": 3 }
}
}
```
```json 422 (qty_base no coincide) theme={null}
{
"error": {
"kind": "purchase_order_qty_base_mismatch",
"message": "Client-provided qty_base does not match the server-derived value"
}
}
```
```json 404 (unidad de artículo no 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"
}
}
```