Registrar ingreso
POST /api/incomes
Autenticación: Bearer del usuario del tenant (Authorization: Bearer <api_token>).
Registra un ingreso con su detalle y sus cobros. El efectivo (cash) entra a la caja abierta del usuario; los cobros a una cuenta entran a esa cuenta. Es la vía recomendada para integraciones: mismas reglas que Registrar ingreso (endpoint existente) (finances/income), con respuestas estándar y códigos HTTP reales. El número del ingreso lo asigna el sistema.
Quién puede usarlo: cualquier usuario autenticado (administrador o vendedor).
Formato de respuesta: estándar {success, data, message?} (registro único). Responde 201 con el ingreso completo (ítems y cobros) y print_url (PDF A4 público).
Cuerpo (JSON):
| Campo | Tipo | Obligatorio | Descripción / valores permitidos |
|---|---|---|---|
income_type_id |
integer | Sí | Tipo de ingreso (tipos de ingreso). |
income_reason_id |
integer | Sí | Motivo de ingreso (motivos de ingreso). |
customer |
string | No | Nombre de quien entrega el dinero (texto libre). Por defecto -. |
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 (≥ 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í | Cobros, al menos uno. La suma debe ser igual a total. |
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
cashusa la caja abierta del usuario del token: sin caja abierta responde409y 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 cobro a una cuenta también exige que el usuario tenga una caja abierta (el cobro se registra dentro de su turno).
Errores:
409cuando una regla de caja lo impide (sin caja abierta, cuenta inexistente o de otra moneda, método no habilitado...).422si falta un campo, la suma de cobros no coincide con el total oexchange_rate_saleno es válido.401sin token o con un token inválido.
Cuerpo
Content-Type: application/json
{
"income_type_id": 1,
"income_reason_id": 1,
"customer": "CARLOS RAMIREZ",
"date_of_issue": "2026-11-07",
"time_of_issue": "11:20:00",
"currency_type_id": "PEN",
"establishment_id": 1,
"total": 120.0,
"items": [
{
"description": "Aporte de capital",
"total": 120.0
}
],
"payments": [
{
"date_of_payment": "2026-11-07",
"payment_method_type_id": "01",
"payment_destination_id": "cash",
"payment": 120.0,
"reference": null
}
]
}
Respuestas
201 — Registrado
{
"success": true,
"data": {
"id": 8,
"external_id": "9b2d4e6f-1a3c-4b5d-8e7f-0a1b2c3d4e5f",
"number": "1",
"number_full": "ING-1",
"date_of_issue": "2026-11-07",
"time_of_issue": "11:20:00",
"state_type_id": "05",
"state_type_description": "Aceptado",
"currency_type_id": "PEN",
"exchange_rate_sale": 1.0,
"total": 120.0,
"user_id": 5,
"establishment_id": 1,
"income_type_id": 1,
"income_type_description": "Otros ingresos",
"income_reason_id": 1,
"income_reason_description": "Aporte de socio",
"customer": "CARLOS RAMIREZ",
"items": [
{
"id": 11,
"description": "Aporte de capital",
"total": 120.0
}
],
"payments": [
{
"id": 15,
"date_of_payment": "2026-11-07",
"payment_method_type_id": "01",
"payment_method_type_description": "Efectivo",
"destination_description": "CAJA - JUAN PEREZ",
"reference": null,
"payment": 120.0
}
],
"print_url": "https://empresa.dominio/print/income/9b2d4e6f-1a3c-4b5d-8e7f-0a1b2c3d4e5f"
},
"message": "Ingreso registrado"
}
409 — Sin caja abierta
{
"success": false,
"message": "La caja se encuentra cerrada. Debes abrirla antes de registrar un ingreso."
}
422 — Cobros no cuadran
{
"success": false,
"message": {
"payments": [
"Los montos ingresados no coinciden con el monto total."
]
}
}
422 — Sin tipo de cambio
{
"success": false,
"message": {
"exchange_rate_sale": [
"No hay tipo de cambio registrado para el 2026-11-07. Envía exchange_rate_sale."
]
}
}
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.