Saltar al contenido principal
Algunas consultas al IMSS tardan más de lo que conviene esperar con una petición HTTP abierta, por eso se ofrecen como endpoints asíncronos: envías la petición con un objeto webhook y te entregamos el resultado en tu URL cuando está listo.

​
Cómo funciona

  1. Crea la petición. Haz POST con la consulta y un objeto webhook. La API responde de inmediato con type: ACCEPTED y un transactionId. Aceptar la petición no se cobra (billable: false).
  2. Recibe el resultado. Cuando la consulta se resuelve, enviamos un POST HTTP a tu webhook.url. El cuerpo es el envelope estándar, con el mismo transactionId del paso 1.
Petición:
Respuesta inmediata:
Si la petición no es válida, recibes INVALID_REQUEST de inmediato en lugar de ACCEPTED, y nunca se cobra:

​
El objeto webhook

​
Tu endpoint de webhook

  • Recibe un POST HTTP con cuerpo JSON (Content-Type: application/json) y los headers que configuraste.
  • Responde con cualquier status 2xx en cuanto recibas el cuerpo, y procésalo después.
  • Hazlo idempotente: el mismo resultado puede llegar más de una vez, así que usa transactionId para descartar duplicados.

​
Intentos de entrega

Intentamos entregar cada resultado hasta 3 veces: de inmediato, y luego 1 minuto y 5 minutos después del intento fallido anterior. Un intento falla cuando tu endpoint no responde con un status 2xx en menos de 10 segundos (no seguimos redirecciones). Después del tercer intento fallido, el resultado ya no se vuelve a enviar. La disponibilidad de tu endpoint de webhook es tu responsabilidad: los créditos se cobran cuando el resultado se resuelve, lo reciba o no tu endpoint. En Contribution Weeks todavía puedes consultar el resultado durante 24 horas (ver Respaldo de Contribution Weeks).

​
Cobro

Los créditos se cobran una sola vez, cuando el resultado se resuelve, con la misma regla que el resto de los endpoints (ver Créditos): billable: true cuando la consulta se realizó — aunque el resultado sea negativo, como CURP_NOT_FOUND — y false en fallas técnicas. El campo billable del cuerpo que recibe tu webhook indica cuál aplica.

​
Resultados por servicio

Cada endpoint asíncrono entrega a tu webhook uno de los siguientes resultados. Abre un tipo para ver su ejemplo completo.

​
Get NSS (Async)

Mismos tipos de resultado que Get NSS, excepto INVALID_REQUEST, que se responde de inmediato al crear la petición.

​
Employment Status (Async)

Mismos tipos de resultado y data que Employment Status, excepto INVALID_REQUEST, que se responde de inmediato al crear la petición. MISMATCH_CURP_NSS solo ocurre si envías nss, y data.files[] solo se incluye con includePdf: true (el contenido del PDF está recortado en el ejemplo).

​
Contribution Weeks

Cómo leer data (SUCCESS e INACTIVE_EMPLOYMENT):
  • Campos oficiales, tomados del documento del IMSS: nss, personalInfo, contributionWeeks (total = contributed − discounted + reinstated), employmentHistory (un renglón por empleo, del más reciente al más antiguo) y reportDetails (folio, issueDate, digitalSeal, …). files[0] es el PDF oficial en base64 (recortado en los ejemplos).
  • El empleo vigente es el renglón de employmentHistory con endDate: null; en INACTIVE_EMPLOYMENT no hay ninguno.
  • Todo lo calculado vive en derivedSignals — currentStatus, jobTenure (meses), stability, salary y salaryTimeline. Son hechos, no un score de crédito.
  • Los salarios (baseSalary, *Salary) son el salario base de cotización (SBC) diario; el equivalente mensual es SBC × 30.44. salaryAtLegalCap: true significa que el salario llegó al tope legal (25 UMA), así que el ingreso real puede ser mayor.
  • Todos los campos siempre están presentes; los que no aplican vienen en null.
IMSS_REPORT_UNAVAILABLE e IMSS_RECORD_ERROR son propios de ese registro mientras el servicio funciona; no se cobran y la misma CURP se puede enviar de nuevo otro día.

​
Respaldo de Contribution Weeks

Si tu webhook no pudo recibir un resultado de Contribution Weeks, consúltalo durante 24 horas con Contribution Weeks Result (gratis), enviando el transactionId:
Responde RESULT_FOUND (con el envelope original del resultado dentro de data), RESULT_PENDING o RESULT_EXPIRED. Úsalo solo como respaldo: el resultado siempre se envía a tu webhook.