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 llevamos a través de todo lo que necesitas para extraer datos de empleo de tus usuarios utilizando nuestro widget. Esto incluye:

Una visión general del flujo de datos
Generar un token de acceso para el widget y crear un enlace
Obtener información de los registros de empleo

Disponibilidad de Empleos Actuales

Empleos Actuales está disponible como una opción de pago adicional solo para enlaces de IMSS — contacta a tu representante de Belvo para habilitarlo.

Requisitos previos

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.

Consulta la guía aquí: Comenzando (Requisitos previos).

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

Notificaciones de cambio de estado de empleo

Si utilizas links recurrentes o realizas una actualización histórica en un solo link, también puedes recibir notificaciones sobre cambios en el estado de empleo (como aumentos salariales, cambios de trabajo o transiciones entre empleado y desempleado). Para más información, consulta Cambios en el estado 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 Request URL

curl -X POST \
  https://sandbox.belvo.com/api/token/ \
  -H 'Content-Type: application/json' \
  -d 'see example payload below'

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"], 
  "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	Requerido	Descripción
`id`	string	true	Reemplaza `YOUR_SECRET_ID` con el ID secreto que generaste en el panel de Belvo.
`password`	string	true	Reemplaza `YOUR_SECRET_PASSWORD` con la contraseña secreta que generaste en el panel 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 los 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 de 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 asincrónica para el usuario. Para datos de registros de empleo en México, puedes enviar `EMPLOYMENT_RECORDS`. También puedes optar por `CURRENT_EMPLOYMENTS` y `EMPLOYMENT_METRICS` — ambos son solo para IMSS y aplican costos adicionales, así que contacta a tu representante de Belvo para habilitarlos. Nota: ninguno de los recursos opcionales está disponible en el entorno sandbox.
`widget.callback_urls`	objeto	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 del 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 Manejo de eventos de callback de la guía del Hosted Widget (OFDA).
`widget.branding`	objeto	true	En el objeto `branding`, debes agregar tu: `company_icon` `company_logo` `company_name` `company_terms_url`. `company_terms_version` (requerido cuando usas un `company_terms_url` personalizado). También puedes opcionalmente agregar un color de fondo personalizado para cuando el widget se abra, así como desactivar los mensajes 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.

Example Token Response

{
  "access": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzI3Mz...", 
  "refresh": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjM0O...."
}

A continuación, necesitarás redirigir a tu usuario al widget en una vista web dentro de tu aplicación, utilizando el token access que recibiste de la solicitud /api/token/:

Hosted Widget URL

https://widget.belvo.io/
	?access_token={access_code}
  &locale=mx
  &institutions=planet_mx_employment
  &access_mode=single
  &external_id=HJLSI-897809

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 hacer coincidir 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 de Iniciando el widget y eventos de callback de nuestra guía del Hosted Widget (Multi-Region).

¡Hecho! Belvo ahora se conectará a la institución y validará que el CURP proporcionado sea 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 Employment Record

Tan pronto como se crea tu enlace de empleo (para México), recuperamos de manera asincrónica los Employment Records para el enlace y te enviamos el siguiente webhook:

Código del Webhook	Descripción
`historical_update`	El número total de Employment Records encontrados para el enlace.

En la carga útil del webhook incluimos el número de Employment Records encontrados para el enlace.

Ejemplo de Actualización Histórica de Employment Records

{
  "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 Employment Record encontrados para el enlace
  }
}

Una vez que recibas la notificación, puedes obtener más detalles haciendo la siguiente solicitud:

Solicitud GET de Employment Records

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`

¿En qué estado de empleo deberías confiar?

Para enlaces IMSS, los Employment Records incluyen un salary_estimation.employment_status_estimate modelado, basado en la fecha del informe del registro de empleo más reciente, útil cuando Current Employments no está habilitado para este enlace. Si has optado por Current Employments, prefiere su campo status en vivo, ya que refleja los datos actuales de la institución en lugar de una estimación modelada. Para enlaces ISSSTE, salary_estimation devuelve null. Para actualizar los datos de Employment Records, utiliza un enlace recurrente o realiza una actualización histórica en el enlace.

Diferentes rutas GET por recurso

Employment Records y Current Employments utilizan diferentes endpoints — nota el segmento adicional /mx/ para Current Employments:

Employment Records: GET /api/employment-records/
Current Employments: GET /api/mx/current-employments/

Esperar un webhook y obtener datos de Empleo Actual

Esta sección se aplica solo a enlaces de IMSS con Empleos Actuales habilitados, y solo cuando incluyes CURRENT_EMPLOYMENTS en fetch_resources.

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.

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