Webhooks de Agregação

Um webhook é um retorno de chamada web que a Belvo usa para enviar notificações sobre um link específico. Você precisará configurar webhooks para usar as APIs da Belvo.

Configurar webhooks

Para configurar um novo webhook:

No seu painel do Belvo, vá para a seção de webhooks de dados.
Na aba Webhooks de Dados, clique em +Novo webhook.
Preencha o formulário Novo webhook com as informações necessárias.
- URL: a URL para receber as notificações do webhook.
- Authorization: um token de autorização opcional para usar se sua URL estiver protegida.
Clique em Criar webhook.

✳️ Feito! O webhook agora está configurado e seu aplicativo será notificado sobre novos eventos relacionados aos seus links.

Usando Autenticação Adicional

Por razões de segurança, você pode adicionar uma camada adicional de autenticação às suas chamadas de webhook. Quando você cria seu webhook, no campo Autenticação (Opcional), insira:

Basic e uma string username:password codificada em base64 (para autenticação Basic)
Bearer e um token (para autenticação Bearer)

Tipos de webhook

Todos os eventos de webhook vêm com um payload principal (conforme descrito no exemplo de código).

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "ACCOUNTS",
  "process_type": "historical_update", // Indica por que o webhook foi acionado
  "webhook_code": "historical_update", // Tipo de webhook
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28", // Link
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id", // Seu ID externo para o link, se você forneceu um.
  "data": { 
    // Conteúdo do webhook. Para mais informações, consulte a documentação relativa ao tipo de Webhook.
    
  }
}

Parâmetro	Obrigatório	Tipo	Descrição	Exemplo
`webhook_id`	sim	string	O ID do webhook da Belvo.	`aadf41a1fc8e4f79a49f7f04027ac999`
`webhook_type`	sim	string	O recurso ao qual este webhook se refere.	`ACCOUNTS`
`process_type`	sim	string	O parâmetro `process_type` indica por que o evento de webhook foi acionado. Retornamos um dos seguintes valores: `historical_update`: O webhook foi acionado quando terminamos uma atualização histórica para a recuperação de dados (para links recorrentes e para links únicos com fetch_resources). `recurrent_update`: O webhook foi acionado devido à atualização recorrente (cíclica) dos dados. `async_post`: O webhook foi acionado quando a recuperação assíncrona de dados de uma chamada POST foi concluída.	`ACCOUNTS`
`webhook_code`	sim	string	O evento que acionou o webhook.	`STATUS_UPDATE`
`external_id`	sim	string	O identificador único que você forneceu ao criar o objeto. Para cobranças e transações, este campo sempre retornará `null`.	`c3c51aaf-aaa3-400c-926d-87ab62e195fd`
`data`	sim	object	Um objeto contendo dados específicos sobre o evento. Os campos retornados neste objeto dependem do `webhook_type` e `webhook_code`. Para informações sobre os dados específicos de um determinado webhook, consulte a página dedicada para cada recurso.	`{}`

Eventos de erro de webhook

Às vezes, ao recuperar informações de uma instituição, pode ocorrer um erro. Nesse caso, o objeto de dados do evento de webhook conterá as informações do erro que ocorreu. Por exemplo:

{
    "webhook_id": "5b82fdf536da43039c69a4305ecb1ceb",
    "webhook_type": "ACCOUNTS",
    "webhook_code": "historical_update",
    "link_id": "c7ba4551-ed8d-46ee-9b67-c864a77d6381",
    "external_id": "your_external_id",
    "data": {
        "errors": [ // Detalhes do erro que ocorreu
            {
              "code": "service_unavailable",
              "message": "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution"
            }
        ]
    }
}

Política de Retentativa

Se a Belvo chamar inicialmente o seu servidor e não receber um código de status HTTP 2XX, tentaremos novamente cinco vezes usando um backoff linear para permitir que o seu servidor se recupere de qualquer mau funcionamento.

Melhores Práticas de Webhook

Responder a webhooks

Assim que você receber um webhook da Belvo, certifique-se de responder com o código de status HTTP 2XX. Se não recebermos uma resposta 2XX do seu servidor, tentaremos novamente cinco vezes usando um backoff linear para permitir que seu servidor se recupere de qualquer mau funcionamento.

Lista de permissões para endereços IP de saída

Lista de Permissões para Endereços IP

Recomendamos fortemente que você adicione esses endereços IP à lista de permissões para que possa receber eventos de webhook.

Você pode receber eventos de webhook dos seguintes endereços IP:

3.130.254.46
18.220.61.186
18.223.45.212

Testando eventos de webhook

Você pode acionar qualquer tipo de evento de webhook (incluindo eventos de link) a partir do seu Dashboard Belvo. Uma vez acionado, você receberá um payload com dados fictícios. Esta é uma excelente maneira de testar se você pode receber webhooks, se configurou corretamente sua autenticação (se necessário) e agir sobre os vários tipos de eventos.

Para acionar um evento:

No Environment Switcher no seu dashboard Belvo, selecione o ambiente em que você deseja testar seu webhook.
Selecione a aba Webhooks.
Clique no menu suspenso ao lado da URL do webhook Sandbox que você deseja testar.
Selecione o tipo de evento de webhook que você deseja. Isso envia o webhook.
Expanda a caixa de status para ver os detalhes do evento de webhook.

accounts

Atualização histórica

Assim que seu link bancário for criado, carregamos assincronamente as contas disponíveis para o link e enviaremos o seguinte webhook:

Código do Webhook	Descrição
historical_update	O número total de contas encontradas para o link.

No payload do webhook, incluímos o número de contas encontradas para o link.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "ACCOUNTS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_accounts": 5 // Número total de contas encontradas.
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET 'https://api.belvo.com/api/accounts/?link=link_id' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

Novas contas disponíveis

De acordo com a taxa de atualização escolhida, a Belvo irá recuperar dados de forma assíncrona sobre quaisquer novas contas que tenham aparecido para o link fornecido desde a última atualização.

Código do Webhook	Descrição
`new_accounts_available`	O número de novas contas encontradas na instituição desde a última atualização.

No payload do webhook, incluímos o número de novas contas encontradas para o link.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "ACCOUNTS",
  "process_type": "recurrent_update",
  "webhook_code": "new_accounts_available",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "new_accounts": 1 // Novas contas encontradas para o link
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET 'https://api.belvo.com/api/accounts/?link=link_id' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

bills

Atualização histórica

Assim que seu link bancário recorrente for criado, carregamos assincronamente as contas disponíveis para o link e enviaremos o seguinte webhook:

Código do Webhook	Descrição
historical_update	O número total de contas encontradas para o link.

No payload do webhook, incluímos o número de contas encontradas para o link.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "BILLS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_bills": 2 // Número total de contas
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET 'https://api.belvo.com/api/bills/?link=link_id' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

Novas contas disponíveis

Código do Webhook	Descrição
`new_bills_available`	O número de novas contas encontradas na instituição desde a última atualização.

No payload do webhook, incluímos o número de novas contas encontradas para o link.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "BILLS",
  "process_type": "recurrent_update",
  "webhook_code": "new_bills_available",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "new_bills": 1 // Número de novas contas
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET 'https://api.belvo.com/api/bills/?link=link_id&created_at__range=date1,date2' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`
`created_at__range`	O intervalo de datas que você deseja receber os empregos. Recomendamos que `date1` seja a data em que você recebeu anteriormente uma notificação e `date2` seja a data em que você recebe a notificação atual (ambas no formato `YYYY-MM-DD`).	`2024-05-01,2024-06-01`

consents

Disponível apenas para links recorrentes

Você só receberá eventos de webhook CONSENT para links recorrentes.

Consentimento prestes a expirar

Opt-in para receber webhooks de consentimento prestes a expirar

Se você deseja receber webhooks para consentimentos que estão prestes a expirar, entre em contato com nossa equipe de suporte.

Você pode receber um evento openfinance_consent_about_to_expire quando o consentimento para um dos seus links OFDA estiver prestes a expirar dentro de sete dias da atualização recorrente do link.

Por exemplo, se você tiver uma taxa de atualização mensal para um link que renova no segundo dia de cada mês, e a data de expiração do consentimento do link for o sexto dia desse mês, você receberá um evento openfinance_consent_about_to_expire. No entanto, se você tiver outro link que renova no segundo dia de cada mês, mas a data de expiração do consentimento for o décimo dia desse mês, você não receberá um evento.

Solicite ao usuário que renove o consentimento

Assim que você receber este evento, pode solicitar ao usuário que renove seu consentimento usando o My Belvo Portal.

{
  "webhook_id": "37a084ee0741437fa7a95393b5636f7b",
  "webhook_type": "CONSENT",
  "process_type": "recurrent_update",
  "webhook_code": "openfinance_consent_about_to_expire",
  "link_id": "da9822bb-5bd6-4a0a-b64d-0aefcc9e86b0",
  "external_id": null,
  "data": {
    "consent_id": "9e763d19-15a4-410c-a106-18c0f60ca5eb", // O ID do consentimento.
    "consent_due_date": "2024-12-26T10:45:58.000Z", // Timestamp ISO-8601 de quando o consentimento irá expirar.
    "action": "renew", // Uma indicação da ação que você precisa tomar. Para webhooks openfinance_consent_about_to_expire, isso é sempre definido como renew.
    "institution": "ofmockbank_br_retail", // A instituição para a qual o usuário forneceu seu consentimento.
    "institution_display_name": "OF Mockbank", // O nome de exibição da instituição.
    "institution_icon_logo": "https://logo.com" // A URL para o logo da instituição.
  }
}

Consentimento expirado

Você pode receber um evento consent_expired quando o consentimento para um dos seus links OFDA tiver expirado.

Solicite ao seu usuário que renove o consentimento

Assim que você receber este evento, pode solicitar ao seu usuário que renove o consentimento usando o My Belvo Portal.

{
  "webhook_id": "e6f08793f967445fb74ce16beae665bc",
  "webhook_type": "CONSENT",
  "process_type": "recurrent_update",
  "webhook_code": "openfinance_consent_expired",
  "link_id": "3d3364b7-0175-483d-a58b-b471f251e533", // O ID do link associado ao consentimento.
  "external_id": null,
  "data": {
    "consent_id": "29a54e55-21f0-4d02-8e34-797ab7d43940", // O ID do consentimento.
    "action": "renew", // Uma indicação da ação que você precisa tomar. Para webhooks openfinance_consent_expired, isso é sempre definido como renew.
    "institution": "ofmockbank_br_retail", // A instituição para a qual o usuário forneceu seu consentimento.
    "institution_display_name": "OF Mockbank", // O nome de exibição da instituição.
    "institution_icon_logo": "https://logo.com" // A URL para o logotipo da instituição.
  }
}

Assim que você receber a notificação, pode solicitar ao seu usuário que renove o consentimento usando o My Belvo Portal.

Consentimento revogado

Você pode receber um evento openfinance_consent_with_unrecoverable_resources quando um consentimento foi revogado devido aos recursos pré-existentes estarem indisponíveis. Um exemplo de quando você pode receber este evento é quando um usuário concedeu seu consentimento para acessar várias contas e, em uma data posterior, fechou essas contas.

{
  "webhook_id": "e6f08793f967445fb74ce16beae665bc",
  "webhook_type": "CONSENT",
  "process_type": "recurrent_update",
  "webhook_code": "openfinance_consent_with_unrecoverable_resources",
  "link_id": "da9822bb-5bd6-4a0a-b64d-0aefcc9e86b0",
  "external_id": null,
  "data": {
    "consent_id": "29a54e55-21f0-4d02-8e34-797ab7d43940", // O ID do consentimento.
    "institution": "ofmockbank_br_retail", // A instituição para a qual o usuário forneceu seu consentimento.
    "message": "The consent was revoked because it was unrecoverable" // Mensagem de erro sobre o consentimento revogado.
  }
}

Consentimento temporariamente indisponível

Você pode receber um evento openfinance_consent_with_temporarily_unavailable_resources quando um consentimento está temporariamente indisponível devido aos recursos pré-existentes estarem indisponíveis. Um exemplo de quando isso pode ocorrer é quando o usuário concedeu seu consentimento para acessar uma determinada conta, mas não usou essa conta por um tempo (o número de dias até que uma conta seja marcada como inativa depende de cada instituição).

{
  "webhook_id": "745156bbbd0d47b0a33ff995d7b4e5d8",
  "webhook_type": "CONSENT",
  "process_type": "recurrent_update",
  "webhook_code": "openfinance_consent_with_temporarily_unavailable_resources",
  "link_id": "da9822bb-5bd6-4a0a-b64d-0aefcc9e86b0",
  "external_id": null,
  "data": {
    "consent_id": "29a54e55-21f0-4d02-8e34-797ab7d43940", // O ID do consentimento.
    "institution": "ofmockbank_br_retail", // A instituição para a qual o usuário forneceu seu consentimento.
    "message": "The consent is temporarily unusable" // Mensagem de erro sobre o consentimento temporariamente indisponível.
  }
}

employment-metrics

Atualização histórica

Assim que seu link de emprego for criado (para SAT México) e você tiver adicionado EMPLOYMENT_METRICS à lista de recursos em fetch_resources, calculamos assincronamente as métricas de emprego para o link e enviaremos o seguinte webhook:

Código do Webhook	Descrição
historical_update	O número total de métricas de emprego geradas para o link.

No payload do webhook, incluímos o número de métricas de emprego encontradas para o link.

{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "EMPLOYMENT_METRICS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_employment_metrics": 1 // O número total de relatórios de métricas de emprego gerados
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET 'https://api.belvo.com/api/employment-metrics/?link=link_id' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

employment-records

Atualização histórica

Assim que seu link de emprego for criado (para SAT México), calculamos assincronamente as métricas de emprego para o link e enviaremos o seguinte webhook:

Código do Webhook	Descrição
historical_update	O número total de registros de emprego encontrados para o link.

No payload do webhook, incluímos o número de faturas encontradas para o link.

{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "EMPLOYMENT_RECORDS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_employment_record_profiles": 1 // O número total de perfis de registros de emprego encontrados para o link
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET 'https://api.belvo.com/api/employment-records/?link=link_id' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

Alterações no status de emprego

Interessado em acessar este novo recurso?

Entre em contato com nossa equipe, e eles ajudarão você a configurar!

De acordo com a taxa de atualização escolhida, a Belvo recuperará de forma assíncrona dados sobre quaisquer novas alterações no emprego que tenham aparecido para o link fornecido desde a última atualização.

Código do Webhook	Descrição
employment_changes	Uma lista de alterações de emprego que ocorreram para o link.

No payload do webhook, incluímos as alterações de emprego identificadas para o link.

{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "EMPLOYMENT_RECORDS",
  "process_type": "recurrent_update",
  "webhook_code": "employment_changes",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "employment_changes": ["EMPLOYED", "SALARY_INCREASED"] // Lista de alterações desde a última verificação
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET 'https://api.belvo.com/api/employment-records/?link=link_id' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

Opções de mudança de emprego

Na sua frequência de atualização definida, a Belvo extrairá novas informações de emprego para o seu link e comparará o status de emprego e as informações salariais com a extração de dados anterior.

Frequência de atualização recomendada

Recomendamos uma frequência de atualização mínima de dois meses. No entanto, entre em contato com nossa equipe e eles poderão aconselhá-lo melhor dependendo do seu caso de uso.

No data.employment_changes array do webhook, você pode receber uma ou mais das seguintes mudanças de emprego:

Mudança	Descrição
`UNEMPLOYED`	O funcionário estava empregado, mas foi demitido ou se demitiu do empregador.
`EMPLOYED`	O funcionário estava desempregado na última verificação e agora está empregado.
`EMPLOYEE_CHANGED_JOBS`	O funcionário mudou de emprego.
`SALARY_INCREASE`	O salário do funcionário aumentou pelo menos 10% desde a última verificação.
`SALARY_DECREASE`	O salário do funcionário diminuiu pelo menos 10% desde a última verificação.

Você pode receber mais de uma mudança no data.employment_changes array, dependendo da situação. Por exemplo, se uma pessoa mudou de emprego e agora está recebendo um salário mais alto, então no data.employment_changes array você receberá:

{
  "data": {
    "employment_changes": ["EMPLOYEE_CHANGED_JOBS", "SALARY_INCREASE"]
  }
}

Cenários com registros excluídos ou ausentes

A Belvo envia notificações de emprego após comparar os dados recém-obtidos com os dados obtidos anteriormente. No entanto, pode haver casos em que atualizamos um link de emprego que não possui nenhum dado de registro de emprego no banco de dados da Belvo. Nesses casos, você ainda receberá um employment_changes webhook. No entanto, como a Belvo verifica os dados recém-retornados em relação a dados inexistentes no banco de dados da Belvo, neste caso, você receberá uma das seguintes combinações de alterações de emprego:

Caso quando atualizado	Valores
Usuário está empregado	`EMPLOYED`, `EMPLOYEE_CHANGED_JOBS`, `SALARY_INCREASE`
Usuário está desempregado	`UNEMPLOYED`

Isso pode ocorrer devido a qualquer um dos seguintes motivos:

Ao criar um link, você define `stale_in` para um período menor que sua taxa de atualização.

Ao criar um link, você pode opcionalmente adicionar o parâmetro stale_in para controlar por quanto tempo o Belvo armazena dados derivados do usuário. O período é relativo ao timestamp last_updated_at do link (a última vez que a conta do usuário foi acessada).

Por exemplo, se você definir stale_in para 62 dias ao criar um link em 01.03.2024, os dados serão armazenados no banco de dados do Belvo por 62 dias após essa data. Se então, para o mesmo link, você acessar os dados um mês depois (01.04.2024), a contagem é reiniciada e o Belvo excluirá os dados 62 dias após 01.04.2024.

No entanto, se você definir um período stale_in menor que sua taxa de atualização, o Belvo excluirá os dados antes da próxima atualização. Como resultado, os novos dados retornados serão comparados com dados inexistentes, acionando um webhook employment_changes com os status mencionados acima.

Para evitar isso, você pode:

Não passar o parâmetro stale_in (que por padrão é 365 dias).
Definir um valor stale_in que seja maior que sua taxa de atualização. Por exemplo, se você tiver um período de atualização de 60 dias, então seu parâmetro stale_in deve ser definido para pelo menos 62 dias.

Ao fazer um POST para Recuperar registros de emprego, defina `save_data` como `false`.

Ao recuperar dados de registros de emprego usando o Recuperar detalhes do registro de emprego, definir save_data como false impede que a Belvo armazene os dados. Consequentemente, quaisquer dados recém-recuperados serão comparados com dados inexistentes, resultando no webhook employment_changes mencionado acima.

Para evitar isso, recomendamos que você defina save_data como true.

Dados de registro de emprego excluídos

Se você excluir dados de registro de emprego usando a solicitação Excluir um registro de emprego, todos os dados dessa entrada de emprego serão removidos do banco de dados da Belvo. Durante a próxima atualização, a Belvo compara os novos dados com os dados excluídos (inexistentes), resultando no employment_changes webhook mencionado acima.

Não havia dados na extração inicial dos dados de registro de emprego

No caso de uma recuperação anterior de registro de emprego não ter sido bem-sucedida, pois não havia dados para o usuário na instituição (resultando na API retornando uma resposta vazia) ou a instituição de emprego estava sem resposta, durante a próxima atualização, a Belvo compara os novos dados com os dados inexistentes, resultando no employment_changes webhook mencionado acima.

employments-brazil

Atualização histórica

Assim que seu link bancário recorrente for criado, carregamos assincronamente as informações de emprego disponíveis para o link e enviaremos o seguinte webhook:

Código do Webhook	Descrição
historical_update	O número total de empregos encontrados para o link.

No payload do webhook, incluímos o número de empregos encontrados para o link.

{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "EMPLOYMENTS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_employments": 1 // O número total de perfis de registro de emprego encontrados para o link
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET 'https://api.belvo.com/api/br/employments/?link=link_id' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

Novos empregos disponíveis

De acordo com a taxa de atualização escolhida, a Belvo irá recuperar dados de forma assíncrona sobre quaisquer novos empregos que tenham aparecido para o link fornecido desde a última atualização.

Código do Webhook	Descrição
`new_employments_available`	O número de novos empregos encontrados desde a última atualização.

No payload do webhook, incluímos o número de novos empregos encontrados para o link.

{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "EMPLOYMENTS",
  "process_type": "recurrent_update",
  "webhook_code": "new_employments_available",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "new_employments": 1 // Número de novos empregos encontrados desde o último evento
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET 'https://api.belvo.com/api/br/employments/?link=link_id&created_at__range=date1,date2' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`
`created_at__range`	O intervalo de datas para o qual você deseja receber os empregos. Recomendamos que `date1` seja a data em que você recebeu uma notificação anteriormente e `date2` seja a data em que você recebe a notificação atual (ambas no formato `YYYY-MM-DD`).	`2024-05-01,2024-06-01`

financial-statements-mexico

Atualização histórica

Assim que seu link fiscal for criado, carregamos assincronamente os últimos três anos de demonstrações financeiras e enviaremos o seguinte webhook:

Código do Webhook	Descrição
historical_update	Os últimos três anos de demonstrações financeiras.

No payload do webhook, incluímos o número de demonstrações financeiras recebidas.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "FINANCIAL_STATEMENTS",
  "webhook_code": "historical_update",
  "process_type": "historical_update",
  "link_id": "2f8ca7a1-c28f-46f2-bb41-21633099a280",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "COHORT_32_User_6790023X5",
  "data": {
    "new_financial_statements": 3
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/financial-statements/?link=link_id'

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

Novas demonstrações financeiras disponíveis

Aplicável apenas para chamadas POST assíncronas

Quando você faz uma solicitação "ad hoc" para demonstrações financeiras (com o cabeçalho X-Belvo-Request-Mode: async), a Belvo irá recuperar de forma assíncrona as informações da demonstração financeira e enviar o seguinte webhook:

Código do Webhook	Descrição
`new_financial_statements_available`	O número de novas demonstrações financeiras encontradas para o link.

No payload do webhook, incluímos o número de novas demonstrações financeiras encontradas para o link.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "FINANCIAL_STATEMENTS",
  "webhook_code": "new_financial_statements_available",
  "process_type": "async_post",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "COHORT_32_User_6790023X5",
  "data": {
    "new_financial_statements": 1
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/financial-statements/?link=link_id'

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

Erros ao extrair Demonstrações Financeiras

Para fornecer maior visibilidade sobre a extração de dados de Demonstrações Financeiras, incluímos um novo campo error no payload de resposta para cada demonstração financeira que você receberá.

Se, para um determinado ano em que uma demonstração financeira está disponível, não conseguirmos recuperar os dados devido à instituição não fornecer as informações no formato correto, o campo error indicará o motivo da extração malsucedida:

[
  {
    "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
    "link": "30cb4806-6e00-48a4-91c9-ca55968576c8",
    "collected_at": "2022-02-09T08:45:50.406032Z",
    "created_at": "2022-02-09T08:45:50.406032Z",
    "error": "Unable to validate if the user has an available financial statement for the specified year.",
    "year": 2020,
    "currency": "MXN",
    "balance_sheet": null,
    "income_statement": null
  }
]

As possíveis mensagens de erro são:

Unable to validate if the user has an available financial statement for the specified year.
No available financial statement found for the user for the specified year, preventing data extraction.
Unable to verify if the user has _conceptos vigentes_ for the specified year.
The fiscal institution provided the financial statement in an unrecognized format.

Se você receber payloads de demonstrações financeiras com esses erros, por favor, entre em contato com nossa equipe de suporte.

incomes

Atualização histórica

Assim que seu link bancário for criado e você tiver adicionado INCOMES à lista de recursos em fetch_resources, calculamos de forma assíncrona os dados de renda para o link e enviaremos o seguinte webhook:

Código do Webhook	Descrição
historical_update	O número total de rendas e fluxos de renda identificados para o link.

No payload do webhook, incluímos o número de rendas e fluxos de renda identificados para o link.

{
  "webhook_id": "75f0c2ca92e64f228da04cc7f5039c03",
  "webhook_type": "INCOMES",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_incomes": 1, // Sempre = 1, Indica que a análise está pronta para recuperação.
    "number_of_income_streams": 5, // Número total de fluxos de renda identificados.
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET 'https://api.belvo.com/api/incomes/?link=link_id' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

investment-transactions

Atualização histórica

Assim que seu link bancário for criado, carregamos assincronamente as transações de investimento disponíveis para o link e enviaremos o seguinte webhook:

Código do Webhook	Descrição
historical_update	O número total de transações de investimento para o link no último ano.

No payload do webhook, incluímos o número de transações de investimento encontradas para o link (incluindo o número de transações de entrada e saída), bem como o intervalo de datas ao qual a informação se aplica.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "INVESTMENT_TRANSACTIONS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_transactions": 19, // Número total de transações encontradas
    "total_inflow_transactions": 10, // Número total de transações de entrada
    "total_outflow_transactions": 9, // Número total de transações de saída
    "first_transaction_date": "2023-01-03", // Data da primeira transação
    "last_transaction_date": "2024-01-03" // Data da última transação
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/br/investment-transactions/?link=link_id'

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

Você pode adicionar mais filtros para restringir os resultados, por exemplo:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/br/investment-transactions/?link=link_id&type=INFLOW'

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`
`type`	O tipo de transação. Pode ser `INFLOW` ou `OUTFLOW`.	`INFLOW`

Novas transações disponíveis

De acordo com a taxa de atualização escolhida, a Belvo irá recuperar assincronamente dados sobre quaisquer novas transações de investimento que tenham aparecido para o link fornecido desde a última atualização.

Definimos novas transações de investimento como transações encontradas na instituição para um determinado link desde a última atualização. Por exemplo, estas podem ser novas transações de investimento das últimas 24 horas ou novas transações de investimento de alguns dias atrás que foram apenas recentemente adicionadas pela instituição.

Código do Webhook	Descrição
`new_investment_transactions_available`	O número de novas transações de investimento encontradas na instituição desde a última atualização.

No payload do webhook, incluímos o número de novas transações encontradas para o link.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "INVESTMENT_TRANSACTIONS",
  "process_type": "recurrent_update",
  "webhook_code": "new_investment_transactions_available",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "new_investment_transactions": 19 // Número de novas transações encontradas desde o último evento
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/br/investment-transactions/?link=link_id&type=INFLOW&created_at__range=date1,date2'

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`
`created_at__range`	O intervalo de datas para o qual você deseja receber transações. Recomendamos que `date1` seja a data em que você recebeu anteriormente uma notificação e `date2` seja a data em que você recebe a notificação atual (ambas no formato `YYYY-MM-DD`).	`2024-05-01,2024-06-01`

investimentos

Atualização histórica

Assim que seu link bancário for criado, carregamos assincronamente as contas de investimento disponíveis para o link e enviaremos o seguinte webhook:

Código do Webhook	Descrição
historical_update	O número total de contas de investimento encontradas para o link.

No payload do webhook, incluímos o número de contas de investimento encontradas para o link.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "INVESTMENTS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_investments": 5 // Número total de contas de investimento encontradas.
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET 'https://api.belvo.com/api/br/investments/?link=link_id' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

Novo investimento disponível

De acordo com a taxa de atualização escolhida, a Belvo irá recuperar de forma assíncrona dados sobre quaisquer novas contas de investimento que tenham aparecido para o link fornecido desde a última atualização.

Código do Webhook	Descrição
`new_investments_available`	O número de novas contas encontradas na instituição desde a última atualização.

No payload do webhook, incluímos o número de novas contas encontradas para o link.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "INVESTMENTS",
  "process_type": "recurrent_update",
  "webhook_code": "new_investments_available",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "new_investments": 1 // Novas contas de investimento encontradas para o link
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET 'https://api.belvo.com/api/br/investments/?link=link_id' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

invoices

Atualizações iniciais

Assim que seu link fiscal recorrente for criado, carregamos assincronamente os últimos 30 dias de histórico de faturas. Você receberá duas notificações via um webhook sempre que os últimos 30 dias de faturas estiverem disponíveis para você acessar.

Código do Webhook	Descrição
`initial_inflow_update`	Os últimos 30 dias de faturas de ENTRADA (recebidas).
`initial_outflow_update`	Os últimos 30 dias de faturas de SAÍDA (enviadas).

Incluímos o número de faturas encontradas durante este período para o tipo de fatura, bem como as datas da primeira e última fatura no intervalo.

{
  "webhook_id": "ccc9c589bfcb44bc99ce749229ccf142",
  "webhook_type": "INVOICES",
  "process_type": "historical_update",
  "webhook_code": "initial_inflow_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_invoices": 3456,
    "first_invoice_date": "2021-04-05",
    "last_invoice_date": "2021-05-05"
  }
}

{
  "webhook_id": "ccc9c589bfcb44bc99ce749229ccf578",
  "webhook_type": "INVOICES",
  "process_type": "historical_update",
  "webhook_code": "initial_outflow_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "data": {
    "total_invoices": 3456,
    "first_invoice_date": "2021-04-05",
    "last_invoice_date": "2021-05-05"
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/invoices/?type=INFLOW&link=link_id&invoice_date__range=first_invoice_date,last_invoice_date'

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/invoices/?type=OUTFLOW&link=link_id&invoice_date__range=first_invoice_date,last_invoice_date'

Parâmetro de Consulta	Descrição	Exemplo
`type`	O tipo de fatura. Pode ser `INFLOW` ou `OUTFLOW`. Se você receber um webhook `initial_inflow_update`, isso deve ser definido como `INFLOW`. Se você receber um webhook `initial_outflow_update`, isso deve ser definido como `OUTFLOW`.	`INFLOW`
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`
`invoice_date__range`	O intervalo de datas para o qual você deseja obter faturas. Este deve ser o `first_invoice_date` e `last_invoice_date` que você recebeu na notificação do webhook.	`2017-07-31,2018-07-31`

Atualizações históricas

Assim que seu link fiscal recorrente for criado, carregamos assincronamente os últimos três anos de histórico de notas fiscais de ENTRADA e SAÍDA para SAT. Você receberá até 6 notificações via um webhook sempre que o histórico de notas fiscais estiver disponível para você acessar. Para cada ano que a Belvo extrai dados, você receberá os seguintes webhooks:

Código do Webhook	Descrição
`historical_inflow_update`	O último 1 ano de notas fiscais de ENTRADA (recebidas).
`historical_outflow_update`	O último 1 ano de notas fiscais de SAÍDA (enviadas).

No payload do webhook, incluímos o número de notas fiscais encontradas durante este período para o tipo de nota fiscal, bem como as datas da primeira e última nota fiscal no intervalo.

{
  "webhook_id": "ccc9c589bfcb44bc99ce749229ccf142",
  "webhook_type": "INVOICES",
  "process_type": "historical_update",
  "webhook_code": "historical_inflow_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_invoices": 5333, // Número total de notas fiscais encontradas
    "first_invoice_date": "2017-07-31", // Primeira nota fiscal de entrada encontrada
    "last_invoice_date": "2018-07-31" // Última nota fiscal de entrada encontrada
  }
}

{
  "webhook_id": "1ac2917cb25f4e38af9260c0782d3408",
  "webhook_type": "INVOICES",
  "process_type": "historical_update",
  "webhook_code": "historical_outflow_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "data": {
    "total_invoices": 1000,
    "first_invoice_date": "2017-07-31",
    "last_invoice_date": "2018-07-31"
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/invoices/?type=INFLOW&link=link_id&invoice_date__range=first_invoice_date,last_invoice_date'

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/invoices/?type=OUTFLOW&link=link_id&invoice_date__range=first_invoice_date,last_invoice_date'

Parâmetro de Consulta	Descrição	Exemplo
`type`	O tipo de nota fiscal. Pode ser `INFLOW` ou `OUTFLOW`. Se você receber um webhook `historical_inflow_update`, isso deve ser definido como `INFLOW`. Se você receber um webhook `historical_outflow_update`, isso deve ser definido como `OUTFLOW`.	`INFLOW`
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`
`invoice_date__range`	O intervalo de datas para o qual você deseja obter notas fiscais. Este deve ser o `first_invoice_date` e `last_invoice_date` que você recebeu na notificação do webhook.	`2017-07-31,2018-07-31`

Novas faturas disponíveis

De acordo com a taxa de atualização escolhida, a Belvo irá recuperar de forma assíncrona dados sobre quaisquer novas faturas que tenham aparecido no sistema SAT para um determinado link desde a última atualização.

Código do Webhook	Descrição
`new_invoices_available`	Uma lista de novas faturas que foram recuperadas desde a última atualização.

Você pode receber uma notificação new_invoices_available sempre que novas faturas estiverem disponíveis para um link fiscal recorrente. Você pode receber mais de um evento de webhook para um link ao mesmo tempo, dependendo do tipo de faturas encontradas. Por exemplo, você pode receber um evento de webhook para faturas de INFLOW e outro separado para faturas de OUTFLOW.

Definimos novas faturas como todas as novas faturas encontradas na instituição para este link desde nossa última atualização. Por exemplo, se você tiver uma taxa de atualização diária, podem ser as novas faturas das últimas 24 horas ou faturas adicionadas pela instituição nas últimas 24 horas para dias anteriores.

No payload do webhook, incluímos o número de faturas encontradas desde a última atualização, o tipo de faturas (INFLOW ou OUTFLOW), bem como um array de ids de faturas.

{
  "webhook_id": "28364bef400f4374a80872b61ba204289",
  "webhook_type": "INVOICES",
  "process_type": "recurrent_update",
  "webhook_code": "new_invoices_available",
  "link_id": "0284557b-df47-450a-po09e-7875195c2259",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "count": 5,
    "type": "INFLOW",
    "new_invoices": [
      // Um array de IDs de faturas
      "7d0afe4c-373d-490c-90e4-06xx4cdd4a17",
      "a53759bc-ca02-46f0-b1d5-31xxcd54db41",
      "64ecc7df-f322-4934-82f5-3b3ae675ef4a",
      "0452ae0d-ax2f-4093-888c-bb2ae826xa0b",
      "9c266fff-ee3d-4389-adb3-1c5690d3c032"
    ]
  }
}

Assim que você receber a notificação, poderá obter mais detalhes sobre as novas faturas fazendo a seguinte solicitação:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/invoices/?link=link_id&id__in=invoice_id_1,invoice_id_2,invoice_id_3'

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`
`id__in`	A lista de `id`s de faturas que você recebeu no `data.new_invoices` da notificação do webhook.	`24ccab1d-3a86-4136-a6eb-e04bf52b356f,beb2b197-3cf7-428d-bef3-f415c0d57509`

Cancelled invoices

De acordo com a taxa de atualização escolhida, a Belvo irá recuperar de forma assíncrona dados sobre quaisquer faturas canceladas que tenham aparecido no sistema SAT para um determinado link desde a última atualização.

Webhook Code	Descrição
`invoices_cancelled`	Uma lista de faturas canceladas que foram recuperadas desde a última atualização.

Definimos faturas canceladas como todas as faturas existentes com um novo status "cancelado" na instituição para este link

No payload do webhook, incluímos o tipo de faturas canceladas (INFLOW ou OUTFLOW) assim como um array de ids de faturas.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "INVOICES",
  "process_type": "recurrent_update",
  "webhook_code": "invoices_cancelled",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "type": "INFLOW",
    "cancelled_invoices": [
      // Um array de IDs de faturas
      "0a362860-c92f-4414-a731-a772e88ab54b",
      "0a376126-c23r-2131-b745-a876d77cd76c"
    ]
  }
}

Assim que você receber a notificação, poderá obter mais detalhes sobre as faturas canceladas fazendo a seguinte solicitação:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/invoices/?link=link_id&id__in=invoice_id_1,invoice_id_2,invoice_id_3'

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`
`id__in`	A lista de `id`s de faturas que você recebeu no `data.cancelled_invoices` da notificação do webhook.	`24ccab1d-3a86-4136-a6eb-e04bf52b356f,beb2b197-3cf7-428d-bef3-f415c0d57509`

links

Widget Update Mode

Recomendamos fortemente que você use nosso Connect Widget com Update Mode após receber um evento de webhook de Link para lidar com a atualização de credenciais ou token.

Credenciais inválidas

Você pode receber uma notificação invalid_credentials sempre que as credenciais de um usuário não forem mais válidas para atualizar um link recorrente. Isso pode acontecer quando um usuário altera suas credenciais bancárias.

Assim que você receber essa notificação, pode pedir ao seu usuário para atualizar sua nova senha usando o hosted widget no Modo de Atualização. Assim que as credenciais estiverem corretas, o link recorrente é atualizado.

Se você não estiver usando o Connect Widget, pode pedir ao seu usuário para enviar a nova senha e, em seguida, realizar uma solicitação de Atualização de Link para salvar a nova senha. Por exemplo, se você receber o seguinte webhook:

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "LINK",
  "process_type": "recurrent_update",
  "webhook_code": "invalid_credentials",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "error_code": "login_error", // Erro do evento Webhook
    "error_message": "Invalid credentials provided to login to the institution", // Mensagem descritiva do erro
    "status": 400
  }
}

Assim que você receber as credenciais necessárias do seu usuário, faça uma solicitação PUT para o nosso endpoint Links com os detalhes atualizados:

curl -X PUT https://api.belvo.com/api/links/{id} \
  -H 'Content-Type: application/json' \
  -H 'Host: api.belvo.com' \
  -H 'cache-control: no-cache' \
  -d '{
      "password": "{user_provided_password}"
  }' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Onde:

{id} é o link_id que você recebe na notificação do webhook.
{user_provided_password} é a senha atualizada que você recebe do seu usuário.

Link deletado

Quando você usa o cabeçalho X-Belvo-Request-Mode: async da Belvo ao solicitar a Exclusão de um Link, a Belvo excluirá de forma assíncrona todos os dados associados a esse link (por exemplo: transações, contas, faturas, declarações de impostos, empregos, etc.). Assim que o processo for concluído, você receberá um evento de webhook link_deleted indicando que o Link e todos os dados associados foram excluídos com sucesso.

Exemplo de Link Deletado

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "LINK",
  "process_type": "async_delete",
  "webhook_code": "link_deleted",
  "link_id": "30cb4806-6e00-48a4-91c9-ca55968576c8",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": null
}

No caso de haver um erro durante o processo de exclusão do Link, você será notificado usando o mesmo código de webhook, mas com detalhes adicionais no campo data indicando que a exclusão do link não foi bem-sucedida e para tentar novamente a solicitação:

Exemplo de Erro na Exclusão do Link

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "LINK",
  "process_type": "async_delete",
  "webhook_code": "link_deleted",
  "link_id": "30cb4806-6e00-48a4-91c9-ca55968576c8",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "error_code": "link_deletion_failed",
    "error_message": "Link deletion failed. Please retry the request."
  }
}

Se você receber um erro mais de duas vezes para um determinado link, entre em contato com nossa equipe de suporte com o request_id.

Token necessário

Você pode receber uma notificação token_required sempre que um novo token MFA for necessário pela instituição para manter o link recorrente funcionando.

Assim que você receber esta notificação, pode pedir ao seu usuário para fornecer um novo token usando o Connect widget em modo de atualização. Assim que o token for fornecido, o link recorrente é atualizado.

Observe que até que o link seja atualizado, a Belvo não enviará nenhum webhook relacionado a este link.

Se você não estiver usando o Connect Widget, pode pedir ao seu usuário para enviar sua nova senha e então realizar uma solicitação de Atualização de Link para fornecer o novo token MFA. Por exemplo, se você receber o seguinte webhook:

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "LINK",
  "process_type": "recurrent_update",
  "webhook_code": "token_required",
  "link_id": "30cb4806-6e00-48a4-91c9-ca55968576c8",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "error_code": "token_required", // Erro do evento Webhook
    "error_message": "MFA token was required by the institution", // Mensagem descritiva do erro
    "status": 428,
    "session": "2675b703b9d4451f8d4861a3eee54449",
    "expiry": 9600,
    "token_generation_data": {
      "instructions": "Use este código para gerar o token",
      "type": "numeric",
      "value": "12345"
    }
  }
}

Assim que você receber as credenciais de token necessárias do seu usuário, faça uma solicitação PATCH para nosso endpoint Links com o token atualizado:

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

Onde:

{sessionId} é a session que você recebe na notificação do webhook.
{userToken} é o novo token que você recebe do seu usuário.
{linkId} é o link_id que você recebe na notificação do webhook.

proprietários

Atualização histórica

Assim que seu link bancário for criado, carregamos de forma assíncrona as informações do proprietário disponíveis para o link e enviaremos o seguinte webhook:

Código do Webhook	Descrição
historical_update	O número total de proprietários encontrados para o link.

No payload do webhook, incluímos o número de proprietários encontrados para o link.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "OWNERS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_owners": 2 // Número total de proprietários
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET 'https://api.belvo.com/api/owners/?link=link_id' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

Novos proprietários disponíveis

De acordo com a taxa de atualização escolhida, a Belvo irá recuperar assincronamente dados sobre quaisquer novas contas que tenham aparecido para o link fornecido desde a última atualização.

Código do Webhook	Descrição
`new_owners_available`	O número de novos proprietários encontrados desde a última atualização.

No payload do webhook, incluímos o número de novos proprietários encontrados para o link.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "OWNERS",
  "process_type": "recurrent_update",
  "webhook_code": "new_owners_available",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "new_owners": 1 // Número de novos proprietários
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET 'https://api.belvo.com/api/owners/?link=link_id' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

despesas-recorrentes

Atualização histórica

Assim que seu link bancário for criado e você tiver adicionado RECURRING_EXPENSES à lista de recursos em fetch_resources, calculamos assincronamente os dados de despesas recorrentes para o link e enviaremos o seguinte webhook:

Código do Webhook	Descrição
historical_update	O número total de despesas recorrentes identificadas para o link.

No payload do webhook, incluímos o número de despesas recorrentes identificadas para o link.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "RECURRING_EXPENSES",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_recurring_expenses": 23 // Contagem de despesas recorrentes identificadas.
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET 'https://api.belvo.com/api/recurring-expenses/?link=link_id' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

risk-insights

Atualização histórica

Assim que seu link bancário for criado e você tiver adicionado RISK_INSIGHTS à lista de recursos em fetch_resources, geramos de forma assíncrona as análises de risco para o link e enviaremos o seguinte webhook:

Código do Webhook	Descrição
historical_update	O número total de análises de risco identificadas para o link.

No payload do webhook, incluímos o número de análises de risco identificadas para o link.

{
  "webhook_id": "58577409546a4247848055e1e11bbc71",
  "webhook_type": "RISK_INSIGHTS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_risk_insights": 1 // Sempre = 1, Indica que a análise está pronta para ser recuperada.
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET 'https://api.belvo.com/api/risk-insights/?link=link_id' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

tax-compliance-status

Atualização histórica

Assim que seu link fiscal for criado, recuperamos de forma assíncrona o documento de Status de Conformidade Fiscal (Opinión de Cumplimiento de Obligaciones Fiscales) e enviaremos o seguinte webhook:

Código do Webhook	Descrição
`historical_update`	O Status de Conformidade Fiscal atual para o usuário.

No payload do webhook, você receberá o número total de documentos de Status de Conformidade Fiscal.

{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "TAX_COMPLIANCE_STATUS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_tax_compliance_status": 1 // O número total de documentos de declaração de conformidade fiscal
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/tax-compliance-status/?link=link_id'

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

retenções-de-impostos

Atualização histórica

Assim que seu link fiscal for criado, carregamos assincronamente o último ano de retenções de impostos e enviaremos o seguinte webhook:

Código do Webhook	Descrição
`historical_update`	O último ano de Retenções de Impostos.

No payload do webhook, incluímos o número total de retenções de impostos encontradas no último ano, juntamente com o intervalo de datas para o qual recuperamos os dados.

{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "TAX_RETENTIONS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_tax_retentions": 1, // O número total de retenções de impostos
    "first_tax_retention_date": "2023-06-01", // A data da primeira retenção de imposto encontrada
    "last_tax_retention_date": "2023-08-20" // A data da última retenção de imposto encontrada
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/tax-retentions/?link=link_id'

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

declarações-de-imposto

Atualização histórica

Assim que seu link fiscal for criado, carregamos assincronamente os últimos cinco anos de declarações de impostos anuais, bem como os 12 meses de declarações de impostos mensais. Você receberá uma notificação historical_update para cada tipo de declaração de imposto (anual e mensal) sempre que o histórico de declarações de impostos estiver disponível para você acessar.

Código do Webhook	Descrição
`historical_update`	Os últimos 5 anos de declarações de impostos anuais.
`historical_update`	Os últimos 12 meses de declarações de impostos mensais.

No payload do webhook, incluímos o tipo de declarações de impostos, o número total de declarações de impostos encontradas, bem como o primeiro e o último ano das declarações de impostos recuperadas.

{
  "webhook_id": "80fa38b7cad34950b210626abd86bfe9",
  "webhook_type": "TAX_RETURNS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "type": "yearly", // either yearly or monthly
    "total_tax_returns": 2, // Total number of tax returns found
    "first_tax_return_year": 2017, // First filed tax return
    "last_tax_return_year": 2018 // Last filed tax return
  }
}

{
  "webhook_id": "80fa38b7cad34950b210626abd866549",
  "webhook_type": "TAX_RETURNS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "type": "monthly", // either yearly or monthly
    "total_tax_returns": 7, // Total number of tax returns found
    "first_tax_return_year": 2017, // First filed tax return
    "last_tax_return_year": 2018 // Last filed tax return
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/tax-returns/?link=link_id&ejercicio__range=first_tax_return_year,last_tax_return_year'

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`
`ejercicio__range`	O intervalo de datas para o qual você deseja obter as declarações de impostos. Este deve ser o `first_tax_return_year` e `last_tax_return_year` que você recebeu na notificação do webhook.	`2017,2020`

Novas declarações de imposto disponíveis

De acordo com a taxa de atualização escolhida, a Belvo irá recuperar de forma assíncrona dados sobre quaisquer novas declarações de imposto que tenham aparecido no sistema SAT para um determinado link desde a última atualização.

Código do Webhook	Descrição
`new_tax_returns_available`	Uma contagem de novas declarações de imposto desde a última atualização.

Você pode receber uma notificação new_tax_returns_available sempre que novas declarações de imposto estiverem disponíveis para um link fiscal recorrente. Você pode receber mais de um evento de webhook para um link ao mesmo tempo, dependendo do tipo de declarações de imposto encontradas. Por exemplo, você pode receber um evento de webhook para declarações de imposto mensais e outro separado para declarações de imposto anuais.

Definimos novas declarações de imposto como todas as novas declarações de imposto encontradas na instituição para este link desde nossa última atualização. Podem ser novas declarações de imposto do último ano ou também declarações de imposto que foram adicionadas pela instituição para anos ou meses anteriores.

No payload do webhook, incluímos o tipo de declarações de imposto (mensal ou anual) bem como o número de declarações de imposto encontradas desde a última atualização.

{
  "webhook_id": "351610c401e34e728900495fda5b970a",
  "webhook_type": "TAX_RETURNS",
  "process_type": "recurrent_update",
  "webhook_code": "new_tax_returns_available",
  "link_id": "331ba983-0cfa-4186-93fc-936f3946cca3",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "type": "yearly", // pode ser anual ou mensal
    "new_tax_returns": 1 // Número total de novas declarações de imposto encontradas
  }
}

{
  "webhook_id": "351610c401e34e728900495fda5b970a",
  "webhook_type": "TAX_RETURNS",
  "process_type": "recurrent_update",
  "webhook_code": "new_tax_returns_available",
  "link_id": "331ba983-0cfa-4186-93fc-936f3946cca3",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "type": "monthly", // pode ser anual ou mensal
    "new_tax_returns": 1 // Número total de novas declarações de imposto encontradas
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/tax-returns/?link=link_id&created_at__range=date1,date2'

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`
`created_at__range`	O intervalo de datas para o qual você deseja receber as declarações de imposto. Recomendamos que `date1` seja a data em que você recebeu anteriormente uma notificação e `date2` seja a data em que você recebe a notificação atual (ambas no formato `YYYY-MM-DD`).	`2024-05-01,2024-06-01`

tax-status

Atualização histórica

Assim que seu link fiscal for criado, recuperamos de forma assíncrona o documento de Situação Fiscal (Constancia de Situación Fiscal) e enviaremos o seguinte webhook:

Código do Webhook	Descrição
`historical_update`	A Situação Fiscal mais recente para o usuário.

No payload do webhook, você receberá o número total de documentos de Situação Fiscal para o usuário, juntamente com a última data em que a Situação Fiscal foi atualizada.

{
  "webhook_id": "03d1ca0d62db4f769488265d141047b7",
  "webhook_type": "TAX_STATUS",
  "webhook_code": "historical_update",
  "process_type": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_tax_status": 1, // Número de situações fiscais
    "last_status_change_date": "1995-08-01" // Ano em que a situação fiscal foi alterada pela última vez
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/tax-status/?link=link_id'

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

transações

Atualização histórica

Assim que seu link bancário for criado, carregamos assincronamente as transações disponíveis para o link e enviaremos o seguinte webhook:

Código do Webhook	Descrição
historical_update	O número total de transações para o link no último ano.

No payload do webhook, incluímos o número de transações encontradas para o link (incluindo o número de transações de entrada e saída), bem como o intervalo de datas ao qual a informação se aplica.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "TRANSACTIONS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_transactions": 19, // Número total de transações encontradas
    "total_inflow_transactions": 10, // Número total de transações de entrada
    "total_outflow_transactions": 9, // Número total de transações de saída
    "first_transaction_date": "2023-01-03", // Data da primeira transação
    "last_transaction_date": "2024-01-03" // Data da última transação
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/transactions/?link=link_id'

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`

Você pode adicionar mais filtros para restringir os resultados, por exemplo:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/transactions/?link=link_id&type=INFLOW&value_date__range=first_transaction_date,last_transaction_date'

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`
`type`	O tipo de transação. Pode ser `INFLOW` ou `OUTFLOW`.	`INFLOW`
`value_date__range`	O intervalo de datas para o qual você deseja obter transações. Este deve ser o `first_transaction_date` e `last_transaction_date` que você recebeu na notificação do webhook.	`2023-01-03,2024-01-03`

Novas transações disponíveis

De acordo com a taxa de atualização escolhida, a Belvo irá recuperar dados de forma assíncrona sobre quaisquer novas transações que tenham aparecido para o link fornecido desde a última atualização.

Definimos novas transações como transações encontradas na instituição para um determinado link desde a última atualização. Por exemplo, estas podem ser novas transações das últimas 24 horas ou novas transações de alguns dias atrás que foram apenas recentemente adicionadas pela instituição.

Código do Webhook	Descrição
`new_transactions_available`	O número de novas transações encontradas na instituição desde a última atualização.

No payload do webhook, incluímos o número de novas transações encontradas para o link.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "TRANSACTIONS",
  "process_type": "recurrent_update",
  "webhook_code": "new_transactions_available",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "new_transactions": 19 // Número de novas transações encontradas desde o último evento
  }
}

Assim que você receber a notificação, poderá obter mais detalhes fazendo a seguinte solicitação:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/transactions/?link=link_id&type=INFLOW&created_at__range=date1,date2'

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`
`created_at__range`	O intervalo de datas para o qual você deseja receber transações. Recomendamos que `date1` seja a data em que você recebeu anteriormente uma notificação e `date2` seja a data em que você recebe a notificação atual (ambas no formato `YYYY-MM-DD`).	`2024-05-01,2024-06-01`

Transação atualizada

Este webhook está disponível para ambos os links únicos e recorrentes

Sempre que a Belvo identifica que uma transação foi atualizada na instituição (por exemplo, uma alteração no campo de descrição ou na data de valor), enviará o seguinte webhook:

Código do Webhook	Descrição
`transactions_updated`	O número de transações atualizadas junto com a lista de IDs de transação.

No payload do webhook, incluímos o número de transações que foram atualizadas junto com uma lista de IDs de transação da Belvo.

{
  "webhook_id": "28364bef400f4374a80872b61ba204289",
  "webhook_type": "TRANSACTIONS",
  "process_type": "recurrent_update",
  "webhook_code": "transactions_updated",
  "link_id": "0284557b-df47-450a-po09e-7875195c2259",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "count": 5, // Número total de transações atualizadas.
    "updated_transactions": [
      "7d0afe4c-373d-490c-90e4-06xx4cdd4a17", // O ID da transação atualizada.
      "a53759bc-ca02-46f0-b1d5-31xxcd54db41",
      "64ecc7df-f322-4934-82f5-3b3ae675ef4a",
      "0452ae0d-ax2f-4093-888c-bb2ae826xa0b",
      "9c266fff-ee3d-4389-adb3-1c5690d3c032"
    ]
  }
}

Assim que você receber a notificação, poderá obter a lista completa de transações para aquele link usando a seguinte chamada:

curl --request GET \
-u [Secret Key ID]:[Secret Key PASSWORD] \
'https://api.belvo.com/api/transactions/?link=link_id&id__in=transaction1,transaction2,transaction3

Parâmetro de Consulta	Descrição	Exemplo
`link`	O `link_id` que você recebeu na notificação do webhook.	`2f5d361d-dad6-45d4-a0bf-26d479766067`
`id__in`	A lista de `id`s de transação que você recebeu no `data.updated_transactions` da notificação do webhook.	`7d0afe4c-373d-490c-90e4-06xx4cdd4a17,53759bc-ca02-46f0-b1d5-31xxcd54db41,64ecc7df-f322-4934-82f5-3b3ae675ef4a`

Alterações que acionam um `transactions_updated` webhook

A Belvo monitora os seguintes campos para todas as transações e, quando detecta uma alteração entre a última vez que os dados foram recuperados e agora, enviará um transactions_updated webhook:

amount
currency
description
value_date
internal_identification
type
status
credit_card_data.bill_internal_identification (somente OFDA)
credit_card_data.credit_card_bill.id (somente OFDA)

Transação excluída

Este webhook está disponível para ambos os links únicos e recorrentes

A Belvo monitora e limpa regularmente os dados transacionais em seu banco de dados para melhorar a consistência dos dados que você recebe. Quando uma transação é identificada como duplicada (o que pode ocorrer, por exemplo, devido a chamadas POST feitas em rápida sucessão para a API para o mesmo link), ela é removida do banco de dados. Nesse caso, você receberá um transactions_deleted webhook com uma lista das transações que foram excluídas.

{
  "webhook_id": "28364bef400f4374a80872b61ba204289",
  "webhook_type": "TRANSACTIONS",
  "process_type": "recurrent_update",
  "webhook_code": "transactions_deleted",
  "link_id": "0284557b-df47-450a-po09e-7875195c2259",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "count": 5, // Número total de transações excluídas.
    "deleted_transactions": [
      "7d0afe4c-373d-490c-90e4-06xx4cdd4a17", // O ID da transação excluída.
      "a53759bc-ca02-46f0-b1d5-31xxcd54db41",
      "64ecc7df-f322-4934-82f5-3b3ae675ef4a",
      "0452ae0d-ax2f-4093-888c-bb2ae826xa0b",
      "9c266fff-ee3d-4389-adb3-1c5690d3c032"
    ]
  }
}

Webhook de Status da Instituição (Externo)

Configure o webhook

Para assinar o webhook de Status da Instituição:

Acesse a página Status da Instituição Belvo.
Clique em Subscribe to Updates.
Na navegação superior, clique no ícone <>.
Na aba de webhooks, forneça as informações necessárias e clique em Subscribe.
4.1 URL onde você deseja receber o webhook
4.2 Um endereço de e-mail para confirmar o URL do webhook.

No diálogo, escolha sobre quais instituições você deseja receber atualizações e clique em Save.

Feito! Confirme Seu Endereço de E-mail

Agora basta confirmar seu endereço de e-mail e você começará a receber eventos de status do webhook para as instituições que selecionou. Mas esperamos que isso não aconteça com frequência 😉.

Payload do Webhook

No payload do webhook que você recebe de statuspage.io, os campos-chave que você deve analisar são:

Campo	Descrição
`incident.name`	Indica a natureza do problema com a instituição.
`incident.status`	O status atual do incidente no momento do webhook. Pode ser: investigating identified monitoring resolved
`components.status`	A gravidade da interrupção da instituição. Pode ser: operational (tudo está funcionando) partial_outage (certas funcionalidades estão indisponíveis) major_outage (instituição está completamente indisponível)
`components.name`	O nome da instituição afetada.

O payload que você recebe é bastante grande, como você pode ver no exemplo de código abaixo. No entanto, se você analisar os campos mencionados acima, terá todas as informações relevantes de que precisa sobre o incidente.

{
   "meta":{
      "unsubscribe":"http://institutions.belvo.com/?unsubscribe=73cj0w1mm121",
      "documentation":"https://help.statuspage.io/knowledge_base/topics/webhook-notifications",
      "generated_at":"2021-04-19T14:46:37.135Z"
   },
   "page":{
      "id":"3h4nklhdf7jr",
      "status_indicator":"major",
      "status_description":"Partial System Outage"
   },
   "incident":{
      "name":"bancoppel_mx_retail: Link creation and existing links operations are showing high error rates", // importante
      "status":"investigating", // importante
      "created_at":"2021-04-19T14:46:34.737Z",
      "updated_at":"2021-04-19T14:46:34.844Z",
      "monitoring_at":"None",
      "resolved_at":"None",
      "impact":"critical",
      "shortlink":"https://stspg.io/74hxzgnrmjnt",
      "scheduled_for":"None",
      "scheduled_until":"None",
      "scheduled_remind_prior":false,
      "scheduled_reminded_at":"None",
      "impact_override":"None",
      "scheduled_auto_in_progress":false,
      "scheduled_auto_completed":false,
      "metadata":{
      },
      "started_at":"2021-04-19T14:46:34.731Z",
      "id":"p3b3zhn5p0pz",
      "page_id":"3h4nklhdf7jr",
      "incident_updates":[
         {
            "status":"investigating",
            "body":"We are currently investigating this issue related to both link creation and POST calls.",
            "created_at":"2021-04-19T14:46:34.841Z",
            "wants_twitter_update":false,
            "twitter_updated_at":"None",
            "updated_at":"2021-04-19T14:46:34.841Z",
            "display_at":"2021-04-19T14:46:34.841Z",
            "deliver_notifications":true,
            "tweet_id":"None",
            "id":"m9dcv76z7jwf",
            "incident_id":"p3b3zhn5p0pz",
            "custom_tweet":"None",
            "affected_components":[
               {
                  "code":"1f4dxgqr6pkg",
                  "name":"🇲🇽 Retail banking - bancoppel_mx_retail",
                  "old_status":"operational",
                  "new_status":"major_outage"
               }
            ]
         }
      ],
      "postmortem_body":"None",
      "postmortem_body_last_updated_at":"None",
      "postmortem_ignored":false,
      "postmortem_published_at":"None",
      "postmortem_notified_subscribers":false,
      "postmortem_notified_twitter":false,
      "components":[
         {
            "status":"major_outage", // importante
            "name":"bancoppel_mx_retail", // importante
            "created_at":"2021-04-13T09:50:24.288Z",
            "updated_at":"2021-04-19T14:46:34.768Z",
            "position":5,
            "description":"None",
            "showcase":true,
            "start_date":"2021-04-13T00:00:00.000Z",
            "id":"1f4dxgqr6pkg",
            "page_id":"3h4nklhdf7jr",
            "group_id":"bqcwjbwjhvjt"
         }
      ]
   }
}

Webhooks de Agregação

Configurar webhooks

Tipos de webhook

Eventos de erro de webhook

Política de Retentativa

Melhores Práticas de Webhook

Responder a webhooks

Lista de permissões para endereços IP de saída

Testando eventos de webhook

accounts

Atualização histórica

Novas contas disponíveis

bills

Atualização histórica

Novas contas disponíveis

consents

Consentimento prestes a expirar

Consentimento expirado

Consentimento revogado

Consentimento temporariamente indisponível

employment-metrics

Atualização histórica

employment-records

Atualização histórica

Alterações no status de emprego

Opções de mudança de emprego

Cenários com registros excluídos ou ausentes

Ao criar um link, você define stale_in para um período menor que sua taxa de atualização.

Ao fazer um POST para Recuperar registros de emprego, defina save_data como false.

Dados de registro de emprego excluídos

Não havia dados na extração inicial dos dados de registro de emprego

employments-brazil

Atualização histórica

Novos empregos disponíveis

financial-statements-mexico

Atualização histórica

Novas demonstrações financeiras disponíveis

Erros ao extrair Demonstrações Financeiras

incomes

Atualização histórica

investment-transactions

Atualização histórica

Novas transações disponíveis

investimentos

Atualização histórica

Novo investimento disponível

invoices

Atualizações iniciais

Atualizações históricas

Novas faturas disponíveis

Cancelled invoices

links

Credenciais inválidas

Link deletado

Token necessário

proprietários

Atualização histórica

Novos proprietários disponíveis

despesas-recorrentes

Atualização histórica

risk-insights

Atualização histórica

tax-compliance-status

Atualização histórica

retenções-de-impostos

Atualização histórica

declarações-de-imposto

Atualização histórica

Novas declarações de imposto disponíveis

tax-status

Atualização histórica

transações

Atualização histórica

Novas transações disponíveis

Transação atualizada

Alterações que acionam um transactions_updated webhook

Transação excluída

Webhook de Status da Instituição (Externo)

Configure o webhook

Payload do Webhook

Ao criar um link, você define `stale_in` para um período menor que sua taxa de atualização.

Ao fazer um POST para Recuperar registros de emprego, defina `save_data` como `false`.

Alterações que acionam um `transactions_updated` webhook