# Extraer Registros de Empleo (Widget)
> ¿En México? Esta guía te guiará a través del proceso de usar nuestra API para extraer registros de empleo de manera segura y eficiente, permitiéndote verificar el empleo, entender el historial laboral y más.
## Introducción
En esta guía, te guiaremos a través de todo lo que necesitas para extraer datos de empleo sobre tus usuarios utilizando nuestro widget. Esto incluye:
- Una visión general del flujo de datos
- Generación de un token de acceso para el widget y creación de un enlace
- Obtención de información de registros de empleo
¡Empleos Actuales Próximamente!
Esta guía menciona actualmente un nuevo recurso que está en desarrollo: **Empleos Actuales**. Este recurso estará disponible en los próximos días, y actualizaremos esta guía una vez que esté listo. Por ahora, solo puedes extraer **Registros de Empleo**.
## Prerrequisitos
Antes de proceder con tu integración, asegúrate de haber revisado nuestra guía de inicio. En la guía de inicio, crearás una cuenta de Belvo, generarás algunas claves de API de sandbox y configurarás una URL de webhook. Para propósitos de prueba y desarrollo de tu integración, recomendamos encarecidamente usar el entorno de Sandbox siempre que sea posible.
## Flujo general de datos
Tiempo promedio para recuperar datos de empleo
El tiempo promedio que tarda Belvo en recuperar datos de empleo de una institución de empleo y enviarte un evento de webhook es de 15 segundos. Sin embargo, esto puede variar dependiendo de la capacidad de respuesta de la institución y su carga actual de solicitudes.
Belvo utiliza *flujos de trabajo asincrónicos* para mejorar tu flujo de datos (consulta el diagrama a continuación).
Cada vez que creas un enlace, Belvo extrae automáticamente todos los datos de empleo para ti en segundo plano, y una vez que tenemos todos los datos, te notificamos a través de un webhook que los datos están listos para ser recuperados. Para que podamos notificarte una vez que los datos estén listos, necesitarás proporcionar una URL a la que podamos enviar eventos.
```mermaid
sequenceDiagram
autonumber
participant App as Aplicación
participant Belvo as Belvo
participant EI as Institución de Empleo
App->>Belvo: POST /token/
fetch_resources =
["EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS"]
Belvo-->>App: 200 - Token Generado
App->>App: Dirige a tu usuario al Hosted Widget
App->>EI: El usuario inicia sesión en su institución
EI-->>Belvo: Belvo recupera información histórica de empleo para el ID del enlace
Belvo-->>App: Usuario redirigido de vuelta a tu aplicación. Recibes un ID de enlace para el usuario.
Note over App,EI: Para cada recurso listado en fetch_resources, recibirás un webhook historical_update.
Belvo->>App: WEBHOOK historical_update (EMPLOYMENT_RECORDS)
App->>Belvo: GET /employment-records/?link={id}
Belvo-->>App: 200 + Detalles del Registro de Empleo
Belvo->>App: WEBHOOK historical_update (CURRENT_EMPLOYMENTS)
App->>Belvo: GET /current-employments/?link={id}
Belvo-->>App: 200 + Detalles del Empleo Actual
Note over App,EI: Si usas enlaces recurrentes, a la frecuencia de actualización programada recibirás un webhook.
Belvo->>App: WEBHOOK new_employment_records_available
App->>Belvo: GET /employment-records/?link={id}
Belvo-->>App: 200 + Detalles del Registro de Empleo
```
## Generar un token de acceso
El token de acceso devuelto es válido por 10 minutos y lo invalidamos tan pronto como un usuario conecta exitosamente su cuenta.
Para que el widget aparezca a tus usuarios finales, necesitas generar un token de `access` en tu servidor y enviarlo a Belvo. Una vez que recibamos la solicitud, recibirás un objeto con dos claves: access y refresh. Pasa el valor de la clave access al iniciar el hosted widget.
Para generar un token de `access`, simplemente realiza una llamada desde tu servidor a Belvo:
Sandbox
```shell Sandbox Request URL
curl -X POST \
https://sandbox.belvo.com/api/token/ \
-H 'Content-Type: application/json' \
-d 'ver ejemplo de payload abajo'
```
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 'ver ejemplo de payload abajo'
```
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 | Requerido | Descripción | Ejemplo |
| --- | --- | --- | --- | --- |
| `id` | string | true | Reemplaza `YOUR_SECRET_ID` con el ID secreto que generaste en el dashboard de Belvo. |
| `password` | string | true | Reemplaza `YOUR_SECRET_PASSWORD` con la contraseña secreta que generaste en el dashboard de Belvo. |
| `scopes` | string | true | El parámetro `scopes` contiene una lista de permisos que te permiten crear un enlace para el usuario. Este es un parámetro requerido y debe enviarse exactamente como se muestra. |
| `stale_in` | string | opcional | El parámetro `stale_in` te permite controlar por cuánto tiempo Belvo almacena datos derivados del usuario. Para más información, consulta la sección `stale_in` de nuestro artículo sobre controles de retención de datos. |
| `credentials_storage` | string | opcional | El parámetro `credentials_storage` te permite controlar cuánto tiempo debe Belvo almacenar las credenciales para los usuarios. Si creas enlaces recurrentes, esto debe establecerse en `store`. Para más información, consulta la sección `credentials_storage` de nuestro artículo sobre controles de retención de datos. |
| `fetch_resources` | array de strings | true | En el parámetro `fetch_resources`, proporcionas una lista de recursos que deseas que Belvo recupere de manera asíncrona para el usuario. Para datos de registros de empleo en México, puedes enviar `["EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS"]`. **Nota**: `CURRENT_EMPLOYMENTS` no está disponible en el entorno sandbox. |
| `widget.callback_urls` | object | true | En el objeto `callback_urls`, debes agregar enlaces a donde tu usuario debe ser redirigido en los siguientes casos:- `success` (tu usuario conectó exitosamente sus cuentas)
- `exit` (tu usuario salió del widget antes de completar el proceso)
- `event` (ocurrió un error durante el proceso de conexión) Para más información, consulta la sección callback_urls en nuestra guía de Hosted Widget (OFDA). Belvo también enviará información adicional del evento dependiendo del evento. Para más información, asegúrate de consultar la sección de Manejo de eventos de callback de la guía de Hosted Widget (OFDA).
|
| `widget.branding`
| object
| true
| En el objeto `branding`, debes agregar tu:
- `company_icon`
- `company_logo`
- `company_name`
- `company_terms_url`.
También puedes agregar opcionalmente un color de fondo personalizado para cuando el widget se abra, así como desactivar el mensaje de Belvo sobre cuántas cuentas han sido conectadas. Para más información sobre las opciones de personalización y branding del widget, consulta nuestra guía dedicada.
|
| `widget.theme` | array de objetos | opcional | Puedes opcionalmente agregar los colores de tu marca al widget usando el parámetro `theme`. Para más información sobre dónde aparecerán estos colores en el widget, consulta la sección dedicada Agregar colores personalizados al widget de nuestra guía de Branding. |
```json Example Token Response
{
"access": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzI3Mz...", // [!code highlight]
"refresh": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjM0O...."
}
```
## Inicia el widget en tu aplicación para tu usuario
A continuación, necesitarás redirigir a tu usuario al widget en una vista web dentro de tu aplicación, usando el token `access` que recibiste de la solicitud `/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]
```
Producción
```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 | Requerido | Descripción |
| --- | --- | --- |
| `access_token` | true | Reemplaza `access_code` con el token `access` que recibiste. |
| `locale` | true | Para que el hosted widget funcione correctamente para tus usuarios en México, debes establecer el parámetro de consulta locale a `mx`. |
| `institutions` | false | Con el parámetro `institutions`, puedes proporcionar una (o más) instituciones que deberían mostrarse en el widget. En el caso de los Registros de Empleo en México, recomendamos establecer este parámetro a `imss_mx_employment,issste_mx_employment`. |
| `access_mode` | false | El tipo de enlace a crear (`single` o `recurrent`). Para los Registros de Empleo en México, recomendamos usar enlaces `single`. Para más información sobre el `access_mode` de un enlace, consulta nuestra sección dedicada aquí. |
| `external_id`
| altamente recomendado
| Tu referencia interna para este usuario. Esto es extremadamente útil ya que puedes los datos que Belvo recupera para este usuario en tu sistema. El `external_id` que proporciones:
- debe ser un ID único para cada usuario en tu base de datos.
- debe tener al menos tres caracteres de longitud.
- solo puede estar compuesto por letras, números, guiones (`-`) y guiones bajos (`_`).
- no puede contener ninguna información personal identificable sobre el usuario (correo electrónico, nombre, número de teléfono, número de tarjeta de crédito, etc.).
|
Además, revisa nuestras secciones Iniciando el widget y eventos de callback de nuestra guía de Hosted Widget (Multi-Region).
**¡Hecho**! Belvo ahora se conectará a la institución y validará que el CURP proporcionado es correcto. Una vez validado y creado tu enlace, Belvo cargará asincrónicamente los datos de empleo. Te enviaremos un webhook una vez que hayamos recuperado los datos para el enlace dado, y luego podrás extraerlos con una solicitud get.
## Espera un webhook y obtén datos de Registro de Empleo
Tan pronto como se crea tu enlace de empleo (para México), recuperamos de manera asincrónica los Registros de Empleo para el enlace y te enviamos el siguiente webhook:
| Código del Webhook | Descripción |
| --- | --- |
| `historical_update` | El número total de Registros de Empleo encontrados para el enlace. |
En la carga útil del webhook incluimos el número de Registros de Empleo encontrados para el enlace.
```json Ejemplo de Actualización Histórica de Registros de Empleo
{
"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 // El número total de perfiles de Registro de Empleo encontrados para el enlace
}
}
```
Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:
```shell Solicitud GET de Registros de Empleo
curl --request GET 'https://api.belvo.com/api/employment-records/?link=link_id' \
-u SECRET_ID:SECRET_PASSWORD
```
| Parámetro de Consulta | Descripción | Ejemplo |
| --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |
## Esperar un webhook y obtener datos de Empleo Actual
Tan pronto como se crea tu enlace de empleo (para México), recuperamos de manera asincrónica los Empleos Actuales para el enlace y te enviamos el siguiente webhook:
| Código del Webhook | Descripción |
| --- | --- |
| `historical_update` | El número total de registros de Empleo Actual encontrados para el enlace. |
En la carga útil del webhook incluimos el número de registros de Empleo Actual encontrados para el enlace.
```json Ejemplo de Actualización Histórica de Empleos Actuales
{
"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 // El número total de registros de Empleo Actual encontrados para el enlace
}
}
```
Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:
```shell Solicitud GET de Empleos Actuales
curl --request GET 'https://api.belvo.com/api/mx/current-employments/?link=link_id' \
-u SECRET_ID:SECRET_PASSWORD
```
| Parámetro de Consulta | Descripción | Ejemplo |
| --- | --- | --- |
| `link` | El `link_id` que recibiste en la notificación del webhook. | `2f5d361d-dad6-45d4-a0bf-26d479766067` |