# Completar una solicitud de ingresos Se utiliza para reanudar una sesión de recuperación de ingresos que se pausó porque la institución requería un token MFA. Endpoint: PATCH /api/incomes/ Version: 1.223.0 Security: basicAuth ## Query parameters: - `omit` (string) Omite ciertos campos para que no se devuelvan en la respuesta. Para más información, consulta nuestro artículo del DevPortal Filtrando respuestas. - `fields` (string) Devuelve solo los campos especificados en la respuesta. Para obtener más información, consulta nuestro artículo del DevPortal Filtrando respuestas. ## Request fields (application/json): - `session` (string, required) La sesión que deseas reanudar. Necesitas usar el valor de que se proporciona en la respuesta 428 Token Required que recibes después de realizar tu solicitud POST. Example: "6e7b283c6efa449c9c028a16b5c249fa" - `token` (string) El token MFA generado por la institución que se requiere para continuar una sesión. Example: "1234ab" - `link` (string, required) El que deseas reanudar. Debe ser el mismo que recibes en la respuesta 428 Token Required que contiene el ID de . Example: "683005d6-f45c-4adb-b289-f1a12f50f80c" - `save_data` (boolean) Indica si se debe o no persistir los datos en Belvo. Por defecto, esto está configurado en y devolvemos una respuesta 201 Created. Cuando se establece en , los datos no se persistirán y devolvemos una respuesta 200 OK. Example: true ## Response 200 fields (application/json): - `id` (string, required) Identificador único de Belvo para el elemento actual. Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d" - `link` (string,null, required) El al que pertenecen los datos. Example: "30cb4806-6e00-48a4-91c9-ca55968576c8" - `created_at` (string, required) La marca de tiempo ISO-8601 de cuando se creó el punto de datos en la base de datos de Belvo. Example: "2022-02-09T08:45:50.406032Z" - `income_streams` (array, required) Una matriz de objetos de flujo de ingresos enriquecidos. - `income_streams.account_id` (string, required) ID único para la cuenta bancaria que se verificará para flujos de ingresos. Example: "EBACA-89077589" - `income_streams.income_type` (string, required) El tipo de ingreso utilizado en los cálculos. Devolvemos uno de los siguientes valores de enum: - - - - - - - - - - Enum: "SALARY", "GOVERNMENT", "INTEREST", "RENT", "RETIREMENT", "FREELANCE", "ALTERNATIVE_INCOME", "TRANSFER", "DEPOSIT", "UNKNOWN" - `income_streams.frequency` (string, required) Con qué frecuencia se recibe el ingreso. Devolvemos uno de los siguientes valores de enum: - - Para transacciones que ocurren una vez al mes. - - Para transacciones que ocurren una vez cada dos semanas. - - Para transacciones que ocurren una vez por semana. - - Para transacciones que no ocurren con un patrón de frecuencia definido. - - Para transacciones que ocurren solo una vez y no se repiten. Enum: "MONTHLY", "FORTNIGHTLY", "WEEKLY", "IRREGULAR", "SINGLE" - `income_streams.monthly_average` (number, required) La cantidad promedio de ingresos recibidos de la fuente durante . Example: 2500 - `income_streams.monthly_median` (number) La cantidad mediana de ingresos recibidos de la fuente durante un mes natural. Example: 2200 - `income_streams.average_income_amount` (number, required) El monto promedio de transacción de ingresos de la fuente. Example: 2500 - `income_streams.last_income_amount` (number, required) El monto del ingreso más reciente recibido de la fuente. Example: 2500 - `income_streams.currency` (string, required) El código de moneda de tres letras del ingreso. Por ejemplo: • 🇧🇷 BRL (Real Brasileño) • 🇨🇴 COP (Peso Colombiano) • 🇲🇽 MXN (Peso Mexicano) Example: "BRL" - `income_streams.last_income_description` (string, required) La descripción del ingreso más reciente del stream. Example: "Salário" - `income_streams.last_income_date` (string, required) La fecha en que se recibió el ingreso más reciente del flujo, en formato . Example: "2023-02-09" - `income_streams.stability` (number,null, required) La estabilidad del ingreso basada en su cantidad, con un rango de 0 a 1, donde 1 representa estabilidad perfecta. Para transacciones con =, este valor devuelve . Example: 1 - `income_streams.regularity` (number,null, required) La regularidad del ingreso se basa en su frecuencia, con un rango de 0 a 1, donde 1 representa una regularidad perfecta. Para transacciones con =, este valor devuelve . Example: 1 - `income_streams.trend` (number,null, required) La tendencia de ingresos durante un período de tiempo se calcula entre el último ingreso y el primer ingreso recibido, donde: - un número flotante negativo significa que la tendencia de ingresos está disminuyendo durante el período de tiempo. - un número flotante positivo significa que la tendencia de ingresos está aumentando durante el período de tiempo. Para transacciones con =, este valor devuelve . - `income_streams.lookback_periods` (integer, required) Número de unidades de período (basadas en ) utilizadas para generar conocimientos y cálculos. Un es un período de 30 días. Por ejemplo, del 2023-01-15 al 2023-02-15. Example: 9 - `income_streams.full_periods` (integer, required) Número de unidades de período (basado en ) con datos para realizar cálculos. Un es un período de 30 días. Por ejemplo, del 2023-01-15 al 2023-02-15. Example: 9 - `income_streams.periods_with_income` (integer, required) Número de unidades de período (basadas en ) con al menos un ingreso disponible. Un es un período de 30 días. Por ejemplo, del 2023-01-15 al 2023-02-15. Example: 9 - `income_streams.number_of_incomes` (integer, required) Número de transacciones de ingresos durante los . Example: 9 - `income_streams.confidence` (string, required) Nivel de confianza de Belvo para ingresos futuros. Devolvemos uno de los siguientes valores de enum: - - - Enum: "HIGH", "MEDIUM", "LOW" - `income_source_type` (string, required) El tipo de fuente de la que generamos información sobre ingresos. Devolvemos uno de los siguientes valores de 'enum': - Enum: "BANK" - `first_transaction_date` (string,null, required) La fecha en que ocurrió la primera transacción, en formato . Example: "2022-06-09" - `last_transaction_date` (string, required) La fecha en la que ocurrió la última transacción, en formato . Example: "2023-02-09" - `best_working_day_to_charge` (integer, required) El mejor día laborable del mes para cobrar al usuario. Example: 22 - `good_working_days_to_charge` (array, required) Días laborales adicionales que se han identificado como buenos días para cobrar al usuario. Example: [17,7,2] - `number_of_income_streams` (integer, required) Número de flujos de ingresos totales analizados. Example: 1 - `monthly_average` (number, required) Cantidad promedio de ingresos recibidos por mes en todas las cuentas para el usuario específico. Example: 2500 - `monthly_average_regular` (number, required) Cantidad promedio de ingresos regulares (con una frecuencia de , o ) recibidos por mes para el usuario específico. Example: 2500 - `monthly_average_irregular` (number, required) Monto promedio de ingresos irregulares (con una frecuencia de o ) recibidos por mes para el usuario específico. - `monthly_average_low_confidence` (number, required) Cantidad promedio de ingresos recibidos por mes para el usuario específico con confianza . - `monthly_average_medium_confidence` (number, required) Cantidad promedio de ingresos recibidos por mes para el usuario específico con confianza . - `monthly_average_high_confidence` (number, required) Cantidad promedio de ingresos recibidos por mes para el usuario específico con confianza . Example: 2500 - `total_income_amount` (number, required) Monto total de todos los ingresos recibidos para el usuario específico. Example: 22500 - `total_regular_income_amount` (number, required) Cantidad total de ingresos regulares (con una frecuencia de , , ) para el usuario específico. Example: 22500 - `total_irregular_income_amount` (number) Monto total de ingresos irregulares (con una frecuencia de o ) para el usuario específico. - `total_low_confidence` (number, required) Cantidad total de ingresos para el usuario específico con confianza . - `total_medium_confidence` (number, required) Cantidad total de ingresos para el usuario específico con confianza . - `total_high_confidence` (number, required) Cantidad total de ingresos para el usuario específico con confianza . Example: 22500 ## Response 201 fields (application/json): - `id` (string, required) Identificador único de Belvo para el elemento actual. Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d" - `link` (string,null, required) El al que pertenecen los datos. Example: "30cb4806-6e00-48a4-91c9-ca55968576c8" - `created_at` (string, required) La marca de tiempo ISO-8601 de cuando se creó el punto de datos en la base de datos de Belvo. Example: "2022-02-09T08:45:50.406032Z" - `income_streams` (array, required) Una matriz de objetos de flujo de ingresos enriquecidos. - `income_streams.account_id` (string, required) ID único para la cuenta bancaria que se verificará para flujos de ingresos. Example: "EBACA-89077589" - `income_streams.income_type` (string, required) El tipo de ingreso utilizado en los cálculos. Devolvemos uno de los siguientes valores de enum: - - - - - - - - - - Enum: "SALARY", "GOVERNMENT", "INTEREST", "RENT", "RETIREMENT", "FREELANCE", "ALTERNATIVE_INCOME", "TRANSFER", "DEPOSIT", "UNKNOWN" - `income_streams.frequency` (string, required) Con qué frecuencia se recibe el ingreso. Devolvemos uno de los siguientes valores de enum: - - Para transacciones que ocurren una vez al mes. - - Para transacciones que ocurren una vez cada dos semanas. - - Para transacciones que ocurren una vez por semana. - - Para transacciones que no ocurren con un patrón de frecuencia definido. - - Para transacciones que ocurren solo una vez y no se repiten. Enum: "MONTHLY", "FORTNIGHTLY", "WEEKLY", "IRREGULAR", "SINGLE" - `income_streams.monthly_average` (number, required) La cantidad promedio de ingresos recibidos de la fuente durante . Example: 2500 - `income_streams.monthly_median` (number) La cantidad mediana de ingresos recibidos de la fuente durante un mes natural. Example: 2200 - `income_streams.average_income_amount` (number, required) El monto promedio de transacción de ingresos de la fuente. Example: 2500 - `income_streams.last_income_amount` (number, required) El monto del ingreso más reciente recibido de la fuente. Example: 2500 - `income_streams.currency` (string, required) El código de moneda de tres letras del ingreso. Por ejemplo: • 🇧🇷 BRL (Real Brasileño) • 🇨🇴 COP (Peso Colombiano) • 🇲🇽 MXN (Peso Mexicano) Example: "BRL" - `income_streams.last_income_description` (string, required) La descripción del ingreso más reciente del stream. Example: "Salário" - `income_streams.last_income_date` (string, required) La fecha en que se recibió el ingreso más reciente del flujo, en formato . Example: "2023-02-09" - `income_streams.stability` (number,null, required) La estabilidad del ingreso basada en su cantidad, con un rango de 0 a 1, donde 1 representa estabilidad perfecta. Para transacciones con =, este valor devuelve . Example: 1 - `income_streams.regularity` (number,null, required) La regularidad del ingreso se basa en su frecuencia, con un rango de 0 a 1, donde 1 representa una regularidad perfecta. Para transacciones con =, este valor devuelve . Example: 1 - `income_streams.trend` (number,null, required) La tendencia de ingresos durante un período de tiempo se calcula entre el último ingreso y el primer ingreso recibido, donde: - un número flotante negativo significa que la tendencia de ingresos está disminuyendo durante el período de tiempo. - un número flotante positivo significa que la tendencia de ingresos está aumentando durante el período de tiempo. Para transacciones con =, este valor devuelve . - `income_streams.lookback_periods` (integer, required) Número de unidades de período (basadas en ) utilizadas para generar conocimientos y cálculos. Un es un período de 30 días. Por ejemplo, del 2023-01-15 al 2023-02-15. Example: 9 - `income_streams.full_periods` (integer, required) Número de unidades de período (basado en ) con datos para realizar cálculos. Un es un período de 30 días. Por ejemplo, del 2023-01-15 al 2023-02-15. Example: 9 - `income_streams.periods_with_income` (integer, required) Número de unidades de período (basadas en ) con al menos un ingreso disponible. Un es un período de 30 días. Por ejemplo, del 2023-01-15 al 2023-02-15. Example: 9 - `income_streams.number_of_incomes` (integer, required) Número de transacciones de ingresos durante los . Example: 9 - `income_streams.confidence` (string, required) Nivel de confianza de Belvo para ingresos futuros. Devolvemos uno de los siguientes valores de enum: - - - Enum: "HIGH", "MEDIUM", "LOW" - `income_source_type` (string, required) El tipo de fuente de la que generamos información sobre ingresos. Devolvemos uno de los siguientes valores de 'enum': - Enum: "BANK" - `first_transaction_date` (string,null, required) La fecha en que ocurrió la primera transacción, en formato . Example: "2022-06-09" - `last_transaction_date` (string, required) La fecha en la que ocurrió la última transacción, en formato . Example: "2023-02-09" - `best_working_day_to_charge` (integer, required) El mejor día laborable del mes para cobrar al usuario. Example: 22 - `good_working_days_to_charge` (array, required) Días laborales adicionales que se han identificado como buenos días para cobrar al usuario. Example: [17,7,2] - `number_of_income_streams` (integer, required) Número de flujos de ingresos totales analizados. Example: 1 - `monthly_average` (number, required) Cantidad promedio de ingresos recibidos por mes en todas las cuentas para el usuario específico. Example: 2500 - `monthly_average_regular` (number, required) Cantidad promedio de ingresos regulares (con una frecuencia de , o ) recibidos por mes para el usuario específico. Example: 2500 - `monthly_average_irregular` (number, required) Monto promedio de ingresos irregulares (con una frecuencia de o ) recibidos por mes para el usuario específico. - `monthly_average_low_confidence` (number, required) Cantidad promedio de ingresos recibidos por mes para el usuario específico con confianza . - `monthly_average_medium_confidence` (number, required) Cantidad promedio de ingresos recibidos por mes para el usuario específico con confianza . - `monthly_average_high_confidence` (number, required) Cantidad promedio de ingresos recibidos por mes para el usuario específico con confianza . Example: 2500 - `total_income_amount` (number, required) Monto total de todos los ingresos recibidos para el usuario específico. Example: 22500 - `total_regular_income_amount` (number, required) Cantidad total de ingresos regulares (con una frecuencia de , , ) para el usuario específico. Example: 22500 - `total_irregular_income_amount` (number) Monto total de ingresos irregulares (con una frecuencia de o ) para el usuario específico. - `total_low_confidence` (number, required) Cantidad total de ingresos para el usuario específico con confianza . - `total_medium_confidence` (number, required) Cantidad total de ingresos para el usuario específico con confianza . - `total_high_confidence` (number, required) Cantidad total de ingresos para el usuario específico con confianza . Example: 22500 ## Response 408 fields (application/json): - `code` (string) Un código de error único () que te permite clasificar y manejar el error de manera programática. ℹ️ Consulta nuestro DevPortal para obtener más información sobre cómo manejar errores 408 request_timeout. Example: "request_timeout" - `message` (string) Una breve descripción del error. Para los errores de , la descripción es: - . Example: "The request timed out, you can retry asking for less data by changing your query parameters" - `request_id` (string) Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: ). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones. Example: "9e7b283c6efa449c9c028a16b5c249fb" ## Response 428 fields (application/json): - `code` (string) Un código de error único () que te permite clasificar y manejar el error de forma programática. ℹ️ Consulta nuestro DevPortal para obtener más información sobre cómo manejar errores 428 token_required. Example: "token_required" - `message` (string) Una breve descripción del error. Para los errores , la descripción es: - . Example: "A MFA token is required by the institution to login" - `request_id` (string) Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: ). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones. Example: "9e7b283c6efa449c9c028a16b5c249fb" - `session` (string) Un ID único de 32 caracteres de la sesión de inicio de sesión (que coincide con un patrón de regex de: ). Example: "2675b703b9d4451f8d4861a3eee54449" - `expiry` (integer) Tiempo de duración de la sesión en segundos. Example: 9600 - `link` (string) Identificador único creado por Belvo, utilizado para referenciar el Link actual. Example: "30cb4806-6e00-48a4-91c9-ca55968576c8" - `token_generation_data` (object) Detalles sobre cómo generar el token. - `token_generation_data.instructions` (string) Instrucciones para la generación de tokens. Example: "Use this code to generate the token" - `token_generation_data.type` (string) Tipo de datos para generar el token (código QR, desafío numérico). Example: "numeric" - `token_generation_data.value` (string) Valor a utilizar para generar el token. Example: "12345" - `token_generation_data.expects_user_input` (boolean) Indica si el usuario necesita proporcionar información para completar la autenticación. Cuando se establece en , es posible que su usuario necesite: - confirmar el inicio de sesión en otro dispositivo - escanear un código QR Aún necesitará realizar una llamada PATCH para completar la solicitud. Example: true ## Response 500 fields (application/json): - `code` (string) Un código de error único () que te permite clasificar y manejar el error de manera programática. ℹ️ Consulta nuestro DevPortal para obtener más información sobre cómo manejar errores 500 unexpected_error. Example: "unexpected_error" - `message` (string) Una breve descripción del error. Para los errores , la descripción es: - . Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution" - `request_id` (string) Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: ). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones. Example: "9e7b283c6efa449c9c028a16b5c249fb"