No México? Este guia irá orientá-lo no processo de uso da nossa API para extrair registros de emprego de forma segura e eficiente, permitindo que você verifique o emprego, entenda o histórico de carreira e muito mais.
Neste guia, vamos orientá-lo em tudo o que você precisa para extrair dados de emprego sobre seus usuários usando nosso widget. Isso inclui:
- Uma visão geral do fluxo de dados
- Gerar um token de acesso ao widget e criar um link
- Obter informações do registro de emprego
Este guia menciona atualmente um novo recurso que está em desenvolvimento: Empregos Atuais. Este recurso estará disponível nos próximos dias, e atualizaremos este guia assim que estiver pronto. Por enquanto, você só pode extrair Registros de Emprego.
Antes de prosseguir com sua integração, certifique-se de ter lido nosso guia de introdução. No guia de introdução, você criará uma conta Belvo, gerará uma chave 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.
Confira o guia aqui: Começando (Pré-requisitos).
O tempo médio que a Belvo leva para 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 você cria um link, 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. Para que possamos notificá-lo quando os dados estiverem prontos, você precisará fornecer uma URL para onde possamos enviar eventos.
Se você usar links recorrentes ou realizar uma atualização histórica em um único link, também poderá receber notificações sobre mudanças de status de emprego (como aumentos salariais, mudanças de emprego ou transições entre empregado e desempregado). Para mais informações, veja Mudanças de status de emprego.
O token de acesso retornado é válido por 10 minutos e invalidamos o token assim que um usuário conecta sua conta com sucesso.
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.
Para gerar um token de access, basta fazer uma chamada do seu servidor para a Belvo:
curl -X POST \
https://sandbox.belvo.com/api/token/ \
-H 'Content-Type: application/json' \
-d 'veja o exemplo de payload abaixo'{
"id": "YOUR_SECRET_ID",
"password": "YOUR_SECRET_PASSWORD",
"scopes": "read_institutions,write_links",
"stale_in": "365d",
"credentials_storage": "store",
"fetch_resources": ["EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS"],
"widget": {
"callback_urls": {
"success": "your-url-here://success",
"exit": "your-url-here://exit",
"event": "your-url-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 | Exemplo |
|---|---|---|---|---|
id | string | sim | Substitua YOUR_SECRET_ID pelo ID secreto que você gerou no painel da Belvo. | |
password | string | sim | Substitua YOUR_SECRET_PASSWORD pela senha secreta 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 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 registro de emprego no México, você pode enviar ["EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS"]. Nota: CURRENT_EMPLOYMENTS não está disponível no ambiente sandbox. | |
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 adicionar opcionalmente 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. |
{
"access": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzI3Mz...",
"refresh": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjM0O...."
}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=mx
&institutions=planet_mx_employment
&access_mode=single
&external_id=HJLSI-897809| Parâmetro | Obrigatório | Descrição |
|---|---|---|
access_token | sim | Substitua access_code pelo token access que você recebeu. |
locale | sim | Para que o hosted widget funcione corretamente para seus usuários no México, você deve definir o parâmetro de consulta locale como mx. |
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 Registros de Emprego no México, recomendamos definir este parâmetro como imss_mx_employment,issste_mx_employment. |
access_mode | não | O tipo de link a ser criado (single ou recurrent). Para Registros de Emprego no México, recomendamos usar links single. Para mais informações sobre o access_mode de um link, veja nossa seção dedicada aqui. |
| altamente recomendado | Sua referência interna para este usuário. Isso é extremamente útil, pois você pode os dados que a Belvo recupera para este usuário em seu sistema. O
|
Além disso, confira nossas seções Iniciando o widget e eventos de callback do nosso guia de Hosted Widget (Multi-Region).
Feito! A Belvo agora se conectará à instituição e validará se o CURP 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 de emprego (para o México) for criado, recuperamos assincronamente os Registros de Emprego para o link e enviamos 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 Registros de Emprego encontrados 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 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/employment-records/?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 |
Assim que seu link de emprego (para o México) for criado, recuperamos assincronamente os Empregos Atuais para o link e enviamos o seguinte webhook:
| Código do Webhook | Descrição |
|---|---|
historical_update | O número total de registros de Emprego Atual encontrados para o link. |
No payload do webhook, incluímos o número de registros de Emprego Atual encontrados para o link.
{
"webhook_id": "03d1ca0d62db4f769488265d141047b7",
"webhook_type": "CURRENT_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_current_employments": 1 // O número total de registros de Emprego Atual 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/mx/current-employments/?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 |