Semanas cotizadas del IMSS por API — constancia e historial laboral

Qué es del IMSS y qué es nuestro

Tres capas, siempre separadas.

Para que tu equipo de riesgo y tu auditor sepan exactamente de dónde sale cada número, la respuesta separa lo que viene del documento de lo que calculamos nosotros.

1 · El documento oficialEl PDF completo del IMSS, con folio y sello digital verificable. Es la fuente auditable: todo lo demás es nuestra lectura de él. Llega en files[0].

◈

2 · Campos oficialesLo que está impreso en la constancia, pasado a JSON sin modificarlo: semanas, historial de empleos, identidad y datos del reporte. Solo se normaliza el formato de fechas y montos.

∑

3 · Señales calculadasTodo lo que calculamos vive en un solo lugar, derivedSignals, y en ningún otro. Son hechos medibles —meses, conteos, porcentajes—, nunca un score ni una recomendación.

La respuesta del API

Qué trae cada parte.

Qué recibes	Campo	Origen	Qué contiene
Semanas cotizadas	`contributionWeeks`	Oficial	Total, cotizadas, descontadas y reintegradas, tal como las imprime el IMSS.
Historial de empleos	`employmentHistory[]`	Oficial	Un renglón por empleo, del más reciente al más antiguo: patrón, registro patronal, estado, fecha de alta, fecha de baja y salario base de cotización.
Identidad	`personalInfo · nss`	Oficial	Nombre, CURP, fecha de nacimiento y NSS, como los tiene el IMSS.
Datos del documento	`reportDetails`	Oficial	Folio, fecha de emisión, número de serie y sello digital del IMSS.
El PDF	`files[0]`	Oficial	La constancia oficial completa, en base64.
Señales	`derivedSignals`	Calculado	Situación actual, antigüedad, estabilidad, salario y línea de tiempo salarial.

¿Tiene empleo vigente? Lo sabes de dos formas. La rápida es el type: SUCCESS si hay empleo vigente, INACTIVE_EMPLOYMENT si no lo hay. Y para saber dónde trabaja hoy, es el renglón del historial sin fecha de baja (endDate: null). Todos los campos vienen siempre; los que no aplican llegan en null.

Cómo lo calculamos

Cada señal, con su fórmula.

Nada de cajas negras. Estas son las cuatro reglas que aplican a todo, y después cada señal con la operación exacta. Puedes recalcular cualquiera a partir del historial oficial y te debe dar el mismo número.

La fecha de referencia es la de emisión"Hoy" siempre es la fecha en que el IMSS emitió la constancia, no el día en que la consultas. Un empleo vigente se mide hasta esa fecha.

Un mes son 30.44 díasEs el promedio del calendario. Los meses se obtienen dividiendo días entre 30.44, con un decimal. El salario mensual es el diario por 30.44.

Los empleos simultáneos no se suman dobleSi dos empleos se traslapan, el tiempo trabajado se cuenta una sola vez: se unen los periodos antes de sumar.

Las semanas oficiales no se recalculanEl total de semanas es aritmética sobre los números impresos por el IMSS. El tiempo de calendario va aparte y no equivale a semanas cotizadas.

Un ejemplo, paso a paso

Una persona con tres empleos. La constancia se emitió el 1 de octubre de 2026.

Patrón	Alta	Baja	Salario diario	Duración
EMPRESA EJEMPLO UNO	2015-03-02	2017-08-31	$250.00	30 meses
EMPRESA EJEMPLO DOS	2018-02-01	2021-12-15	$380.00	46.4 meses
EMPRESA EJEMPLO TRES	2022-03-01	`vigente`	$520.00	55 meses

Entre el primer y el segundo empleo pasaron 5.1 meses sin empleo formal; entre el segundo y el tercero, 2.5.

Señal	Cómo se calcula	En el ejemplo
Semanas oficiales	Cotizadas − descontadas + reintegradas, con los números impresos en la constancia.	560 − 4 + 0 = 556
Situación actual
¿Tiene empleo?	Sí, si hay un renglón sin fecha de baja.	Sí
Meses en la situación actual	Con empleo: de la fecha de alta del empleo vigente a la emisión. Sin empleo: de la última baja a la emisión.	1 mar 2022 → 1 oct 2026 = 55 meses
Último salario mensual	Salario diario del empleo vigente (o del más reciente) × 30.44.	$520.00 × 30.44 = $15,828.80
Salario en el tope legal	Verdadero si el salario diario llegó al máximo que la ley permite cotizar: 25 UMA diarias, que en 2026 son $2,932.75 al día. Se usa la UMA vigente en la fecha de emisión de la constancia.	$520.00 es menor que $2,932.75 → No
Antigüedad
Promedio por empleo	Suma de la duración de cada empleo ÷ número de empleos.	(30 + 46.4 + 55) ÷ 3 = 43.8 meses
Empleo más largo y más corto	El máximo y el mínimo de esas duraciones.	55 y 30 meses
Meses desde el primer empleo	De la primera fecha de alta a la emisión.	2 mar 2015 → 1 oct 2026 = 139 meses
Estabilidad
Empleos y patrones distintos	Renglones del historial, y cuántos registros patronales diferentes hay entre ellos.	3 y 3
Meses promedio por patrón	Meses desde el primer empleo ÷ número de empleos.	139 ÷ 3 = 46.3 meses
Cambios de empleo	Número de empleos − 1. En los últimos 5 años: empleos cuya alta cae en los 5 años previos a la emisión.	2 en total · 1 en 5 años
Periodos sin empleo	Cada hueco entre el fin de un periodo trabajado y el inicio del siguiente. Se reportan cuántos son, su suma, el más largo y hace cuánto terminó el último.	2 huecos · 5.1 + 2.5 = 7.6 meses
Meses efectivamente empleado	Tiempo de calendario con al menos un empleo, uniendo los periodos que se traslapan.	139 − 7.6 = 131.4 meses
% del tiempo con empleo	Meses efectivamente empleado ÷ meses desde el primer empleo.	131.4 ÷ 139 = 94.6%
Empleos simultáneos	Empleos cuyo periodo se encima con el de otro. Una baja y un alta el mismo día cuentan como continuidad, no como simultáneos.	0
Salario
Primero, último, más alto y más bajo	Salarios diarios del historial, ordenados por fecha de alta.	$250 · $520 · $520 · $250
Cambio del primero al último	(Último − primero) ÷ primero × 100.	(520 − 250) ÷ 250 = +108%
Cambios de patrón con aumento o recorte	Cada vez que cambia de patrón se compara el salario nuevo contra el anterior.	2 con aumento · 0 con recorte
Salario hace 1, 3 y 5 años	El salario del empleo que tenía en esa fecha. Si estaba sin empleo, el más reciente anterior. Incluye el % de cambio contra el actual.	$520 · $520 · $380 (+36.8% desde entonces)

Son hechos, no un score. No devolvemos una calificación de crédito ni una recomendación: esa decisión es tuya.

El salario tiene un máximo. Lo que ves es el salario base de cotización que el patrón reporta al IMSS, y la ley lo limita a 25 UMA diarias: $2,932.75 al día en 2026, unos $89,272.91 al mes. Nadie aparece con un salario mayor a ese, gane lo que gane. Por eso, cuando salaryAtLegalCap es verdadero, la persona llegó al máximo y su ingreso real puede ser más alto que el que ves. El valor cambia cada año, el 1 de febrero.

Casos de negocio

Cada respuesta ya trae su decisión.

El campo type nombra el caso con un código estable. Tu backend hace un switch, no interpreta textos.

type	Qué pasó	Qué hacer
`SUCCESS`	Se obtuvo la constancia y la persona tiene empleo vigente.	Avanza. Usa el historial y las señales en tu modelo.
`INACTIVE_EMPLOYMENT`	Se obtuvo la constancia, pero hoy no hay empleo vigente.	Analiza. Tienes la trayectoria completa y cuánto lleva sin empleo formal.
`CURP_NOT_FOUND`	El IMSS no localizó esa CURP.	Analiza. Verifica la CURP contra RENAPO.
`PERSON_WITHOUT_NSS`	La CURP existe, pero no tiene NSS asignado.	Analiza. Nunca ha sido dada de alta ante el IMSS; no hay historial.
`IMSS_INCONSISTENT_DATA`	La CURP existe, pero sus datos son inconsistentes en el IMSS.	Analiza. La persona tiene que aclararlo ante el instituto.
`IMSS_OPERATION_LIMIT`	El IMSS aplicó un límite temporal a esa consulta.	Reintenta más tarde.
`IMSS_REPORT_UNAVAILABLE`	El IMSS no pudo generar el reporte de ese registro.	Reintenta otro día. No se cobra.
`IMSS_RECORD_ERROR`	El IMSS devolvió un error inesperado para ese registro.	Reintenta otro día. No se cobra.
`SERVICE_UNAVAILABLE`	El IMSS no está disponible.	Reintenta. No se cobra.
`INVALID_REQUEST`	La CURP viene mal formada o falta el webhook. Se responde de inmediato, al crear la consulta.	Corrige la petición. No se cobra.

Si tu webhook falló

El resultado no se pierde: pídelo con el folio.

Intentamos la entrega tres veces. Si tu dirección no pudo recibirlo, durante 24 horas puedes pedir el resultado enviando el folio que te dimos en el acuse. Esta consulta no cuesta.

type	Qué significa	Qué hacer
`RESULT_FOUND`	El resultado está listo. Viene completo dentro de `data`, idéntico al que se envió a tu webhook.	Úsalo. Es el mismo resultado, sin cobro adicional.
`RESULT_PENDING`	La consulta sigue en proceso.	Espera. El resultado se enviará a tu webhook cuando esté listo.
`RESULT_EXPIRED`	Pasaron más de 24 horas desde que se resolvió.	Vuelve a consultar la CURP si aún necesitas el dato.
`INVALID_REQUEST`	El folio no existe o pertenece a otra cuenta.	Revisa el folio que guardaste del acuse.

Es un respaldo, no la vía normal: el resultado siempre se envía a tu webhook, así que no hace falta consultar una y otra vez para saber si ya está.

consultar-resultado
          
          
        
const res = await fetch("https://api.origoid.com/mex/social-security/v1/imss-contribution-weeks-results", {
  method: "POST",
  headers: {
    "x-api-key": process.env.ORIGOID_API_KEY,
    "content-type": "application/json",
  },
  // el folio que recibiste en el acuse
  body: JSON.stringify({ transactionId: "975cf12f-f270-51cc-9037-d710134940c9" }),
});

const r = await res.json();
if (r.type === "RESULT_FOUND") procesar(r.data.type, r.data.data);curl -X POST https://api.origoid.com/mex/social-security/v1/imss-contribution-weeks-results \
  -H "x-api-key: $ORIGOID_API_KEY" \
  -H "content-type: application/json" \
  -d '{"transactionId": "975cf12f-f270-51cc-9037-d710134940c9"}'Respuesta
{
  "status": "OK",
  "type": "RESULT_FOUND",
  "data": {
    "type": "SUCCESS",
    "data": { "contributionWeeks": { … }, "employmentHistory": [ … ] },
    "transactionId": "975cf12f-f270-51cc-9037-d710134940c9",
    "billable": true
  },
  "billable": false
}

Infraestructura cruda · 100% API REST

Una llamada. Un dato de entrada.

Mandas la CURP y la dirección de tu webhook. Mismo envelope que todos los servicios de OrigoID.

Solo la CURPNo necesitas el NSS ni ningún otro dato de la persona.

3 créditos por consulta resueltaSe cobra cuando hay resultado. El acuse y la consulta de respaldo no cuestan.

Disponible 24 horas, luego se eliminaEl resultado se conserva solo ese plazo, como respaldo de la entrega. No lo usamos para nada más.

Ver documentación ↗

semanas-cotizadas
          
          
          
        
const res = await fetch("https://api.origoid.com/mex/social-security/v1/imss-contribution-weeks", {
  method: "POST",
  headers: {
    "x-api-key": process.env.ORIGOID_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    curp: "XEXX010101HNEXXXA4",
    webhook: { url: "https://tu-dominio.com/hooks/origoid" },
  }),
});

const acuse = await res.json(); // type: "ACCEPTED"import os, requests

res = requests.post(
    "https://api.origoid.com/mex/social-security/v1/imss-contribution-weeks",
    headers={"x-api-key": os.environ["ORIGOID_API_KEY"]},
    json={
        "curp": "XEXX010101HNEXXXA4",
        "webhook": {"url": "https://tu-dominio.com/hooks/origoid"},
    },
    timeout=30,
)
acuse = res.json()  # type: "ACCEPTED"curl -X POST https://api.origoid.com/mex/social-security/v1/imss-contribution-weeks \
  -H "x-api-key: $ORIGOID_API_KEY" \
  -H "content-type: application/json" \
  -d '{"curp": "XEXX010101HNEXXXA4", "webhook": {"url": "https://tu-dominio.com/hooks/origoid"}}'Acuse inmediato
{
  "status": "OK",
  "type": "ACCEPTED",
  "transactionId": "975cf12f-f270-51cc-9037-d710134940c9",
  "billable": false
}Lo que llega a tu webhook (abreviado)
{
  "type": "SUCCESS",
  "data": {
    "contributionWeeks": { "total": 556, "contributed": 560, "discounted": 4, "reinstated": 0 },
    "employmentHistory": [{
      "employerName": "EMPRESA EJEMPLO TRES S.A. DE C.V.",
      "startDate": "2022-03-01", "endDate": null,
      "baseSalary": { "amount": "520.00", "currency": "MXN" }
    }],
    "derivedSignals": {
      "currentStatus": { "employed": true, "monthsInCurrentStatus": 55 },
      "stability": { "percentOfTimeEmployed": 94.6, "jobChanges": 2 }
    },
    "reportDetails": { "folio": "0000…", "digitalSeal": "…" },
    "files": [{ "contentType": "application/pdf", "content": "JVBERi0x…" }]
  },
  "transactionId": "975cf12f-f270-51cc-9037-d710134940c9",
  "billable": true
}

Preguntas frecuentes

Lo que suelen preguntarnos.

¿Qué es la Constancia de Semanas Cotizadas?

El documento oficial del IMSS que resume la vida laboral de una persona: cuántas semanas ha cotizado y, empleo por empleo, con qué patrón, en qué fechas y con qué salario base de cotización.

¿Qué necesito para consultarla?

Solo la CURP de la persona y una dirección de webhook donde recibir el resultado. No necesitas el NSS.

¿Qué calculan ustedes y qué viene del IMSS?

Del IMSS vienen el PDF, las semanas, el historial de empleos, la identidad y los datos del documento. Nosotros calculamos solo lo que está en derivedSignals: situación actual, antigüedad, estabilidad y salario. Cada señal tiene su fórmula publicada en esta página.

¿Devuelven un score de crédito?

No. Devolvemos hechos medibles —meses, conteos, porcentajes y montos—. La calificación y la decisión son tuyas.

¿El salario que aparece es su sueldo real?

Es el salario base de cotización diario que el patrón reporta al IMSS. El equivalente mensual es ese salario por 30.44. Tiene un máximo legal de 25 UMA diarias, $2,932.75 al día en 2026: cuando salaryAtLegalCap es verdadero, la persona llegó a ese máximo y su ingreso real puede ser mayor.

¿Cómo recibo el resultado?

En tu webhook. Al crear la consulta recibes un acuse con un folio; cuando el resultado está listo lo enviamos a tu dirección con ese mismo folio. Si tu webhook falló, lo puedes consultar durante 24 horas.

¿Cuánto cuesta?

3 créditos por consulta resuelta. No se cobra el acuse, la consulta de respaldo ni los casos en que el IMSS no pudo generar el reporte. Los planes están publicados.

¿Guardan la constancia?

El resultado queda disponible 24 horas como respaldo de la entrega y después se elimina. No lo usamos para ningún otro fin.

Toda la vida laboral de una persona, con su CURP.

La trayectoria completa, no solo la foto de hoy.

No te pedimos que nos creas. Compruébalo.