Saltar al contenido
Facturador

Registrar gasto (heredado)

POST /api/finances/expense

Autenticación: Bearer del usuario del tenant (Authorization: Bearer <api_token>).

Vía recomendada: POST /api/expenses (mismas reglas y campos, respuesta 201 con el gasto completo y errores con código HTTP real: 409 por reglas de caja, 422 por validación). Este endpoint se mantiene por compatibilidad con la app móvil. exchange_rate_sale es opcional: sin él o con 0 se usa el tipo de cambio del día (en soles sin tipo registrado, 1).

Registra un gasto con su detalle y sus pagos. Los pagos en efectivo (cash) salen de la caja abierta del usuario.

Quién puede usarlo: cualquier usuario autenticado (administrador o vendedor).

Campo Tipo Obligatorio Descripción / valores permitidos
expense_type_id integer Sí Tipo de comprobante del gasto (ver sección Catálogos de gastos e ingresos, tipos de gasto). El tipo 4 ("Otros") no exige número.
expense_reason_id integer Sí Motivo del gasto (sección Catálogos de gastos e ingresos, motivos de gasto).
number string Sí salvo tipo 4 Número del comprobante del proveedor (máx. 100).
supplier_id integer Sí Id del proveedor (persona registrada como proveedor).
date_of_issue date Sí Fecha YYYY-MM-DD.
time_of_issue string Sí Hora HH:MM:SS.
currency_type_id string Sí PEN o USD.
exchange_rate_sale numeric No Sin él o con 0, el tipo de cambio del día (en soles sin tipo registrado, 1).
establishment_id integer Sí Establecimiento.
total numeric Sí Total, mayor que 0. Debe ser igual a la suma de items[].total.
items array Sí Detalle: [{description (máx. 500), total (> 0)}].
payments array Sí Pagos: [{date_of_payment, payment_method_type_id, payment_destination_id, payment, reference}]. La suma no puede superar total.

Métodos de pago (payment_method_type_id): catálogo de la empresa. Los estándar son 01 Efectivo, 02 Tarjeta de crédito, 03 Tarjeta de débito, 04 Transferencia; cada empresa puede tener otros (Yape, Plin, depósito, etc.). Obtén la lista vigente con GET /api/finances/tables (data.payment_method_types).

Destino (payment_destination_id): cash = la caja abierta del usuario autenticado, o el id de una cuenta bancaria / billetera (ver 5. Cuentas bancarias o data.payment_destinations de GET /api/finances/tables).

Respuestas:

  • 200 con success: true y data (id, external_id, number, print_url del PDF A4).
  • 422 con el formato estándar si falla la validación (p. ej. pagos que superan el total).
  • 200 con success: false y message cuando una regla de negocio lo impide (p. ej. pago en efectivo sin caja abierta). Revisa siempre success.

Cuerpo

Content-Type: application/json

{
  "expense_type_id": 1,
  "expense_reason_id": 2,
  "number": "F001-4587",
  "supplier_id": 14,
  "date_of_issue": "2026-11-07",
  "time_of_issue": "10:15:00",
  "currency_type_id": "PEN",
  "exchange_rate_sale": 1,
  "establishment_id": 1,
  "total": 50.0,
  "items": [
    {
      "description": "Servicio de limpieza noviembre",
      "total": 50.0
    }
  ],
  "payments": [
    {
      "date_of_payment": "2026-11-07",
      "payment_method_type_id": "01",
      "payment_destination_id": "cash",
      "payment": 50.0,
      "reference": null
    }
  ]
}

Respuestas

200 — Registrado

{
  "success": true,
  "data": {
    "id": 25,
    "external_id": "4f1c2b8e-7a9d-4d1e-9a3b-2c6e8f0a1b2c",
    "number": "F001-4587",
    "print_url": "https://empresa.dominio/print/expense/4f1c2b8e-7a9d-4d1e-9a3b-2c6e8f0a1b2c"
  }
}

422 — Validación

{
  "success": false,
  "message": {
    "number": [
      "El número del comprobante es obligatorio para este tipo de gasto."
    ],
    "payments": [
      "Los montos ingresados superan el monto total."
    ]
  }
}

200 — Regla de caja

{
  "success": false,
  "message": "Abre una caja antes de registrar este pago en efectivo: sin caja abierta no aparecería en ningún cierre."
}

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.