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.
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.
Omite ciertos campos para que no se devuelvan en la respuesta. Para más información, consulta nuestro artículo del DevPortal Filtrando respuestas.
Devuelve solo los campos especificados en la respuesta. Para obtener más información, consulta nuestro artículo del DevPortal Filtrando respuestas.
- Mock server
https://developers.belvo.com/_mock/es/apis/belvoopenapispec/api/accounts/{id}/
- Sandbox
https://sandbox.belvo.com/api/accounts/{id}/
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
'https://developers.belvo.com/_mock/es/apis/belvoopenapispec/api/accounts/{id}/?omit=string&fields=string'De acuerdo
Identificador único de Belvo para el elemento actual.
El link.id al que pertenecen los datos.
Detalles sobre la institución.
La marca de tiempo ISO-8601 cuando se recopiló el punto de datos.
La marca de tiempo ISO-8601 de cuando se creó el punto de datos en la base de datos de Belvo.
La marca de tiempo ISO-8601 del acceso más reciente y exitoso de Belvo a la institución para el enlace dado.
El tipo de cuenta.
Devolvemos uno de los siguientes valores de enum:
ADVANCE_DEPOSIT_ACCOUNTCHECKING_ACCOUNTCREDIT_CARDFINANCING_ACCOUNTINVESTMENT_ACCOUNTINVOICE_FINANCING_ACCOUNTLOAN_ACCOUNTPENSION_FUND_ACCOUNTSAVINGS_ACCOUNTUNCATEGORIZED
Indica si esta cuenta es un ASSET o un LIABILITY. Puedes considerar el saldo de un ASSET como positivo, mientras que el saldo de un LIABILITY como negativo.
El tipo de cuenta, según lo designado por la institución.
No anulable: La red de finanzas abiertas de Brasil debe devolver un valor.
El subtipo de cuenta, según lo designado por la institución.
No anulable: La red de finanzas abiertas de Brasil debe devolver un valor.
El nombre de la cuenta, tal como lo proporciona la institución.
El número de cuenta, tal como lo designa la institución.
El código de sucursal donde se abrió el producto.
El dígito de control del número del producto, si corresponde.
Detalles sobre los saldos actual y disponible de la cuenta.
El saldo actual se calcula de manera diferente según el tipo de cuenta.
- 💰 Cuentas corrientes y de ahorro:
El saldo de la cuenta del usuario en el momento del timestamp collected_at.
- 💳 Tarjetas de crédito:
La cantidad que el usuario ha gastado en el período de facturación actual de la tarjeta (consulte credit_data.cutting_date para obtener información sobre cuándo finaliza el período de facturación actual).
- 🏡 Cuentas de préstamo:
La cantidad restante por pagar en el préstamo del usuario.
El saldo que el titular de la cuenta puede utilizar.
- 💰 Cuentas corrientes y de ahorro:
El saldo disponible puede ser diferente al saldo current debido a transacciones pendientes.
- 💳 Tarjetas de crédito:
El monto de crédito que el usuario aún tiene disponible para el período actual. El monto se calcula como credit_data.credit_limit menos balance.current.
- 🏡 Cuentas de préstamo:
El valor presente requerido para liquidar el préstamo, según lo proporcionado por la institución.
Nota: Si la institución no proporciona este valor, devolvemos null.
La cantidad que está actualmente bloqueada debido a transacciones pendientes.
No anulable: Se debe devolver un valor por la red de finanzas abiertas de Brasil si el campo
balancesestá disponible.
El código de moneda de tres letras (ISO-4217).
No anulable: Se debe devolver un valor por la red de finanzas abiertas de Brasil si el campo
balancesestá disponible.
El nombre público para el tipo de identificación. Para cuentas de ahorro y corrientes en 🇧🇷 Brasil, este campo será AGENCY/ACCOUNT.
El valor para el public_identification_name.
Para cuentas de ahorro y corriente OFDA brasileñas 🇧🇷, este campo será el número de agencia y cuenta bancaria, separados por una barra. Por ejemplo: 0444/45722-0.
Para cuentas de tarjeta de crédito OFDA brasileñas 🇧🇷, devolveremos una cadena de números de tarjeta de crédito concatenados asociados con la cuenta. Por ejemplo: "8763,9076,5522"
La identificación interna de la institución para la cuenta.
No anulable: Se debe devolver un valor por la red de finanzas abiertas de Brasil si el campo
balancesestá disponible.
Detalles sobre las tarjetas de crédito asociadas con esta cuenta.
La marca de tiempo ISO-8601 cuando se recopiló el punto de datos.
El límite de crédito superior de la tarjeta.
No anulable: La red de finanzas abiertas de Brasil debe devolver un valor.
La fecha de vencimiento de la factura de la tarjeta de crédito.
La cantidad mínima que el titular de la cuenta necesita pagar en el período de crédito actual.
La red de crédito con la que está asociada la tarjeta. Devolvemos uno de los siguientes valores:
VISAMASTERCARDAMERICAN_EXPRESSDINERS_CLUBHIPERCARDBANDEIRA_PROPRIACHEQUE_ELETRONICOELOOTHER
No anulable: La red de finanzas abiertas de Brasil debe devolver un valor.
Información adicional sobre la red de tarjetas de crédito.
Nota: Este campo no es aplicable para OF Brazil y devolverá null.
Nota: Este campo no es aplicable para OF Brazil y devolverá null.
Nota: Este campo no es aplicable para OF Brazil y devolverá null.
Nota: Este campo no es aplicable para OF Brazil y devolverá null.
Las opciones de préstamo asociadas con esta cuenta.
La marca de tiempo ISO-8601 cuando se recopiló el punto de datos.
El número de contrato estandarizado específico del país.
No anulable: La red de finanzas abiertas de Brasil debe devolver un valor.
El monto total inicial del préstamo cuando se firmó el contrato, calculado por la institución. Este monto incluye el principal + intereses + impuestos + tarifas.
El costo total efectivo inicial del préstamo.
El tipo de préstamo, según la institución.
No anulable: La red de finanzas abiertas de Brasil debe devolver un valor.
El monto restante a pagar en total, incluidos los intereses.
Desglose del interés aplicado al préstamo. Con OF Brasil, recomendamos encarecidamente utilizar la información en interest_rate_data para obtener información detallada.
No anulable: La red de finanzas abiertas de Brasil debe devolver un valor.
El nombre del tipo de tasa de interés aplicada al préstamo.
Nota: Para OFDA Brasil, recomendamos usar el parámetro interest_date_data.tax_type.
El período durante el cual se aplica el interés al préstamo.
No anulable: La red de finanzas abiertas de Brasil debe devolver un valor.
La tasa de interés (en porcentaje o valor monetario).
Nota: Para OFDA Brasil, recomendamos usar el parámetro interest_date_data.pre_fixed_rate y interest_date_data.post_fixed_rate.
Información detallada sobre la tasa de interés.
El tipo de impuesto sobre la tasa de interés. Devolvemos uno de los siguientes valores:
NOMINALEFFECTIVE
No anulable: La red de finanzas abiertas de Brasil debe devolver un valor.
El tipo de tasa de interés. Devolvemos uno de los siguientes valores:
SIMPLECOMPOUND
No anulable: La red de finanzas abiertas de Brasil debe devolver un valor.
El período durante el cual se aplica el interés al préstamo.
No anulable: La red de finanzas abiertas de Brasil debe devolver un valor.
El cálculo base para la tasa de interés.
No anulable: La red de finanzas abiertas de Brasil debe devolver un valor.
La tasa de índice de referencia. Devolvemos uno de los siguientes valores:
WITHOUT_INDEX_TYPEPRE_FIXEDPOST_FIXEDFLOATINGINDEXED_PRICERURAL_CREDITOTHER_INDEX
No anulable: La red de finanzas abiertas de Brasil debe devolver un valor.
El subtipo de la tasa de índice de referencia.
Información adicional sobre la tasa del índice de referencia.
La tasa de interés con porcentaje prefijado.
No anulable: La red de finanzas abiertas de Brasil debe devolver un valor.
La tasa de porcentaje post-fijada de la tasa de interés.
No anulable: La red de finanzas abiertas de Brasil debe devolver un valor.
Desglose de las tarifas aplicadas al préstamo.
Nota: Este campo no es aplicable para OF Brazil y devolverá null.
El valor total de la tarifa. Misma moneda que el préstamo.
El nombre de la tarifa.
No anulable: Se debe devolver un valor por la red de finanzas abiertas de Brasil si el campo
feesestá disponible.
El código de tarifa.
No anulable: Se debe devolver un valor por la red de finanzas abiertas de Brasil si el campo
feesestá disponible.
Indica el tipo de cargo. Devolvemos uno de los siguientes valores:
SINGLEPER_INSTALLMENT
No anulable: Se debe devolver un valor por la red de finanzas abiertas de Brasil si el campo
feesestá disponible.
Método de facturación, según lo acordado con la institución. Devolvemos uno de los siguientes valores:
MINIMUMMAXIMUMFIXEDPERCENTAGE
No anulable: Se debe devolver un valor por la red de finanzas abiertas de Brasil si el campo
feesestá disponible.
Lo siento, no hay texto proporcionado para traducir. Por favor, proporciona el texto que necesitas que traduzca.
Detalles sobre cualquier garantía de préstamo que el individuo o negocio haya proporcionado.
El tipo de garantía, según lo definido por la institución.
No anulable: Se debe devolver un valor por la red de finanzas abiertas de Brasil si el campo
collateralsestá disponible.
El subtipo de la garantía, según lo definido por la institución.
No anulable: Se debe devolver un valor por la red de finanzas abiertas de Brasil si el campo
collateralsestá disponible.
El código de moneda de tres letras (ISO-4217).
No anulable: Se debe devolver un valor por la red de finanzas abiertas de Brasil si el campo
collateralsestá disponible.
Información detallada sobre cualquier pago global del préstamo, si corresponde.
La frecuencia de los pagos a plazos contratados, tal como se definió cuando se firmó el contrato por primera vez. Devolvemos uno de los siguientes:
DAYWEEKMONTHYEARNO_DEADLINE_REMAININGnull
La frecuencia con la que se pagan las cuotas. Devolvemos uno de los siguientes valores:
IRREGULARWEEKLYFORTNIGHTLYMONTHLYBIMONTHLYQUARTERLYBIANNUALLYANNUALLYOTHER
No anulable: La red de finanzas abiertas de Brasil debe devolver un valor.
Información adicional sobre el installment_frequency.
La fecha en la que debe pagarse la primera cuota del préstamo, en formato YYYY-MM-DD.
El número total de cuotas necesarias para pagar el préstamo.
El número de cuotas restantes por pagar.
El número de cuotas ya pagadas.
El número de cuotas que están vencidas.
Un array de fechas cuando se desembolsó el préstamo.
La fecha en que se liquidó el préstamo, en formato YYYY-MM-DD.
La fecha en que se firmó el contrato de préstamo, en formato YYYY-MM-DD.
No anulable: Se debe devolver un valor por la red de finanzas abiertas de Brasil.
La fecha en la que se espera que el préstamo se complete, en formato YYYY-MM-DD.
La frecuencia de los pagos de las cuotas restantes contratadas, tal como se definió cuando se firmó el contrato por primera vez. Devolvemos uno de los siguientes valores:
DAYWEEKMONTHYEARNO_DEADLINE_REMAININGnull
El número total de cuotas restantes del préstamo.
El calendario de amortización del préstamo.
No anulable: La red de finanzas abiertas de Brasil debe devolver un valor.
Información adicional sobre el amortization_schedule.
El ID del consignatario del préstamo.
El número de contrato del préstamo, tal como lo proporciona la institución.
Nota: Este campo no es aplicable para OF Brazil y devolverá null.
Nota: Este campo no es aplicable para OF Brazil y devolverá null.
Nota: Este campo no es aplicable para OF Brazil y devolverá null.
Nota: Este campo no es aplicable para OF Brazil y devolverá null.
Nota: Este campo no es aplicable para OF Brazil y devolverá null.
Nota: Este campo no es aplicable para OF Brazil y devolverá null.
Nota: Este campo no es aplicable para OF Brazil y devolverá null.
Nota: Este campo no es aplicable para OF Brazil y devolverá null.
Nota: Este campo no es aplicable para OF Brazil y devolverá null.
Nota: Este campo no es aplicable para OF Brazil y devolverá null.
Nota: Este campo no es aplicable para OF Brazil y devolverá null.
Ejemplo de una cuenta corriente (OFDA Brasil).
{ "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d", "link": "30cb4806-6e00-48a4-91c9-ca55968576c8", "institution": { "name": "ofmockbank_br_retail", "type": "bank" }, "collected_at": "2019-09-27T13:01:41.941Z", "created_at": "2022-02-09T08:45:50.406032Z", "last_accessed_at": "2021-03-09T10:28:40.000Z", "category": "CHECKING_ACCOUNT", "balance_type": "ASSET", "overdraft": { "used": 10000.99, "arranged": 99.99, "unarranged": 99.99 }, "type": "CONTA_DEPOSITO_A_VISTA", "subtype": "INDIVIDUAL", "name": null, "number": "11188222", "agency": "6272", "check_digit": "4", "balance": { "current": 999.99, "available": 15000, "blocked": 41233.07, "automatically_invested": 15000 }, "currency": "BRL", "public_identification_name": "AGENCY/NUMBER", "public_identification_value": "6272/11188222", "internal_identification": "92792126019929279212650822221989319252576", "credit_data": null, "loan_data": null, "funds_data": null }
Solicitud
Eliminar una cuenta específica de tu cuenta de Belvo.
Este endpoint tiene un límite de tasa. Solo puedes eliminar 5 elementos por minuto. Si excedes este límite, recibirás un código de estado 429.
Cuando eliminas una cuenta, todas las transacciones asociadas y la información del propietario para esa cuenta también se eliminan.
- Mock server
https://developers.belvo.com/_mock/es/apis/belvoopenapispec/api/accounts/{id}/
- Sandbox
https://sandbox.belvo.com/api/accounts/{id}/
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X DELETE \
-u <username>:<password> \
'https://developers.belvo.com/_mock/es/apis/belvoopenapispec/api/accounts/{id}/'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.
Bank Accounts (Brazil)
Para recibir pagos entrantes en la cuenta bancaria de su organización, debe registrar las cuentas bancarias (individuales y empresariales) utilizando la Payments API de Belvo.
- Las cuentas bancarias individuales deben ser creadas para cada pagador (su cliente).
- Las cuentas bancarias empresariales deben ser creadas para el beneficiario del pago (su organización).
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.