🧪 Ambiente de pruebas (modo mock)

Todos los servicios síncronos —Seguro Social, Afore, Hacienda y Telefonía— tienen una ruta espejo bajo /v3/mock que devuelve respuestas de ejemplo sin ejecutar la consulta real. Sirve para que integres el contrato completo antes de comprar tu primer paquete.

No consume créditos. Ni los descuenta ni los requiere.
No requiere compra previa. Basta una cuenta activa y confirmada con su API Key.
No consulta al proveedor. Las respuestas son fijas; nadie del otro lado se entera.

Los reportes asincrónicos tienen su propio ambiente de pruebas

El reporte detallado de semanas cotizadas, la constancia de vigencia de derechos y las actas son asíncronos —uuid, polling y webhook firmado— y su modo mock se documenta en sus propias páginas, con otro contrato.

Rutas

Productivo	Mock equivalente
`POST /v3/imss`	`POST /v3/mock/imss`
`POST /v3/afore`	`POST /v3/mock/afore`
`POST /v3/sat`	`POST /v3/mock/sat`
`POST /v3/phones`	`POST /v3/mock/phones`

El cuerpo de la petición, los parámetros de query (incluido _v en las consultas del Seguro Social) y la forma de la respuesta son los mismos que en la ruta productiva.

Migración: elimina /mock del path. El header X-Mock-Mode se ignora en producción.

Autenticación

Misma API Key y mismas reglas de identidad que en producción:

Situación	Respuesta
Header `x-api-key` ausente	`401` `missing_api_key`
Clave inválida, o cuenta bloqueada / no confirmada / desactivada	`401` `unauthorized_user`
Rate limit excedido	`429` `rate_limit_exceeded`

Lo que no aplica en el mock son los dos guards de dinero: no se exige compra previa (403 api_key_requires_purchase) ni saldo disponible (429 too_many_requests). Ese es justamente el punto del ambiente de pruebas.

Consultas disponibles

Doce combinaciones, las mismas que documenta este sitio:

Servicio	Ruta	Selector
NSS rápido	`/v3/mock/imss`	`type: nss`
NSS profundo	`/v3/mock/imss?_v=2`	`type: nss`
Vigencia de derechos al correo	`/v3/mock/imss?_v=2`	`type: vd`
Solo validar vigencia	`/v3/mock/imss`	`type: vd_validity`
No derechohabiencia	`/v3/mock/imss`	`type: no_dh_web`
Reporte RECI	`/v3/mock/imss`	`type: reci`
Detalles de Afore	`/v3/mock/afore`	`variant: encrypt`
Validación de RFC	`/v3/mock/sat`	`variant: rfc_validation`
Búsqueda de RFC	`/v3/mock/sat`	`variant: rfc_search`
Búsqueda de contribuyente	`/v3/mock/sat`	`variant: tax_payer_search`
Validación de contribuyente	`/v3/mock/sat`	`variant: tax_payer_validation`
Consulta de teléfono	`/v3/mock/phones`	`variant: ifetel`

Cualquier otro type o variant que el validador acepte —por ejemplo la variante email de Afore— responde 400 con errorCode: "unsupported_mock_request_type". No hay ambiente de pruebas para CFE ni para estudios.

Header `X-Mock-Mode`

Elige qué respuesta quieres recibir. Tres valores, iguales para los cuatro servicios:

Valor	Comportamiento
`success`	Respuesta exitosa con datos de ejemplo.
`provider_error`	El error de proveedor más representativo de esa consulta, con su status y su mensaje reales.
`unknown_error`	`500` con el mensaje genérico de fallo inesperado.
(ausente)	Equivale a `success`.

Un valor fuera de esos tres → 400 con errorCode: "invalid_mock_mode".

Qué devuelve cada consulta en `provider_error`

Consulta	Status	`message`
NSS rápido	`400`	La CURP capturada no es válida o no cuenta con NSS
NSS profundo	`400`	La CURP capturada no es válida
Vigencia al correo	`400`	El NSS no fue localizado en el Seguro Social
Solo validar vigencia	`400`	No se encontró un registro asociado a la CURP ni al NSS proporcionado
No derechohabiencia	`400`	La CURP ingresada sí cuenta con servicio médico en el Seguro Social
RECI	`400`	No se pudo suscribir al usuario para obtener el reporte
Afore	`422`	No se encontró la CURP en RENAPO, favor de verificar
Validación de RFC	`400`	No se encontró un RFC válido
Búsqueda de RFC	`400`	No se encontró un RFC válido
Búsqueda de contribuyente	`422`	No se encontró el contribuyente, favor de verificar el RFC e intentar nuevamente
Validación de contribuyente	—	no aplica
Telefonía	`422`	No se encontró un registro con los datos proporcionados

Validación de contribuyente no tiene provider_error: en producción esa consulta no falla con un 4xx de proveedor, solo puede terminar en 500. Pedirle ese modo devuelve 400 con errorCode: "mock_mode_not_supported", en vez de inventarte un error que nunca vas a recibir.

Los errores simulados llegan sin errorCode

En provider_error y unknown_error el campo errorCode viene vacío. No es una carencia del mock: es exactamente lo que devuelve producción hoy para estos cuatro servicios, donde el campo estable todavía no está disponible y el dato útil es el par status + message.

Los únicos códigos que el mock sí emite son los suyos: invalid_mock_mode, mock_mode_not_supported, unsupported_mock_request_type y mock_daily_quota_exceeded. Ninguno existe en producción.

Respuestas exitosas alternas

Tres consultas tienen más de una respuesta 200 legítima. El mock elige a partir de lo que envías, sin modos adicionales:

Consulta	Regla del ambiente de pruebas
Búsqueda de contribuyente	RFC de 12 caracteres → persona moral; de 13 → persona física
Validación de contribuyente	`zipCode` igual a `"00000"` → `isValid: false`; cualquier otro → `true`
Telefonía	número que empieza con `55`, `33` u `81` → `"Fijo"`; el resto → `"Móvil"`

Son convenciones del ambiente de pruebas

En producción esa rama la decide el proveedor a partir de datos reales, no la forma de tu petición. Úsalas para ejercitar los dos caminos de tu código, no para inferir cómo se comporta el servicio real.

Ojo con el caso contrario: validación y búsqueda de RFC devuelven siempre isValid: true en un 200. Cuando el RFC no resulta válido, la API responde 400 — no un 200 con la bandera en false. Para ejercitar ese camino usa X-Mock-Mode: provider_error.

Datos de ejemplo

Las respuestas exitosas hacen eco de los identificadores que enviaste —curp, nss, rfc, taxPayer, zipCode, phoneNumber— y rellenan el resto con datos ficticios fijos, para que puedas correlacionar cada respuesta con su petición.

La persona ficticia es la misma en todos los servicios (incluidos los mocks de semanas cotizadas y actas): JUAN MOCK PEREZ, CURP MOPJ800101HDFRRN09, NSS 12345678901. Las consultas que entregan documento (no derechohabiencia y RECI) devuelven una pdfUrl de ejemplo y un PDF dummy en pdfBase64.

Cuota diaria

El mock no gasta créditos, así que su volumen se acota con una cuota diaria por servicio y por usuario. Al agotarla recibes 429 con errorCode: "mock_daily_quota_exceeded" y un header Retry-After con los segundos que faltan para el siguiente intento.

Los cupos son independientes entre servicios: agotar el de Hacienda no te impide seguir probando el Seguro Social.
Van por usuario, no por clave: rotar tu API Key no reinicia el contador.
Se reponen de forma continua a lo largo del día, no de golpe a medianoche.
Un rechazo del propio mock —modo inválido o consulta no cubierta— no te gasta cuota.

Ejemplos

NSS rápido (camino feliz):

bash

curl -X POST https://api.consultaunica.mx/v3/mock/imss \
  -H "x-api-key: $CU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "nss",
    "nss": { "curp": "LOOA531113HTCPBN07" },
    "userEmail": "[email protected]"
  }'

Afore simulando error del proveedor:

bash

curl -X POST https://api.consultaunica.mx/v3/mock/afore \
  -H "x-api-key: $CU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Mock-Mode: provider_error" \
  -d '{ "variant": "encrypt", "curp": "LOOA531113HTCPBN07" }'

json

{
    "message": "No se encontró la CURP en RENAPO, favor de verificar",
    "description": "",
    "errorCode": ""
}

Búsqueda de contribuyente, rama de persona moral:

bash

curl -X POST https://api.consultaunica.mx/v3/mock/sat \
  -H "x-api-key: $CU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "variant": "tax_payer_search", "taxPayerSearch": { "rfc": "COP920428Q20" } }'

json

{
    "variant": "tax_payer_search",
    "taxPayerSearch": {
        "entityType": "company",
        "company": { "name": "EMPRESA MOCK SA DE CV" }
    }
}

Telefonía, teléfono móvil:

bash

curl -X POST https://api.consultaunica.mx/v3/mock/phones \
  -H "x-api-key: $CU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "variant": "ifetel", "ifetel": { "phoneNumber": "6141234567" } }'

Fallo inesperado, en cualquier servicio:

bash

curl -X POST https://api.consultaunica.mx/v3/mock/sat \
  -H "x-api-key: $CU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Mock-Mode: unknown_error" \
  -d '{ "variant": "rfc_validation", "rfcValidation": { "rfc": "LOOA531113FI5" } }'

Lo que el mock no simula

Latencia. Responde de inmediato; no lo uses para calibrar timeouts.
Reglas de negocio del servicio real: límites diarios por CURP, ventanas de disponibilidad del proveedor o consultas duplicadas. Esas viven en el canal productivo.
Errores de validación: esos no necesitan simulación. El mock valida tu payload con las mismas reglas que producción, así que un cuerpo malformado te devuelve el mismo 409 con la misma lista errors en ambos lados.

Cuando estés listo

Quita /mock del path y compra un paquete en https://consultaunica.mx/paquetes. No hay ningún otro cambio: mismo cuerpo, mismos headers, mismas respuestas.

🧪 Ambiente de pruebas (modo mock) ​

Rutas ​

Autenticación ​

Consultas disponibles ​

Header X-Mock-Mode ​

Qué devuelve cada consulta en provider_error ​

Respuestas exitosas alternas ​

Datos de ejemplo ​

Cuota diaria ​

Ejemplos ​

Lo que el mock no simula ​

Cuando estés listo ​

🧪 Ambiente de pruebas (modo mock)

Rutas

Autenticación

Consultas disponibles

Header `X-Mock-Mode`

Qué devuelve cada consulta en `provider_error`

Respuestas exitosas alternas

Datos de ejemplo

Cuota diaria

Ejemplos

Lo que el mock no simula

Cuando estés listo