# Extrair Registros de Emprego (API) > Procurando acessar dados de histórico de emprego para seus usuários no México? Este guia irá orientá-lo no processo de usar 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 nossa API. Isso inclui: - Uma visão geral do fluxo de dados - Criando um link (via API) - Obtendo informações de registros de emprego históricos - Obtendo informações de registros de emprego atuais 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 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 você cria um link, a Belvo extrai automaticamente todos os dados 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. ```mermaid sequenceDiagram participant App as Application participant Belvo as Belvo participant EI as Employment Institution App->>Belvo: POST /links/ Note over App,Belvo: fetch_resources =
["EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS"] Belvo->>EI: Conectar e confirmar a criação do link Belvo-->>App: 201 - Created EI-->>Belvo: A Belvo recupera informações históricas de emprego para o ID do link Note over App,EI: Para cada recurso listado em fetch_resources, você receberá um webhook de 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. ## Criar um link O que é um link? Um link é o termo da Belvo para uma conexão entre o seu usuário (CURP) e a instituição de emprego (IMSS ou ISSSTE). Sempre que você quiser extrair informações de um novo usuário, precisará criar um link. Para criar um link, você só precisa fazer a seguinte solicitação **POST Register a new link**: Sandbox ```curl Sandbox Request URL curl --location 'https://sandbox.belvo.com/api/links/' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic BASE64(SECRET_ID:SECRET_PASSWORD)' \ --data '{see examples below}' ``` ```json Sandbox Request Body { "institution": "planet_mx_employment", "username": "BLPM951331IONVGR54", "fetch_resources": ["EMPLOYMENT_RECORDS"], "access_mode": "single", "external_id":"COHORT_32_User_6790023X5" } ``` Produção ```curl Production Request URL curl --location 'https://api.belvo.com/api/links/' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic BASE64(SECRET_ID:SECRET_PASSWORD)' \ --data '{see examples below}' ``` ```json Production Request Body { "institution": "imss_mx_employment", "username": "valid_curp", "fetch_resources": ["EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS"], "access_mode": "single", "external_id":"COHORT_32_User_6790023X5" } ``` | Parâmetro | Tipo | Obrigatório | Descrição | Exemplo | | --- | --- | --- | --- | --- | | `institution` | string | sim | A instituição onde você deseja criar o link. Você pode escolher:- - `planet_mx_employment` para Sandbox - - `imss_mx_employment` ou `issste_mx_employment` para Produção | `planet_mx_employment` | | `username` | string | sim | O CURP do indivíduo.A Belvo usa criptografia simétrica AES-256 padrão do setor para criptografar credenciais. | `BLPM951331IONVGR54` | | `fetch_resources` | array de strings | sim | Os recursos que você deseja que a Belvo recupere. Para Registros de Emprego no México, você pode enviar: `EMPLOYMENT_RECORDS` e `CURRENT_EMPLOYMENTS`. **Nota**: `CURRENT_EMPLOYMENTS` não está disponível no ambiente sandbox. | `["EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS"]` | | `access_mode` | string | sim | 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. | `single` | | `external_id` | string | 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.). Para mais detalhes, veja a seção Adicionando seu próprio identificador do nosso guia de melhores práticas de criação de Links. | `COHORT_32_User_6790023X5` | ```json Example Link Response { "id": "74c01cb4-edf1-44d6-8876-b1dc2aebcb14", // [!code highlight] "institution": "planet_mx_employment", "access_mode": "single", "status": "valid", "refresh_rate": null, "created_by": "6e9be884-4781-4143-b673-aca02475ee8c", "last_accessed_at": "2024-06-26T16:25:54.344113Z", "external_id": "COHORT_32", "created_at": "2024-06-26T16:25:54.334413Z", "institution_user_id": "BidIxnZkKvQx0_F0oSYVx6Jnsh4Zmoat2ot2iOoG018=", "credentials_storage": "365d", "stale_in": null, "fetch_resources": [ "EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS" ] } ``` **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. ### Erros comuns ao criar um link Ao criar um link com o IMSS México, você pode receber erros específicos devido ao CURP que você fornece. Abaixo você pode ver alguns erros comuns junto com as explicações de por que eles ocorrem. Quando os Erros Ocorrem Na tabela abaixo, também indicamos quando o erro pode ocorrer na coluna **Occurs During**. Os valores possíveis são: - **Link Creation**: Erros que ocorrem ao criar o link. - **Data Extraction**: Erros que ocorrem ao extrair dados após o link ser criado. Você receberá este erro em uma notificação de webhook. | Belvo error_code | Mensagem de Erro | Motivo | Occurs During | Recomendação | | --- | --- | --- | --- | --- | | `400 invalid_credentials` | El NSS capturado no coincide con la CURP | O NSS associado não corresponde ao número CURP. | Data Extraction | Não é necessário tentar novamente, o usuário final não possui dados. | | `400 login_error` | El NSS no fue localizado en el IMSS | O número NSS não está presente no sistema do IMSS. | Link Creation | Não é necessário tentar novamente, o usuário final não possui dados. | | `400 login_error` | El CURP proporcionado no fue localizado en la entidad externa RENAPO | O CURP não foi encontrado no sistema RENAPO. | Data Extraction | Valide o CURP, ele deve ter exatamente 18 caracteres, tente novamente. | | `400 login_error` | CURP es incorrecto | O CURP está incorreto (pode ter um erro de digitação, não ter caracteres suficientes ou estar mal formatado) | Link Creation | Valide o CURP, ele deve ter exatamente 18 caracteres, tente novamente. | | `400 login_error` | Por favor, ingresa un CURP válido. Debe contener 18 caracteres | O CURP fornecido tem mais ou menos de 18 caracteres. | Link Creation | Valide o CURP, ele deve ter exatamente 18 caracteres, tente novamente. | | `400 login_error` | La persona no cuenta con NSS | O indivíduo não possui um número de *Número de Seguridad Social* (NSS). | Link Creation | Não é necessário tentar novamente, o usuário final não possui dados. | | `400 login_error` | Los datos registrados en el IMSS asociados a la CURP, presentan alguna inconsistencia, por favor acude a tu Subdelegación para obtener tu Número de Seguridad Social. | Há uma inconsistência com as informações fornecidas para login e o que a instituição possui. | Data Extraction | Entre em contato com o usuário final e recomende que vá ao escritório do IMSS mais próximo para apresentar documentação adicional para que a operação seja realizada. Tente novamente assim que for resolvido. | | `400 login_error` | Es necesario que acudas a la subdelegación más cercana a tu domicilio a presentar tu trámite | O usuário associado ao CURP precisa ir ao escritório do IMSS mais próximo para apresentar documentação adicional para que a operação seja realizada. | Data Extraction | Entre em contato com o usuário final e recomende que vá ao escritório do IMSS mais próximo para apresentar documentação adicional para que a operação seja realizada. Tente novamente assim que for resolvido. | | `400 login_error` | El correo ya está registrado con otro CURP | O endereço de e-mail já está registrado com outro CURP. | Data Extraction | Valide o e-mail compartilhado em username2 e tente a conexão novamente. | | `403 forbidden_by_host` | Has agotado el número de solicitudes permitidas por día. | O CURP do usuário foi usado mais de três vezes para fazer login na instituição dentro de um período de 24 horas. Recomendamos que você tente recuperar os dados no dia seguinte. | Data Extraction | Aguarde 24 horas e tente extrair os dados novamente. | | `400 institution_unavailable` | The financial institution is unavailable | A instituição financeira está indisponível | Link Creation | Tente a conexão novamente mais tarde. Backoff exponencial até três tentativas. | ## 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` |