Documentación de la API de Belvo (1.222.0)
Alcanza nuevas audiencias y convierte más usuarios conectándote fácil y seguramente a sus datos financieros, entendiendo su comportamiento y habilitando pagos instantáneos con finanzas abiertas. A través de nuestra API, puedes acceder a:
Belvo es una API de banca abierta para América Latina que permite a las empresas acceder a información bancaria y fiscal de manera segura y ágil.
A través de nuestra API, puedes acceder a:
- Información Bancaria en Brasil
- Información Laboral en Brasil
- Información Laboral en México
- Información Fiscal en México
- Información Fiscal en Chile
También puedes usar nuestra API para realizar pagos en:
- Brasil
- México
Si deseas la documentación de respuesta en formato Excel o CSV, por favor descárgalos desde nuestro Repositorio Público de GitHub: Diccionarios de Datos de Belvo Open Finance.
Nuestros archivos EXCEL y CSV están adicionalmente localizados en español y portugués (Brasil).
Disponible para:
- 🟢 Agregación y Enriquecimiento
- ⚪️ Iniciación de Pagos
Usa nuestro entorno Sandbox para construir tu integración. Ofrecemos datos ficticios que imitan casos de uso del mundo real, lo que significa que puedes probar todos los endpoints, usar el widget e implementar webhooks, tal como lo harías con datos reales.
Todo lo que necesitas para comenzar con el entorno Sandbox es obtener tus claves API. Realmente recomendamos que comiences creando tu integración en este entorno.
Disponible para:
- 🟢 Agregación y Enriquecimiento
- 🟢 Iniciación de Pagos
Después de haber probado tu integración en el entorno Sandbox y estar listo para ir en vivo, necesitarás solicitar acceso a nuestro entorno de Producción. Después de solicitar acceso, nuestro equipo de ventas se pondrá en contacto contigo para programar una reunión solo para asegurarse de que se cumplan tus necesidades, y luego solo necesitarás pasar por un proceso de certificación con uno de nuestros ingenieros para asegurarte de que tu integración esté funcionando de manera óptima. Para prepararte para la reunión de certificación, solo sigue nuestra lista de verificación de integración.
Una vez que tu integración esté certificada, todo lo que necesitarás hacer es:
- Solicitar claves API de Producción (y cambiar tus claves API de Sandbox en el código por estas nuevas).
- Cambiar la URL base a la que haces solicitudes de
sandbox.belvo.comaapi.belvo.com. - Si estás usando webhooks, asegúrate de establecer una URL de Producción para tus webhooks.
Usamos el siguiente código de estado HTTP en la respuesta dependiendo del éxito o fracaso:
| Código de Estado | Descripción |
|---|---|
200 | ✅ Éxito - El contenido está disponible en el cuerpo de la respuesta. |
201 | ✅ Éxito - El contenido fue creado exitosamente en Belvo. |
204 | ✅ Éxito - No hay contenido para devolver. |
400 | ❌ Error de Solicitud Incorrecta - La solicitud devolvió un error, detalle en el contenido. |
401 | ❌ No Autorizado - Las credenciales de Belvo proporcionadas no son válidas. |
404 | ❌ No Encontrado - El recurso al que intentas acceder no se puede encontrar. |
405 | ❌ Método No Permitido - El método HTTP que estás usando no es aceptado para este recurso. |
408 | ❌ Tiempo de Solicitud Agotado - La solicitud se agotó y fue terminada por el servidor. |
428 | ❌ Se Requiere Token MFA - La institución requirió un token MFA para conectar. |
500 | ❌ Error Interno del Servidor - El detalle del error está disponible en el cuerpo de la respuesta. |
Los errores de la API de Belvo se devuelven en formato JSON. Por ejemplo, un error podría verse así:
[
{
"request_id": "a6e1c493d7a29d91aed4338e6fcf077d",
"message": "Este campo es obligatorio.",
"code": "required",
"field": "link"
}
]Típicamente, una respuesta de error tendrá los siguientes parámetros:
request_id: un ID único para la solicitud, debes compartirlo con el equipo de soporte de Belvo para investigaciones.message: descripción del error en lenguaje humano.code: un código único para el error. Consulta la tabla a continuación para ver cómo manejar cada código de error.field(opcional): El campo específico en el cuerpo de la solicitud que tiene un problema.
Cuando necesites ayuda con un error específico, incluye el identificador de solicitud (request_id) en tu mensaje al equipo de soporte de Belvo. Esto acelerará las investigaciones y te permitirá volver a funcionar en poco tiempo.
Para una lista completa de errores y cómo solucionarlos, por favor consulta nuestro artículo dedicado Manejo de Errores.
Implementa un retroceso exponencial automatizado de hasta cinco reintentos. Recomendamos usar un intervalo base de tres segundos con un factor de dos. Por ejemplo, el primer reintento debe ser después de tres segundos, el segundo reintento después de seis segundos (2 * 3), el tercer reintento después de 12 segundos (2 * 6), el cuarto reintento después de 24 segundos (2 * 12), y el quinto reintento después de 48 segundos (2 * 24).
No debes reintentar hacer solicitudes si recibes una respuesta 40x, ya que esto es un error del cliente.
La única excepción es el error de "Demasiadas Sesiones", ya que significa que tu usuario final está accediendo a la cuenta desde otro navegador al mismo tiempo. En este caso, por favor implementa la misma política de reintentos que con los errores 50x.
En nuestro esquema, puedes ver que un campo ha sido marcado como deprecated. Esto significa que este campo ya no es mantenido por el equipo de Belvo. Aún puedes recibir datos para este campo dependiendo de la institución, sin embargo, no debes confiar en este campo.
En nuestra especificación de API, verás que algunos parámetros de respuesta tendrán una anotación de required. Según la especificación de OpenAPI, cuando un parámetro de respuesta está marcado como required, esto significa que la clave de respuesta debe ser devuelta. Sin embargo, el valor de ese parámetro de respuesta puede ser null.
📘 Info
En resumen, cualquier parámetro de respuesta marcado como requerido será devuelto por nuestra API, pero el valor puede ser establecido en null.
https://developers.belvo.com/_mock/es/apis/belvoopenapispec/
https://sandbox.belvo.com/
Institutions
Una institución es una entidad de la que Belvo puede acceder a información. Puede ser una:
- institución bancaria, como Nubank Brasil.
- institución fiscal, como el Servicio de Administración Tributaria (SAT) en México.
- institución de empleo, como el Instituto Mexicano del Seguro Social (IMSS) en México o el Instituto Nacional do Seguro Social (INSS) en Brasil.
Links
Un Link es un conjunto de credenciales asociadas al acceso de un usuario final a una institución. Necesitarás registrar un Link antes de acceder a la información de ese usuario final específico, como los detalles de cuenta o transacciones.
Recomendamos usar el Belvo Hosted Widget para gestionar el proceso de conexión.
El parámetro scopes contiene una lista de permisos que te permiten crear un enlace para el usuario. Este es un parámetro obligatorio y debe enviarse exactamente como se muestra.
Indica cuánto tiempo se debe almacenar cualquier dato derivado del usuario en la base de datos de Belvo para el enlace (tanto único como recurrente). Por ejemplo, si envías 90d, Belvo eliminará cualquier dato relacionado con el usuario de su base de datos después de 90 días. Para más información, consulta la sección stale_in de nuestro artículo sobre controles de retención de datos.
📘 Info
Belvo solo eliminará datos para enlaces que no se hayan actualizado en el período que proporciones en
stale_in. Belvo solo eliminará datos para enlaces que no se hayan actualizado en el período que proporciones enstale_in.
Por defecto, Belvo almacena los datos del usuario durante 365 días, a menos que el enlace sea eliminado.
Una matriz de recursos para los que le gustaría recibir una actualización histórica.
Para las instituciones bancarias, puede seleccionar los siguientes recursos:
ACCOUNTSOWNERSTRANSACTIONSBILLS(solo para instituciones de Brasil OFDA)INCOMESRECURRING_EXPENSESRISK_INSIGHTS
El objeto widget contiene información adicional sobre cómo configurar el widget, incluyendo la personalización de la marca, tus términos y condiciones, URLs de callback, e información sobre el usuario para el que deseas extraer datos.
En el parámetro purpose, puedes personalizar el mensaje que se muestra a tu usuario sobre para qué caso de uso estás solicitando sus datos. Para más información, consulta la sección de purpose en nuestra guía del Hosted Widget (OFDA).
El parámetro openfinance_feature indica que el usuario final pasará por el flujo OFDA. Debe establecerse en consent_link_creation.
En el objeto callback_urls, debes agregar enlaces a donde tu usuario debe ser redirigido en los siguientes casos:
- success (tu usuario conectó sus cuentas exitosamente)
- exit (tu usuario salió del widget antes de completar el proceso)
- event (ocurrió un error durante el proceso de conexión)
Para más información, consulta la sección de callback_urls en nuestra guía del Widget Alojado (OFDA).
📘 Eventos de Callback
Belvo también enviará información adicional sobre el evento dependiendo del mismo. Para más información, asegúrate de consultar la sección de Manejo de eventos de callback de la guía del Widget Alojado (OFDA).
La URL a la que se redirige a su usuario cuando conecta exitosamente su cuenta.
La URL a la que se redirige a tu usuario cuando salen del proceso antes de conectar su cuenta.
En el objeto branding, debes agregar tu:
También puedes opcionalmente agregar un color de fondo personalizado para cuando el widget se abra, así como desactivar los mensajes de Belvo sobre cuántas cuentas se han conectado.
Para más información sobre las opciones de personalización y branding del widget, consulta nuestra guía dedicada.
Puede agregar el ícono de su empresa al widget para que esté más alineado con su marca. Para obtener más información, consulte la sección company_icon de nuestra guía de Branding y personalización (OFDA).
Puede agregar el logotipo de su empresa al widget para que esté más alineado con su marca. Para obtener más información, consulte la sección company_icon de nuestra guía de Branding y personalización (OFDA).
Puede agregar el nombre de su empresa para que se muestre cuando el widget se inicie por primera vez. De forma predeterminada, solo mostrará "Link your account". Cuando agregue el nombre de su empresa, el mensaje seguirá el formato "[company_name] uses Belvo to connect your account". Para obtener más información, consulte la sección company_name de nuestra guía de Branding y personalización (OFDA).
Puede agregar un enlace a su política de privacidad (o términos y condiciones) en la pantalla inicial del widget que, al hacer clic, redirigirá a sus usuarios a la página web vinculada. Esto ayuda a sus usuarios a comprender mejor cuál es su caso de uso con respecto a los datos que está solicitando. Para obtener más información, consulte la sección company_terms_url de nuestra guía de Branding y personalización (OFDA).
Puede agregar un color de superposición personalizado para cuando el widget se carga en su aplicación de escritorio. Para obtener más información, consulte la sección overlay_background_color de nuestra guía de Branding y personalización (OFDA).
Puede optar por ocultar el mensaje "Mais de 5 milhões de usuários já conectaram com segurança suas contas." que aparece cuando su usuario selecciona su institución en el widget. Para obtener más información, consulte la sección social_proof de nuestra guía de Branding y personalización (OFDA).
Puede agregar opcionalmente los colores de su marca al widget utilizando el parámetro theme.
Para obtener más información sobre dónde aparecerán estos colores en el widget, consulte la sección dedicada Agregar colores personalizados al widget de nuestra guía de Branding.
El objeto consent es exclusivo del widget OFDA y debe ser enviado.
En el parámetro terms_and_conditions_url, debe proporcionar un enlace a los términos y condiciones de su empresa.
El parámetro permissions contiene los recursos que deseas extraer de la Red de Finanzas Abiertas de Brasil para el usuario. Este valor debe establecerse en ["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"].
En el array identification_info, necesitas proporcionar la información de identificación del usuario para el cual deseas recuperar información. La información que proporciones aquí debe coincidir con la información que la institución regulada tiene para el usuario (por ejemplo, para empresas, el CPF y el nombre deben ser de un usuario con acceso a la cuenta empresarial).
- Para individuos, solo necesitas proporcionar el CPF y el nombre.
- Para empresas, necesitas proporcionar tanto la información del CPF como del CNPJ.
Para más información, consulta la sección identification_info de nuestra guía del Hosted Widget (OFDA).
El número de CPF o CNPJ de la persona o empresa asociada con la identificación.
- Mock server
https://developers.belvo.com/_mock/es/apis/belvoopenapispec/api/token/
- Sandbox
https://sandbox.belvo.com/api/token/
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
https://developers.belvo.com/_mock/es/apis/belvoopenapispec/api/token/ \
-H 'Content-Type: application/json' \
-d '{
"id": "string",
"password": "string",
"scopes": "read_institutions,write_links,read_consents,write_consents,write_consent_callback,delete_consents",
"stale_in": "42d",
"fetch_resources": [
"ACCOUNTS",
"TRANSACTIONS",
"OWNERS",
"BILLS"
],
"widget": {
"purpose": "Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito.",
"openfinance_feature": "consent_link_creation",
"callback_urls": {
"success": "your_deeplink_here://success",
"exit": "your_deeplink_here://exit",
"event": "your_deeplink_here://error"
},
"branding": {
"company_icon": "https://mysite.com/icon.svg",
"company_logo": "https://mysite.com/logo.svg",
"company_name": "ACME",
"company_terms_url": "https://belvo.com/terms-service/",
"overlay_background_color": "#F0F2F4",
"social_proof": true
},
"theme": [
{
"css_key": "--color-primary-base",
"value": "#907AD6"
}
],
"consent": {
"terms_and_conditions_url": "https://www.your_terms_and_conditions.com",
"permissions": [
"REGISTER",
"ACCOUNTS",
"CREDIT_CARDS",
"CREDIT_OPERATIONS"
],
"identification_info": [
{
"type": "CPF",
"number": 76109277673,
"name": "Ralph Bragg"
}
]
}
}
}'Operación exitosa
El token de acceso que se utilizará para autenticar el widget.
El token de actualización que se utilizará para autenticar el widget.
{ "access": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzI3MzYwMTk1LCJpYXQiOjE3MjczNTg5OTUsImp0aSI6ImRhN2Q3OTM1ZDZlZTQ0MTBhYTMwYTc3NWQ1OWMxZWIzIiwidXNlcl9pZCI6IjZlOWJlODg0LTQ3ODEtNDE0My1iNjczLWFjYTAyNDc1ZWU4YyIsIm9yZ2FuaXphdGlvbl9uYW1lIjoiRG9taW5payBDaG9sZXdza2kncyB0ZWFtIiwib3JnYW5pemF0aW9uX2lkIjoiNmU5YmU4ODQtNDc4MS00MTQzLWI2NzMtYWNhMDI0NzVlZThjIiwic2NvcGVzIjpbInJlYWRfaW5zdGl0dXRpb25zIiwid3JpdGVfbGlua3MiXSwiZW52aXJvbm1lbnQiOiJzYW5kYm94IiwiYXBpX3VybCI6InNhbmRib3guYmVsdm8uY29tIiwiY3JlZGVudGlhbHNfc3RvcmFnZSI6IjMwZCIsInN0YWxlX2luIjoiMzY1ZCIsImZldGNoX3Jlc291cmNlcyI6WyJPV05FUlMiLCJFTVBMT1lNRU5UUyJdLCJpc3MiOiJzYW5kYm94LmJlbHZvLmNvbSJ9.DaQ8xVTEjA4BD-0SbBCQDylO3NrjhsHiWXTaoPdKWRucS2E0jxNUHC5lwrejrz73-GytgcXTeiI1fhZBYW719A", "refresh": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjM0OTQzODk5NSwiaWF0IjoxNzI3MzU4OTk1LCJqdGkiOiI2YmUyMGFmNTcxZDU0NjQzYjA0Y2U3YTVhNjI5ZDRiMSIsInVzZXJfaWQiOiI2ZTliZTg4NC00NzgxLTQxNDMtYjY3My1hY2EwMjQ3NWVlOGMiLCJvcmdhbml6YXRpb25fbmFtZSI6IkRvbWluaWsgQ2hvbGV3c2tpJ3MgdGVhbSIsIm9yZ2FuaXphdGlvbl9pZCI6IjZlOWJlODg0LTQ3ODEtNDE0My1iNjczLWFjYTAyNDc1ZWU4YyIsInNjb3BlcyI6WyJyZWFkX2luc3RpdHV0aW9ucyIsIndyaXRlX2xpbmtzIl0sImVudmlyb25tZW50Ijoic2FuZGJveCIsImFwaV91cmwiOiJzYW5kYm94LmJlbHZvLmNvbSIsImNyZWRlbnRpYWxzX3N0b3JhZ2UiOiIzMGQiLCJzdGFsZV9pbiI6IjM2NWQiLCJmZXRjaF9yZXNvdXJjZXMiOlsiT1dORVJTIiwiRU1QTE9ZTUVOVFMiXSwiaXNzIjoic2FuZGJveC5iZWx2by5jb20ifQ.T-tnX2BwAjQI0MaYCO686bZD6H7EMIgi_CbOWtHDexGIiTKLer0d7RJGisXJqM6oA_L4y_A_774LEj8NNb7YXQ" }
Owners
Un owner representa a la persona que tiene acceso a un Link y es el propietario de todas las cuentas dentro del Link.
Puedes usar este endpoint para obtener información útil sobre tu cliente, como:
- su nombre completo
- información de contacto clave
- información sobre el documento de identificación que usaron al abrir la cuenta
Accounts
Una cuenta es la representación de una cuenta bancaria dentro de una institución financiera. Un usuario puede tener una o más cuentas en una institución.
Por ejemplo, un usuario (o enlace) puede tener una cuenta corriente, varias tarjetas de crédito y una cuenta de préstamo.
Consultar la información de la cuenta de un usuario es útil ya que puedes obtener información sobre:
- qué tipos de cuentas tiene el usuario.
- el saldo de cada cuenta (ahorros, cuenta corriente, tarjeta de crédito, préstamo, etc.).
- información detallada sobre sus gastos con tarjeta de crédito.
- la situación actual de cualquier préstamo que puedan tener.
Employments Brazil
Nuestro recurso de empleos para Brasil te permite obtener una vista completa del historial laboral actual de tu usuario y la información salarial.
Para cada usuario, proporcionamos:
- historial laboral (incluyendo ocupaciones y datos del empleador)
- información salarial histórica y actual (por empleador)
En este momento, el recurso de empleos está disponible para:
- 🇧🇷 Brasil (INSS)
Employment Records Mexico
Nuestro recurso de registros de empleo para México te permite obtener una visión completa de las contribuciones actuales al seguro social y el historial laboral de tu usuario.
Con el recurso de registros de empleo de Belvo para México, puedes acceder a información sobre las contribuciones actuales al seguro social y el historial laboral de tu usuario. Para cada usuario, proporcionamos:
- datos personales
- historial laboral
- salario base diario histórico y actual
- ¡y más!
En este momento, el recurso de registros de empleo está disponible para:
- 🇲🇽 México (IMSS)
- 🇲🇽 México (ISSSTE)
Current Employments Mexico
El recurso de Empleos Actuales proporciona acceso en tiempo real al estado de empleo actual de individuos en México. Este recurso ofrece información detallada sobre si una persona está actualmente empleada o desempleada, junto con sus registros de empleo activos.
Incomes
Utiliza el endpoint de Incomes para obtener información sobre las fuentes de ingresos de una cuenta en los últimos 365 días. Este endpoint es particularmente útil cuando deseas verificar los ingresos de una persona.
📘 Información
El recurso de incomes está solo disponible para cuentas de Checking y Savings asociadas con enlaces bancarios.
Recurring Expenses
La API de Gastos Recurrentes de Belvo te permite identificar los pagos regulares de un usuario para servicios de suscripción, como Netflix o membresías de gimnasio, así como pagos de servicios públicos, como facturas de electricidad o teléfono. Devolvemos información de hasta 365 días.
📘 Info
El recurso de gastos recurrentes está solo disponible para cuentas de Cheques, Ahorros y Tarjetas de Crédito asociadas con enlaces bancarios.
Customers (Brazil)
Un cliente es el pagador que va a transferir fondos a tu cuenta bancaria. Necesitas crear un cliente para recibir pagos entrantes en la cuenta bancaria de tu organización.
Este endpoint admite versionado a nivel de recurso. Al incluir el encabezado X-Belvo-API-Resource-Version: Payments-BR.V2, puedes acceder a los formatos de solicitud y respuesta más recientes (V2). Si no se proporciona el encabezado, se utilizará el formato predeterminado (V1). Consulta la documentación de la API para obtener detalles sobre las diferencias entre versiones.
Bank Accounts (Brazil)
Para recibir pagos entrantes en la cuenta bancaria de su organización, debe registrar las cuentas bancarias (individuales y comerciales) utilizando la API de Pagos de Belvo.
- Las cuentas bancarias individuales deben ser creadas para cada pagador (su cliente).
- Las cuentas bancarias comerciales deben ser creadas para el beneficiario del pago (su organización).
Este endpoint admite el versionado a nivel de recurso. Al incluir el encabezado X-Belvo-API-Resource-Version: Payments-BR.V2, puede acceder a los formatos de solicitud y respuesta más recientes (V2). Si no se proporciona el encabezado, se utilizará el formato predeterminado (V1). Consulte la documentación de la API para obtener detalles sobre las diferencias entre versiones.
Payment Intents (Brazil)
Un payment intent es un punto único de acceso para crear pagos utilizando cualquier método de pago ofrecido por Belvo.
Un payment intent captura toda la información del pago (como el monto a cobrar, la descripción del pago, el proveedor, etc.) y guía a tus clientes a través del flujo de pago.
Nota: Para las instituciones que requieren el
username_typeen el arrayform_fields, debes enviar este valor en tu solicitud PATCH.