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

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

```mermaid
sequenceDiagram
  autonumber

  participant App as Aplicação
  participant Belvo as Belvo
  participant EI as Instituição de Emprego

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

Notificações de mudança de status de emprego
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.

## 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'
```

Registros de Emprego México
```json Registros de Emprego México
{
  "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/",
      "company_terms_version": "2024-03-15"
    },
    "theme": [] // See our dedicated widget customization article
  }
}
```

Produção
```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'
```

Registros de Emprego México
```json Registros de Emprego México
{
  "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/",
      "company_terms_version": "2024-03-15"
    },
    "theme": [] // See our dedicated widget customization article
  }
}
```

| Parâmetro  | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| `id` | string | true | Substitua `YOUR_SECRET_ID` pelo ID secreto que você gerou no painel da Belvo. |
| `password` | string | true | Substitua `YOUR_SECRET_PASSWORD` pela senha secreta que você gerou no painel da Belvo. |
| `scopes` | string | true | 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 | true | 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 | true | 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 no nosso guia Hosted Widget (OFDA). A Belvo também enviará informações adicionais sobre eventos 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
 | true
 | No objeto `branding`, você deve adicionar seu:
- `company_icon`
- `company_logo`
- `company_name`
- `company_terms_url`.
- `company_terms_version` (obrigatório ao usar um `company_terms_url` personalizado).

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 underscores (`_`).
- 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).

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

## 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` |