# Registrar e Acompanhar Portfólios de Empréstimos Disponibilidade do recurso A Loans API está disponível apenas para comerciantes com o recurso **Managed Collections** habilitado em sua conta. Se você receber uma resposta `403 Forbidden`, entre em contato com o gerente de conta da Belvo para habilitar o Managed Collections. A Loans API da Belvo permite que você registre instantâneos de portfólios de empréstimos para clientes de débito direto. Cada instantâneo é tanto um registro do estado atual do seu empréstimo **quanto** uma instrução de cobrança — assim que você faz um POST de um instantâneo, a Belvo automaticamente tenta uma cobrança por débito direto para aquele cliente no mesmo dia (ou no próximo dia útil), de acordo com o seu arranjo de Managed Collections. O fluxo geral é: 1. **POST de um instantâneo de empréstimo** — forneça o estado atual do empréstimo, incluindo o `defaultDate` (a data em que o empréstimo se tornou inadimplente). 2. **Belvo coleta imediatamente** — nenhuma ação adicional é necessária de sua parte. A Belvo aciona o débito direto no mesmo dia do seu pedido (ou no próximo dia útil). 3. **Receba um webhook** — a Belvo notifica você sobre o resultado da cobrança. 4. **POST de um novo instantâneo** — cada vez que você quiser que a Belvo tente outra cobrança, envie um novo instantâneo. ```mermaid sequenceDiagram participant App as Sua Aplicação participant Belvo as Belvo Note over App,Belvo: 1. Registrar um instantâneo de empréstimo (primeira vez para um cliente) App->>Belvo: POST /loans Note over Belvo: Cria empréstimo + primeiro instantâneo internamente Belvo-->>App: 201 Created + snapshotId Note over App,Belvo: 2. Registrar um instantâneo subsequente App->>Belvo: POST /loans Note over Belvo: Adiciona instantâneo ao empréstimo existente Belvo-->>App: 201 Created + snapshotId Note over App,Belvo: 3. Belvo coleta automaticamente (mesmo dia ou próximo dia útil) Note over Belvo: Belvo aciona cobrança por débito direto Belvo-->>App: WEBHOOK resultado da cobrança Note over App,Belvo: 4. Revisar histórico de empréstimos App->>Belvo: GET /loans?merchant_customer_id=CUST001234 Belvo-->>App: 200 OK + lista de instantâneos ``` ## Pré-requisitos Antes de começar, certifique-se de: 1. Gerar suas chaves de API. 2. Configurar um webhook para escutar eventos. 3. Ter um cliente existente e método de pagamento criado. Veja Pagamentos por Débito Direto via API para instruções de configuração. ## Como funcionam os snapshots de empréstimo Cada vez que você faz uma solicitação `POST /loans`, a Belvo cria um **snapshot de empréstimo** — um registro do estado atual do empréstimo em um determinado momento. A Belvo define automaticamente a data de coleta (`targetCollectionDate`) para o dia atual ou o próximo dia útil — você não pode especificá-la na solicitação. - **Primeiro POST** para um par `merchantCustomerId` + `paymentMethodId`: a Belvo cria um registro de empréstimo pai em segundo plano e anexa o snapshot a ele. Você não interagirá diretamente com o empréstimo pai. - **POSTs subsequentes** para o mesmo par: a Belvo anexa o novo snapshot ao empréstimo existente. Isso fornece um histórico de auditoria de cada solicitação de coleta que você fez. Um snapshot por cliente por dia Cada snapshot é identificado de forma única por `merchantCustomerId` + o `targetCollectionDate` atribuído automaticamente. Como `targetCollectionDate` é sempre definido para o dia atual, você só pode fazer um POST de um snapshot por cliente por dia. Uma solicitação duplicada no mesmo dia retorna um `409 Conflict`. ## Criar um instantâneo de empréstimo Para agendar uma cobrança, faça uma solicitação POST Criar um instantâneo de empréstimo: ```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 obrigatórios | Parâmetro | Tipo | Obrigatório | Descrição | Exemplo | | --- | --- | --- | --- | --- | | `paymentMethodId` | string (uuid) | Sim | O ID do método de pagamento a ser debitado. Deve existir e pertencer à sua conta de comerciante. | `43e5a5b1-b2c6-4f45-8c1f-f28fec707a4b` | | `merchantCustomerId` | string | Sim | Seu identificador alfanumérico único para o cliente. Máximo de 50 caracteres. | `CUST001234` | | `daysOverdue` | integer | Sim | O número de dias que o empréstimo está em atraso no momento deste instantâneo. Deve ser 0 ou maior. | `45` | | `totalBalance` | number | Sim | O saldo total pendente no momento deste instantâneo. Deve ser positivo e não exceder 9999999999.99. | `15000.50` | | `principalAmount` | number | Sim | O valor principal do empréstimo. Deve ser positivo e não exceder 9999999999.99. | `12000.00` | | `defaultDate` | string (date) | Sim | A data em que o empréstimo se tornou inadimplente, no formato `YYYY-MM-DD`. | `2026-03-01` | | `issueDate` | string (date) | Sim | A data em que o empréstimo foi originalmente emitido, no formato `YYYY-MM-DD`. | `2026-01-15` | Para todos os parâmetros opcionais, consulte a referência da API POST Create a loan snapshot. #### Resposta Uma solicitação bem-sucedida retorna uma resposta `201 Created` com o ID do snapshot recém-criado: ```json Create a Loan Snapshot Response (201 Created) { "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d" } ``` Salve este `id` — você pode usá-lo para recuperar os detalhes do snapshot mais tarde. defaultDate não é retornado nas respostas GET `defaultDate` é aceito no corpo da solicitação POST, mas não é incluído na resposta dos endpoints List ou Get. Esta é uma limitação conhecida da API. ## Listar instantâneos de empréstimos Para recuperar todos os instantâneos, faça uma solicitação de Listar todos os instantâneos de empréstimos. Recomendamos filtrar por `merchant_customer_id` para limitar os resultados a um único cliente: ``` GET /loans?merchant_customer_id=CUST001234 ``` Isso retorna uma lista plana de todos os instantâneos postados para esse cliente, em todos os seus métodos de pagamento, em ordem cronológica inversa. ## Obter um instantâneo de empréstimo Para recuperar um instantâneo específico, faça uma solicitação de Obter detalhes de um instantâneo de empréstimo usando o `id` do instantâneo retornado quando você o criou: ``` GET /loans/{id} ``` ## Webhooks de cobrança Quando a Belvo tenta a cobrança por débito direto acionada por um snapshot de empréstimo, você recebe um webhook `payment_request_update` com o resultado. Cobrança bem-sucedida ```json Webhook Payload — Cobrança Bem-sucedida { "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 } } ``` Cobrança falhada ```json Webhook Payload — Cobrança Falhada { "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" } } ``` O `details.id` no payload do webhook é o ID da solicitação de pagamento, não o ID do snapshot de empréstimo. Para a lista completa de códigos `failedReason`, veja Códigos de Erro Bancário. Para informações gerais sobre configuração de webhooks, política de tentativas e campos de payload, veja Webhooks.