# Extract Employment Records (API) > ¿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. ## Introducción 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 ¡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**. ## 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. ## 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 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. ```mermaid sequenceDiagram participant App as Aplicación participant Belvo as Belvo participant EI as Institución de Empleo App->>Belvo: POST /links/ Note over App,Belvo: fetch_resources =
["EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS"] Belvo->>EI: Conectar y confirmar la creación del link Belvo-->>App: 201 - Creado EI-->>Belvo: Belvo recupera información histórica de empleo para el ID del link Note over App,EI: Para cada recurso listado en fetch_resources, recibirás un webhook de 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 links recurrentes, en 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 ``` ## Crear un enlace ¿Qué es un enlace? 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**: 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" } ``` Production ```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 | Requerido | Descripción | Ejemplo | | --- | --- | --- | --- | --- | | `institution` | string | true | La institución donde deseas crear el enlace. Puedes elegir:- - `planet_mx_employment` para Sandbox - - `imss_mx_employment` o `issste_mx_employment` para Producción | `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:- 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.). Para más detalles, consulta la sección Agregar tu propio identificador de nuestra guía de mejores prácticas para la creación de enlaces. | `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" ] } ``` **¡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. ### Errores comunes al crear un enlace 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. Cuándo Ocurren Errores 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. | ## Esperar un webhook y obtener 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` |