Registrar compra
POST /api/purchases
Autenticación: Bearer del usuario del tenant (Authorization: Bearer <api_token>).
Registra una compra y suma el stock de cada ítem en su almacén. Los pagos se registran después con Registrar pago de compra.
Quién puede usarlo: cualquier usuario autenticado (administrador o vendedor).
| Campo | Tipo | Obligatorio | Descripción / valores permitidos |
|---|---|---|---|
document_type_id |
string | Sí | Tipo de comprobante del proveedor: 01 factura, 03 boleta, GU75 guía, NE76 nota de entrada (ver GET /api/purchases/tables). |
series |
string | Sí | Serie del comprobante del proveedor (p. ej. F001). |
number |
numeric | Sí | Número del comprobante (solo dígitos). |
date_of_issue |
date | Sí | Fecha de emisión YYYY-MM-DD. |
time_of_issue |
string | Sí | Hora HH:MM:SS. |
date_of_due |
date | No | Fecha de vencimiento. |
supplier_id |
integer | Sí | Id del proveedor (persona de tipo proveedor). |
currency_type_id |
string | Sí | PEN o USD. |
exchange_rate_sale |
numeric | Sí | Tipo de cambio (1 en soles). |
total_* / total |
numeric | Sí | Totales de cabecera: total_taxed (gravado), total_exonerated, total_unaffected, total_free, total_igv, total_taxes, total_value (sin IGV), subtotal y total (con IGV). Deben cuadrar con la suma de las líneas: la plataforma no recalcula los totales que envías. |
total_perception |
numeric | No | Percepción. |
observation |
string | No | Observación. |
items |
array | Sí | Líneas de la compra (ver tabla de líneas). unit_price es el costo con IGV. Opcionales propios de compras: warehouse_id (almacén donde entra el stock), lot_code y date_of_due (lote y vencimiento), affectation_igv_type (objeto de la afectación). |
charges / discounts / attributes / guides / payments |
array | No | Usa []. Los pagos enviados aquí no se registran. |
Línea de la compra (items[]):
| Campo | Tipo | Obligatorio | Descripción / valores permitidos |
|---|---|---|---|
item_id |
integer | Sí | Id del producto. |
item |
object | Sí | Copia del producto tal como se guardará en el documento (al menos id, description, unit_type_id, internal_id, is_set, presentation). Se obtiene de los endpoints de productos de la API. |
quantity |
numeric | Sí | Cantidad (> 0). |
unit_value |
numeric | Sí | Valor unitario sin IGV. |
unit_price |
numeric | Sí | Precio unitario con IGV. |
affectation_igv_type_id |
string | Sí | Afectación IGV (catálogo SUNAT 07): 10 gravado, 20 exonerado, 30 inafecto. |
price_type_id |
string | Sí | 01 precio unitario (incluye IGV), 02 valor referencial (gratuito). |
percentage_igv |
numeric | Sí | Porcentaje de IGV (18, o 10 si aplica la Ley 31556). |
total_base_igv / total_igv / total_taxes / total_value / total |
numeric | Sí | Totales de la línea: base imponible, IGV, impuestos, valor (sin IGV) y total (con IGV). |
warehouse_id |
integer | No | Almacén del que sale el stock (por defecto el del establecimiento). |
total_discount / total_charge / charges / discounts / attributes |
varios | No | Descuentos, cargos y atributos de la línea (usa 0 y [] si no aplica). |
system_isc_type_id / total_base_isc / percentage_isc / total_isc / total_plastic_bag_taxes |
varios | No | ISC e ICBPER (usa null/0 si no aplica). |
Errores: 422 si falta supplier_id, series, number (o no es numérico), date_of_issue o items.
Respuesta: data con id, number_full, external_id, state_type_id, proveedor, total y enlaces al PDF (print_a4, print_ticket).
Cuerpo
Content-Type: application/json
{
"document_type_id": "01",
"series": "F001",
"number": "4587",
"date_of_issue": "2026-11-07",
"time_of_issue": "09:30:00",
"date_of_due": "2026-12-07",
"supplier_id": 14,
"currency_type_id": "PEN",
"exchange_rate_sale": 1,
"total_prepayment": 0,
"total_charge": 0,
"total_discount": 0,
"total_exportation": 0,
"total_free": 0,
"total_taxed": 100.0,
"total_unaffected": 0,
"total_exonerated": 0,
"total_igv": 18.0,
"total_base_isc": 0,
"total_isc": 0,
"total_base_other_taxes": 0,
"total_other_taxes": 0,
"total_taxes": 18.0,
"total_value": 100.0,
"total": 118.0,
"total_perception": 0,
"observation": "Entrega en almacén central",
"items": [
{
"item_id": 120,
"item": {
"id": 120,
"item_id": 120,
"internal_id": "P0001",
"description": "GASEOSA 500ML",
"unit_type_id": "NIU",
"currency_type_id": "PEN",
"sale_unit_price": 3.5,
"purchase_unit_price": 2.2,
"sale_affectation_igv_type_id": "10",
"purchase_affectation_igv_type_id": "10",
"is_set": false,
"has_igv": true,
"presentation": null
},
"currency_type_id": "PEN",
"quantity": 50,
"unit_value": 2.0,
"affectation_igv_type_id": "10",
"total_base_igv": 100.0,
"percentage_igv": 18,
"total_igv": 18.0,
"system_isc_type_id": null,
"total_base_isc": 0,
"percentage_isc": 0,
"total_isc": 0,
"total_base_other_taxes": 0,
"percentage_other_taxes": 0,
"total_other_taxes": 0,
"total_plastic_bag_taxes": 0,
"total_taxes": 18.0,
"price_type_id": "01",
"unit_price": 2.36,
"total_value": 100.0,
"total_discount": 0,
"total_charge": 0,
"total": 118.0,
"attributes": [],
"charges": [],
"discounts": [],
"warehouse_id": 1,
"affectation_igv_type": {
"id": "10",
"active": 1,
"exportation": 0,
"free": 0,
"description": "Gravado - Operación Onerosa"
},
"lot_code": null,
"date_of_due": null
}
],
"charges": [],
"discounts": [],
"attributes": [],
"guides": [],
"payments": []
}
Respuestas
200 — Registrada
{
"success": true,
"data": {
"id": 77,
"state_type_id": "01",
"state_type_description": "Registrado",
"number_full": "F001-4587",
"external_id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
"filename": "F001-4587-77-20261107",
"supplier": {
"id": 14,
"name": "DISTRIBUIDORA DEL SUR S.A.C.",
"number": "20456789123",
"email": null,
"phone": null
},
"total": 118.0,
"print_a4": "https://empresa.dominio/purchases/print/c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f/a4",
"print_ticket": "https://empresa.dominio/purchases/print/c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f/ticket"
}
}
422 — Validación
{
"success": false,
"message": {
"number": [
"number debe ser numérico."
]
}
}
Pruébalo
Prueba este endpoint con tu empresa y tu token: elige la URL en Servers, pega el token en Authorize y haz clic en Try it out.