Registrar pago de comprobante
POST /api/document-payments
Autenticación: Bearer del usuario del tenant (Authorization: Bearer <api_token>).
Registra un pago de un comprobante (factura, boleta). Si el comprobante es una nota de crédito, el pago es una devolución (sale dinero del destino).
Quién puede usarlo: cualquier usuario autenticado (administrador o vendedor).
Formato de respuesta: heredado {success, message?, data?} sin paginación. Ante reglas de negocio puede responder HTTP 200 con success: false: revisa siempre success. Devuelve el id del pago en la raíz de la respuesta.
Cuerpo (JSON):
| Campo | Tipo | Obligatorio | Descripción / valores permitidos |
|---|---|---|---|
document_id |
integer | Sí | Id del comprobante (debe existir). |
date_of_payment |
date | Sí | Fecha del pago YYYY-MM-DD. |
payment_method_type_id |
string | Sí | Método de pago (01 efectivo, 04 transferencia...). |
payment_destination_id |
string/integer | Sí | cash o id de cuenta bancaria / billetera. |
payment |
numeric | Sí | Monto, mayor que 0. |
reference |
string | No | Número de operación, voucher, etc. |
has_card |
boolean | No | true si fue con tarjeta. |
card_brand_id |
string | No | Marca de tarjeta (01 Visa, 02 Mastercard...). |
id |
integer | No | Id de un pago existente para editarlo. Omitido = pago nuevo. |
Destino (payment_destination_id): cash = caja abierta del usuario autenticado, o el id de una cuenta bancaria / billetera. Obtén los valores válidos con Catálogos para registrar pagos de comprobantes (payment_destinations).
Reglas de caja: cuando una regla de caja impide la operación responde 422 con {success: false, message, cash_rule: true}; el message explica la causa y puede mostrarse al usuario tal cual (caja cerrada, sin caja abierta para un pago en efectivo, pago duplicado en menos de 20 segundos, etc.).
Reglas:
- Cuando el saldo del comprobante llega a 0, el crédito pendiente queda saldado en la caja abierta del usuario.
Errores:
422{success: false, message: {campo: [errores]}}si falla la validación de campos.422concash_rule: truecuando una regla de caja lo impide.
Cuerpo
Content-Type: application/json
{
"document_id": "1",
"date_of_payment": "2026-11-07",
"payment_method_type_id": "04",
"payment_destination_id": 3,
"payment": 30.0,
"reference": "OP-778812",
"has_card": false,
"card_brand_id": null,
"id": null
}
Respuestas
200 — Registrado
{
"success": true,
"message": "Pago registrado con éxito",
"id": 57
}
422 — Validación
{
"success": false,
"message": {
"payment": [
"El campo payment debe ser mayor que 0."
],
"document_id": [
"El campo document id seleccionado es inválido."
]
}
}
422 — 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.",
"cash_rule": true
}
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.