# Colecciones Inteligentes

Beta
Smart Collections está actualmente en Beta. Algunos contratos en esta página aún están siendo confirmados con nuestro equipo de ingeniería, por lo que deben considerarse provisionales y se esperan refinamientos antes de la disponibilidad general, incluyendo:

- Cargas útiles de webhook y códigos de eventos
- Actualizaciones de referencia de la API para los endpoints de Collection Instructions, Payment Authorization y Charge
- Nombres de campos y mejoras en la documentación (terminología, diagramas)


Contacta a tu gerente de cuenta de Belvo para unirte al programa Beta.

Con las Colecciones Inteligentes de Belvo, puedes delegar el monitoreo de saldo a Belvo y activar un Cobro Pix cuando la cuenta de tu usuario tenga fondos suficientes. En lugar de verificar el saldo de tu usuario por ti mismo, le indicas a Belvo los montos que deseas recolectar, así como las condiciones de saldo a esperar, y Belvo supervisa la cuenta en segundo plano, notificándote cuando es el momento de recolectar.

Divulgación Regulatoria
De acuerdo con la **Resolução Conjunta nº 17** de BACEN, Belvo opera como un **Iniciador de Transacción de Pago (ITP)** regulado. Para asegurar el cumplimiento con los requisitos de transparencia y marca:

- **Responsabilidad de Belvo:** Belvo garantiza que todos los elementos y divulgaciones dentro del **Belvo Widget** cumplan completamente con las regulaciones de BACEN y comunica cualquier cambio requerido a los socios.
- **Responsabilidad del Socio:** Los socios deben declarar claramente en su UI/servicio que su empresa no es la entidad de pago regulada e identificar a **Belvo** como el proveedor responsable de la iniciación del pago.


## Cómo funciona

Smart Collections combina dos productos de Belvo a lo largo de dos fases. El diagrama a continuación muestra los tres pasos principales de una integración completa.


```mermaid
sequenceDiagram
    participant Client as Your application
    participant Aggregation as Belvo Aggregation API
    participant Payments as Belvo Payments API

    rect rgba(0, 100, 255, .05)
        Note over Client, Payments: 1. Collection Instruction setup

        Client->>Aggregation: POST /api/collection-instructions/
        Aggregation-->>Client: 201 Created

        loop Background balance monitoring
            Note right of Aggregation: Belvo checks the linked account balance. Once your criteria are met, you'll receive a webhook you can act on. See step 3.
        end
    end

    rect rgba(0, 200, 100, .05)
        Note over Client, Payments: 2. Payment Authorization setup

        Client->>Payments: POST /payments/br/payment-authorizations/
        Payments-->>Client: 201 Created (authorization_url)

        Note right of Payments: User approves the authorization at their bank

        Payments->>Client: Webhook: PAYMENT_AUTHORIZATION
        Client->>Payments: GET /payments/br/payment-authorizations/{id}/
        Payments-->>Client: 200 OK (status: AUTHORIZED)
    end

    rect rgba(255, 150, 0, .05)
        Note over Client, Payments: 3. Charge creation

        Aggregation->>Client: Webhook: item_ready_to_charge
        Note over Client, Payments: Also requires an AUTHORIZED Payment Authorization from step 2

        Client->>Payments: POST /payments/br/payment-authorizations/{id}/charges/
        Payments-->>Client: 201 Created

        Payments->>Client: Webhook: CHARGE
        Client->>Payments: GET /payments/br/payment-authorizations/{id}/charges/{charge_id}/
        Payments-->>Client: 200 OK
    end
```

**Paso 1: Configuración de la Instrucción de Cobro.** Creas una Instrucción de Cobro describiendo el monto que deseas cobrar y las condiciones de saldo a esperar. Belvo luego monitorea la cuenta vinculada en segundo plano, para que no tengas que hacer consultas tú mismo. Una vez que el saldo cumple con tus criterios, Belvo envía un webhook `item_ready_to_charge`, que es lo que desencadena el paso 3. Fase 1: Verificación de Saldo cubre el Paso 1.

**Paso 2: Configuración de la Autorización de Pago.** Independientemente del paso 1, y en cualquier momento antes de que necesites cobrar, creas una Autorización de Pago de Smart Transfers para el pagador. Smart Transfers mueve fondos entre cuentas mantenidas por la misma persona o empresa, por lo que la cuenta que recibe los fondos debe ser mantenida por el pagador. Belvo te notifica cuando su estado cambia con un webhook, pero como estos son webhooks de Payments-BR.V2, la notificación en sí no lleva el estado. Obtienes la autorización con una solicitud `GET` para confirmar que está `AUTHORIZED` y lista para usar.

**Paso 3: Creación del Cobro.** Cuando cobras a través de una Instrucción de Cobro, esperas hasta haber recibido `item_ready_to_charge` y confirmado que la autorización está `AUTHORIZED`, y luego desencadenas un Cobro. (Un Cobro único sin una Instrucción de Cobro solo necesita la autorización `AUTHORIZED`, ver abajo.) Belvo procesa el pago Pix y envía otro webhook cuando el estado del Cobro cambia. Al igual que con la autorización, obtienes el Cobro con una solicitud `GET` para ver si tuvo éxito o falló. Fase 2: Creación de Pagos cubre los Pasos 2 y 3.

Las dos fases son independientes
La Fase 1 y la Fase 2 están débilmente acopladas. Belvo no las vincula entre sí, por lo que almacena los IDs de tus ítems, autorizaciones y Cobros juntos para correlacionarlos en tu propio sistema.

De hecho, la Fase 1 es opcional. Con una Autorización de Pago `AUTHORIZED` puedes desencadenar un Cobro directamente, una colección única, sin crear una Instrucción de Cobro en absoluto.

## Opciones de integración

Configurar Smart Collections combina dos rutas de integración. Usa el OFDA Widget para incorporar usuarios y crear un Link para el monitoreo de saldo, y la Payments API (Direct API (Smart Transfers)) para crear Autorizaciones de Pago y Cargos.

Para gestionar las Instrucciones de Cobro, consulta Fase 1: Verificación de Saldo y la referencia de la API de Instrucciones de Cobro.