Saltar al contenido
Facturador

Registrar pago de nota de venta

POST /api/sale-notes/{sale_note_id}/payments

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

Registra un pago (total o parcial). El dinero entra/sale del destino indicado (caja o cuenta) y queda en el libro de caja y bancos.

Quién puede usarlo: cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde 403.

Campo Tipo Obligatorio Descripción / valores permitidos
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 Referencia: 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...

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

Responde 409 cuando una regla de caja lo impide, por ejemplo:

  • destino cash y el usuario no tiene una caja abierta;
  • el método de pago no está habilitado para ese tipo de operación o destino;
  • el pago pertenece a una caja ya cerrada (al eliminar);
  • el mismo pago (mismo monto y método) se registró hace menos de 20 segundos (protección contra doble envío);
  • el registro está anulado.

El mensaje (message) explica la causa y puede mostrarse al usuario tal cual.

Otros errores: 422 si falta un campo o payment ≤ 0; 404 si el registro no existe; 403 si es de otro vendedor.

La respuesta trae el pago creado (data.payment) y el resumen actualizado (data.summary). summary trae total (total del registro), total_paid (suma de pagos) y total_difference (saldo pendiente).

Parámetros

Parámetro Dónde Obligatorio Ejemplo Descripción
sale_note_id ruta sí 1

Cuerpo

Content-Type: application/json

{
  "date_of_payment": "2026-11-07",
  "payment_method_type_id": "04",
  "payment_destination_id": 3,
  "payment": 20.0,
  "reference": "OP-458721",
  "has_card": false,
  "card_brand_id": null
}

Respuestas

201 — Pago registrado

{
  "success": true,
  "data": {
    "payment": {
      "id": 31,
      "date_of_payment": "2026-11-07",
      "payment_method_type_id": "04",
      "payment_method_type_description": "Transferencia",
      "destination_type": "BankAccount",
      "destination_id": 3,
      "destination_description": "BCP SOLES",
      "reference": "OP-458721",
      "payment": 20.0
    },
    "summary": {
      "total": 50.0,
      "total_paid": 20.0,
      "total_difference": 30.0
    }
  },
  "message": "Pago registrado con éxito"
}

422 — Monto inválido

{
  "success": false,
  "message": {
    "payment": [
      "El campo payment debe ser mayor que 0."
    ]
  }
}

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

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.