Saltar al contenido
Facturador

Registrar gasto

POST /api/expenses

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

Registra un gasto con su detalle y sus pagos. El efectivo (cash) sale de la caja abierta del usuario; los pagos a una cuenta salen de esa cuenta. Es la vía recomendada para integraciones: mismas reglas que Registrar gasto (endpoint existente) (finances/expense), con respuestas estándar y códigos HTTP reales.

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

Formato de respuesta: estándar {success, data, message?} (registro único). Responde 201 con el gasto completo (ítems y pagos) y print_url (PDF A4 público).

Cuerpo (JSON):

Campo Tipo Obligatorio Descripción / valores permitidos
expense_type_id integer Sí Tipo de comprobante del gasto (tipos de gasto). El tipo 4 ("Otros") no exige número.
expense_reason_id integer Sí Motivo del gasto (motivos de gasto).
number string (máx. 100) Sí salvo tipo 4 Número del comprobante del proveedor.
supplier_id integer Sí Id del proveedor (persona registrada).
date_of_issue date Sí Fecha de emisión YYYY-MM-DD.
time_of_issue string Sí Hora HH:MM:SS.
currency_type_id string Sí PEN o USD.
exchange_rate_sale numeric (≥ 0) No Tipo de cambio venta. Si no lo envías o envías 0, se usa el tipo de cambio del día de date_of_issue registrado en el sistema; en soles (PEN) sin tipo registrado ese día se guarda 1; en otra moneda, si no hay ninguno disponible, responde 422 pidiéndolo.
establishment_id integer Sí Establecimiento.
total numeric Sí Total, mayor que 0.
items array Sí Detalle, al menos uno: [{description (máx. 500), total (> 0)}].
payments array Sí Pagos, al menos uno. La suma no puede superar total (puede ser menor: el resto queda pendiente y se paga luego con Registrar pago de gasto).
payments[].expense_method_type_id integer No Solo para integraciones antiguas (catálogo de métodos de gasto): 1 = caja general, se convierte en efectivo a la caja. Usa payment_method_type_id.

Cada elemento de payments: date_of_payment (YYYY-MM-DD), payment_method_type_id (método de pago), payment_destination_id (cash = la caja abierta del usuario, o el id de una cuenta bancaria o billetera), payment (monto > 0) y reference (opcional: número de operación, voucher...).

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).

Reglas:

  • Un pago con destino cash usa la caja abierta del usuario del token: sin caja abierta responde 409 y no se guarda nada.
  • Un pago a una cuenta: la cuenta debe existir, ser de la misma moneda del registro y estar disponible para el establecimiento; el método de pago debe estar habilitado para esa operación y ese destino (ver Configuración del flujo de caja). Si no, 409.
  • Todo el registro se guarda en una sola operación: si algún pago se rechaza, no queda ni el registro ni ningún pago.
  • Si envías id, se ignora: este endpoint siempre crea un registro nuevo (para editar usa Editar gasto / Editar ingreso).
  • Un pago en efectivo no puede superar el efectivo disponible en la caja (409).

Errores:

  • 409 cuando una regla de caja lo impide (sin caja abierta, cuenta de otra moneda, método no habilitado para pagos...). El message explica la causa y puede mostrarse tal cual.
  • 422 {success: false, message: {campo: [errores]}} si falta un campo, los pagos superan el total o exchange_rate_sale no es válido.
  • 401 sin token o con un token inválido.

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": 0,
  "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

201 — Registrado

{
  "success": true,
  "data": {
    "id": 25,
    "external_id": "4f1c2b8e-7a9d-4d1e-9a3b-2c6e8f0a1b2c",
    "number": "F001-4587",
    "number_full": "F001-4587",
    "date_of_issue": "2026-11-07",
    "time_of_issue": "10:15:00",
    "state_type_id": "05",
    "state_type_description": "Aceptado",
    "currency_type_id": "PEN",
    "exchange_rate_sale": 1.0,
    "total": 50.0,
    "user_id": 5,
    "establishment_id": 1,
    "expense_type_id": 1,
    "expense_type_description": "FACTURA",
    "expense_reason_id": 2,
    "expense_reason_description": "Servicios",
    "supplier_id": 14,
    "supplier": {
      "name": "SERVICIOS GENERALES S.A.C.",
      "number": "20456789123"
    },
    "items": [
      {
        "id": 40,
        "description": "Servicio de limpieza noviembre",
        "total": 50.0
      }
    ],
    "payments": [
      {
        "id": 31,
        "date_of_payment": "2026-11-07",
        "payment_method_type_id": "01",
        "payment_method_type_description": "Efectivo",
        "destination_description": "CAJA - JUAN PEREZ",
        "reference": null,
        "payment": 50.0
      }
    ],
    "print_url": "https://empresa.dominio/print/expense/4f1c2b8e-7a9d-4d1e-9a3b-2c6e8f0a1b2c"
  },
  "message": "Gasto registrado"
}

409 — Sin caja abierta

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

409 — Método no habilitado

{
  "success": false,
  "message": "\"Transferencia\" no está marcado para pagos. Actívalo en Configuración → Métodos de pago, o elige otro."
}

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."
    ]
  }
}

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.