🚦 Estado del servicio e incidentes

Dos endpoints para que tu integración sepa si un servicio está sano y si hay un incidente activo que lo afecte, sin abrir ticket ni depender de que alguien mire el status page.

Endpoint	Qué responde
GET /v3/status	Tasa de éxito, tasas de error y tiempo promedio por tipo de consulta.
GET /v3/incidents	Incidentes activos redactados por el equipo, con su última actualización.

• URL base: https://api.consultaunica.mx
• Método: GET en ambos.
• No consumen créditos, no requieren compra previa y no aparecen en tu historial de consultas.

Funcionan aunque te hayas quedado sin saldo

A diferencia del resto de /v3, estos dos endpoints no aplican los guards de saldo ni de compra previa. Un 429 too_many_requests por saldo agotado no te deja sin forma de preguntar si la API está caída, que es justo cuando lo necesitas.

🔑 Autenticación

Misma x-api-key y mismas reglas de identidad que el resto de la API: una cuenta bloqueada, no confirmada o desactivada recibe 401.

Los errores usan el formato estándar —message, description y errorCode—. Programa contra errorCode.

Situación	HTTP	errorCode
Header x-api-key ausente	401	missing_api_key
Clave inválida, o cuenta bloqueada / no confirmada / desactivada	401	unauthorized_user
typeId, frame o serviceId fuera de los valores válidos	409	bad_request
Rate limit excedido	429	rate_limit_exceeded
Fallo interno	500	unknown

El rate limit es el mismo cupo por API Key que comparten todas las consultas de /v3. El contador anti-enumeración de claves (too_many_invalid_keys) de Estatus de Consumo no aplica aquí.

---

📊 GET /v3/status

Métricas del agregado de toda la plataforma, no de tus propias consultas. Sirven para responder "¿el servicio está fallando, o soy yo?".

Parámetros de query

Param	Tipo	Requerido	Default	Descripción
typeId	int	No	—	Tipo de consulta. Si se omite, devuelve todos los tipos con tráfico en la ventana.
frame	string	No	today	Ventana del agregado: live, today, week o month. live son los últimos 15 minutos.

Ejemplo de consumo

curl 'https://api.consultaunica.mx/v3/status?typeId=13&frame=live' \
  -H 'x-api-key: 1a2b3c4d5e6f1a2b3c4d5e6f1a2b3c4d5e6f1a2b3c4d5e6f'

✅ Respuesta exitosa. HTTP 200

{
  "frame": "live",
  "updatedAt": "2026-08-28T11:15:04",
  "types": [
    {
      "typeId": 13,
      "name": "sc_premium",
      "description": "Semanas cotizadas premium",
      "serviceId": 4,
      "successRate": 91.74,
      "clientErrorRate": 0.0,
      "serverErrorRate": 8.26,
      "avgElapsedSeconds": 32.7,
      "maintenance": false
    }
  ]
}

Campo	Tipo	Descripción
frame	string	La ventana efectivamente servida.
updatedAt	string | null	Momento en que se calculó el agregado, no el de tu petición. null si aún no hay agregado para la ventana.
typeId	int	Identificador estable del tipo de consulta.
name / description	string	Nombre corto y descripción del tipo.
serviceId	int	Servicio al que pertenece el tipo. Ver la tabla de abajo.
successRate	float | null	Porcentaje de consultas con respuesta exitosa.
clientErrorRate	float | null	Porcentaje de errores atribuibles a la petición: datos inválidos, registro no encontrado.
serverErrorRate	float | null	Porcentaje de errores del servicio o de su proveedor.
avgElapsedSeconds	float | null	Tiempo promedio de las consultas exitosas, en segundos.
maintenance	bool	true si el tipo está temporalmente deshabilitado. Sus métricas se siguen reportando.

updatedAt puede llegar sin offset horario; trátalo como hora del centro de México (UTC-06:00), la zona en la que opera la plataforma.

Qué tipos llegan en la respuesta

Depende de si envías typeId:

• Con typeId: siempre recibes ese tipo, con su nombre, su serviceId y su bandera de mantenimiento, aunque no haya registrado consultas.
• Sin typeId: recibes únicamente los tipos con tráfico en la ventana. Un tipo que nadie consultó hoy no aparece en frame=today. Si necesitas vigilar un tipo concreto, pídelo por typeId en vez de buscarlo en la lista completa.

Cuando no hay medición

Las cuatro métricas llegan en null —con 200, no con error— cuando el tipo no registró consultas en la ventana o cuando todavía no hay agregado publicado para ella.

null no significa "caído"

Un endpoint de estado que respondiera error al no conocer el estado te obligaría a distinguir "la API está caída" de "el estado está caído" con el mismo código HTTP. Por eso la ausencia de datos es un 200 con null: si vas a levantar una alerta, hazlo con successRate bajo, nunca con successRate nulo.

Frescura de los datos

No todas las ventanas se recalculan con la misma frecuencia:

Ventana	Cubre	Se recalcula
live	Últimos 15 minutos	Cada 15 minutos
today	El día en curso	Cada 15 minutos
week	Últimos 7 días	Una vez al día
month	Últimos 30 días	Una vez al día

Un month consultado por la tarde puede tener varias horas de antigüedad; por eso viaja updatedAt. Para detectar una degradación en curso usa live: week y month sirven para juzgar tendencia, no para decidir si reintentas ahora.

Catálogo de tipos

typeId	name	Consulta	serviceId
1	nss_quick	NSS rápido	4
2	nss_email	NSS al correo	4
3	vd_email	Vigencia de derechos al correo	4
4	sc_email_restricted	Semanas cotizadas al correo (canal interno)	4
5	vd_no_dh	Constancia de no derechohabiencia	4
6	sc_rpci	Reporte RECI	4
7	rfc_search	Búsqueda de RFC	14
8	tax_payer_search	Búsqueda de contribuyente	14
9	tax_payer_validation	Validación de contribuyente	14
10	afore_quick	Detalles de Afore	8
11	afore_email	Afore al correo oficial (canal interno)	8
12	ifetel	Consulta de teléfono	15
13	sc_premium	Reporte detallado de semanas cotizadas	4
14	sc_otp	Semanas cotizadas por enlace (canal interno)	4
15	sat_listado_69b_rfc	Listado 69-B de Hacienda por RFC (canal interno)	14
16	sat_listado_69b_tax_payer	Listado 69-B de Hacienda por razón social (canal interno)	14
17	acta_nacimiento	Acta de nacimiento	16
18	acta_matrimonio	Acta de matrimonio	16
19	acta_defuncion	Acta de defunción	16

Los serviceId son los mismos que usa GET /v3/incidents:

serviceId	Servicio
4	Seguro Social
8	Afore
14	Hacienda
15	Telefonía
16	Registro Civil

El catálogo no es un espejo del listado de servicios

Es el catálogo interno de tipos de la plataforma: incluye canales que no expone la API pública —correo, WhatsApp, enlaces— y algunas consultas documentadas comparten tipo con otra de su misma familia. Los tipos marcados como canal interno pueden aparecer en la respuesta; ignóralos si no te sirven.

---

🚨 GET /v3/incidents

Incidentes activos, redactados por el equipo cuando algo se sale de lo normal. Un incidente resuelto deja de aparecer aquí; el historial completo vive en https://status.consultaunica.mx.

Parámetros de query

Param	Tipo	Requerido	Default	Descripción
serviceId	int	No	—	Servicio a consultar. Si se omite, devuelve todos los incidentes activos.

Ejemplo de consumo

curl 'https://api.consultaunica.mx/v3/incidents?serviceId=4' \
  -H 'x-api-key: 1a2b3c4d5e6f1a2b3c4d5e6f1a2b3c4d5e6f1a2b3c4d5e6f'

✅ Respuesta exitosa. HTTP 200

{
  "hasActiveIncident": true,
  "incidents": [
    {
      "id": 16,
      "title": "Servicio de semanas cotizadas en mantenimiento",
      "description": "El mantenimiento se debe a actualizaciones del sistema de semanas cotizadas y pensiones",
      "status": "identified",
      "impact": "outage",
      "scope": "service",
      "affectedServices": [4],
      "startedAt": "2026-08-24T17:12:00-06:00",
      "nextUpdateAt": "2026-08-28T08:00:00-06:00",
      "latestUpdate": {
        "body": "De manera oficial, el servicio se reanudará hasta el viernes.",
        "createdAt": "2026-08-25T19:25:34-06:00"
      }
    }
  ]
}

Campo	Tipo	Descripción
hasActiveIncident	bool	Atajo para ramificar sin inspeccionar el arreglo.
id	int	Identificador del incidente. Estable mientras dura.
title / description	string	Encabezado y detalle redactados por el equipo. description puede ser null.
status	string	investigating, identified o monitoring. Los resueltos no llegan por aquí.
impact	string	degraded (servicio lento o parcial) u outage (servicio caído).
scope	string	global o service. Ver abajo.
affectedServices	int[]	serviceId afectados. Vacío cuando el incidente es global.
startedAt	string	Inicio del incidente, ISO 8601 con offset.
nextUpdateAt	string | null	Próxima comunicación comprometida. Se expone aunque ya haya pasado.
latestUpdate	object | null	Última entrada de la bitácora: body y createdAt. null si aún no hay ninguna.

Sin incidentes activos

{
  "hasActiveIncident": false,
  "incidents": []
}

Es la respuesta normal: 200 con el arreglo vacío, nunca 404.

Incidentes globales

Un incidente que afecta a toda la plataforma llega con scope: "global" y affectedServices: [], y aparece sin importar el serviceId que envíes. Filtrarlo te daría un falso "todo bien" durante una caída total, que es cuando el endpoint más importa.

Ramifica por scope, no por affectedServices

affectedServices vacío significa "global", no "ninguno". Si quieres saber si el incidente es específico de tu servicio o general, lee scope.

Fechas

Todas las fechas de incidentes llevan el offset explícito del centro de México (2026-08-24T17:12:00-06:00). Sin él, new Date(...) las interpretaría como hora local del navegador y quien esté fuera del huso vería una hora falsa en la comunicación de una caída.

---

🧭 Cómo usarlos juntos

El patrón para el que fueron diseñados, ante un 5xx o una racha de fallos en una consulta:

1. GET /v3/status?typeId=<tu tipo>&frame=live — si successRate está bajo o maintenance es true, el problema no es tu integración.
2. GET /v3/incidents?serviceId=<tu servicio> — si hasActiveIncident es true, ahí está la explicación, la severidad y cuándo esperar la siguiente actualización (nextUpdateAt).
3. Si ambos vienen limpios, revisa tu petición antes de escribir a soporte: el errorCode de la respuesta fallida es el mejor punto de partida.

Consúltalos cuando algo falla o cada varios minutos, no en cada consulta: comparten el cupo de tu API Key con las consultas que sí te generan valor, y el agregado se recalcula cada 15 minutos, así que un polling más frecuente devuelve el mismo número.

No preguntes: que te avisemos

Si no quieres depender de acordarte de preguntar, registra un webhook de incidentes: te mandamos un POST firmado en cuanto damos de alta o actualizamos un incidente que te afecta. El webhook te despierta; estos dos endpoints te dicen cómo va y cuándo se normalizó.

Para tus usuarios finales, la página pública https://status.consultaunica.mx muestra lo mismo con el historial de incidentes resueltos.