Saltar al contenido
Facturador

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.
  • 422 con cash_rule: true cuando 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.