Introducción

Cada vez que un usuario se conecta a su institución utilizando la API de Belvo, creamos un Link. Un Link es un conjunto de credenciales encriptadas, por ejemplo, el nombre de usuario y la contraseña, que están asociadas con el usuario. Siempre necesitarás registrar primero un Link antes de poder acceder a la información específica de ese usuario final.

Enlaces recurrentes

Con los enlaces recurrentes, Belvo actualiza automáticamente la información semanalmente y te notifica a través de un <a href="../../developer_resources/resources-webhooks-aggregation target="_blank">webhook para que siempre tengas datos actualizados. Luego, cuando recibas el webhook, puedes usar solicitudes GET a los endpoints de Lista o Detalle para acceder instantáneamente a la información actualizada, sin necesidad de conectarte a la institución.

Cuando creas un enlace recurrente, Belvo recupera automáticamente información clave sobre el Link ID. Una vez que tenemos la información, te enviaremos un evento de webhook histórico indicando que puedes hacer una solicitud GET para esa información.

Recomendamos que no realices llamadas POST inmediatamente después de crear un enlace. En su lugar, espera un webhook de actualización histórica que indique que Belvo ha extraído los datos y luego puedes hacer una solicitud GET para recuperar la información (el webhook se envía poco después de que se crea un enlace). Si haces una solicitud GET antes de recibir un webhook histórico, recibirás respuestas con campos de datos vacíos o información duplicada.

Tasas de actualización

Por defecto, los enlaces recurrentes se actualizan automáticamente una vez cada siete días. Sin embargo, puedes cambiar la frecuencia de actualización de tus enlaces recurrentes a cada:

• 6 horas (cuatro veces al día)
• 12 horas (dos veces al día)
• 24 horas (una vez al día)
• 30 días (una vez al mes)
  Nota: con la tasa de actualización de 30 días, distribuimos las actualizaciones de enlaces entre el día 1 y el día 20 del mes en cuestión. La fecha de actualización para cada enlace recurrente mensual se asigna inicialmente de manera aleatoria entre el 1 y el 20 del mes. Si las siguientes actualizaciones del enlace son exitosas, las actualizaciones posteriores para este enlace ocurrirán el mismo día de cada mes. Los enlaces no están programados para ser actualizados después del día 20 del mes para reservar algo de tiempo para posibles reintentos. Para más información, consulta nuestro artículo del Centro de Ayuda sobre enlaces recurrentes mensuales.

Con los enlaces recurrentes, actualizamos la siguiente información de acuerdo con la frecuencia elegida:

Enlaces únicos

Los enlaces únicos se utilizan para realizar acceso a datos ad hoc a cuentas, propietarios, transacciones, etc. Por ejemplo, puedes usarlos cuando deseas realizar un proceso de evaluación para evaluar el riesgo antes de prestar dinero.

Para los enlaces únicos, necesitas pasar el parámetro fetch_resources al crear y luego escuchar los webhooks una vez que los datos históricos han sido extraídos de manera asincrónica.

Estados de los enlaces

Un enlace puede tener diferentes estados, que reflejan si el enlace está operativo o si se necesita una acción para restaurarlo.

Verificando el estado de un enlace

Puedes encontrar el estado de un enlace realizando una de las siguientes consultas y verificando el valor del campo de estado en la respuesta JSON:

Listar todos los enlaces actuales

Utiliza el método Listar todos los enlaces para obtener todos los enlaces a los que actualmente tienes acceso. Puedes realizar filtrado en las respuestas para devolver solo los enlaces que tienen un cierto estado. En el ejemplo a continuación, filtramos la respuesta para tener solo enlaces inválidos.

# Filtrar por enlaces inválidos
curl --request POST 'https://sandbox.belvo.com/api/links/?page_size=1000&status=invalid'\
  -u [Secret Key ID]:[Secret Key PASSWORD]

# Obtener la lista completa de enlaces
curl --request POST 'https://sandbox.belvo.com/api/links/?page_size=1000'\
  -u [Secret Key ID]:[Secret Key PASSWORD]

Si deseas saber más sobre cómo aplicar filtros en tus consultas, consulta nuestro artículo Filtrando respuestas.

Obtener detalles de un enlace específico

Utiliza el método Obtener los detalles de un enlace para obtener los detalles de un enlace específico.

curl --request GET 'https://sandbox.belvo.com/api/links/{id}' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Donde:

• {id} es el ID del enlace. Por ejemplo: c70a25d4-d8ad-9999-b59e-b8f57f0e7123.

Mejores Prácticas para la Creación de Enlaces

Cuando estés configurando tu flujo de creación de enlaces:

1. Asegúrate de primero registrar a tus usuarios en tu plataforma.
2. Usa el Connect Widget para crear tus enlaces.
3. Almacena el link_id recibido en tu base de datos.

Enlaces huérfanos

Un enlace huérfano es un enlace que fue creado pero no ha sido asociado con un usuario en tu base de datos.

Los enlaces huérfanos pueden ocurrir cuando:

• no registras primero a tu usuario en tu plataforma.
• tu usuario cierra tu aplicación (móvil o navegador) durante un proceso de conexión exitoso.

Para recuperar enlaces huérfanos creados debido a que el usuario cerró tu aplicación, recomendamos usar el parámetro external_id como un identificador adicional para tu enlace en la base de datos de Belvo.

Agregar tu propio identificador

Puedes usar el parámetro opcional external_id al crear un nuevo enlace para proporcionar un identificador único adicional dentro del sistema de Belvo. Esto es particularmente útil ya que luego puedes hacer una solicitud al endpoint de Links de Belvo y filtrar todos los enlaces asociados a un external_id.

Al usar external_id y filtrar, puedes:

• listar todos los enlaces relacionados con un usuario.
• obtener el estado más reciente de cada enlace y, si es necesario, solicitar al usuario que actualice su token o sus credenciales para una institución.
• identificar cualquier enlace huérfano para ese usuario y luego asociar el link_id en tu base de datos.

El external_id que proporciones:

• debe ser un ID único para cada usuario en tu base de datos.
• debe tener al menos tres caracteres de longitud.
• solo puede estar compuesto por letras, números, guiones (-) y guiones bajos (_).
• no puede contener ninguna información personal identificable sobre el usuario (correo electrónico, nombre, número de teléfono, número de tarjeta de crédito, etc.).

Consejos para usar external_id

Para usar el parámetro opcional external_id, recomendamos encarecidamente el siguiente flujo:

1. Registra primero a tus usuarios en tu plataforma y crea un ID único para ese usuario en tu base de datos.
2. Usa el ID único como el valor del parámetro external_id al crear un enlace.
3. Usa el Connect Widget para crear tus enlaces.

Luego, según sea necesario, puedes llamar periódicamente a /links/?external_id={ID único del usuario en tu sistema} e identificar cualquier enlace huérfano o enlaces que necesiten actualizar su estado.

Evitando enlaces duplicados

Los enlaces duplicados ocurren cuando:

• el usuario intenta conectar su cuenta a la misma institución con las mismas credenciales por segunda vez.
• no estás almacenando el link_id en tu base de datos.
• el usuario cierra tu aplicación (móvil o navegador) durante un proceso de conexión exitoso.

Para ayudarte a evitar la duplicación de enlaces, echa un vistazo a nuestros consejos útiles a continuación.

Consejo #1 - Registra a tus usuarios primero
Asegúrate de registrar a tu usuario en tu plataforma primero. De esta manera, siempre tendrás una forma de asociar los enlaces creados con un usuario en tu base de datos y hacer un seguimiento de qué cuentas ya han conectado.

Consejo #2 - Usa external_id

Cuando tu usuario inicia una nueva sesión en tu plataforma:

1. Solicita todos los enlaces asociados para el usuario: /links/?external_id={ID único del usuario en tu sistema}.

2. Asocia cualquier enlace huérfano que tenga status=valid con tu usuario en tu base de datos e informa a tu usuario que el enlace se creó exitosamente.

Si el estado del enlace no es valid, puedes:

• eliminar el enlace y solicitar al usuario que conecte su cuenta nuevamente.
• actualizar el estado del enlace usando Widget Update Mode.

De esta manera, te asegurarás de no tener enlaces huérfanos y que todos los enlaces asociados con un usuario tengan un estado valid.

Consejo #3 - Usa los metadatos del callback del widget

Después de recibir el Success callback del widget, puedes usar el ID del link para recuperar información sobre el enlace. La información del enlace puede luego compararse con los enlaces existentes que este usuario ya creó en tu base de datos (Consejos #1 y #2) y utilizar esto para detectar posibles duplicados. Por ejemplo, puedes comparar una combinación del institution_id de la cuenta, el name de la cuenta y el number de la cuenta para determinar si tu usuario ha vinculado previamente una cuenta a tu aplicación.

Consejo #4 - Muestra cuentas ya conectadas

Antes de que tus usuarios abran el widget, en tu interfaz de usuario, muestra una lista de cuentas que ya han conectado (para encontrar todas las cuentas que tienen, puedes usar el external_id en combinación con los metadatos que recibes del Widget en el Consejo #3). Al mostrar esta información, tus usuarios evitarán vincular la misma cuenta nuevamente (y tú evitas enlaces duplicados).

Consejo #5 - Usa institution_user_id para hacer seguimiento de los enlaces

Cuando tu usuario conecta su cuenta, devolvemos el institution_user_id, que es una cadena única de 44 caracteres que puede usarse para identificar a un usuario en una institución dada. Puedes usar este identificador para comparar en tu base de datos si tu usuario ha conectado previamente esta cuenta, y si deseas evitar enlaces duplicados, puedes optar por reemplazar el link.id existente en tu base de datos.

Ejemplo:

1. Tu usuario conecta su cuenta a una institución y recibes el siguiente id de enlace y institution_user_id:

{
	"id": "link-id-1",
	"institution_user_id": "ooE7XJWEKypZJR603ecaWYk-8Ap0oD8Nr1pBQ4eG9c="
}

2. Tu usuario conecta la misma cuenta nuevamente usando las mismas credenciales y recibes:

{
	"id": "link-id-2",
	"institution_user_id": "ooE7XJWEKypZJR603ecaWYk-8Ap0oD8Nr1pBQ4eG9c="
}

3. Comparando el institution_user_id en tu base de datos, ves que esta es la misma cuenta. Si prefieres no tener enlaces duplicados en tu base de datos, puedes reemplazar el link-id-1 con link-id-2 en tu base de datos y usar link-id-2 para tus futuras solicitudes.

Opt-in para prevenir enlaces duplicados

Belvo ofrece una función de opt-in diseñada para evitar que se creen enlaces duplicados, asegurando que tus usuarios nunca conecten la misma cuenta dos veces a tu aplicación. Si tu usuario ya ha conectado exitosamente su cuenta y trata de conectar la misma cuenta nuevamente:

• Integraciones usando el Connect Widget de Belvo - tus usuarios recibirán un error en el Connect Widget y tu backend recibirá un Error Event Callback.
• Integraciones que no usan el Connect Widget de Belvo - recibirás un error de API 400 duplicated.

Si deseas optar por esta función, simplemente contacta a nuestro equipo de soporte y con gusto te ayudarán. Para usar esta función, es posible que debas modificar tu integración para usar el parámetro external_id al crear el enlace.

Actualización manual de datos históricos

Puedes activar programáticamente una actualización histórica para los datos de un enlace utilizando nuestro método Trigger a historical update for a link. Esto es útil cuando necesitas obtener los datos más recientes para recursos específicos sin esperar la próxima actualización programada de un enlace recurrente o si deseas activar una actualización para un solo enlace.

Cuando realizas una solicitud a este endpoint, puedes especificar qué recursos (ACCOUNTS, TRANSACTIONS, etc.) deseas actualizar. Si no especificas ninguno, actualizaremos todos los recursos compatibles con la institución.

Manejo de Autenticación Multifactor (MFA)

Flujo general

El flujo general para MFA es:

1. Haces una solicitud POST a la institución para recuperar algunos datos o para crear un enlace.
2. Belvo envía una respuesta 428 Token Required, detallando qué método MFA se necesita para completar la solicitud.
3. Solicitas al usuario que ingrese el token de autenticación requerido.
4. Haces una solicitud PATCH Complete para el recurso dado con el ID del enlace, el ID de la sesión y el token de autenticación proporcionado por el usuario.
5. Belvo envía un mensaje de éxito 201.

428 Respuesta

A continuación, puedes ver un payload anotado para una respuesta 428 Token Required. Para obtener información detallada sobre el objeto token_generation_data, consulta la sección de Métodos MFA.

[
    {
        "code": "token_required", // Código de respuesta
        "message": "Se requiere un token MFA por la institución para iniciar sesión", // Descripción legible de la respuesta.
        "session": "be7a15d5f0b84d8ea60f6c12cb2a7b32", // ID de sesión (requerido en tu solicitud PATCH).
        "expiry": "720", // La duración en la que el usuario final necesita proporcionar un token, en segundos.
        "link": "449e388c-812b-4798-8743-7d11efb6becf", // ID de enlace del usuario final (requerido en tu solicitud PATCH).
        "token_generation_data": {
           
			// Contiene detalles sobre el Método MFA requerido (inputless, numeric, qr, text). 
			// Consulta la sección relevante
			// a continuación para obtener información detallada.

        },
        "request_id": "b7a3a5b3a3a2b6aa28f4cc98d55cf1f1" // El ID de la solicitud (utilizado para propósitos de depuración). 
    }
]

expect_user_input

En el objeto token_generation_data, incluimos un parámetro expect_user_input. Cuando se establece en false, esto indica que el usuario solo necesita, por ejemplo:

• Escanear un código QR para completar la autenticación (similar a cómo autenticas la aplicación de escritorio de Whatsapp).
• Confirmar el inicio de sesión en otro dispositivo (similar a la autenticación sin contraseña).

Inputless

El método MFA Inputless requiere que tu usuario genere un token de autenticación usando su dispositivo y te proporcione el token generado. La respuesta 428 Token Required que recibes tendrá inputless en el campo type. En tu interfaz de usuario, simplemente solicita a tu usuario que agregue su token de entrada.

[
    {
        "code": "token_required",
        "message": "A MFA token is required by the institution to login",
        "session": "be7a15d5f0b84d8ea60f6c12cb2a7b32",
        "expiry": "720",
        "link": "449e388c-812b-4798-8743-7d11efb6becf",
        "token_generation_data": {
            "instructions": "Use your app or device to generate a token",
            "type": "inputless", // <-- El método MFA es inputless.
            "value": null, // <-- No se pasa ningún valor.
          	"expects_user_input": true // <-- Indica que el usuario necesita proporcionarte datos para completar la autenticación.
        },
        "request_id": "b7a3a5b3a3a2b6aa28f4cc98d55cf1f1"
    }
]

Después de haber recibido el token de tu usuario final, realizas una solicitud PATCH.

Numérico

El método MFA numérico requiere que tu usuario final ingrese un código en su dispositivo para recibir el token de autenticación. El código que necesitarán ingresar en su dispositivo se pasa en la respuesta 428 Token Required, donde el campo type será numeric y el campo value contendrá el código que el usuario necesita ingresar en su aplicación. En tu interfaz de usuario, puedes mostrar este código a tu usuario para que luego lo ingrese en su aplicación.

[
    {
        "code": "token_required",
        "message": "A MFA token is required by the institution to login",
        "session": "731b8a5ed45245b3a2bd595382016b5e",
        "expiry": "60",
        "link": "04134743-73f9-41c3-a6dd-06cee3fab627",
        "token_generation_data": {
            "instructions": "Use this code to generate the token",
            "type": "numeric", // <-- El método MFA es numérico.
            "value": "703837", // <-- El código para mostrar al usuario.
            "expects_user_input": true // <-- Indica que el usuario necesita proporcionarte datos para completar la autenticación.
        },
        "request_id": "63cece2a9374b06495a16da5b2265793"
    }
]

Después de haber recibido el token de tu usuario final, realizas una solicitud PATCH.

Código QR

El método de MFA con Código QR requiere que tu usuario final escanee un código QR para obtener el token de autenticación.

El código QR que necesitarán escanear con su aplicación se pasa en la respuesta 428 Token Required. El código que necesitarán ingresar en su dispositivo se pasa en la respuesta 428 Token Required, donde el campo type será qr y el campo value contendrá la representación en cadena BASE64 del Código QR. Puedes analizar esta cadena para generar el código QR y mostrarlo a tu usuario en tu interfaz de usuario.

[
    {
        "code": "token_required",
        "message": "A MFA token is required by the institution to login",
        "session": "433142d512854cf6b10a3ccc08f3fa7d",
        "expiry": "60", 
        "link": "66a5cf30-512d-4830-b616-7dd7d6ecf09f",
        "token_generation_data": {
            "instructions": "Scan this QR code to generate the token",
            "type": "qr", // <-- El método de MFA es un código QR.
            "value": "...", // <-- Cadena BASE64 para analizar y generar el código QR.
          	"expects_user_input": true // <-- Indica que el usuario necesita proporcionarte datos para completar la autenticación
        },
        "request_id": "ce05c19b323c1caae6445aff5d4229f8"
    }
]

Después de haber recibido el token de tu usuario final, realizas una solicitud PATCH.

Texto

El método de MFA de Texto requiere que tu usuario responda una pregunta de seguridad. La respuesta 428 Token Required que recibes tendrá text en el campo type. En tu interfaz de usuario, simplemente solicita a tu usuario que responda su pregunta de seguridad y usa la cadena proporcionada como el valor del parámetro token en tu solicitud PATCH.

[
    {
        "code": "token_required",
        "message": "A MFA token is required by the institution to login",
        "session": "be7a15d5f0b84d8ea60f6c12cb2a7b32",
        "expiry": "720",
        "link": "449e388c-812b-4798-8743-7d11efb6becf",
        "token_generation_data": {
            "instructions": "Answer the question to proceed",
            "type": "text", // <-- El método de MFA es una respuesta a una pregunta de seguridad.
            "value": "Where were you born?", // <-- Pregunta de seguridad que el usuario necesita responder.
          	"expects_user_input": true // <-- Indica que el usuario necesita proporcionarte datos para completar la autenticación
        },
        "request_id": "b7a3a5b3a3a2b6aa28f4cc98d55cf1f1"
    }
]

Después de haber recibido el token de tu usuario final, realizas una solicitud PATCH.

Enviar token MFA después de una respuesta 428

Cuando se requiere que proporciones un token durante el proceso de conexión, recibirás una respuesta 428 Token Required e instrucciones sobre qué método MFA se necesita. Después de haber solicitado al usuario que ingrese su token de autenticación, debes enviar una solicitud PATCH al endpoint Resume del recurso al que deseas acceder.

Por ejemplo:

curl -X PATCH \
  https://sandbox.belvo.com/api/links/ \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
    "session": "{sessionId}",
		"link": "{linkId}",
    "token": "{userToken}"
}' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Donde:

• {sessionId} es el valor en el campo session que recibes en la respuesta 428 Token Required.
• {linkId} es el valor en el campo link que recibes en la respuesta 428 Token Required.
• {userToken} es el token de autenticación (incluyendo una respuesta a una pregunta de seguridad) que proporciona tu usuario.