Neste guia, vamos orientá-lo em tudo o que você precisa para extrair dados de emprego sobre seus usuários usando nossa API. Isso inclui:
- Uma visão geral do fluxo de dados
- Gerar um token de acesso ao widget e criar um link
- Obter informações de emprego e do proprietário
Antes de prosseguir com sua integração, certifique-se de que você leu nosso guia de introdução. No guia de introdução, você criará uma conta Belvo, gerará algumas chaves de API sandbox e configurará uma URL de webhook. Para fins de teste e desenvolvimento de sua integração, recomendamos fortemente o uso do ambiente Sandbox sempre que possível.
O tempo médio que leva para a Belvo recuperar dados de emprego de uma instituição de emprego e enviar um evento de webhook para você é de 15 segundos. No entanto, isso pode variar dependendo da capacidade de resposta da instituição e da carga atual de solicitações.
A Belvo usa fluxos de trabalho assíncronos para melhorar o fluxo de dados (veja o diagrama abaixo). Sempre que seu usuário cria com sucesso um link usando o Hosted Widget, a Belvo extrai automaticamente todos os dados de Emprego para você em segundo plano, e assim que tivermos todos os dados, notificamos você via um webhook que os dados estão prontos para serem recuperados (veja as seções WEBHOOK em roxo no diagrama abaixo). Para que possamos notificá-lo assim que os dados estiverem prontos, você precisa fornecer uma URL para onde possamos enviar eventos.
Para que o widget apareça para seus usuários finais, você precisa gerar um token de access no seu servidor e enviá-lo para a Belvo. Assim que recebermos a solicitação, você receberá um objeto com duas chaves: access e refresh. Passe o valor da chave access ao iniciar o hosted widget.
Os valores retornados são válidos por 10 minutos e invalidamos o token assim que um usuário conecta sua conta com sucesso.
Para gerar um token de access, basta fazer uma chamada do seu servidor para a Belvo:
curl -X POST \
https://production.belvo.com/api/token/ \
-H 'Content-Type: application/json' \
-H 'Host: production.belvo.com' \
-d 'veja exemplos de payloads abaixo'{
"id": "YOUR_SECRET_ID",
"password": "YOUR_SECRET_PASSWORD",
"scopes": "read_institutions,write_links",
"stale_in": "365d",
"credentials_storage": "store",
"fetch_resources": ["EMPLOYMENTS", "OWNERS"],
"widget": {
"callback_urls": {
"success": "your_deeplink_here://success",
"exit": "your_deeplink_here://exit",
"event": "your_deeplink_here://error"
},
"branding": {
"company_icon": "https://mysite.com/icon.svg",
"company_logo": "https://mysite.com/logo.svg",
"company_name": "ACME",
"company_terms_url": "https://belvo.com/terms-service/"
},
"theme": [] // See our dedicated widget customization article
}
}| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | sim | Substitua YOUR_SECRET_ID pelo secretID que você gerou no painel da Belvo. |
password | string | sim | Substitua YOUR_SECRET_PASSWORD pelo secretPassword que você gerou no painel da Belvo. |
scopes | string | sim | O parâmetro scopes contém uma lista de permissões que permitem criar um link para o usuário. Este é um parâmetro obrigatório e deve ser enviado exatamente como mostrado. |
stale_in | string | opcional | O parâmetro stale_in permite controlar por quanto tempo a Belvo armazena dados derivados do usuário. Para mais informações, confira a seção stale_in do nosso artigo sobre controles de retenção de dados. |
credentials_storage | string | opcional | O parâmetro credentials_storage permite controlar por quanto tempo a Belvo deve armazenar credenciais para os usuários. Se você criar links recorrentes, isso deve ser configurado como store. Para mais informações, confira a seção credentials_storage do nosso artigo sobre controles de retenção de dados. |
fetch_resources | array de strings | sim | No parâmetro fetch_resources, você fornece uma lista de recursos que deseja que a Belvo recupere de forma assíncrona para o usuário. Para dados de emprego no Brasil, você deve enviar ["EMPLOYMENTS", "OWNERS"]. |
widget.callback_urls | objeto | sim | No objeto callback_urls, você deve adicionar links para onde seu usuário deve ser redirecionado nos seguintes casos:
|
| objeto | sim | No objeto
Você também pode opcionalmente adicionar uma cor de fundo personalizada para quando o widget abrir, bem como desativar a mensagem da Belvo sobre quantas contas foram conectadas. Para mais informações sobre as opções de branding e personalização do widget, confira nosso guia dedicado. |
widget.theme | array de objetos | opcional | Você pode opcionalmente adicionar as cores da sua marca ao widget usando o parâmetro theme. Para mais informações sobre onde essas cores aparecerão no widget, confira a seção dedicada Adicionar cores personalizadas ao widget do nosso guia de Branding. |
Em seguida, você precisará redirecionar seu usuário para o widget em uma webview dentro do seu aplicativo, usando o token access que você recebeu da solicitação /api/token/:
https://widget.belvo.io/
?access_token={access_code}
&locale=pt
&institutions=inss_br_employment
&access_mode=single
&external_id=HJLSI-897809
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
access_token | sim | Substitua access_code pelo token de acesso que você recebeu. |
locale | sim | Para que o hosted widget funcione corretamente para seus usuários no Brasil, você deve definir o parâmetro de consulta locale como pt. |
institutions | não | Com o parâmetro institutions, você pode fornecer uma (ou mais) instituições que devem ser exibidas no widget. No caso de Empregos no Brasil, recomendamos definir este parâmetro como inss_br_employment. |
access_mode | não | Você pode usar o parâmetro access_mode para definir qual tipo de link você deseja criar (single ou recurrent). Por padrão, a Belvo cria links recurrent. |
| altamente recomendado | Você pode adicionar um identificador adicional para ser associado ao link no banco de dados da Belvo. O
|
Além disso, confira nossas seções Iniciando o widget e eventos de callback do nosso guia de Hosted Widget (Multi-Region).
A Belvo agora se conectará à instituição e validará se o CPF fornecido está correto. Uma vez validado e seu link criado, a Belvo carregará os dados de emprego de forma assíncrona. Enviaremos um webhook assim que tivermos recuperado os dados para o link fornecido, e você poderá então extraí-los com uma solicitação get.
Assim que seu link for criado, carregamos assincronamente as informações de emprego disponíveis para o link e enviaremos o seguinte webhook:
{
"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={id}' \
-u SECRET_ID:SECRET_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 |
Assim que seu link for criado, carregamos assincronamente 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_ID:SECRET_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 |