# Recuperar rendimentos para um link Recupere insights de renda para contas correntes e poupança a partir de um link específico. Você pode receber insights para um período de até 365 dias, dependendo do histórico de transações disponível para cada instituição. Endpoint: POST /api/incomes/ Version: 1.223.0 Security: basicAuth ## Query parameters: - `omit` (string) Omitir certos campos de serem retornados na resposta. Para mais informações, consulte nosso artigo Filtrando respostas no DevPortal. - `fields` (string) Retorne apenas os campos especificados na resposta. Para mais informações, consulte nosso artigo no DevPortal Filtrando respostas. ## Request fields (application/json): - `link` (string, required) O para o qual você deseja recuperar informações. Example: "c81a1dea-6dd6-4999-8b9f-541ee8197058" - `allowed_income_types` (array) As categorias das receitas para as quais você deseja obter informações. Enum: "SALARY", "GOVERNMENT", "INTEREST", "RENT", "RETIREMENT", "FREELANCE", "ALTERNATIVE_INCOME", "TRANSFER", "DEPOSIT", "UNKNOWN" - `minimum_confidence_level` (string) O nível mínimo de confiança das receitas para as quais você deseja obter informações. Você pode enviar um dos seguintes valores: - - - Enum: "HIGH", "MEDIUM", "LOW" - `date_from` (string) A data a partir da qual você deseja começar a obter dados, no formato . ⚠️ O valor de não pode ser maior que . Example: "2020-08-05" - `date_to` (string) A data em que você deseja parar de receber dados, no formato . ⚠️ O valor de não pode ser maior que a data de hoje (ou seja, não são permitidas datas futuras). Example: "2020-10-05" - `token` (string) O token MFA gerado pela instituição, que é necessário para continuar uma sessão. Example: "1234ab" - `save_data` (boolean) Indica se os dados devem ou não ser persistidos no Belvo. Por padrão, isso é definido como e retornamos uma resposta 201 Created. Quando definido como , os dados não serão persistidos e retornamos uma resposta 200 OK. Example: true ## Response 200 fields (application/json): - `id` (string, required) Identificador único da Belvo para o item atual. Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d" - `link` (string,null, required) O ao qual os dados pertencem. Example: "30cb4806-6e00-48a4-91c9-ca55968576c8" - `created_at` (string, required) O carimbo de data e hora ISO-8601 de quando o ponto de dados foi criado no banco de dados da Belvo. Example: "2022-02-09T08:45:50.406032Z" - `income_streams` (array, required) Um array de objetos de fluxo de renda enriquecidos. - `income_streams.account_id` (string, required) ID único para a conta bancária a ser verificada para fluxos de renda. Example: "EBACA-89077589" - `income_streams.income_type` (string, required) O tipo de renda usado nos cálculos. Retornamos um dos seguintes valores do enum: - - - - - - - - - - Enum: "SALARY", "GOVERNMENT", "INTEREST", "RENT", "RETIREMENT", "FREELANCE", "ALTERNATIVE_INCOME", "TRANSFER", "DEPOSIT", "UNKNOWN" - `income_streams.frequency` (string, required) Com que frequência a renda é recebida. Retornamos um dos seguintes valores do enum: - - Para transações que ocorrem uma vez por mês. - - Para transações que ocorrem uma vez a cada duas semanas. - - Para transações que ocorrem uma vez por semana. - - Para transações que não ocorrem em um padrão de frequência definido. - - Para transações que ocorrem apenas uma vez e não se repetem. Enum: "MONTHLY", "FORTNIGHTLY", "WEEKLY", "IRREGULAR", "SINGLE" - `income_streams.monthly_average` (number, required) A quantidade média de renda recebida da fonte durante . Example: 2500 - `income_streams.monthly_median` (number) A quantidade mediana de renda recebida da fonte ao longo de um mês natural. Example: 2200 - `income_streams.average_income_amount` (number, required) O valor médio da transação de renda da fonte. Example: 2500 - `income_streams.last_income_amount` (number, required) O valor da renda mais recente recebida da fonte. Example: 2500 - `income_streams.currency` (string, required) O código de moeda de três letras da receita. Por exemplo: • 🇧🇷 BRL (Real Brasileiro) • 🇨🇴 COP (Peso Colombiano) • 🇲🇽 MXN (Peso Mexicano) Example: "BRL" - `income_streams.last_income_description` (string, required) A descrição da receita mais recente do stream. Example: "Salário" - `income_streams.last_income_date` (string, required) A data em que a receita mais recente do stream foi recebida, no formato . Example: "2023-02-09" - `income_streams.stability` (number,null, required) A estabilidade da renda com base em seu valor, com um intervalo de 0 a 1, onde 1 representa estabilidade perfeita. Para transações com =, este valor retorna . Example: 1 - `income_streams.regularity` (number,null, required) A regularidade da renda é baseada em sua frequência, com um intervalo de 0 a 1, onde 1 representa regularidade perfeita. Para transações com =, este valor retorna . Example: 1 - `income_streams.trend` (number,null, required) A tendência de renda durante um período de tempo é calculada entre a última renda e a primeira renda recebida, onde: - um número float negativo significa que a tendência de renda está diminuindo durante o período de tempo. - um número float positivo significa que a tendência de renda está aumentando durante o período de tempo. Para transações com =, este valor retorna . - `income_streams.lookback_periods` (integer, required) Número de unidades de período (com base em ) usadas para gerar insights e cálculos. Um é um período de 30 dias. Por exemplo, de 2023-01-15 a 2023-02-15. Example: 9 - `income_streams.full_periods` (integer, required) Número de unidades de período (baseado em ) com dados para realizar cálculos. Um é um período de 30 dias. Por exemplo, de 2023-01-15 a 2023-02-15. Example: 9 - `income_streams.periods_with_income` (integer, required) Número de unidades de período (com base em ) com pelo menos uma receita disponível. Um é um período de 30 dias. Por exemplo, de 2023-01-15 a 2023-02-15. Example: 9 - `income_streams.number_of_incomes` (integer, required) Número de transações de renda durante os . Example: 9 - `income_streams.confidence` (string, required) Nível de confiança da Belvo para rendas futuras. Retornamos um dos seguintes valores do enum: - - - Enum: "HIGH", "MEDIUM", "LOW" - `income_source_type` (string, required) O tipo de fonte da qual geramos insights de renda. Retornamos um dos seguintes valores de enum: - Enum: "BANK" - `first_transaction_date` (string,null, required) A data em que a primeira transação ocorreu, no formato . Example: "2022-06-09" - `last_transaction_date` (string, required) A data em que a última transação ocorreu, no formato . Example: "2023-02-09" - `best_working_day_to_charge` (integer, required) O melhor dia útil do mês para cobrar o usuário. Example: 22 - `good_working_days_to_charge` (array, required) Dias úteis adicionais que foram identificados como bons dias para cobrar o usuário. Example: [17,7,2] - `number_of_income_streams` (integer, required) Número total de fluxos de renda analisados. Example: 1 - `monthly_average` (number, required) Valor médio de renda recebida por mês em todas as contas para o usuário específico. Example: 2500 - `monthly_average_regular` (number, required) Valor médio de renda regular (com uma frequência de , ou ) recebida por mês para o usuário específico. Example: 2500 - `monthly_average_irregular` (number, required) Valor médio de renda irregular (com uma frequência de ou ) recebida por mês para o usuário específico. - `monthly_average_low_confidence` (number, required) Valor médio de renda recebida por mês para o usuário específico com confiança . - `monthly_average_medium_confidence` (number, required) Valor médio de renda recebida por mês para o usuário específico com confiança . - `monthly_average_high_confidence` (number, required) Valor médio de renda recebida por mês para o usuário específico com confiança . Example: 2500 - `total_income_amount` (number, required) Valor total de toda a receita recebida para o usuário específico. Example: 22500 - `total_regular_income_amount` (number, required) Valor total da renda regular (com uma frequência de , , ) para o usuário específico. Example: 22500 - `total_irregular_income_amount` (number) Valor total da renda irregular (com uma frequência de ou ) para o usuário específico. - `total_low_confidence` (number, required) Valor total de renda para o usuário específico com confiança . - `total_medium_confidence` (number, required) Quantidade total de renda para o usuário específico com confiança . - `total_high_confidence` (number, required) Valor total de renda para o usuário específico com confiança . Example: 22500 ## Response 201 fields (application/json): - `id` (string, required) Identificador único da Belvo para o item atual. Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d" - `link` (string,null, required) O ao qual os dados pertencem. Example: "30cb4806-6e00-48a4-91c9-ca55968576c8" - `created_at` (string, required) O carimbo de data e hora ISO-8601 de quando o ponto de dados foi criado no banco de dados da Belvo. Example: "2022-02-09T08:45:50.406032Z" - `income_streams` (array, required) Um array de objetos de fluxo de renda enriquecidos. - `income_streams.account_id` (string, required) ID único para a conta bancária a ser verificada para fluxos de renda. Example: "EBACA-89077589" - `income_streams.income_type` (string, required) O tipo de renda usado nos cálculos. Retornamos um dos seguintes valores do enum: - - - - - - - - - - Enum: "SALARY", "GOVERNMENT", "INTEREST", "RENT", "RETIREMENT", "FREELANCE", "ALTERNATIVE_INCOME", "TRANSFER", "DEPOSIT", "UNKNOWN" - `income_streams.frequency` (string, required) Com que frequência a renda é recebida. Retornamos um dos seguintes valores do enum: - - Para transações que ocorrem uma vez por mês. - - Para transações que ocorrem uma vez a cada duas semanas. - - Para transações que ocorrem uma vez por semana. - - Para transações que não ocorrem em um padrão de frequência definido. - - Para transações que ocorrem apenas uma vez e não se repetem. Enum: "MONTHLY", "FORTNIGHTLY", "WEEKLY", "IRREGULAR", "SINGLE" - `income_streams.monthly_average` (number, required) A quantidade média de renda recebida da fonte durante . Example: 2500 - `income_streams.monthly_median` (number) A quantidade mediana de renda recebida da fonte ao longo de um mês natural. Example: 2200 - `income_streams.average_income_amount` (number, required) O valor médio da transação de renda da fonte. Example: 2500 - `income_streams.last_income_amount` (number, required) O valor da renda mais recente recebida da fonte. Example: 2500 - `income_streams.currency` (string, required) O código de moeda de três letras da receita. Por exemplo: • 🇧🇷 BRL (Real Brasileiro) • 🇨🇴 COP (Peso Colombiano) • 🇲🇽 MXN (Peso Mexicano) Example: "BRL" - `income_streams.last_income_description` (string, required) A descrição da receita mais recente do stream. Example: "Salário" - `income_streams.last_income_date` (string, required) A data em que a receita mais recente do stream foi recebida, no formato . Example: "2023-02-09" - `income_streams.stability` (number,null, required) A estabilidade da renda com base em seu valor, com um intervalo de 0 a 1, onde 1 representa estabilidade perfeita. Para transações com =, este valor retorna . Example: 1 - `income_streams.regularity` (number,null, required) A regularidade da renda é baseada em sua frequência, com um intervalo de 0 a 1, onde 1 representa regularidade perfeita. Para transações com =, este valor retorna . Example: 1 - `income_streams.trend` (number,null, required) A tendência de renda durante um período de tempo é calculada entre a última renda e a primeira renda recebida, onde: - um número float negativo significa que a tendência de renda está diminuindo durante o período de tempo. - um número float positivo significa que a tendência de renda está aumentando durante o período de tempo. Para transações com =, este valor retorna . - `income_streams.lookback_periods` (integer, required) Número de unidades de período (com base em ) usadas para gerar insights e cálculos. Um é um período de 30 dias. Por exemplo, de 2023-01-15 a 2023-02-15. Example: 9 - `income_streams.full_periods` (integer, required) Número de unidades de período (baseado em ) com dados para realizar cálculos. Um é um período de 30 dias. Por exemplo, de 2023-01-15 a 2023-02-15. Example: 9 - `income_streams.periods_with_income` (integer, required) Número de unidades de período (com base em ) com pelo menos uma receita disponível. Um é um período de 30 dias. Por exemplo, de 2023-01-15 a 2023-02-15. Example: 9 - `income_streams.number_of_incomes` (integer, required) Número de transações de renda durante os . Example: 9 - `income_streams.confidence` (string, required) Nível de confiança da Belvo para rendas futuras. Retornamos um dos seguintes valores do enum: - - - Enum: "HIGH", "MEDIUM", "LOW" - `income_source_type` (string, required) O tipo de fonte da qual geramos insights de renda. Retornamos um dos seguintes valores de enum: - Enum: "BANK" - `first_transaction_date` (string,null, required) A data em que a primeira transação ocorreu, no formato . Example: "2022-06-09" - `last_transaction_date` (string, required) A data em que a última transação ocorreu, no formato . Example: "2023-02-09" - `best_working_day_to_charge` (integer, required) O melhor dia útil do mês para cobrar o usuário. Example: 22 - `good_working_days_to_charge` (array, required) Dias úteis adicionais que foram identificados como bons dias para cobrar o usuário. Example: [17,7,2] - `number_of_income_streams` (integer, required) Número total de fluxos de renda analisados. Example: 1 - `monthly_average` (number, required) Valor médio de renda recebida por mês em todas as contas para o usuário específico. Example: 2500 - `monthly_average_regular` (number, required) Valor médio de renda regular (com uma frequência de , ou ) recebida por mês para o usuário específico. Example: 2500 - `monthly_average_irregular` (number, required) Valor médio de renda irregular (com uma frequência de ou ) recebida por mês para o usuário específico. - `monthly_average_low_confidence` (number, required) Valor médio de renda recebida por mês para o usuário específico com confiança . - `monthly_average_medium_confidence` (number, required) Valor médio de renda recebida por mês para o usuário específico com confiança . - `monthly_average_high_confidence` (number, required) Valor médio de renda recebida por mês para o usuário específico com confiança . Example: 2500 - `total_income_amount` (number, required) Valor total de toda a receita recebida para o usuário específico. Example: 22500 - `total_regular_income_amount` (number, required) Valor total da renda regular (com uma frequência de , , ) para o usuário específico. Example: 22500 - `total_irregular_income_amount` (number) Valor total da renda irregular (com uma frequência de ou ) para o usuário específico. - `total_low_confidence` (number, required) Valor total de renda para o usuário específico com confiança . - `total_medium_confidence` (number, required) Quantidade total de renda para o usuário específico com confiança . - `total_high_confidence` (number, required) Valor total de renda para o usuário específico com confiança . Example: 22500 ## Response 403 fields (application/json): - `code` (string) Um código de erro único () que permite classificar e tratar o erro programaticamente. ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com 403 access_to_resource_denied. Example: "access_to_resource_denied" - `message` (string) Uma breve descrição do erro. Para erros , a descrição é: - . Example: "You don't have access to this resource." - `request_id` (string) Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: ). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações. Example: "9e7b283c6efa449c9c028a16b5c249fb" ## Response 404 fields (application/json): - `code` (string) Um código de erro único () que permite classificar e lidar com o erro programaticamente. Example: "not_found" - `message` (string) Uma breve descrição do erro. Para erros , a descrição é: - Example: "Not found" - `request_id` (string) Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: ). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações. Example: "9e7b283c6efa449c9c028a16b5c249fb" ## Response 408 fields (application/json): - `code` (string) Um código de erro único () que permite classificar e lidar com o erro programaticamente. ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com erros 408 request_timeout. Example: "request_timeout" - `message` (string) Uma breve descrição do erro. Para erros de , a descrição é: - . Example: "The request timed out, you can retry asking for less data by changing your query parameters" - `request_id` (string) Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: ). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações. Example: "9e7b283c6efa449c9c028a16b5c249fb" ## Response 500 fields (application/json): - `code` (string) Um código de erro único () que permite classificar e tratar o erro de forma programática. ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com erros 500 unexpected_error. Example: "unexpected_error" - `message` (string) Uma breve descrição do erro. Para erros , a descrição é: - . 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) Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: ). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações. Example: "9e7b283c6efa449c9c028a16b5c249fb"