Saltar al contenido
Facturador

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.