Casi todos los formularios de alta en México piden lo mismo: CURP, nombre, fecha de nacimiento y domicilio. Y casi todos fallan en lo mismo:
- La CURP "válida" que no existe. La regex la acepta, el dígito verificador cuadra, pero RENAPO no la tiene o pertenece a otra persona.
- La dirección escrita a mano. "Monterey", "N.L.", "Col. Centro" en un código postal que no tiene colonia Centro. Después nadie puede entregar el paquete ni cotejar el comprobante de domicilio.
En este artículo armamos en Node.js (18 o más reciente, con fetch nativo) y Express un backend pequeño que resuelve las dos cosas:
- Revisa el formato de la CURP sin red (formato, fecha real, dígito verificador).
- La confirma con RENAPO y compara lo que la persona escribió contra lo que el registro tiene.
- Con los cinco dígitos del código postal llena estado, municipio y la lista de colonias del catálogo de Correos de México (SEPOMEX).
- Si la persona no sabe su código postal, lo busca por nombre de colonia.
Para las consultas uso MexCheck, el API que construí (abajo va la aclaración completa). Todo el código está probado con node --test contra respuestas simuladas con la forma exacta de la especificación OpenAPI del API.
1. La CURP sin red: formato, fecha y dígito verificador
La CURP tiene 18 caracteres: cuatro letras del nombre, la fecha de nacimiento (AAMMDD), el sexo (H o M; el validador también acepta X), la entidad de nacimiento (dos letras; NE si nació en el extranjero), tres consonantes internas, un carácter que distingue el siglo y el dígito verificador.
Tres errores comunes al validarla:
- Aceptar cualquier fecha:
560231pasa una regex de\d{6}, pero no existe el 31 de febrero. - Ignorar el siglo: la posición 17 es un dígito para nacidos antes de 2000 y una letra del 2000 en adelante. Sin eso,
000229puede ser el 29 de febrero de 1900 (que no existió) o de 2000 (que sí). - No calcular el dígito verificador: con él atrapas la mayoría de los errores de dedo antes de gastar una consulta.
// Validación de formato de la CURP, sin red. No dice si la CURP existe: eso lo sabe RENAPO.
const DICC = '0123456789ABCDEFGHIJKLMNÑOPQRSTUVWXYZ';
const RE_CURP = /^([A-Z][AEIOUX][A-Z]{2})(\d{2})(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])([HMX])(AS|BC|BS|CC|CL|CM|CS|CH|DF|DG|GT|GR|HG|JC|MC|MN|MS|NT|NL|OC|PL|QT|QR|SP|SL|SR|TC|TS|TL|VZ|YN|ZS|NE)([B-DF-HJ-NP-TV-Z]{3})([A-Z\d])(\d)$/;
function digitoVerificador(curp17) {
let suma = 0;
for (let i = 0; i < 17; i++) suma += DICC.indexOf(curp17[i]) * (18 - i);
return (10 - (suma % 10)) % 10;
}
function validarCurp(valor) {
const curp = String(valor ?? '').trim().toUpperCase();
const m = curp.match(RE_CURP);
if (!m) return { ok: false, curp, motivo: 'formato' };
// Posición 17: dígito = nacido antes de 2000, letra = 2000 en adelante
const anio = (/\d/.test(m[8]) ? 1900 : 2000) + Number(m[2]);
const mes = Number(m[3]), dia = Number(m[4]);
const f = new Date(Date.UTC(anio, mes - 1, dia));
if (f.getUTCMonth() !== mes - 1 || f.getUTCDate() !== dia) {
return { ok: false, curp, motivo: 'fecha' };
}
if (digitoVerificador(curp) !== Number(m[9])) {
return { ok: false, curp, motivo: 'digito' };
}
const fechaNacimiento = `${anio}-${m[3]}-${m[4]}`; // AAAA-MM-DD
return { ok: true, curp, fechaNacimiento, sexo: m[5], entidad: m[6] };
}
module.exports = { validarCurp, digitoVerificador };
Esto no dice si la CURP existe. Dice que podría existir. Para lo demás hay que preguntarle a RENAPO.
2. Un cliente para el API que sabe cuándo reintentar
Los tres endpoints que vamos a usar son POST con JSON y la llave en la cabecera x-api-key:
| Endpoint | Entra | Sale | Costo |
|---|---|---|---|
/v1/curp/lookup |
curp |
identidad registrada en RENAPO | 5 créditos |
/v1/geo/zip |
zip (5 dígitos, como texto) |
estado, municipio, ciudad y colonias | gratis con plan activo; 1 crédito en pago por uso |
/v1/geo/zip-search |
settlement, municipality o zip (2 a 5 dígitos), opcionalmente state
|
colonias que coinciden, con su CP | igual que /geo/zip
|
Lo importante es qué hacer cuando algo sale mal:
-
found: nullen/curp/lookupsignifica que RENAPO no contestó. No es "no existe". No se cobra; se reintenta. -
429,500,504(la consulta no terminó en 90 s) y503(geo_unavailable, el catálogo de códigos postales se está cargando) también se reintentan. -
401(llave),402(sin saldo) y422(datos inválidos) no: repetir la petición no cambia nada. - El timeout del cliente va arriba de 90 segundos. Si cortas antes, el API cancela la consulta y te quedas sin respuesta.
// Cliente mínimo para MexCheck: reintenta lo que se puede reintentar y nada más.
const BASE_URL = 'https://mexcheck.com/v1';
const REINTENTABLES = new Set([429, 500, 503, 504]);
class MexCheckError extends Error {
constructor(status, cuerpo) {
super(cuerpo?.message || cuerpo?.error || `HTTP ${status}`);
this.status = status;
this.codigo = cuerpo?.error; // invalid_curp, invalid_fields, ...
this.cuerpo = cuerpo;
}
}
function crearCliente({
apiKey = process.env.MEXCHECK_API_KEY,
fetchImpl = globalThis.fetch,
intentos = 4,
esperar = (ms) => new Promise((r) => setTimeout(r, ms)),
} = {}) {
async function post(ruta, cuerpo) {
for (let i = 0; i < intentos; i++) {
if (i > 0) await esperar(1000 * 2 ** (i - 1)); // 1 s, 2 s, 4 s
let r;
try {
r = await fetchImpl(`${BASE_URL}${ruta}`, {
method: 'POST',
headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' },
body: JSON.stringify(cuerpo),
signal: AbortSignal.timeout(95_000), // RENAPO puede tardar; el API espera hasta 90 s
});
} catch (e) {
continue; // red o timeout de nuestro lado: reintenta
}
if (REINTENTABLES.has(r.status)) continue;
const datos = await r.json().catch(() => ({}));
if (!r.ok) throw new MexCheckError(r.status, datos); // 401, 402, 422: repetir no cambia nada
if ('found' in datos && datos.found === null) continue; // RENAPO no contestó; no se cobra
return datos;
}
return null; // sin respuesta definitiva
}
return {
consultarCurp: (curp) => post('/curp/lookup', { curp }),
codigoPostal: (zip) => post('/geo/zip', { zip }),
buscarColonias: (filtros) => post('/geo/zip-search', filtros),
};
}
module.exports = { crearCliente, MexCheckError };
fetchImpl y esperar se inyectan para poder probar sin red y sin esperar segundos reales.
3. RENAPO dice quién es; tú decides si coincide
Una respuesta exitosa de /v1/curp/lookup se ve así (datos de ejemplo de la documentación):
{
"curp": "PEMJ800101HDFRRN07",
"found": true,
"message": "Identity retrieved from RENAPO",
"person": {
"curp": "PEMJ800101HDFRRN07",
"renapo_valid": true,
"names": "JUAN",
"paternal_surname": "PEREZ",
"mothers_maiden_name": "MARTINEZ",
"sex": "HOMBRE",
"birthdate": "01/01/1980",
"entity_birth": "DF",
"status_curp": "RCN",
"certified": true,
"certification": "CURP Certificada: verificada con el Registro Civil",
"associated_curps": []
}
}
Tres detalles:
-
birthdateviene comoDD/MM/AAAA. -
status_curpes el código de RENAPO tal cual. Los que empiezan conBson bajas (la CURP se dio de baja;BDes baja por defunción). Una CURP dada de baja no debería abrir una cuenta. -
found: falsesignifica que RENAPO no regresó un registro. Si ademásperson.homonimoestrue, RENAPO reporta un problema con esa clave. Esta respuesta sí se cobra, porque RENAPO contestó.
Para comparar nombres hay que normalizar: la persona escribe "José Pérez Núñez" y el registro tiene mayúsculas sin acentos. Quito acentos (y la tilde de la Ñ, para compararla igual en ambos lados), paso a mayúsculas y colapso espacios:
// Compara lo que escribió la persona con lo que RENAPO tiene registrado.
const normalizar = (s) =>
String(s ?? '')
.normalize('NFD').replace(/[\u0300-\u036f]/g, '') // quita acentos y la tilde de la Ñ
.toUpperCase().replace(/[^A-Z ]/g, ' ')
.replace(/\s+/g, ' ').trim();
// "1980-01-31" -> "31/01/1980", el formato de RENAPO
const aDDMMAAAA = (iso) => iso.split('-').reverse().join('/');
function compararIdentidad(capturado, person) {
const diferencias = [];
if (normalizar(capturado.nombres) !== normalizar(person.names)) diferencias.push('nombres');
if (normalizar(capturado.primerApellido) !== normalizar(person.paternal_surname)) diferencias.push('primerApellido');
if (normalizar(capturado.segundoApellido) !== normalizar(person.mothers_maiden_name)) diferencias.push('segundoApellido');
if (capturado.fechaNacimiento && aDDMMAAAA(capturado.fechaNacimiento) !== person.birthdate) {
diferencias.push('fechaNacimiento');
}
return diferencias;
}
module.exports = { normalizar, compararIdentidad, aDDMMAAAA };
Con eso la decisión queda en cuatro resultados:
- aprobada: existe, no está dada de baja y todo coincide.
- revisar: existe pero algún dato difiere (un segundo nombre que la persona no escribió, un apellido con otra grafía). Esto va a una persona, no a un rechazo automático.
- rechazada: formato inválido, la fecha escrita no coincide con la de la CURP, RENAPO no la encontró o está dada de baja.
- pendiente: RENAPO no contestó después de los reintentos. Guarda el alta y vuelve a intentar más tarde.
const { validarCurp } = require('./curp');
const { compararIdentidad } = require('./comparar');
// Devuelve { resultado: 'aprobada' | 'revisar' | 'rechazada' | 'pendiente', motivos: [...] }
async function verificarCurp(cliente, capturado) {
const formato = validarCurp(capturado.curp);
if (!formato.ok) return { resultado: 'rechazada', motivos: [`curp_${formato.motivo}`] };
// Si escribió su fecha, debe coincidir con la que va dentro de la CURP (gratis, sin red)
if (capturado.fechaNacimiento && capturado.fechaNacimiento !== formato.fechaNacimiento) {
return { resultado: 'rechazada', motivos: ['fecha_no_coincide_con_curp'] };
}
const r = await cliente.consultarCurp(formato.curp);
if (r === null) return { resultado: 'pendiente', motivos: ['renapo_sin_respuesta'] };
if (r.found === false) {
return { resultado: 'rechazada', motivos: [r.person?.homonimo ? 'renapo_problema_con_la_clave' : 'renapo_no_encontrada'], mensaje: r.message };
}
const p = r.person;
if (p.status_curp?.startsWith('B')) return { resultado: 'rechazada', motivos: [`curp_baja_${p.status_curp}`] };
const diferencias = compararIdentidad(capturado, p);
if (diferencias.length) return { resultado: 'revisar', motivos: diferencias.map((d) => `difiere_${d}`) };
return { resultado: 'aprobada', motivos: [], certificada: p.certified };
}
module.exports = { verificarCurp };
Fíjate en el orden: el formato y la fecha se revisan antes de consultar. Una CURP con el dígito mal o una fecha que no coincide nunca sale a la red, así que no cuesta nada. (El API también rechaza con 422 invalid_curp una CURP mal formada sin cobrarla, pero si la atrapas tú, te ahorras la ida y vuelta.)
4. Código postal: estado, municipio y colonias
/v1/geo/zip recibe el código postal como texto (para no perder el cero inicial de los códigos de la Ciudad de México que empiezan con 0, como 06700) y regresa:
{
"zip": "22000",
"found": true,
"state": "Baja California",
"state_code": "02",
"municipality": "Tijuana",
"municipality_code": "004",
"city": "Tijuana",
"settlements": [
{ "name": "Zona Centro", "type": "Colonia", "zone": "Urbano" }
]
}
(Respuesta abreviada.) Un código postal suele cubrir varias colonias, así que la respuesta trae todas en settlements; la persona elige la suya de una lista en vez de escribirla. state_code y municipality_code son las claves del INEGI, útiles si tu base de datos ya usa ese catálogo. Si el código no existe en el catálogo, found es false y la lista viene vacía.
El catálogo se actualiza a diario del lado del API, así que en el servidor guardo cada respuesta un día en memoria. En producción probablemente quieras Redis o similar, pero la idea es la misma: el mismo código postal lo teclean muchas personas.
Para quien no sabe su código postal, /v1/geo/zip-search busca por colonia (al menos tres letras; ignora acentos y mayúsculas) y se puede acotar por estado (state solo acota; no se puede mandar sola). truncated: true avisa que hubo más coincidencias que el limit.
5. El servidor Express
const express = require('express');
const { crearCliente, MexCheckError } = require('./mexcheck');
const { verificarCurp } = require('./decidir');
function crearApp(cliente = crearCliente()) {
const app = express();
app.use(express.json());
// 1) CURP: formato local + RENAPO + comparación con lo capturado
app.post('/api/curp', async (req, res) => {
const { curp, nombres, primerApellido, segundoApellido, fechaNacimiento } = req.body ?? {};
try {
const r = await verificarCurp(cliente, { curp, nombres, primerApellido, segundoApellido, fechaNacimiento });
res.status(r.resultado === 'pendiente' ? 503 : 200).json(r);
} catch (e) {
if (e instanceof MexCheckError && e.status === 422) {
return res.status(200).json({ resultado: 'rechazada', motivos: [e.codigo] });
}
console.error('MexCheck', e.status, e.codigo); // nunca registres la CURP completa
res.status(502).json({ error: 'verificacion_no_disponible' });
}
});
// 2) Código postal -> estado, municipio y colonias (con caché de un día)
const cache = new Map();
const UN_DIA = 24 * 60 * 60 * 1000;
app.get('/api/cp/:cp', async (req, res) => {
const cp = req.params.cp;
if (!/^\d{5}$/.test(cp)) return res.status(400).json({ error: 'cp_invalido' });
const guardado = cache.get(cp);
if (guardado && Date.now() - guardado.en < UN_DIA) return res.json(guardado.datos);
try {
const r = await cliente.codigoPostal(cp);
if (r === null) return res.status(503).json({ error: 'catalogo_no_disponible' });
if (!r.found) return res.status(404).json({ error: 'cp_no_existe' });
const datos = {
cp: r.zip,
estado: r.state,
municipio: r.municipality,
ciudad: r.city,
colonias: r.settlements.map((s) => ({ nombre: s.name, tipo: s.type })),
};
cache.set(cp, { en: Date.now(), datos });
res.json(datos);
} catch (e) {
res.status(502).json({ error: 'catalogo_no_disponible' });
}
});
// 3) "No sé mi código postal": busca por colonia (y opcionalmente estado)
app.get('/api/colonias', async (req, res) => {
const colonia = String(req.query.colonia ?? '').trim();
const estado = String(req.query.estado ?? '').trim();
if (colonia.length < 3) return res.status(400).json({ error: 'escribe_al_menos_3_letras' });
const filtros = { settlement: colonia, limit: 20 };
if (estado) filtros.state = estado;
try {
const r = await cliente.buscarColonias(filtros);
if (r === null) return res.status(503).json({ error: 'catalogo_no_disponible' });
res.json({
resultados: r.results.map((x) => ({ cp: x.zip, colonia: x.settlement, municipio: x.municipality, estado: x.state })),
hayMas: r.truncated,
});
} catch (e) {
res.status(502).json({ error: 'catalogo_no_disponible' });
}
});
return app;
}
module.exports = { crearApp };
if (require.main === module) {
crearApp().listen(3000, () => console.log('http://localhost:3000'));
}
Un par de decisiones que vale la pena explicar:
-
/api/curpresponde503cuando el resultado espendiente, para que el frontend diga "inténtalo en unos minutos" en vez de "tu CURP es inválida". - El log de errores registra el código de estado y el código de error, no la CURP. Una CURP es dato personal; no la dejes en tus logs.
- El código postal se valida (
^\d{5}$) antes de salir a la red.
6. El formulario
Del lado del navegador basta con escuchar el campo del código postal. Cuando tiene cinco dígitos, pide /api/cp/:cp, llena estado y municipio, y convierte la colonia en una lista. Siempre dejo la opción "Mi colonia no aparece": un fraccionamiento muy nuevo puede no estar todavía en el catálogo, y bloquear un alta por eso es peor que recibir una dirección escrita a mano.
// En el navegador: llena estado, municipio y colonias cuando el CP tiene 5 dígitos.
function conectarCodigoPostal(doc = document) {
const cp = doc.querySelector('#cp');
const estado = doc.querySelector('#estado');
const municipio = doc.querySelector('#municipio');
const colonia = doc.querySelector('#colonia');
const aviso = doc.querySelector('#cp-aviso');
let ultimo = '';
cp.addEventListener('input', async () => {
const valor = cp.value.replace(/\D/g, '').slice(0, 5);
cp.value = valor;
if (valor.length !== 5 || valor === ultimo) return;
ultimo = valor;
aviso.textContent = 'Buscando…';
let r;
try {
r = await fetch(`/api/cp/${valor}`);
} catch {
r = { ok: false, status: 0 }; // sin conexión
}
if (cp.value !== valor) return; // la persona siguió escribiendo
if (!r.ok) {
aviso.textContent = r.status === 404
? 'No encontramos ese código postal. Revísalo o escribe tu dirección a mano.'
: 'No pudimos consultar el código postal. Escribe tu dirección a mano.';
return;
}
const d = await r.json();
estado.value = d.estado ?? '';
municipio.value = d.municipio ?? '';
colonia.replaceChildren(
...d.colonias.map((c) => new Option(c.nombre, c.nombre)),
new Option('Mi colonia no aparece', '__otra__'),
);
aviso.textContent = '';
});
}
if (typeof module !== 'undefined') module.exports = { conectarCodigoPostal };
<input id="cp" inputmode="numeric" autocomplete="postal-code" maxlength="6" placeholder="Código postal">
<p id="cp-aviso" aria-live="polite"></p>
<input id="estado" autocomplete="address-level1" placeholder="Estado">
<input id="municipio" autocomplete="address-level2" placeholder="Municipio o alcaldía">
<select id="colonia"></select>
<script src="/formulario.js"></script>
<script>conectarCodigoPostal();</script>
Sirve formulario.js como archivo estático (por ejemplo, con express.static). maxlength="6" deja pegar "64-000" o "64 000"; el script quita lo que no es dígito.
7. Pruebas
Las pruebas usan node:test (incluido en Node) y un fetch falso que responde en orden y guarda lo que se le pidió. Revisan, entre otras cosas, que:
- el dígito verificador y las fechas imposibles (31 de febrero, 29 de febrero de 2001) se rechacen sin red;
- el cliente reintente
found: null,429,503,504y errores de red, y no reintente401,402ni422; - una CURP con dígito incorrecto no genere ninguna llamada al API;
- el mismo código postal se consulte una sola vez gracias a la caché;
- el formulario llene los campos (probado con jsdom).
Un fragmento:
test('cliente: reintenta found:null, 429, 503, 504 y errores de red; no 401/402/422', async () => {
let { c, f } = cliente([[200, M.CURP_NULL], [429, {}], ['red'], [200, M.CURP_OK]]);
assert.equal((await c.consultarCurp('PEMJ800101HDFRRN07')).found, true);
assert.equal(f.llamadas.length, 4);
// ...
for (const [status, error] of [[401, 'unauthorized'], [402, 'payment_required'], [422, 'invalid_curp']]) {
({ c, f } = cliente([[status, { error }]]));
await assert.rejects(c.consultarCurp('X'), (e) => e instanceof MexCheckError && e.status === status && e.codigo === error);
assert.equal(f.llamadas.length, 1);
}
});
Además validé las respuestas simuladas y los cuerpos de petición contra el openapi.json publicado del API, marcando como error cualquier campo que no esté en la especificación. Así me aseguro de no estar programando contra campos inventados.
Privacidad
Vas a tratar CURP, nombre completo, fecha de nacimiento y domicilio. Antes de consultar:
- Ten un aviso de privacidad que diga para qué consultas la CURP y con quién.
- Pide solo lo que necesitas y guarda el resultado de la verificación, no copias de más.
- No mandes la CURP a tus logs ni a herramientas de analítica.
No soy abogado: revisa con quien lleve tu cumplimiento qué aplica a tu caso.
Costos
Pago por uso a $0.015 USD por crédito:
-
/v1/curp/lookup: 5 créditos ($0.075 USD).found: null,422y504no se cobran;found: falsesí. -
/v1/geo/zipy/v1/geo/zip-search: gratis con cualquier plan activo; 1 crédito ($0.015 USD) en pago por uso.
Las cuentas nuevas reciben $5 USD de crédito al registrarse. Los planes mensuales están en la página de precios.
Si programas con un asistente (Claude, Cursor, etc.), el API también está disponible como servidor MCP en https://mexcheck.com/mcp (incluye curp_lookup, geo_zip y geo_zip_search), útil para probar consultas mientras desarrollas. En producción, tu servidor llama al API REST con su llave, como en el código de arriba.
Resumen
- Valida formato, fecha y dígito verificador de la CURP antes de gastar una consulta.
- Confirma con RENAPO y compara nombre y fecha; una diferencia es "revisar", no "rechazar".
- Rechaza CURPs con
status_curpde baja (empiezan conB). -
found: nullsignifica "reintenta", no "no existe". - Pide el código postal primero y ofrece las colonias como lista, con salida para "no aparece".
- Guarda en caché las respuestas de código postal.
La documentación de cada endpoint está en mexcheck.com/docs: CURP, código postal y búsqueda de colonias.
Soy Adrian Rangel, fundador de MexCheck. Las CURP, nombres y códigos postales de este artículo son de ejemplo; el código lo probé con node --test contra respuestas simuladas, no contra consultas reales a RENAPO.
Top comments (0)