# Extrair Dados de Emprego no Brasil

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


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


```mermaid
sequenceDiagram
    participant App as Aplicação
    participant Belvo as Belvo
    participant Institution as Instituição de Emprego

    App->>Belvo: POST /token/
    Note over App,Belvo: fetch_resources = [EMPLOYMENTS, OWNERS]
    Belvo-->>App: 200 - Token Gerado
    
    App->>Belvo: Direcione seu usuário para o Hosted Widget
    Belvo->>Institution: Usuário faz login na sua instituição
    Belvo-->>App: Usuário redirecionado de volta para sua aplicação + link gerado

    Belvo->>Institution: Belvo recupera informações<br/>históricas de EMPLOYMENT e OWNER<br/>para o ID do Link

    Note over Belvo,App: EMPLOYMENTS

    Belvo->>App: WEBHOOK: historical_update
    App->>Belvo: GET /br/employments/{link-id}
    Belvo-->>App: 200 + Detalhes de Emprego

    Note over Belvo,App: OWNERS

    Belvo->>App: WEBHOOK: historical_update
    App->>Belvo: GET /owners/{link-id}
    Belvo-->>App: 200 + Detalhes do Proprietário

    Note over App, Institution: Se estiver usando Links recorrentes, na frequência de atualização agendada<br/>você receberá um webhook new_{resource}_available.

    Belvo->>App: WEBHOOK: new_employments_available
    App->>Belvo: GET /br/employments/{link-id}
    Belvo-->>App: 200 + Detalhes de Emprego
```

## Gerar um token de acesso

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 cURL Request Headers
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'
```

Empregos Brasil
{
  "id": "YOUR_SECRET_ID",
  "password": "YOUR_SECRET_PASSWORD",
  "scopes": "read_institutions,write_links",
  "stale_in": "365d",
  "credentials_storage": "store",
  "fetch_resources": ["EMPLOYMENTS", "OWNERS"], // [!code highlight]
  "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:- 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 de Hosted Widget (OFDA). A Belvo também enviará informações adicionais sobre o evento dependendo do evento. Para mais informações, certifique-se de conferir a seção Handling callback events do guia de 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 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. |


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


```shell Hosted Widget URL
https://widget.belvo.io/
  ?access_token={access_code} # [!code ++]
  &locale=pt # [!code ++]
  &institutions=inss_br_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 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`. |
| `external_id`
 | altamente recomendado
 | Você pode adicionar um identificador adicional para ser associado ao link no banco de dados da Belvo. O `external_id` que você fornecer:
- deve ser um ID único para cada usuário no 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 pessoal 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 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.

## Webhook de emprego em espera

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


```json Exemplo de Webhook Histórico
{
  "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 Exemplo de 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` |


## Esperar pelo webhook do proprietário

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.


```json Exemplo de Webhook Histórico
{
  "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 Exemplo de 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` |