# Registro y Seguimiento de Portafolios de Préstamos Disponibilidad de la función La API de Préstamos solo está disponible para comerciantes con la función de **Cobros Gestionados** habilitada en su cuenta. Si recibes una respuesta `403 Forbidden`, contacta a tu gerente de cuenta de Belvo para habilitar Cobros Gestionados. La API de Préstamos de Belvo te permite registrar instantáneas de portafolios de préstamos para clientes con débito directo. Cada instantánea es tanto un registro del estado actual de tu préstamo **como** una instrucción de cobro — tan pronto como envíes un POST de una instantánea, Belvo intenta automáticamente un cobro por débito directo para ese cliente el mismo día (o el siguiente día hábil), de acuerdo con tu acuerdo de Cobros Gestionados. El flujo general es: 1. **POST de una instantánea de préstamo** — proporciona el estado actual del préstamo, incluyendo el `defaultDate` (la fecha en que el préstamo se volvió moroso). 2. **Belvo cobra inmediatamente** — no se requiere ninguna acción adicional de tu parte. Belvo activa el débito directo el mismo día de tu solicitud (o el siguiente día hábil). 3. **Recibe un webhook** — Belvo te notifica el resultado del cobro. 4. **POST de una nueva instantánea** — cada vez que desees que Belvo intente otro cobro, envía una nueva instantánea. ```mermaid sequenceDiagram participant App as Tu Aplicación participant Belvo as Belvo Note over App,Belvo: 1. Registra una instantánea de préstamo (primera vez para un cliente) App->>Belvo: POST /loans Note over Belvo: Crea préstamo + primera instantánea internamente Belvo-->>App: 201 Created + snapshotId Note over App,Belvo: 2. Registra una instantánea subsecuente App->>Belvo: POST /loans Note over Belvo: Añade instantánea al préstamo existente Belvo-->>App: 201 Created + snapshotId Note over App,Belvo: 3. Belvo cobra automáticamente (mismo día o siguiente día hábil) Note over Belvo: Belvo activa el cobro por débito directo Belvo-->>App: WEBHOOK resultado del cobro Note over App,Belvo: 4. Revisa el historial de préstamos App->>Belvo: GET /loans?merchant_customer_id=CUST001234 Belvo-->>App: 200 OK + lista de instantáneas ``` ## Prerrequisitos Antes de comenzar, asegúrate de: 1. Generar tus claves API. 2. Configurar un webhook para escuchar eventos. 3. Tener un cliente y un método de pago existentes creados. Consulta Pagos por Débito Directo vía API para obtener instrucciones de configuración. ## Cómo funcionan las instantáneas de préstamos Cada vez que realizas una solicitud `POST /loans`, Belvo crea una **instantánea de préstamo** — un registro del estado actual del préstamo en un momento específico. Belvo establece automáticamente la fecha de recolección (`targetCollectionDate`) al día actual o al siguiente día hábil — no puedes especificarla en la solicitud. - **Primer POST** para un par `merchantCustomerId` + `paymentMethodId`: Belvo crea un registro de préstamo principal en segundo plano y le adjunta la instantánea. No interactuarás directamente con el préstamo principal. - **POSTs subsecuentes** para el mismo par: Belvo adjunta la nueva instantánea al préstamo existente. Esto te proporciona un historial de auditoría de cada solicitud de recolección que has realizado. Una instantánea por cliente por día Cada instantánea se identifica de manera única por `merchantCustomerId` + el `targetCollectionDate` asignado automáticamente. Dado que `targetCollectionDate` siempre se establece en el día actual, solo puedes realizar un POST de una instantánea por cliente por día. Una solicitud duplicada en el mismo día devuelve un `409 Conflict`. ## Crear una instantánea de préstamo Para programar una cobranza, realiza una solicitud POST Crear una instantánea de préstamo: ```json Create a Loan Snapshot Request Body { "paymentMethodId": "43e5a5b1-b2c6-4f45-8c1f-f28fec707a4b", "merchantCustomerId": "CUST001234", "daysOverdue": 45, "totalBalance": 15000.50, "principalAmount": 12000.00, "defaultDate": "2026-03-01", "issueDate": "2026-01-15" } ``` #### Campos requeridos | Parámetro | Tipo | Requerido | Descripción | Ejemplo | | --- | --- | --- | --- | --- | | `paymentMethodId` | string (uuid) | Sí | El ID del método de pago a debitar. Debe existir y pertenecer a tu cuenta de comerciante. | `43e5a5b1-b2c6-4f45-8c1f-f28fec707a4b` | | `merchantCustomerId` | string | Sí | Tu identificador alfanumérico único para el cliente. Máximo 50 caracteres. | `CUST001234` | | `daysOverdue` | integer | Sí | El número de días que el préstamo está en mora en el momento de esta instantánea. Debe ser 0 o mayor. | `45` | | `totalBalance` | number | Sí | El saldo total pendiente en el momento de esta instantánea. Debe ser positivo y no exceder 9999999999.99. | `15000.50` | | `principalAmount` | number | Sí | El monto principal del préstamo. Debe ser positivo y no exceder 9999999999.99. | `12000.00` | | `defaultDate` | string (date) | Sí | La fecha en que el préstamo se volvió moroso, en formato `YYYY-MM-DD`. | `2026-03-01` | | `issueDate` | string (date) | Sí | La fecha en que el préstamo fue originalmente emitido, en formato `YYYY-MM-DD`. | `2026-01-15` | Para todos los parámetros opcionales, consulta la referencia de la API POST Crear una instantánea de préstamo. #### Respuesta Una solicitud exitosa devuelve una respuesta `201 Created` con el ID de la nueva instantánea creada: ```json Create a Loan Snapshot Response (201 Created) { "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d" } ``` Guarda este `id` — puedes usarlo para recuperar los detalles de la instantánea más tarde. defaultDate no se devuelve en las respuestas GET `defaultDate` se acepta en el cuerpo de la solicitud POST pero no se incluye en la respuesta de los endpoints List o Get. Esta es una limitación conocida de la API. ## Listar instantáneas de préstamos Para recuperar todas las instantáneas, realiza una solicitud de Listar todas las instantáneas de préstamos. Recomendamos filtrar por `merchant_customer_id` para limitar los resultados a un solo cliente: ``` GET /loans?merchant_customer_id=CUST001234 ``` Esto devuelve una lista plana de cada instantánea publicada para ese cliente, a través de todos sus métodos de pago, en orden cronológico inverso. ## Obtener una instantánea de préstamo Para recuperar una instantánea específica, realiza una solicitud de Obtener los detalles de una instantánea de préstamo utilizando el `id` de la instantánea que se devolvió cuando la creaste: ``` GET /loans/{id} ``` ## Webhooks de cobro Cuando Belvo intenta realizar el cobro por débito directo desencadenado por un snapshot de préstamo, recibes un webhook `payment_request_update` con el resultado. Cobro exitoso ```json Webhook Payload — Cobro Exitoso { "eventType": "payment_request_update", "eventCode": "payment_request_successful", "datetime": "2026-06-10T12:34:56.789Z", "details": { "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", "reference": "your_reference_here", "status": "successful", "amount": 15000.50, "failedReason": null, "failedMessage": null } } ``` Cobro fallido ```json Webhook Payload — Cobro Fallido { "eventType": "payment_request_update", "eventCode": "payment_request_failed", "datetime": "2026-06-10T12:34:56.789Z", "details": { "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", "reference": "your_reference_here", "status": "failed", "amount": 15000.50, "failedReason": "01", "failedMessage": "Cuenta inexistente" } } ``` El `details.id` en el payload del webhook es el ID de la solicitud de pago, no el ID del snapshot de préstamo. Para la lista completa de códigos de `failedReason`, consulta Códigos de Error Bancario. Para información general sobre la configuración de webhooks, política de reintentos y campos del payload, consulta Webhooks.