# Extrair Registros de Emprego (Widget)

> 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.


## Introdução

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


Empregos Atuais Em Breve!
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**.

## Pré-requisitos

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.

## Fluxo geral de dados

Tempo médio para recuperar dados de emprego
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 automaticamente extrai todos os dados de emprego para você em segundo plano, e assim que temos 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.


```mermaid
sequenceDiagram
  autonumber

  participant App as Application
  participant Belvo as Belvo
  participant EI as Employment Institution

  App->>Belvo: POST /token/<br/>fetch_resources =<br/>["EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS"]
  Belvo-->>App: 200 - Token Gerado
  App->>App: Direcione seu usuário para o Hosted Widget
  App->>EI: Usuário faz login na sua instituição
  EI-->>Belvo: Belvo recupera informações históricas de emprego para o ID do link
  Belvo-->>App: Usuário redirecionado de volta para sua aplicação. Você recebe um ID de link para o usuário.

  Note over App,EI: Para cada recurso listado em fetch_resources, você receberá um webhook historical_update.

  Belvo->>App: WEBHOOK historical_update (EMPLOYMENT_RECORDS)
  App->>Belvo: GET /employment-records/?link={id}
  Belvo-->>App: 200 + Detalhes do Registro de Emprego

  Belvo->>App: WEBHOOK historical_update (CURRENT_EMPLOYMENTS)
  App->>Belvo: GET /current-employments/?link={id}
  Belvo-->>App: 200 + Detalhes do Emprego Atual

  Note over App,EI: Se estiver usando links recorrentes, na frequência de atualização agendada você receberá um webhook.

  Belvo->>App: WEBHOOK new_employment_records_available
  App->>Belvo: GET /employment-records/?link={id}
  Belvo-->>App: 200 + Detalhes do Registro de Emprego
```

## Gerar um token de acesso

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:

Sandbox

```shell Sandbox Request URL
curl -X POST \
  https://sandbox.belvo.com/api/token/ \
  -H 'Content-Type: application/json' \
  -d 'veja o exemplo de payload abaixo'
```

Employments Records Mexico
{
  "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"], // [!code highlight]
  "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
  }
}
Production

```shell Production Request URL
curl -X POST \
  https://production.belvo.com/api/token/ \
  -H 'Content-Type: application/json' \
  -d 'veja o exemplo de payload abaixo'
```

Employments Records Mexico
{
  "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"], // [!code highlight]
  "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:- `success` (seu usuário conectou suas contas com sucesso)
- `exit` (seu usuário saiu do widget antes de completar o processo)
- `event` (ocorreu um erro durante o processo de conexão) Para mais informações, confira a seção callback_urls em nosso guia Hosted Widget (OFDA). A Belvo também enviará informações adicionais sobre o evento, dependendo do evento. Para mais informações, certifique-se de verificar a seção Handling callback events do guia Hosted Widget (OFDA).

 |
| `widget.branding`
 | objeto
 | sim
 | No objeto `branding`, você deve adicionar seu:
- `company_icon`
- `company_logo`
- `company_name`
- `company_terms_url`.

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. |



```json Exemplo de Resposta do Token
{
  "access": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzI3Mz...", // [!code highlight]
  "refresh": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjM0O...."
}
```

## Inicie o widget em seu aplicativo para seu usuário

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/`:

Sandbox

```curl Hosted Widget URL
https://widget.belvo.io/
	?access_token={access_code} # [!code ++]
  &locale=mx # [!code ++]
  &institutions=planet_mx_employment # [!code warning]
  &access_mode=single # [!code warning]
  &external_id=HJLSI-897809 # [!code warning]
```

Produção

```curl Hosted Widget URL
https://widget.belvo.io/
	?access_token={access_code} # [!code ++]
  &locale=mx # [!code ++]
  &institutions=imss_mx_employment,issste_mx_employment # [!code warning]
  &access_mode=single # [!code warning]
  &external_id=HJLSI-897809 # [!code warning]
```

| 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. |
| `external_id`
 | 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 `external_id` que você fornecer:
- deve ser um ID único para cada usuário em seu banco de dados.
- deve ter pelo menos três caracteres.
- pode ser composto apenas por letras, números, hífens (`-`) e sublinhados (`_`).
- não pode conter nenhuma informação pessoalmente identificável sobre o usuário (e-mail, nome, número de telefone, número de cartão de crédito, etc.).

 |


Além disso, confira nossas seções Iniciando o widget e eventos de callback do nosso guia de Hosted Widget (Multi-Region).

**Concluído**! 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.

## Aguarde um webhook e obtenha dados de Registro de Emprego

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.


```json Exemplo de Atualização Histórica de Registros de Emprego
{
  "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:


```shell Solicitação GET de Registros de Emprego
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` |


## Aguarde um webhook e obtenha dados de Emprego Atual

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.


```json Exemplo de Atualização Histórica de Empregos Atuais
{
  "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:


```shell Solicitação GET de Empregos Atuais
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` |