<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[Acrogenesis]]></title><description><![CDATA[Acrogenesis]]></description><link>https://acrogenesis.hashnode.dev</link><generator>RSS for Node</generator><lastBuildDate>Fri, 20 Nov 2026 17:49:52 GMT</lastBuildDate><atom:link href="https://acrogenesis.hashnode.dev/rss.xml" rel="self" type="application/rss+xml"/><language><![CDATA[en]]></language><ttl>60</ttl><item><title><![CDATA[Valida la CURP con RENAPO y autocompleta la dirección por código postal en Node.js]]></title><description><![CDATA[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: En este…]]></description><link>https://acrogenesis.hashnode.dev/valida-la-curp-con-renapo-y-autocompleta-la-direcci-n-por-c-digo-postal-en-node-js</link><guid isPermaLink="true">https://acrogenesis.hashnode.dev/valida-la-curp-con-renapo-y-autocompleta-la-direcci-n-por-c-digo-postal-en-node-js</guid><category><![CDATA[JavaScript]]></category><category><![CDATA[Node.js]]></category><category><![CDATA[api]]></category><category><![CDATA[mexico]]></category><dc:creator><![CDATA[Adrian Rangel]]></dc:creator><pubDate>Wed, 18 Nov 2026 21:07:32 GMT</pubDate><content:encoded><![CDATA[<p>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:</p>
<ul>
<li><strong>La CURP "válida" que no existe.</strong> La regex la acepta, el dígito verificador cuadra, pero RENAPO no la tiene o pertenece a otra persona.</li>
<li><strong>La dirección escrita a mano.</strong> "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.</li>
</ul>
<p>En este artículo armamos en Node.js (18 o más reciente, con <code>fetch</code> nativo) y Express un backend pequeño que resuelve las dos cosas:</p>
<ol>
<li>Revisa el formato de la CURP <strong>sin red</strong> (formato, fecha real, dígito verificador).</li>
<li>La confirma con <strong>RENAPO</strong> y compara lo que la persona escribió contra lo que el registro tiene.</li>
<li>Con los cinco dígitos del <strong>código postal</strong> llena estado, municipio y la lista de colonias del catálogo de Correos de México (SEPOMEX).</li>
<li>Si la persona no sabe su código postal, lo busca por <strong>nombre de colonia</strong>.</li>
</ol>
<p>Para las consultas uso <a href="https://mexcheck.com">MexCheck</a>, el API que construí (abajo va la aclaración completa). Todo el código está probado con <code>node --test</code> contra respuestas simuladas con la forma exacta de la especificación OpenAPI del API.</p>
<h2>1. La CURP sin red: formato, fecha y dígito verificador</h2>
<p>La CURP tiene 18 caracteres: cuatro letras del nombre, la fecha de nacimiento (AAMMDD), el sexo (<code>H</code> o <code>M</code>; el validador también acepta <code>X</code>), la entidad de nacimiento (dos letras; <code>NE</code> si nació en el extranjero), tres consonantes internas, un carácter que distingue el siglo y el dígito verificador.</p>
<p>Tres errores comunes al validarla:</p>
<ul>
<li>Aceptar cualquier fecha: <code>560231</code> pasa una regex de <code>\d{6}</code>, pero no existe el 31 de febrero.</li>
<li>Ignorar el siglo: la posición 17 es un <strong>dígito</strong> para nacidos antes de 2000 y una <strong>letra</strong> del 2000 en adelante. Sin eso, <code>000229</code> puede ser el 29 de febrero de 1900 (que no existió) o de 2000 (que sí).</li>
<li>No calcular el dígito verificador: con él atrapas la mayoría de los errores de dedo antes de gastar una consulta.</li>
</ul>
<pre><code class="language-javascript">// 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 &lt; 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 };
</code></pre>
<p>Esto <strong>no</strong> dice si la CURP existe. Dice que podría existir. Para lo demás hay que preguntarle a RENAPO.</p>
<h2>2. Un cliente para el API que sabe cuándo reintentar</h2>
<p>Los tres endpoints que vamos a usar son <code>POST</code> con JSON y la llave en la cabecera <code>x-api-key</code>:</p>
<table>
<thead>
<tr>
<th>Endpoint</th>
<th>Entra</th>
<th>Sale</th>
<th>Costo</th>
</tr>
</thead>
<tbody><tr>
<td><code>/v1/curp/lookup</code></td>
<td><code>curp</code></td>
<td>identidad registrada en RENAPO</td>
<td>5 créditos</td>
</tr>
<tr>
<td><code>/v1/geo/zip</code></td>
<td><code>zip</code> (5 dígitos, como texto)</td>
<td>estado, municipio, ciudad y colonias</td>
<td>gratis con plan activo; 1 crédito en pago por uso</td>
</tr>
<tr>
<td><code>/v1/geo/zip-search</code></td>
<td><code>settlement</code>, <code>municipality</code> o <code>zip</code> (2 a 5 dígitos), opcionalmente <code>state</code></td>
<td>colonias que coinciden, con su CP</td>
<td>igual que <code>/geo/zip</code></td>
</tr>
</tbody></table>
<p>Lo importante es qué hacer cuando algo sale mal:</p>
<ul>
<li><code>found: null</code> en <code>/curp/lookup</code> significa que <strong>RENAPO no contestó</strong>. No es "no existe". No se cobra; se reintenta.</li>
<li><code>429</code>, <code>500</code>, <code>504</code> (la consulta no terminó en 90 s) y <code>503</code> (<code>geo_unavailable</code>, el catálogo de códigos postales se está cargando) también se reintentan.</li>
<li><code>401</code> (llave), <code>402</code> (sin saldo) y <code>422</code> (datos inválidos) no: repetir la petición no cambia nada.</li>
<li>El timeout del cliente va arriba de 90 segundos. Si cortas antes, el API cancela la consulta y te quedas sin respuesta.</li>
</ul>
<pre><code class="language-javascript">// 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) =&gt; new Promise((r) =&gt; setTimeout(r, ms)),
} = {}) {
  async function post(ruta, cuerpo) {
    for (let i = 0; i &lt; intentos; i++) {
      if (i &gt; 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(() =&gt; ({}));
      if (!r.ok) throw new MexCheckError(r.status, datos); // 401, 402, 422: repetir no cambia nada
      if ('found' in datos &amp;&amp; datos.found === null) continue; // RENAPO no contestó; no se cobra
      return datos;
    }
    return null; // sin respuesta definitiva
  }

  return {
    consultarCurp: (curp) =&gt; post('/curp/lookup', { curp }),
    codigoPostal: (zip) =&gt; post('/geo/zip', { zip }),
    buscarColonias: (filtros) =&gt; post('/geo/zip-search', filtros),
  };
}

module.exports = { crearCliente, MexCheckError };
</code></pre>
<p><code>fetchImpl</code> y <code>esperar</code> se inyectan para poder probar sin red y sin esperar segundos reales.</p>
<h2>3. RENAPO dice quién es; tú decides si coincide</h2>
<p>Una respuesta exitosa de <code>/v1/curp/lookup</code> se ve así (datos de ejemplo de la documentación):</p>
<pre><code class="language-json">{
  "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": []
  }
}
</code></pre>
<p>Tres detalles:</p>
<ul>
<li><code>birthdate</code> viene como <code>DD/MM/AAAA</code>.</li>
<li><code>status_curp</code> es el código de RENAPO tal cual. Los que empiezan con <code>B</code> son <strong>bajas</strong> (la CURP se dio de baja; <code>BD</code> es baja por defunción). Una CURP dada de baja no debería abrir una cuenta.</li>
<li><code>found: false</code> significa que RENAPO no regresó un registro. Si además <code>person.homonimo</code> es <code>true</code>, RENAPO reporta un problema con esa clave. Esta respuesta sí se cobra, porque RENAPO contestó.</li>
</ul>
<p>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:</p>
<pre><code class="language-javascript">// Compara lo que escribió la persona con lo que RENAPO tiene registrado.
const normalizar = (s) =&gt;
  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" -&gt; "31/01/1980", el formato de RENAPO
const aDDMMAAAA = (iso) =&gt; 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 &amp;&amp; aDDMMAAAA(capturado.fechaNacimiento) !== person.birthdate) {
    diferencias.push('fechaNacimiento');
  }
  return diferencias;
}

module.exports = { normalizar, compararIdentidad, aDDMMAAAA };
</code></pre>
<p>Con eso la decisión queda en cuatro resultados:</p>
<ul>
<li><strong>aprobada</strong>: existe, no está dada de baja y todo coincide.</li>
<li><strong>revisar</strong>: 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.</li>
<li><strong>rechazada</strong>: formato inválido, la fecha escrita no coincide con la de la CURP, RENAPO no la encontró o está dada de baja.</li>
<li><strong>pendiente</strong>: RENAPO no contestó después de los reintentos. Guarda el alta y vuelve a intentar más tarde.</li>
</ul>
<pre><code class="language-javascript">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 &amp;&amp; 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) =&gt; `difiere_${d}`) };
  return { resultado: 'aprobada', motivos: [], certificada: p.certified };
}

module.exports = { verificarCurp };
</code></pre>
<p>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 <code>422 invalid_curp</code> una CURP mal formada sin cobrarla, pero si la atrapas tú, te ahorras la ida y vuelta.)</p>
<h2>4. Código postal: estado, municipio y colonias</h2>
<p><code>/v1/geo/zip</code> recibe el código postal <strong>como texto</strong> (para no perder el cero inicial de los códigos de la Ciudad de México que empiezan con <code>0</code>, como <code>06700</code>) y regresa:</p>
<pre><code class="language-json">{
  "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" }
  ]
}
</code></pre>
<p>(Respuesta abreviada.) Un código postal suele cubrir varias colonias, así que la respuesta trae <strong>todas</strong> en <code>settlements</code>; la persona elige la suya de una lista en vez de escribirla. <code>state_code</code> y <code>municipality_code</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, <code>found</code> es <code>false</code> y la lista viene vacía.</p>
<p>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.</p>
<p>Para quien no sabe su código postal, <code>/v1/geo/zip-search</code> busca por colonia (al menos tres letras; ignora acentos y mayúsculas) y se puede acotar por estado (<code>state</code> solo acota; no se puede mandar sola). <code>truncated: true</code> avisa que hubo más coincidencias que el <code>limit</code>.</p>
<h2>5. El servidor Express</h2>
<pre><code class="language-javascript">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) =&gt; {
    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 &amp;&amp; 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 -&gt; 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) =&gt; {
    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 &amp;&amp; Date.now() - guardado.en &lt; 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) =&gt; ({ 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) =&gt; {
    const colonia = String(req.query.colonia ?? '').trim();
    const estado = String(req.query.estado ?? '').trim();
    if (colonia.length &lt; 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) =&gt; ({ 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, () =&gt; console.log('http://localhost:3000'));
}
</code></pre>
<p>Un par de decisiones que vale la pena explicar:</p>
<ul>
<li><code>/api/curp</code> responde <code>503</code> cuando el resultado es <code>pendiente</code>, para que el frontend diga "inténtalo en unos minutos" en vez de "tu CURP es inválida".</li>
<li>El log de errores registra el código de estado y el código de error, <strong>no la CURP</strong>. Una CURP es dato personal; no la dejes en tus logs.</li>
<li>El código postal se valida (<code>^\d{5}$</code>) antes de salir a la red.</li>
</ul>
<h2>6. El formulario</h2>
<p>Del lado del navegador basta con escuchar el campo del código postal. Cuando tiene cinco dígitos, pide <code>/api/cp/:cp</code>, 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.</p>
<pre><code class="language-javascript">// 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 () =&gt; {
    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) =&gt; new Option(c.nombre, c.nombre)),
      new Option('Mi colonia no aparece', '__otra__'),
    );
    aviso.textContent = '';
  });
}

if (typeof module !== 'undefined') module.exports = { conectarCodigoPostal };
</code></pre>
<pre><code class="language-html">&lt;input id="cp" inputmode="numeric" autocomplete="postal-code" maxlength="6" placeholder="Código postal"&gt;
&lt;p id="cp-aviso" aria-live="polite"&gt;&lt;/p&gt;
&lt;input id="estado" autocomplete="address-level1" placeholder="Estado"&gt;
&lt;input id="municipio" autocomplete="address-level2" placeholder="Municipio o alcaldía"&gt;
&lt;select id="colonia"&gt;&lt;/select&gt;
&lt;script src="/formulario.js"&gt;&lt;/script&gt;
&lt;script&gt;conectarCodigoPostal();&lt;/script&gt;
</code></pre>
<p>Sirve <code>formulario.js</code> como archivo estático (por ejemplo, con <code>express.static</code>). <code>maxlength="6"</code> deja pegar "64-000" o "64 000"; el script quita lo que no es dígito.</p>
<h2>7. Pruebas</h2>
<p>Las pruebas usan <code>node:test</code> (incluido en Node) y un <code>fetch</code> falso que responde en orden y guarda lo que se le pidió. Revisan, entre otras cosas, que:</p>
<ul>
<li>el dígito verificador y las fechas imposibles (31 de febrero, 29 de febrero de 2001) se rechacen sin red;</li>
<li>el cliente reintente <code>found: null</code>, <code>429</code>, <code>503</code>, <code>504</code> y errores de red, y <strong>no</strong> reintente <code>401</code>, <code>402</code> ni <code>422</code>;</li>
<li>una CURP con dígito incorrecto no genere ninguna llamada al API;</li>
<li>el mismo código postal se consulte una sola vez gracias a la caché;</li>
<li>el formulario llene los campos (probado con jsdom).</li>
</ul>
<p>Un fragmento:</p>
<pre><code class="language-javascript">test('cliente: reintenta found:null, 429, 503, 504 y errores de red; no 401/402/422', async () =&gt; {
  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) =&gt; e instanceof MexCheckError &amp;&amp; e.status === status &amp;&amp; e.codigo === error);
    assert.equal(f.llamadas.length, 1);
  }
});
</code></pre>
<p>Además validé las respuestas simuladas y los cuerpos de petición contra el <code>openapi.json</code> 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.</p>
<h2>Privacidad</h2>
<p>Vas a tratar CURP, nombre completo, fecha de nacimiento y domicilio. Antes de consultar:</p>
<ul>
<li>Ten un aviso de privacidad que diga para qué consultas la CURP y con quién.</li>
<li>Pide solo lo que necesitas y guarda el resultado de la verificación, no copias de más.</li>
<li>No mandes la CURP a tus logs ni a herramientas de analítica.</li>
</ul>
<p>No soy abogado: revisa con quien lleve tu cumplimiento qué aplica a tu caso.</p>
<h2>Costos</h2>
<p>Pago por uso a $0.015 USD por crédito:</p>
<ul>
<li><code>/v1/curp/lookup</code>: 5 créditos ($0.075 USD). <code>found: null</code>, <code>422</code> y <code>504</code> no se cobran; <code>found: false</code> sí.</li>
<li><code>/v1/geo/zip</code> y <code>/v1/geo/zip-search</code>: gratis con cualquier plan activo; 1 crédito ($0.015 USD) en pago por uso.</li>
</ul>
<p>Las cuentas nuevas reciben $5 USD de crédito al registrarse. Los planes mensuales están en la <a href="https://mexcheck.com/docs/pricing">página de precios</a>.</p>
<p>Si programas con un asistente (Claude, Cursor, etc.), el API también está disponible como servidor MCP en <code>https://mexcheck.com/mcp</code> (incluye <code>curp_lookup</code>, <code>geo_zip</code> y <code>geo_zip_search</code>), ú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.</p>
<h2>Resumen</h2>
<ul>
<li>Valida formato, fecha y dígito verificador de la CURP antes de gastar una consulta.</li>
<li>Confirma con RENAPO y compara nombre y fecha; una diferencia es "revisar", no "rechazar".</li>
<li>Rechaza CURPs con <code>status_curp</code> de baja (empiezan con <code>B</code>).</li>
<li><code>found: null</code> significa "reintenta", no "no existe".</li>
<li>Pide el código postal primero y ofrece las colonias como lista, con salida para "no aparece".</li>
<li>Guarda en caché las respuestas de código postal.</li>
</ul>
<p>La documentación de cada endpoint está en <a href="https://mexcheck.com/docs">mexcheck.com/docs</a>: <a href="https://curpcheck.com/docs/endpoints/curp-lookup">CURP</a>, <a href="https://mexcheck.com/docs/endpoints/geo-zip">código postal</a> y <a href="https://mexcheck.com/docs/endpoints/geo-zip-search">búsqueda de colonias</a>.</p>
<hr />
<p><em>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 <code>node --test</code> contra respuestas simuladas, no contra consultas reales a RENAPO.</em></p>
]]></content:encoded></item><item><title><![CDATA[Verifica el estatus de un CFDI y si tu proveedor está en la lista 69-B del SAT con Python]]></title><description><![CDATA[Lee el XML de una factura CFDI 4.0, valida RFCs, consulta al SAT si el CFDI está vigente o cancelado, revisa al emisor contra las listas 69 y 69-B, y…]]></description><link>https://acrogenesis.hashnode.dev/verifica-el-estatus-de-un-cfdi-y-si-tu-proveedor-est-en-la-lista-69-b-del-sat-con-python</link><guid isPermaLink="true">https://acrogenesis.hashnode.dev/verifica-el-estatus-de-un-cfdi-y-si-tu-proveedor-est-en-la-lista-69-b-del-sat-con-python</guid><category><![CDATA[Python]]></category><category><![CDATA[api]]></category><category><![CDATA[mexico]]></category><category><![CDATA[spanish]]></category><dc:creator><![CDATA[Adrian Rangel]]></dc:creator><pubDate>Wed, 18 Nov 2026 20:33:11 GMT</pubDate><content:encoded><![CDATA[<p>Si trabajas en cuentas por pagar, un ERP o una fintech en México, recibes facturas todo el día. Casi todas están bien. Las que no, suelen caer en dos casos que el XML no te avisa:</p>
<ol>
<li><strong>El CFDI ya no está vigente.</strong> El emisor lo canceló (a veces después de que lo recibiste) o el SAT no lo tiene registrado.</li>
<li><strong>El emisor aparece en una lista del SAT</strong>, sobre todo la del artículo 69-B del Código Fiscal de la Federación: los contribuyentes que el SAT presume que emiten facturas por operaciones inexistentes (los famosos EFOS).</li>
</ol>
<p>En este artículo armamos en Python un flujo pequeño que puedes meter en tu proceso de recepción de facturas: leer el XML, validar formatos sin red, consultar al SAT y tomar una decisión (pagar, revisar o bloquear).</p>
<h2>Por qué importa revisar</h2>
<p>Un CFDI cancelado deja de tener efectos fiscales. Si lo pagaste y lo deduces, el problema aparece meses después, en una revisión. Y la cancelación puede ocurrir después de que el XML entró a tu sistema, así que el XML que guardaste no basta: hay que preguntarle al SAT.</p>
<p>Las listas del SAT son otro riesgo:</p>
<ul>
<li><strong>Artículo 69-B.</strong> Cuando el SAT concluye que un contribuyente no tenía capacidad para realizar las operaciones que facturó, lo publica primero como <strong>presunto</strong> y, si no desvirtúa, como <strong>definitivo</strong>. Las facturas de un definitivo se consideran sin efectos fiscales, y quien las usó para deducir o acreditar tiene que demostrar que la operación sí existió o corregir su situación fiscal. Hay también quienes lograron salir: <strong>desvirtuados</strong> y con <strong>sentencia favorable</strong>.</li>
<li><strong>Artículo 69.</strong> Contribuyentes con créditos fiscales firmes, no localizados, cancelados, con sentencia condenatoria por delito fiscal, entre otros. No invalida las facturas por sí solo, pero es una señal que tu equipo de cumplimiento querrá ver.</li>
<li><strong>Artículo 69-B Bis.</strong> Transmisión indebida de pérdidas fiscales.</li>
</ul>
<p>No soy abogado; para la interpretación de cada caso, habla con tu contador. Lo que sí podemos automatizar es el <strong>cuándo revisar</strong>:</p>
<ul>
<li><strong>Al recibir la factura</strong>, para rechazar de inmediato lo que no existe o ya está cancelado.</li>
<li><strong>Antes de programar el pago</strong>, porque entre la recepción y el pago pueden pasar 30, 60 o 90 días, y en ese tiempo el emisor puede cancelar o aparecer en una lista.</li>
<li><strong>Periódicamente sobre las facturas ya pagadas</strong>, si tu operación lo justifica.</li>
</ul>
<h2>Parte 1: sin red, leer el XML</h2>
<p>Empezamos con lo que no cuesta nada. Para hacer la consulta al SAT necesitas tres datos del CFDI: el UUID (folio fiscal, dentro del <code>TimbreFiscalDigital</code>), el RFC del emisor y el RFC del receptor. El total lo guardamos para conciliar.</p>
<p>Este es un XML de <strong>ejemplo sintético</strong>. Los RFC <code>EKU9003173C9</code> y <code>URE180429TM6</code> son los que el SAT usa en sus ambientes de prueba, el UUID es inventado y los sellos están vacíos. No es una factura real:</p>
<pre><code class="language-xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!-- EJEMPLO SINTÉTICO: RFC de pruebas del SAT, UUID inventado, sin sellos reales --&gt;
&lt;cfdi:Comprobante xmlns:cfdi="http://www.sat.gob.mx/cfd/4"
    xmlns:tfd="http://www.sat.gob.mx/TimbreFiscalDigital"
    Version="4.0" Serie="A" Folio="1024" Fecha="2026-11-10T12:30:00"
    SubTotal="10000.00" Moneda="MXN" Total="11600.00"
    TipoDeComprobante="I" Exportacion="01" MetodoPago="PPD"
    LugarExpedicion="64000"&gt;
  &lt;cfdi:Emisor Rfc="EKU9003173C9" Nombre="ESCUELA KEMPER URGATE" RegimenFiscal="601"/&gt;
  &lt;cfdi:Receptor Rfc="URE180429TM6" Nombre="UNIVERSIDAD ROBOTICA ESPAÑOLA"
      DomicilioFiscalReceptor="65000" RegimenFiscalReceptor="601" UsoCFDI="G03"/&gt;
  &lt;cfdi:Conceptos&gt;
    &lt;cfdi:Concepto ClaveProdServ="81111500" Cantidad="1" ClaveUnidad="E48"
        Descripcion="Servicio de desarrollo de software" ValorUnitario="10000.00"
        Importe="10000.00" ObjetoImp="02"/&gt;
  &lt;/cfdi:Conceptos&gt;
  &lt;cfdi:Complemento&gt;
    &lt;tfd:TimbreFiscalDigital Version="1.1"
        UUID="6F3C2A1B-0D4E-4B7A-9C21-5E8F7A6B3D10"
        FechaTimbrado="2026-11-10T12:31:05" RfcProvCertif="SPR190613I52"
        SelloCFD="..." NoCertificadoSAT="00000000000000000000" SelloSAT="..."/&gt;
  &lt;/cfdi:Complemento&gt;
&lt;/cfdi:Comprobante&gt;
</code></pre>
<p>Con la librería estándar alcanza. Lo único delicado son los namespaces: en CFDI 4.0 el comprobante usa <code>http://www.sat.gob.mx/cfd/4</code> y el timbre <code>http://www.sat.gob.mx/TimbreFiscalDigital</code>.</p>
<pre><code class="language-python">import xml.etree.ElementTree as ET
from decimal import Decimal

NS = {
    "cfdi": "http://www.sat.gob.mx/cfd/4",
    "tfd": "http://www.sat.gob.mx/TimbreFiscalDigital",
}

def leer_cfdi(ruta):
    raiz = ET.parse(ruta).getroot()
    if raiz.get("Version") != "4.0":
        raise ValueError(f"Se esperaba CFDI 4.0, llegó {raiz.get('Version')}")
    emisor = raiz.find("cfdi:Emisor", NS)
    receptor = raiz.find("cfdi:Receptor", NS)
    timbre = raiz.find("cfdi:Complemento/tfd:TimbreFiscalDigital", NS)
    if timbre is None:
        raise ValueError("El XML no trae TimbreFiscalDigital (¿no está timbrado?)")
    return {
        "uuid": timbre.get("UUID").upper(),
        "rfc_emisor": emisor.get("Rfc"),
        "rfc_receptor": receptor.get("Rfc"),
        "total": Decimal(raiz.get("Total")),
        "tipo": raiz.get("TipoDeComprobante"),
    }

if __name__ == "__main__":
    print(leer_cfdi("factura_ejemplo.xml"))
</code></pre>
<pre><code class="language-text">$ python3 leer_cfdi.py
{'uuid': '6F3C2A1B-0D4E-4B7A-9C21-5E8F7A6B3D10', 'rfc_emisor': 'EKU9003173C9', 'rfc_receptor': 'URE180429TM6', 'total': Decimal('11600.00'), 'tipo': 'I'}
</code></pre>
<p>Usa <code>Decimal</code> para el total, nunca <code>float</code>; vas a compararlo contra montos de pago.</p>
<h3>Validar el formato del RFC</h3>
<p>Antes de gastar una consulta, descarta lo que ni siquiera tiene forma de RFC: 3 letras para personas morales o 4 para físicas, una fecha <code>AAMMDD</code> y 3 caracteres de homoclave, el último un dígito o <code>A</code>.</p>
<pre><code class="language-python">import re
from datetime import date

# 3 letras (moral) o 4 (física) + AAMMDD + homoclave de 3
RFC_RE = re.compile(r"^([A-ZÑ&amp;]{3,4})(\d{2})(\d{2})(\d{2})([A-Z\d]{2}[A\d])$")

def rfc_con_formato_valido(rfc: str) -&gt; bool:
    m = RFC_RE.match(rfc.strip().upper())
    if not m:
        return False
    aa, mm, dd = (int(g) for g in m.group(2, 3, 4))
    try:
        # el año de 2 dígitos es ambiguo; 2000 es bisiesto y sirve para validar 29-feb
        date(2000 + aa, mm, dd)
    except ValueError:
        return False
    return True

if __name__ == "__main__":
    for rfc in ["EKU9003173C9", "URE180429TM6", "XAXX010101000",
                "EKU9013173C9", "ABC12345", "eku9003173c9"]:
        print(f"{rfc:14} {rfc_con_formato_valido(rfc)}")
</code></pre>
<pre><code class="language-text">$ python3 rfc_formato.py
EKU9003173C9   True
URE180429TM6   True
XAXX010101000  True
EKU9013173C9   False
ABC12345       False
eku9003173c9   True
</code></pre>
<p><code>EKU9013173C9</code> falla porque el mes 13 no existe. Ojo: el formato correcto no significa que el RFC exista ni que esté activo. Para eso necesitas al SAT.</p>
<h2>Parte 2: consultar al SAT con el API de MexCheck</h2>
<p>Para no tener que automatizar el portal Verifica CFDI ni descargar y sincronizar los CSV de las listas, uso dos endpoints de <a href="https://mexcheck.com">MexCheck</a>:</p>
<ul>
<li><code>POST /v1/cfdi/verify</code>: pregunta al portal Verifica CFDI del SAT si el comprobante existe y si está vigente o cancelado. Recibe <code>uuid</code>, <code>rfc_emisor</code> y <code>rfc_receptor</code> (o el XML completo en el campo <code>xml</code>, nunca ambos). Tarda unos 3 segundos.</li>
<li><code>POST /v1/rfc/sat-lists</code>: regresa en qué listas (69, 69-B, 69-B Bis) aparece un RFC. Es una consulta a una base local sincronizada con las publicaciones del SAT, así que responde en milisegundos.</li>
</ul>
<p>La autenticación es con el header <code>x-api-key</code>. La llave va en una variable de entorno, <code>MEXCHECK_API_KEY</code>, nunca en el código.</p>
<h3>Qué significa cada respuesta</h3>
<p><code>/cfdi/verify</code> regresa <code>found</code>, <code>status</code>, <code>uuid</code>, <code>message</code> y <code>cfdi</code> (el registro tal como lo imprime el SAT: <code>estado</code>, <code>es_cancelable</code>, <code>estatus_cancelacion</code>, <code>fecha_cancelacion</code>, <code>motivo</code>, <code>folio_sustitucion</code>, <code>total</code> con formato de moneda, etc.):</p>
<table>
<thead>
<tr>
<th><code>found</code></th>
<th><code>status</code></th>
<th>Qué hacer</th>
</tr>
</thead>
<tbody><tr>
<td><code>true</code></td>
<td><code>vigente</code></td>
<td>Sigue el flujo.</td>
</tr>
<tr>
<td><code>true</code></td>
<td><code>cancelado</code></td>
<td>Bloquea. Revisa <code>motivo</code> y <code>folio_sustitucion</code> (motivo 01 trae la factura que lo sustituye).</td>
</tr>
<tr>
<td><code>false</code></td>
<td><code>no_encontrado</code></td>
<td>El SAT no lo tiene. Si se timbró hace menos de 72 horas puede no estar registrado todavía: reintenta más tarde.</td>
</tr>
<tr>
<td><code>false</code></td>
<td><code>rechazado</code></td>
<td>El portal rechazó la solicitud (por ejemplo, un XML ilegible). <code>message</code> trae la razón.</td>
</tr>
<tr>
<td><code>null</code></td>
<td><code>null</code></td>
<td>No se pudo contactar al SAT. Reintenta; no se cobra.</td>
</tr>
</tbody></table>
<p>Si llega un <code>status</code> que no está en la tabla, la documentación pide tratarlo como ni vigente ni cancelado; por eso el código de abajo lo manda a revisión.</p>
<p><code>/rfc/sat-lists</code> regresa <code>{"rfc": ..., "sat_lists": [...]}</code>. Cada elemento trae <code>article</code> (<code>69</code>, <code>69b</code> o <code>69b_bis</code>), <code>sub_list</code>, <code>situation</code>, <code>name</code> y, cuando la lista lo publica, <code>person_type</code>, <code>state</code> y <code>first_publication_date</code>. Lista vacía = el RFC no aparece en ninguna.</p>
<h3>Cliente con reintentos</h3>
<p>Los reintentos importan porque el SAT a veces no responde. <code>found: null</code>, 429, 500 y 504 se reintentan con backoff; 401 (llave), 402 (sin saldo) y 422 (datos inválidos) no, porque repetir no cambia nada. El timeout va a 95 segundos: una consulta puede tardar hasta 90, y si cortas antes, la consulta se cancela y no recibes respuesta.</p>
<pre><code class="language-python">import os
import time
import requests

BASE_URL = "https://mexcheck.com/v1"
HEADERS = {"x-api-key": os.environ["MEXCHECK_API_KEY"]}
REINTENTABLES = {429, 500, 504}

def _post(ruta, cuerpo, intentos=4):
    """POST con reintentos para found:null, 429, 500 y 504 (no se cobran)."""
    for intento in range(intentos):
        r = requests.post(f"{BASE_URL}{ruta}", json=cuerpo,
                          headers=HEADERS, timeout=95)  # el API puede tardar hasta 90 s
        if r.status_code in REINTENTABLES:
            time.sleep(2 ** intento)
            continue
        r.raise_for_status()  # 401, 402 o 422: no tiene caso reintentar
        datos = r.json()
        if "found" in datos and datos["found"] is None:  # SAT no respondió
            time.sleep(2 ** intento)
            continue
        return datos
    return None  # sin respuesta definitiva: deja la factura en cola

def verificar_cfdi(uuid, rfc_emisor, rfc_receptor):
    return _post("/cfdi/verify", {"uuid": uuid, "rfc_emisor": rfc_emisor,
                                  "rfc_receptor": rfc_receptor})

def listas_sat(rfc):
    return _post("/rfc/sat-lists", {"rfc": rfc})
</code></pre>
<p>Si prefieres mandar el XML completo, el SAT además revisa los sellos y llena <code>sello_cfdi</code> y <code>sello_timbre_fiscal</code>: <code>curl -F xml=@factura.xml -H "x-api-key: $MEXCHECK_API_KEY" https://mexcheck.com/v1/cfdi/verify</code>.</p>
<h3>La decisión</h3>
<p>Aquí va la regla de negocio. La mía es conservadora: bloquear si el CFDI está cancelado o el emisor es 69-B definitivo; mandar a revisión todo lo demás que no esté limpio (presuntos, artículo 69, no encontrados, estatus raros). Ajústala con tu área fiscal.</p>
<pre><code class="language-python">def decidir_pago(cfdi_resp, listas_resp):
    """Regresa (acción, motivos). Acciones: pagar, revisar, reintentar, bloquear."""
    if cfdi_resp is None or listas_resp is None:
        return "reintentar", ["SAT o el API no dieron respuesta definitiva"]

    bloqueos, revisiones = [], []

    status = cfdi_resp.get("status")
    if status == "cancelado":
        c = cfdi_resp["cfdi"]
        bloqueos.append(f"CFDI cancelado el {c.get('fecha_cancelacion')} (motivo {c.get('motivo')})")
    elif status == "no_encontrado":
        revisiones.append("SAT no encuentra el CFDI (si se timbró hace menos de 72 h, reintenta después)")
    elif status != "vigente":
        revisiones.append(f"Estatus inesperado: {status!r} - {cfdi_resp.get('message')}")

    for l in listas_resp.get("sat_lists", []):
        situacion = (l.get("situation") or "").upper()
        if l["article"] == "69b" and "DEFINITIVO" in situacion:
            bloqueos.append(f"Emisor en 69-B como {l['situation']}")
        elif l["article"] == "69b" and ("DESVIRTUADO" in situacion or "FAVORABLE" in situacion):
            revisiones.append(f"Emisor estuvo en 69-B ({l['situation']}); guarda la evidencia")
        else:
            revisiones.append(f"Emisor en art. {l['article']} / {l.get('sub_list')}: {l['situation']}")

    if bloqueos:
        return "bloquear", bloqueos + revisiones
    if revisiones:
        return "revisar", revisiones
    return "pagar", []
</code></pre>
<h3>Probarlo sin gastar créditos</h3>
<p>Para no tocar el API real mientras desarrollas, simulo <code>requests.post</code> con respuestas que tienen exactamente la forma del esquema OpenAPI (los valores son inventados). Escenarios: todo limpio, SAT caído una vez, un 429 seguido de un emisor en 69-B definitivo, un CFDI cancelado y el SAT caído en todos los intentos:</p>
<pre><code class="language-text">$ python3 test_mock.py
vigente + limpio                 -&gt; ('pagar', [])
SAT caído 1 vez, luego vigente   -&gt; ('pagar', [])
429 y luego vigente + EFOS       -&gt; ('bloquear', ['Emisor en 69-B como Definitivo'])
cancelado + limpio               -&gt; ('bloquear', ['CFDI cancelado el 2026-11-12T09:15:00 (motivo 02)'])
SAT caído siempre                -&gt; ('reintentar', ['SAT o el API no dieron respuesta definitiva'])
</code></pre>
<p>Valido además esos mocks contra el <code>openapi.json</code> con <code>jsonschema</code>, prohibiendo campos extra, para no depender de campos inventados. En tu CI puedes hacer lo mismo: el esquema está en la documentación.</p>
<h2>Parte 3: que tu agente de IA lo haga por ti (MCP)</h2>
<p>Si construyes la integración con Claude Code, Cursor u otro cliente MCP, puedes conectar el servidor MCP de MexCheck para que el asistente lea la documentación y ejecute consultas reales mientras escribe el código. Las herramientas relevantes son <code>cfdi_verify</code> y <code>rfc_sat_lists</code>, que reciben los mismos campos que el endpoint REST y regresan el mismo JSON.</p>
<p>Claude Code:</p>
<pre><code class="language-bash">claude mcp add --transport http mexcheck https://mexcheck.com/mcp
</code></pre>
<p>Cursor (<code>.cursor/mcp.json</code>):</p>
<pre><code class="language-json">{
  "mcpServers": {
    "mexcheck": { "url": "https://mexcheck.com/mcp" }
  }
}
</code></pre>
<p>No hay llave que pegar: la primera vez que el asistente usa una herramienta de tu cuenta, abre el navegador para que inicies sesión. Un detalle: el MCP es para desarrollar. En producción tu servidor llama al API REST con su llave, como en el código de arriba. Y las consultas por MCP cuestan lo mismo que por REST.</p>
<h2>Costos</h2>
<p>Pago por uso a $0.015 USD por crédito:</p>
<ul>
<li><code>/v1/cfdi/verify</code>: 5 créditos ($0.075 USD). Las respuestas <code>found: null</code> y los errores 422 no se cobran; un <code>no_encontrado</code> sí, porque el SAT contestó.</li>
<li><code>/v1/rfc/sat-lists</code>: gratis con cualquier plan activo; 1 crédito ($0.015 USD) en pago por uso.</li>
</ul>
<p>Las cuentas nuevas reciben $5 USD de crédito al registrarse. Los planes mensuales están en la <a href="https://mexcheck.com/docs/pricing">página de precios</a>.</p>
<h2>Resumen</h2>
<ul>
<li>Del XML sacas UUID, RFC emisor, RFC receptor y total sin red y sin dependencias.</li>
<li>Valida el formato del RFC antes de consultar, pero no lo confundas con validar que existe.</li>
<li>Consulta el estatus del CFDI al recibirlo <strong>y otra vez antes de pagar</strong>.</li>
<li>Revisa al emisor contra 69-B (y 69) en los mismos dos momentos.</li>
<li><code>found: null</code> significa "reintenta", no "no existe".</li>
<li>Deja que la regla de bloqueo la defina tu área fiscal; el código solo la aplica.</li>
</ul>
<p>La documentación completa está en <a href="https://mexcheck.com/docs">mexcheck.com/docs</a> y puedes crear una cuenta en <a href="https://mexcheck.com">mexcheck.com</a>.</p>
<hr />
<p><em>Soy Adrian Rangel, fundador de MexCheck. Los RFC, UUID y respuestas de este artículo son de ejemplo; el código lo probé contra respuestas simuladas, no contra facturas reales.</em></p>
]]></content:encoded></item><item><title><![CDATA[Validating Mexican RFC and CURP in Python: check digits, edge cases, and when you need a live lookup]]></title><description><![CDATA[Disclosure: I'm Adrian Rangel, the founder of MexCheck, which I mention near the end. The first two thirds of this post are plain Python with no…]]></description><link>https://acrogenesis.hashnode.dev/validating-mexican-rfc-and-curp-in-python-check-digits-edge-cases-and-when-you-need-a-live-lookup</link><guid isPermaLink="true">https://acrogenesis.hashnode.dev/validating-mexican-rfc-and-curp-in-python-check-digits-edge-cases-and-when-you-need-a-live-lookup</guid><category><![CDATA[Python]]></category><category><![CDATA[APIs]]></category><category><![CDATA[mexico]]></category><category><![CDATA[mcp]]></category><dc:creator><![CDATA[Adrian Rangel]]></dc:creator><pubDate>Wed, 18 Nov 2026 18:51:32 GMT</pubDate><content:encoded><![CDATA[<blockquote>
<p>Disclosure: I'm Adrian Rangel, the founder of MexCheck, which I mention near the end. The first two thirds of this post are plain Python with no dependencies, and you can use them without signing up for anything. All identifiers below are public examples, not real people.</p>
</blockquote>
<p>If your company onboards Mexican customers, contractors or suppliers, sooner or later a form asks for an <strong>RFC</strong> (the SAT tax ID) or a <strong>CURP</strong> (the national population ID). Payroll needs both, CFDI invoicing needs the RFC, and KYC usually wants the CURP.</p>
<p>A regex copied from somewhere catches some typos, but lets through wrong check digits, impossible dates, and IDs that are well formed but belong to nobody. Here are the real formats, a tested validator, and where offline validation stops being enough.</p>
<h2>The RFC: 13 characters for people, 12 for companies</h2>
<table>
<thead>
<tr>
<th>Part</th>
<th>Persona fisica (individual)</th>
<th>Persona moral (company)</th>
</tr>
</thead>
<tbody><tr>
<td>Letters</td>
<td>4, from surnames and first name</td>
<td>3, from the company name</td>
</tr>
<tr>
<td>Date</td>
<td><code>YYMMDD</code> birth date</td>
<td><code>YYMMDD</code> incorporation date</td>
</tr>
<tr>
<td>Homoclave</td>
<td>2 characters assigned by SAT</td>
<td>2 characters assigned by SAT</td>
</tr>
<tr>
<td>Check digit</td>
<td><code>0</code>-<code>9</code> or <code>A</code></td>
<td><code>0</code>-<code>9</code> or <code>A</code></td>
</tr>
<tr>
<td>Length</td>
<td>13</td>
<td>12</td>
</tr>
</tbody></table>
<p>So <code>GODE561231GR8</code> (the example in SAT's own instructions) is an individual born 1956-12-31, and <code>SAT970701NN3</code> is a company incorporated 1997-07-01.</p>
<p>Gotchas:</p>
<ul>
<li><strong><code>Ñ</code> and <code>&amp;</code> are legal letters.</strong> A company called "P&amp;G Something" gets an <code>&amp;</code> in its RFC, and surnames like Muñoz give you an <code>Ñ</code>. A <code>[A-Z]</code> regex rejects valid taxpayers. Make sure your column and your form are UTF-8.</li>
<li><strong>The homoclave is not derivable in practice.</strong> There is a published procedure, but SAT assigns it and resolves homonyms on its side. Do not try to regenerate an RFC from the person's name and compare; take what is on their Constancia de Situacion Fiscal.</li>
<li><strong>Inconvenient words.</strong> When the four initials spell an offensive word, the authority replaces a letter with <code>X</code>. Another reason not to rebuild the ID from the name.</li>
<li><strong>Generic RFCs.</strong> <code>XAXX010101000</code> (domestic counterpart without an RFC, used for "publico en general" invoices) and <code>XEXX010101000</code> (foreign counterpart) do not follow the check-digit algorithm. Treat them as a separate case, not as valid customer IDs.</li>
</ul>
<h3>The RFC check digit (mod 11)</h3>
<p>Each of the first 12 characters maps to a value in the table <code>0123456789ABCDEFGHIJKLMN&amp;OPQRSTUVWXYZ Ñ</code> (so <code>&amp;</code> = 24, space = 37, <code>Ñ</code> = 38). Company RFCs are padded with a leading space to 12 characters. Multiply by weights 13 down to 2, sum, and take <code>11 - (sum % 11)</code>; 11 becomes <code>0</code> and 10 becomes <code>A</code>.</p>
<h2>The CURP: 18 characters</h2>
<p><code>PEMJ800101HDFRRN07</code> breaks down as:</p>
<ul>
<li><code>PEMJ</code>: first surname initial + its first internal vowel, second surname initial, first name initial. When these spell an inconvenient word, RENAPO replaces the second character with <code>X</code>, so position 2 is a vowel <strong>or <code>X</code></strong>. An <code>Ñ</code> in a name is also written as <code>X</code> in the key, which is why the CURP regex below only accepts <code>A-Z</code>.</li>
<li><code>800101</code>: birth date <code>YYMMDD</code>.</li>
<li><code>H</code>: sex (<code>H</code>, <code>M</code>, or <code>X</code>).</li>
<li><code>DF</code>: state of birth (32 codes, plus <code>NE</code> for born abroad).</li>
<li><code>RRN</code>: first internal consonants of each surname and the first name.</li>
<li><code>0</code>: differentiator assigned by RENAPO to avoid duplicates (in practice, a digit for people born before 2000 and a letter after).</li>
<li><code>7</code>: check digit.</li>
</ul>
<h3>The CURP check digit (mod 10)</h3>
<p>Map the first 17 characters with <code>0123456789ABCDEFGHIJKLMNÑOPQRSTUVWXYZ</code> (a different table from the RFC one: <code>Ñ</code> sits right after <code>N</code> at value 24, and there is no <code>&amp;</code> or space), multiply by weights 18 down to 2, sum, and the digit is <code>(10 - sum % 10) % 10</code>.</p>
<h2>A tested validator</h2>
<p>Save this as <code>mxid.py</code>. Standard library only.</p>
<pre><code class="language-python">import re
from datetime import date

# --- RFC -------------------------------------------------------------
RFC_RE = re.compile(
    r"^(?P&lt;letters&gt;[A-ZÑ&amp;]{3,4})"          # 3 letters (company) or 4 (person)
    r"(?P&lt;date&gt;\d{6})"                      # YYMMDD
    r"(?P&lt;homoclave&gt;[A-Z\d]{2})"            # assigned by SAT
    r"(?P&lt;check&gt;[A\d])$"                    # check digit: 0-9 or A
)

# SAT value table (0..38): '&amp;' = 24, ' ' = 37, 'Ñ' = 38
RFC_CHARS = "0123456789ABCDEFGHIJKLMN&amp;OPQRSTUVWXYZ Ñ"
GENERIC_RFCS = {"XAXX010101000", "XEXX010101000"}


def _valid_yymmdd(s: str) -&gt; bool:
    # The century is unknown; 2000 is a leap year, so 29 Feb always passes.
    try:
        date(2000 + int(s[:2]), int(s[2:4]), int(s[4:6]))
        return True
    except ValueError:
        return False


def rfc_check_digit(rfc: str) -&gt; str:
    base = rfc[:-1]
    if len(base) == 11:              # company RFC: pad to 12 with a leading space
        base = " " + base
    total = sum(RFC_CHARS.index(c) * (13 - i) for i, c in enumerate(base))
    d = 11 - total % 11
    return "0" if d == 11 else "A" if d == 10 else str(d)


def validate_rfc(value: str) -&gt; str:
    rfc = value.strip().upper()
    m = RFC_RE.match(rfc)
    if not m or not _valid_yymmdd(m["date"]):
        return "bad_format"
    if rfc in GENERIC_RFCS:
        return "generic"
    if rfc_check_digit(rfc) != m["check"]:
        return "bad_check_digit"
    return "ok"


# --- CURP ------------------------------------------------------------
STATES = ("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")
CURP_RE = re.compile(
    r"^[A-Z][AEIOUX][A-Z]{2}"                # surname/name initials
    r"(?P&lt;date&gt;\d{6})"                       # YYMMDD
    r"[HMX]"                                 # sex
    rf"(?:{STATES})"                         # state of birth (NE = born abroad)
    r"[B-DF-HJ-NP-TV-Z]{3}"                  # internal consonants
    r"[A-Z\d]"                               # differentiator
    r"(?P&lt;check&gt;\d)$"                        # check digit
)
CURP_CHARS = "0123456789ABCDEFGHIJKLMNÑOPQRSTUVWXYZ"


def curp_check_digit(curp: str) -&gt; str:
    total = sum(CURP_CHARS.index(c) * (18 - i) for i, c in enumerate(curp[:17]))
    return str((10 - total % 10) % 10)


def validate_curp(value: str) -&gt; str:
    curp = value.strip().upper()
    m = CURP_RE.match(curp)
    if not m or not _valid_yymmdd(m["date"]):
        return "bad_format"
    if curp_check_digit(curp) != m["check"]:
        return "bad_check_digit"
    return "ok"
</code></pre>
<p>Two design choices worth copying:</p>
<ol>
<li>It returns a <strong>reason</strong>, not a boolean. <code>bad_format</code> is a typo you can show inline in the form. <code>bad_check_digit</code> on an RFC is better treated as "ask SAT" than as a hard reject: the registry, not the algorithm, is the source of truth, and the cost of a false rejection at onboarding is a lost customer.</li>
<li>It validates the <strong>date</strong> with <code>datetime</code>, which a regex like <code>(0[1-9]|[12]\d|3[01])</code> cannot do: it happily accepts 31 February.</li>
</ol>
<p>Running it:</p>
<pre><code class="language-python">from mxid import validate_rfc, validate_curp

for rfc in ["GODE561231GR8",   # person, 13 chars (SAT's own example)
            "SAT970701NN3",    # company, 12 chars
            "gode561231gr8 ",  # lowercase + stray whitespace
            "GODE561231GR9",   # wrong check digit
            "GODE560231GR8",   # 31 February
            "XAXX010101000"]:  # SAT generic RFC
    print(f"{rfc!r:18} {validate_rfc(rfc)}")

for curp in ["PEMJ800101HDFRRN07",   # documentation example
             "PEMJ800101HDFRRN08",   # wrong check digit
             "PEMJ800101HZZRRN07",   # ZZ is not a state code
             "PEMJ800230HDFRRN07"]:  # 30 February
    print(f"{curp!r:22} {validate_curp(curp)}")
</code></pre>
<p>Output (Python 3, run as-is):</p>
<pre><code class="language-text">'GODE561231GR8'    ok
'SAT970701NN3'     ok
'gode561231gr8 '   ok
'GODE561231GR9'    bad_check_digit
'GODE560231GR8'    bad_format
'XAXX010101000'    generic
'PEMJ800101HDFRRN07'   ok
'PEMJ800101HDFRRN08'   bad_check_digit
'PEMJ800101HZZRRN07'   bad_format
'PEMJ800230HDFRRN07'   bad_format
</code></pre>
<h2>Why format + checksum is not enough</h2>
<p>Everything above runs offline and catches typos. It cannot tell you any of the things compliance actually cares about:</p>
<ul>
<li><strong>Is the RFC registered and active with SAT?</strong> A well-formed RFC with a correct check digit can belong to nobody. For CFDI 4.0 invoicing, the receiver's RFC, name and postal code must also match SAT's record, or stamping fails.</li>
<li><strong>Is the supplier on a SAT blacklist?</strong> SAT publishes taxpayers under Article 69 (non-compliant, cancelled, etc.), Article 69-B (issuers of simulated invoices, the "EFOS" list) and 69-B Bis. Paying an EFOS can cost you the deduction.</li>
<li><strong>Does the CURP exist in RENAPO, and does it belong to this person?</strong> For KYC you want to compare RENAPO's names and birth date against what the user typed.</li>
<li><strong>Is that invoice still valid?</strong> A CFDI can be cancelled after you receive it; only SAT's Verifica CFDI service says whether it is <code>vigente</code> or <code>cancelado</code>.</li>
</ul>
<p>The government offers no simple JSON API for these. The portals are HTML forms, some with CAPTCHAs, and they go down. You can scrape them yourself or use a service that does.</p>
<h2>A live lookup with the MexCheck API</h2>
<p>This is the part where I talk about my own product. <a href="https://mexcheck.com">MexCheck</a> wraps SAT, RENAPO and other registries behind one REST API. Base URL <code>https://mexcheck.com/v1</code>, every endpoint is <code>POST</code> with JSON, and the key goes in the <code>x-api-key</code> header. Keep it in an environment variable:</p>
<pre><code class="language-bash">export MEXCHECK_API_KEY="your_key_here"
</code></pre>
<p>The client below uses the validator above as a free pre-filter, then calls three documented endpoints: <code>/rfc/verify</code> (is the RFC registered with SAT), <code>/rfc/sat-lists</code> (Article 69 / 69-B / 69-B Bis) and <code>/curp/lookup</code> (RENAPO).</p>
<pre><code class="language-python">import os
import requests

from mxid import validate_rfc, validate_curp

API = "https://mexcheck.com/v1"
session = requests.Session()
session.headers["x-api-key"] = os.environ["MEXCHECK_API_KEY"]


def mexcheck(path: str, body: dict) -&gt; dict:
    # Lookups wait on SAT/RENAPO and can take up to 90 s.
    # If you hang up first, the lookup is cancelled and not charged.
    r = session.post(f"{API}{path}", json=body, timeout=95)
    if r.status_code == 402:
        raise RuntimeError(f"Out of credits: {r.json().get('add_balance_url')}")
    if r.status_code == 422:
        raise ValueError(f"Rejected input: {r.json().get('error')}")
    r.raise_for_status()
    return r.json()


def check_supplier(rfc: str) -&gt; dict:
    if validate_rfc(rfc) == "bad_format":
        return {"ok": False, "reason": "typo"}          # free, no API call
    verify = mexcheck("/rfc/verify", {"rfc": rfc})
    if verify["valid"] is None:
        return {"ok": None, "reason": "SAT unreachable, retry"}
    lists = mexcheck("/rfc/sat-lists", {"rfc": rfc})
    return {
        "ok": verify["valid"] and not lists["sat_lists"],
        "sat_message": verify["message"],
        "sat_lists": [(e["article"], e["situation"]) for e in lists["sat_lists"]],
    }


def check_person(curp: str) -&gt; dict:
    if validate_curp(curp) != "ok":
        return {"ok": False, "reason": "typo"}
    data = mexcheck("/curp/lookup", {"curp": curp})
    if data["found"] is None:
        return {"ok": None, "reason": "RENAPO unreachable, retry (not charged)"}
    if not data["found"]:
        return {"ok": False, "reason": data["message"]}
    p = data["person"]
    return {"ok": True, "names": p["names"], "paternal_surname": p["paternal_surname"],
            "mothers_maiden_name": p["mothers_maiden_name"], "birthdate": p["birthdate"]}
</code></pre>
<p>What the documented responses mean:</p>
<ul>
<li><code>/rfc/verify</code> returns <code>rfc</code>, <code>valid</code> and <code>message</code>. <code>valid</code> is <code>true</code>, <code>false</code>, or <code>null</code> when SAT could not be reached (retry). For the generic RFCs it also returns <code>generic: true</code> without querying SAT. Add <code>name</code> and <code>zip</code> (always together) to check the full CFDI 4.0 combination.</li>
<li><code>/rfc/sat-lists</code> returns a <code>sat_lists</code> array; each entry has <code>article</code>, <code>sub_list</code>, <code>situation</code>, <code>name</code>, <code>person_type</code> and <code>state</code>. An empty list means the RFC is on none of them.</li>
<li><code>/curp/lookup</code> returns <code>found</code> (<code>true</code> / <code>false</code> / <code>null</code>) and a <code>person</code> object with <code>names</code>, <code>paternal_surname</code>, <code>mothers_maiden_name</code>, <code>birthdate</code> (<code>DD/MM/YYYY</code>), <code>status_curp</code> and more. <code>null</code> means RENAPO was unreachable and is not charged. A CURP that fails format or check digit is rejected with <code>422 invalid_curp</code> before RENAPO is called, also not charged.</li>
<li>Set the client timeout to at least 90 seconds. Lookups wait on government sites; a <code>504</code> with <code>{"error": "request_timeout"}</code> is not charged.</li>
</ul>
<p>For invoices there is <code>/cfdi/verify</code>, which takes <code>uuid</code>, <code>rfc_emisor</code> and <code>rfc_receptor</code> (or the XML itself) and returns <code>status</code> as <code>vigente</code> or <code>cancelado</code>.</p>
<h2>Using it from an AI coding assistant (MCP)</h2>
<p>There is also a remote MCP server at <code>https://mexcheck.com/mcp</code> (Streamable HTTP, OAuth 2.1 with dynamic client registration and PKCE). It is for <em>building</em> the integration: the assistant reads the docs, pulls each endpoint's OpenAPI definition, and runs real checks. Production code still calls the REST API with a key.</p>
<p>Claude Code:</p>
<pre><code class="language-bash">claude mcp add --transport http mexcheck https://mexcheck.com/mcp
</code></pre>
<p>Cursor (<code>.cursor/mcp.json</code>):</p>
<pre><code class="language-json">{
  "mcpServers": {
    "mexcheck": { "url": "https://mexcheck.com/mcp" }
  }
}
</code></pre>
<p>There is no key to paste. The docs tools (<code>list_docs</code>, <code>read_doc</code>, <code>get_openapi_operation</code>) work without logging in; the first time the assistant uses a tool that touches your account (like <code>rfc_verify</code> or <code>curp_lookup</code>), it opens a browser for you to sign in. Those checks are real and cost the same as REST calls, and the returned personal data passes through whatever assistant you connected, so only connect one you trust with it.</p>
<h2>Pricing</h2>
<p>From the <a href="https://mexcheck.com/pricing">pricing page</a> at the time of writing: pay as you go at $0.015 USD per credit with a $5 USD signup bonus, or monthly plans from $99 USD/month (Basic, 10,000 credits). <code>/rfc/verify</code> costs 1 credit, <code>/curp/lookup</code> 5, <code>/cfdi/verify</code> 5, and <code>/rfc/sat-lists</code> is free on any plan (1 credit on pay as you go).</p>
<h2>Summary</h2>
<ol>
<li>Validate format, date and check digit locally. It is free and catches most typos.</li>
<li>Return reasons, not booleans; do not hard-reject an RFC only on its check digit.</li>
<li>Handle <code>Ñ</code>, <code>&amp;</code>, generic RFCs and the <code>X</code> substitution rule.</li>
<li>For anything compliance-related (registration, blacklists, identity, invoice status), ask the registry, whether you scrape it yourself or use an API.</li>
</ol>
<p>There is a Spanish version of this topic with curl and Node.js examples <a href="https://dev.to/acrogenesis/como-validar-rfc-y-curp-con-una-api-y-desde-tu-agente-de-ia-via-mcp-4ij4">here</a>. Found an RFC or CURP edge case this validator gets wrong? Tell me in the comments.</p>
]]></content:encoded></item><item><title><![CDATA[Cómo validar RFC y CURP con una API (y desde tu agente de IA vía MCP)]]></title><description><![CDATA[Soy el fundador de MexCheck. Todo lo que aparece aquí sale de la documentación pública del API, y los identificadores son ejemplos. Si tu producto opera en…]]></description><link>https://acrogenesis.hashnode.dev/c-mo-validar-rfc-y-curp-con-una-api-y-desde-tu-agente-de-ia-v-a-mcp</link><guid isPermaLink="true">https://acrogenesis.hashnode.dev/c-mo-validar-rfc-y-curp-con-una-api-y-desde-tu-agente-de-ia-v-a-mcp</guid><category><![CDATA[api]]></category><category><![CDATA[Python]]></category><category><![CDATA[mexico]]></category><category><![CDATA[mcp]]></category><dc:creator><![CDATA[Adrian Rangel]]></dc:creator><pubDate>Wed, 18 Nov 2026 02:31:15 GMT</pubDate><content:encoded><![CDATA[<blockquote>
<p>Soy el fundador de MexCheck. Todo lo que aparece aquí sale de la documentación pública del API, y los identificadores son ejemplos.</p>
</blockquote>
<p>Si tu producto opera en México, tarde o temprano vas a pedirle a alguien su RFC o su CURP. Y tarde o temprano alguien te va a mandar uno con un dígito cambiado, con la letra O en lugar del cero, o uno que existe pero no le pertenece.</p>
<p>En este artículo vamos a:</p>
<ol>
<li>Validar el <strong>formato</strong> de RFC y CURP localmente, sin gastar una sola llamada.</li>
<li>Confirmar contra el <strong>SAT</strong> y <strong>RENAPO</strong> con un API REST (curl, Node.js y Python).</li>
<li>Manejar errores sin cobrar de más.</li>
<li>Conectar el mismo servicio a <strong>Claude Code o Cursor</strong> con MCP para que tu agente lea la documentación y te ayude a integrarlo.</li>
</ol>
<h2>¿Por qué validar RFC y CURP?</h2>
<ul>
<li><strong>KYC y onboarding.</strong> Si das crédito, abres cuentas o haces alta de clientes, necesitas saber que la CURP existe en RENAPO y que el nombre y la fecha de nacimiento coinciden con lo que te dijo la persona.</li>
<li><strong>Facturación.</strong> Con CFDI 4.0 el RFC, el nombre y el código postal del receptor tienen que coincidir con lo que tiene el SAT. Si no, el timbrado falla y alguien termina corrigiendo facturas a mano.</li>
<li><strong>Nómina.</strong> Un RFC o una CURP mal capturados en el alta de un empleado se arrastran a cada recibo de nómina timbrado.</li>
<li><strong>Proveedores.</strong> Antes de pagarle a un proveedor conviene saber si aparece en las listas del SAT (artículos 69, 69-B y 69-B Bis).</li>
</ul>
<h2>Paso 1: valida el formato localmente</h2>
<p>Antes de llamar a cualquier API, descarta lo que claramente está mal escrito. Es gratis, es instantáneo y te ahorra llamadas.</p>
<ul>
<li><strong>RFC:</strong> 3 letras (persona moral) o 4 (persona física), fecha <code>AAMMDD</code>, homoclave de 2 caracteres y un dígito verificador (número o <code>A</code>).</li>
<li><strong>CURP:</strong> 18 caracteres: 4 letras, fecha <code>AAMMDD</code>, sexo (<code>H</code>, <code>M</code> o <code>X</code>), clave de entidad de 2 letras, 3 consonantes internas, un carácter diferenciador y un dígito verificador.</li>
</ul>
<pre><code class="language-python">import re

RFC_RE = re.compile(
    r"^([A-ZÑ&amp;]{3,4})"                                # 3 letras (moral) o 4 (física)
    r"(\d{2})(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])"   # AAMMDD
    r"([A-Z\d]{2})([A\d])$"                          # homoclave + dígito verificador
)

ESTADOS = ("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")

CURP_RE = re.compile(
    r"^[A-Z][AEIOUX][A-Z]{2}"
    r"\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])"
    r"[HMX]"
    rf"({ESTADOS})"
    r"[B-DF-HJ-NP-TV-Z]{3}"
    r"[A-Z\d]\d$"
)

CURP_CHARS = "0123456789ABCDEFGHIJKLMNÑOPQRSTUVWXYZ"

def curp_digito_ok(curp: str) -&gt; bool:
    suma = sum(CURP_CHARS.index(c) * (18 - i) for i, c in enumerate(curp[:17]))
    return (10 - suma % 10) % 10 == int(curp[17])

def rfc_formato_ok(rfc: str) -&gt; bool:
    return bool(RFC_RE.match(rfc.strip().upper()))

def curp_formato_ok(curp: str) -&gt; bool:
    curp = curp.strip().upper()
    return bool(CURP_RE.match(curp)) and curp_digito_ok(curp)
</code></pre>
<p>Probándolo con identificadores de ejemplo:</p>
<pre><code class="language-python"># Ejemplos: RFC genérico del SAT y CURP de ejemplo de la documentación
print(rfc_formato_ok("XAXX010101000"))       # True
print(rfc_formato_ok("XAXX011301000"))       # False (mes 13)
print(curp_formato_ok("PEMJ800101HDFRRN07")) # True
print(curp_formato_ok("PEMJ800101HDFRRN08")) # False (dígito verificador)
print(curp_formato_ok("PEMJ800101HZZRRN07")) # False (entidad inexistente)
</code></pre>
<p>Ojo con lo que esto <strong>no</strong> te dice: una regex no sabe si el RFC está dado de alta en el SAT, si la CURP existe en RENAPO ni si le pertenece a la persona. Para eso hay que preguntarle al registro.</p>
<h2>Paso 2: pregúntale al SAT y a RENAPO</h2>
<p>Uso <a href="https://mexcheck.com">MexCheck</a>, que consulta directamente al registro dueño del dato (SAT para RFC y CFDI, RENAPO para CURP, INE para la credencial para votar, CFE para recibos de luz) y devuelve JSON. Lo básico:</p>
<ul>
<li>Base URL: <code>https://mexcheck.com/v1</code>. Todos los endpoints son <code>POST</code> con JSON.</li>
<li>Autenticación: header <code>x-api-key</code>. Generas la llave en el panel después de registrarte.</li>
<li>Guárdala en una variable de entorno, nunca en el código:</li>
</ul>
<pre><code class="language-bash">export MEXCHECK_API_KEY="tu_llave_aquí"
</code></pre>
<h3>Verificar un RFC con el SAT (<code>/v1/rfc/verify</code>)</h3>
<p>Es la consulta más rápida (1 a 2 segundos, 1 crédito). Con solo el RFC confirma que está registrado y activo. Si además mandas <code>name</code> y <code>zip</code> (siempre juntos), confirma que la combinación coincide con el SAT, que es justo lo que pide CFDI 4.0.</p>
<pre><code class="language-bash">curl -X POST https://mexcheck.com/v1/rfc/verify \
  -H "x-api-key: $MEXCHECK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rfc": "XAXX010101000"}'
</code></pre>
<p>Así se ve la respuesta documentada para otro RFC de ejemplo (<code>ACME010101AAA</code>), en modo solo RFC:</p>
<pre><code class="language-json">{
  "rfc": "ACME010101AAA",
  "valid": true,
  "message": "RFC válido, y susceptible de recibir facturas"
}
</code></pre>
<p>Dos detalles útiles del esquema: <code>valid</code> puede ser <code>true</code>, <code>false</code> o <code>null</code> (<code>null</code> significa que el SAT no respondió y conviene reintentar), y para los RFC genéricos del SAT (<code>XAXX010101000</code>, <code>XEXX010101000</code>, <code>EXTF900101NI1</code>, <code>EXT990101NI1</code>) la respuesta trae <code>generic: true</code> y se contesta sin consultar al SAT, porque no identifican a ningún contribuyente.</p>
<p>Si necesitas más (nombre registrado, código postal, certificados y presencia en listas del SAT), existe <code>/v1/rfc/validate</code>, que tarda de 7 a 11 segundos y cuesta 10 créditos. Para revisar solo las listas 69, 69-B y 69-B Bis está <code>/v1/rfc/sat-lists</code>, que responde en milisegundos y es gratis con cualquier plan.</p>
<h3>Consultar una CURP en RENAPO (<code>/v1/curp/lookup</code>)</h3>
<pre><code class="language-bash">curl -X POST https://mexcheck.com/v1/curp/lookup \
  -H "x-api-key: $MEXCHECK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"curp": "PEMJ800101HDFRRN07"}'
</code></pre>
<p>Respuesta de ejemplo de la documentación (datos ficticios):</p>
<pre><code class="language-json">{
  "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",
    "nationality": "MEXICO",
    "entity_birth": "DF",
    "status_curp": "RCN",
    "certified": true,
    "certification": "CURP Certificada: verificada con el Registro Civil",
    "associated_curps": [],
    "probation_document": "ACTA DE NACIMIENTO",
    "probation_document_data": {},
    "homonimo": false
  }
}
</code></pre>
<p>Para KYC lo importante es comparar <code>names</code>, <code>paternal_surname</code>, <code>mothers_maiden_name</code> y <code>birthdate</code> (formato <code>DD/MM/AAAA</code>) con lo que capturó el usuario. <code>status_curp</code> es el código de RENAPO tal cual; los que empiezan con <code>B</code> son bajas.</p>
<h3>Node.js (fetch nativo, Node 18+)</h3>
<pre><code class="language-js">const API = "https://mexcheck.com/v1";

async function mexcheck(path, body) {
  const res = await fetch(`${API}${path}`, {
    method: "POST",
    headers: {
      "x-api-key": process.env.MEXCHECK_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
    // Las consultas pueden tardar hasta 90 s porque esperan al registro
    signal: AbortSignal.timeout(95_000),
  });

  const data = await res.json().catch(() =&gt; ({}));
  if (!res.ok) {
    // 401, 402, 422, 429, 500, 504: el cuerpo trae `error` (y a veces `message`)
    throw new Error(`${res.status} ${data.error ?? ""} ${data.message ?? ""}`.trim());
  }
  return data;
}

const rfc = await mexcheck("/rfc/verify", { rfc: "XAXX010101000" }); // ejemplo
if (rfc.valid === null) console.log("El SAT no respondió, reintenta más tarde");
else console.log(rfc.valid, rfc.message);

const curp = await mexcheck("/curp/lookup", { curp: "PEMJ800101HDFRRN07" }); // ejemplo
console.log(curp.found, curp.person?.names);
</code></pre>
<h3>Python (requests)</h3>
<pre><code class="language-python">import os
import requests

API = "https://mexcheck.com/v1"
session = requests.Session()
session.headers.update({"x-api-key": os.environ["MEXCHECK_API_KEY"]})

def mexcheck(path: str, body: dict) -&gt; dict:
    # timeout &gt;= 90 s: la consulta espera la respuesta del registro
    r = session.post(f"{API}{path}", json=body, timeout=95)
    if r.status_code == 402:
        raise RuntimeError(f"Sin saldo, agrega créditos: {r.json().get('add_balance_url')}")
    if r.status_code == 422:
        raise ValueError(f"Entrada inválida: {r.json().get('error')}")
    r.raise_for_status()
    return r.json()

curp = "PEMJ800101HDFRRN07"  # ejemplo
if curp_formato_ok(curp):            # paso 1: filtro local gratis
    data = mexcheck("/curp/lookup", {"curp": curp})
    if data["found"] is None:
        print("RENAPO no respondió; reintenta (no se cobra)")
    elif data["found"]:
        print(data["person"]["names"], data["person"]["birthdate"])
    else:
        print("RENAPO no devolvió registro:", data["message"])
</code></pre>
<h2>Paso 3: errores y qué se cobra</h2>
<p>Según la <a href="https://rfccheck.com/docs/errors">documentación de errores</a> y el <a href="https://mexcheck.com/openapi.json">OpenAPI</a>:</p>
<table>
<thead>
<tr>
<th>Código</th>
<th>Qué significa</th>
</tr>
</thead>
<tbody><tr>
<td><code>401</code></td>
<td>Llave faltante o inválida.</td>
</tr>
<tr>
<td><code>402</code></td>
<td>Sin créditos ni saldo. El cuerpo trae <code>add_balance_url</code>.</td>
</tr>
<tr>
<td><code>422</code></td>
<td>Entrada inválida. <code>error</code> es, por ejemplo, <code>missing_rfc</code>, <code>invalid_rfc</code>, <code>missing_curp</code> o <code>invalid_curp</code>.</td>
</tr>
<tr>
<td><code>429</code></td>
<td>Límite de peticiones. Espera y reintenta.</td>
</tr>
<tr>
<td><code>504</code></td>
<td><code>{"error": "request_timeout"}</code>: no terminó en 90 s. <strong>No se cobra.</strong></td>
</tr>
</tbody></table>
<p>Puntos que vale la pena tener presentes:</p>
<ul>
<li><code>found: null</code> en CURP, INE, CFDI y constancia significa que el registro no respondió. <strong>No se cobra</strong>; reintenta.</li>
<li>Una CURP con formato, fecha, entidad o dígito verificador inválidos se rechaza con <code>422 invalid_curp</code> antes de ir a RENAPO, y <strong>no se cobra</strong>.</li>
<li><code>found: false</code> sí se cobra: el registro contestó, solo que no encontró nada.</li>
<li>Si tu cliente HTTP cierra la conexión antes de que termine la consulta, se cancela y no se cobra. Por eso los ejemplos usan un timeout mayor a 90 s.</li>
</ul>
<h2>Paso 4: conéctalo a tu agente de IA vía MCP</h2>
<p>MexCheck tiene un servidor MCP remoto en <code>https://mexcheck.com/mcp</code>. Sirve para <strong>construir</strong> la integración: tu asistente puede leer la documentación, consultar la definición OpenAPI de cada endpoint y hacer consultas reales para ver respuestas exactas. En producción, tu servidor sigue llamando al API REST con su llave.</p>
<p><strong>Claude Code:</strong></p>
<pre><code class="language-bash">claude mcp add --transport http mexcheck https://mexcheck.com/mcp
</code></pre>
<p><strong>Cursor</strong> (<code>.cursor/mcp.json</code>):</p>
<pre><code class="language-json">{
  "mcpServers": {
    "mexcheck": { "url": "https://mexcheck.com/mcp" }
  }
}
</code></pre>
<p>No hay llave que pegar. Las herramientas de documentación (<code>list_docs</code>, <code>read_doc</code>, <code>get_openapi_operation</code>) funcionan sin iniciar sesión. La primera vez que el agente usa una herramienta que toca tu cuenta (por ejemplo <code>rfc_verify</code> o <code>curp_lookup</code>), se abre el navegador para que inicies sesión con OAuth y elijas la cuenta. Esas consultas son reales y cuestan lo mismo que por REST.</p>
<p>Un prompt que funciona bien:</p>
<blockquote>
<p>Lee la documentación de <code>/v1/curp/lookup</code> con el MCP de MexCheck y escribe un cliente en TypeScript con tipos generados desde su definición OpenAPI. Maneja <code>found: null</code> con reintentos.</p>
</blockquote>
<p>Una advertencia de privacidad que la propia documentación hace: lo que devuelve una consulta (nombres, CURP, datos fiscales) pasa por el asistente que conectaste y por la empresa que lo opera. Conecta solo asistentes a los que les confiarías esos datos, y no le pases identificadores de personas reales que no te autorizaron.</p>
<h2>Precios</h2>
<p>Al momento de escribir esto, según <a href="https://mexcheck.com/pricing">la página de precios</a>:</p>
<ul>
<li><strong>Pago por uso:</strong> $0.015 USD por crédito, sin suscripción, y $5 USD de bono al registrarte.</li>
<li><strong>Planes mensuales</strong> desde $99 USD/mes (Basic, 10,000 créditos).</li>
<li>Costos por endpoint: <code>/rfc/verify</code> 1 crédito, <code>/curp/lookup</code> 5, <code>/rfc/validate</code> 10. <code>/rfc/sat-lists</code> es gratis con cualquier plan (1 crédito en pago por uso).</li>
</ul>
<h2>Resumen</h2>
<ol>
<li>Filtra formato localmente con regex y el dígito verificador de la CURP.</li>
<li>Confirma contra el registro: <code>/v1/rfc/verify</code> para el SAT y <code>/v1/curp/lookup</code> para RENAPO.</li>
<li>Trata <code>null</code> como "reintenta", usa un timeout de al menos 90 s y lee el campo <code>error</code> en los 4xx.</li>
<li>Si trabajas con Claude Code o Cursor, conecta <code>https://mexcheck.com/mcp</code> y deja que el agente lea la documentación por ti.</li>
</ol>
<p>Documentación completa: <a href="https://mexcheck.com/docs">mexcheck.com/docs</a> (en español en <a href="https://mexcheck.com/es/docs/quickstart">mexcheck.com/es/docs</a>). Si tienes dudas o algo no te cuadra, déjalo en los comentarios.</p>
]]></content:encoded></item></channel></rss>