¿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 llevamos 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
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.
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.
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.
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). Siempre que desees extraer información de un nuevo usuario, necesitarás crear un enlace.
Para crear un enlace, solo necesitas hacer 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. Belvo utiliza cifrado simétrico AES-256 estándar de la industria para cifrar credenciales. | BLPM951331IONVGR54 |
fetch_resources | array de strings | true | Los recursos que deseas que Belvo recupere. Para Registros de Empleo en México, puedes enviar: EMPLOYMENT_RECORDS y CURRENT_EMPLOYMENTS . Nota: CURRENT_EMPLOYMENTS no 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 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 extraerlo con una solicitud get.
Cuando creas un enlace con el IMSS México, podrías recibir errores específicos debido a la 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 Ocurre Durante. Los valores posibles son:
- Creación de Enlace: Errores que ocurren al crear el enlace.
- Extracción de Datos: Errores que ocurren al extraer datos después de que se crea el enlace. Recibirás este error en una notificación de webhook.
Belvo error_code | Mensaje de Error | Razón | Ocurre Durante | Recomendación |
---|---|---|---|---|
400 invalid_credentials | El NSS capturado no coincide con la CURP | El NSS asociado no coincide con el número de CURP. | Extracción de Datos | 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. | Creación de Enlace | 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 fue encontrado en el sistema RENAPO. | Extracción de Datos | 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 tener suficientes caracteres o estar mal formateado) | Creación de Enlace | 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. | Creación de Enlace | 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). | Creación de Enlace | 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. | Extracción de Datos | Contacta al usuario final y recomiéndale ir a su oficina del IMSS más cercana para presentar documentación adicional para que se lleve a cabo la operación. Reintenta una vez que se resuelva. |
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 la CURP necesita ir a su oficina del IMSS más cercana para presentar documentación adicional para que se lleve a cabo la operación. | Extracción de Datos | Contacta al usuario final y recomiéndale ir a su oficina del IMSS más cercana para presentar documentación adicional para que se lleve a cabo la operación. Reintenta una vez que se resuelva. |
400 login_error | El correo ya está registrado con otro CURP | La dirección de correo electrónico ya está registrada con otro CURP. | Extracción de Datos | Valida el correo compartido en username2 y reintenta la conexión. |
403 forbidden_by_host | Has agotado el número de solicitudes permitidas por día. | La 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. Te recomendamos reintentar la extracción de datos al día siguiente. | Extracción de Datos | 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 | Creación de Enlace | 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 |
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 |