¿Buscas acceder a los datos del historial laboral de tus usuarios en México? Esta guía te llevará a través del proceso de usar nuestra API para extraer de manera segura y eficiente los registros de empleo, permitiéndote verificar el empleo, entender el historial de carrera y más.
En esta guía, te guiamos a través de todo lo que necesitas para extraer datos de empleo sobre tus usuarios utilizando nuestra API. Esto incluye:
- Una visión general del flujo de datos
- Creación de un enlace (a través de la API)
- Obtención de información de registros de empleo históricos
- Obtención de información de registros de empleo actuales
Empleos Actuales está disponible como una opción de pago solo para enlaces de IMSS — contacta a tu representante de Belvo para habilitarlo.
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).
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 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.
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.
Un enlace es el término de Belvo para una conexión entre tu usuario (CURP) y la institución de empleo (IMSS o ISSSTE). Cada vez que quieras extraer información de un nuevo usuario, necesitarás crear un enlace.
Para crear un enlace, solo necesitas realizar la siguiente solicitud POST Registrar un nuevo enlace:
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}'{
"institution": "planet_mx_employment",
"username": "BLPM951331IONVGR54",
"fetch_resources": ["EMPLOYMENT_RECORDS"],
"access_mode": "single",
"external_id":"COHORT_32_User_6790023X5"
}| Parámetro | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
institution | string | true | La institución donde deseas crear el enlace. Puedes elegir:
| planet_mx_employment |
username | string | true | El CURP del individuo — un identificador de 18 caracteres en mayúsculas, estructurado como 4 letras, 6 dígitos, 6 letras y luego 2 caracteres alfanuméricos. Belvo utiliza cifrado simétrico AES-256 estándar de la industria para cifrar credenciales. | BLPM951331IONVGR54 |
username2 | string | requerido condicionalmente | La dirección de correo electrónico del usuario utilizada para iniciar sesión en la institución. Requerido para issste_mx_employment. Opcional para imss_mx_employment. | carlos@bex.com |
fetch_resources | array de strings | true | Los recursos que deseas que Belvo recupere. Para 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 de sandbox. | ["EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS"] |
access_mode | string | true | El tipo de enlace a crear (single o recurrent). Para 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í. | single |
external_id | string | 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:
| COHORT_32_User_6790023X5 |
{
"id": "74c01cb4-edf1-44d6-8876-b1dc2aebcb14",
"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"
]
}¡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.
Cuando creas un enlace con IMSS México, podrías recibir errores específicos debido al CURP que proporcionas. A continuación, puedes ver un par de errores comunes junto con las explicaciones de por qué ocurren.
En la tabla a continuación, también indicamos cuándo puede ocurrir el error en la columna Occurs During. Los valores posibles son:
- Link Creation: Errores que ocurren al crear el enlace.
- Data Extraction: Errores que ocurren al extraer datos después de que el enlace se ha creado. Recibirás este error en una notificación de webhook.
| Belvo error_code | Mensaje de Error | Razón | Occurs During | Recomendación |
|---|---|---|---|---|
400 invalid_credentials | El NSS capturado no coincide con la CURP | El NSS asociado no coincide con el número de CURP. | Data Extraction | No es necesario reintentar, el usuario final no tiene datos. |
400 login_error | El NSS no fue localizado en el IMSS | El número de NSS no está presente en el sistema del IMSS. | Link Creation | No es necesario reintentar, el usuario final no tiene datos. |
400 login_error | El CURP proporcionado no fue localizado en la entidad externa RENAPO | El CURP no se encontró en el sistema RENAPO. | Data Extraction | Valida el CURP, debe tener exactamente 18 caracteres, intenta de nuevo. |
400 login_error | CURP es incorrecto | El CURP es incorrecto (puede tener un error tipográfico, no suficientes caracteres o estar mal formateado) | Link Creation | Valida el CURP, debe tener exactamente 18 caracteres, intenta de nuevo. |
400 login_error | Por favor, ingresa un CURP válido. Debe contener 18 caracteres | El CURP proporcionado tiene más o menos de 18 caracteres. | Link Creation | Valida el CURP, debe tener exactamente 18 caracteres, intenta de nuevo. |
400 login_error | La persona no cuenta con NSS | El individuo no tiene un número de Número de Seguridad Social (NSS). | Link Creation | No es necesario reintentar, el usuario final no tiene datos. |
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. | Hay una inconsistencia con la información proporcionada para iniciar sesión y lo que la institución tiene. | Data Extraction | Contacta al usuario final y recomiéndale ir a su oficina del IMSS más cercana para presentar documentación adicional para que la operación se lleve a cabo. Reintenta una vez que se haya resuelto. |
400 login_error | Es necesario que acudas a la subdelegación más cercana a tu domicilio a presentar tu trámite | El usuario asociado con el CURP necesita ir a su oficina del IMSS más cercana para presentar documentación adicional para que la operación se lleve a cabo. | Data Extraction | Contacta al usuario final y recomiéndale ir a su oficina del IMSS más cercana para presentar documentación adicional para que la operación se lleve a cabo. Reintenta una vez que se haya resuelto. |
400 login_error | El correo ya está registrado con otro CURP | La dirección de correo electrónico ya está registrada con otro CURP. | Data Extraction | Pregunta al usuario por la dirección de correo electrónico que usa para iniciar sesión en la institución. username2 no se puede cambiar en un enlace existente, así que crea un nuevo enlace usando la dirección de correo electrónico correcta. |
403 forbidden_by_host | Has agotado el número de solicitudes permitidas por día. | El CURP del usuario se ha utilizado más de tres veces para iniciar sesión en la institución dentro de un período de 24 horas. Recomendamos intentar recuperar los datos al día siguiente. | Data Extraction | Espera 24 horas y reintenta la extracción de datos. |
400 institution_unavailable | La institución financiera no está disponible | La institución financiera no está disponible | Link Creation | Reintenta la conexión más tarde. Retroceso exponencial hasta tres reintentos. |
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.
{
"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:
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 |
Para enlaces IMSS, los Registros de Empleo 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 Registros de Empleo, utiliza un enlace recurrente o realiza una actualización histórica en el enlace.
Registros de Empleo y Current Employments utilizan diferentes endpoints — nota el segmento adicional /mx/ para Current Employments:
- Registros de Empleo:
GET /api/employment-records/ - Current Employments:
GET /api/mx/current-employments/
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.
{
"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:
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 |