Saltar al contenido
Facturador

Reclamar pago recibido y asignarlo a un comprobante

POST /api/received-payments/{received_payment_id}/claim

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

Asigna un pago pendiente a un comprobante: registra el pago del comprobante con el monto y la fecha del pago recibido y el método/destino que envías, y el pago pasa a matched. Es atómico: si dos usuarios lo reclaman a la vez, solo uno lo consigue.

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.

Parámetros de la URL:

Campo Tipo Obligatorio Descripción / valores permitidos
id integer Sí Id del pago recibido.

Cuerpo (JSON):

Campo Tipo Obligatorio Descripción / valores permitidos
document_id integer Sí Id del comprobante a pagar (debe existir).
payment_method_type_id string Sí Método de pago existente (p. ej. el de Yape o Plin de la empresa).
payment_destination_id string/integer Sí cash o id de cuenta bancaria / billetera.

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

Errores:

  • 409 si el pago ya fue reclamado o descartado.
  • 422 {success: false, message: {campo: [errores]}} si falla la validación de campos.
  • 422 con cash_rule: true si una regla de caja lo impide.
  • 500 si el id no existe (el mensaje técnico no es apto para mostrar al usuario: valida el id antes).

Parámetros

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

Cuerpo

Content-Type: application/json

{
  "document_id": "1",
  "payment_method_type_id": "12",
  "payment_destination_id": 3
}

Respuestas

200 — Reclamado

{
  "success": true,
  "message": "Pago reclamado y asignado al comprobante con exito",
  "data": {
    "id": 12,
    "provider": "YAPE",
    "amount": 25.5,
    "sender_name": "MARIA LOPEZ",
    "raw_text": "Yape! MARIA LOPEZ te envió un pago por S/ 25.50",
    "package_name": "com.bcp.innovacxion.yapeapp",
    "posted_at": "2026-11-07 13:42:05",
    "device_id": "caja-1-android",
    "dedup_hash": "a3f1c9e2b7d4...",
    "status": "matched",
    "matched_document_id": 1520,
    "matched_document_payment_id": 58,
    "claimed_by_user_id": 5,
    "created_at": "2026-11-07 13:42:06"
  }
}

409 — Ya procesado

{
  "success": false,
  "message": "El pago ya fue procesado por otro dispositivo."
}

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.