Soy el desarrollador 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 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.
En este artículo vamos a:
- Validar el formato de RFC y CURP localmente, sin gastar una sola llamada.
- Confirmar contra el SAT y RENAPO con un API REST (curl, Node.js y Python).
- Manejar errores sin cobrar de más.
- Conectar el mismo servicio a Claude Code o Cursor con MCP para que tu agente lea la documentación y te ayude a integrarlo.
¿Por qué validar RFC y CURP?
- KYC y onboarding. 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.
- Facturación. 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.
- Nómina. Un RFC o una CURP mal capturados en el alta de un empleado se arrastran a cada recibo de nómina timbrado.
- Proveedores. Antes de pagarle a un proveedor conviene saber si aparece en las listas del SAT (artículos 69, 69-B y 69-B Bis).
Paso 1: valida el formato localmente
Antes de llamar a cualquier API, descarta lo que claramente está mal escrito. Es gratis, es instantáneo y te ahorra llamadas.
- RFC: 3 letras (persona moral) o 4 (persona física), fecha
AAMMDD, homoclave de 2 caracteres y un dígito verificador (número oA). - CURP: 18 caracteres: 4 letras, fecha
AAMMDD, sexo (H,MoX), clave de entidad de 2 letras, 3 consonantes internas, un carácter diferenciador y un dígito verificador.
import re RFC_RE = re.compile( r"^([A-ZÑ&]{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) -> 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) -> bool: return bool(RFC_RE.match(rfc.strip().upper())) def curp_formato_ok(curp: str) -> bool: curp = curp.strip().upper() return bool(CURP_RE.match(curp)) and curp_digito_ok(curp) Probándolo con identificadores de ejemplo:
# 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) Ojo con lo que esto no 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.
Paso 2: pregúntale al SAT y a RENAPO
Uso MexCheck, 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:
- Base URL:
https://mexcheck.com/v1. Todos los endpoints sonPOSTcon JSON. - Autenticación: header
x-api-key. Generas la llave en el panel después de registrarte. - Guárdala en una variable de entorno, nunca en el código:
export MEXCHECK_API_KEY="tu_llave_aquí" Verificar un RFC con el SAT (/v1/rfc/verify)
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 name y zip (siempre juntos), confirma que la combinación coincide con el SAT, que es justo lo que pide CFDI 4.0.
curl -X POST https://mexcheck.com/v1/rfc/verify \ -H "x-api-key: $MEXCHECK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"rfc": "XAXX010101000"}' Así se ve la respuesta documentada para otro RFC de ejemplo (ACME010101AAA), en modo solo RFC:
{ "rfc": "ACME010101AAA", "valid": true, "message": "RFC válido, y susceptible de recibir facturas" } Dos detalles útiles del esquema: valid puede ser true, false o null (null significa que el SAT no respondió y conviene reintentar), y para los RFC genéricos del SAT (XAXX010101000, XEXX010101000, EXTF900101NI1, EXT990101NI1) la respuesta trae generic: true y se contesta sin consultar al SAT, porque no identifican a ningún contribuyente.
Si necesitas más (nombre registrado, código postal, certificados y presencia en listas del SAT), existe /v1/rfc/validate, 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á /v1/rfc/sat-lists, que responde en milisegundos y es gratis con cualquier plan.
Consultar una CURP en RENAPO (/v1/curp/lookup)
curl -X POST https://mexcheck.com/v1/curp/lookup \ -H "x-api-key: $MEXCHECK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"curp": "PEMJ800101HDFRRN07"}' Respuesta de ejemplo de la documentación (datos ficticios):
{ "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 } } Para KYC lo importante es comparar names, paternal_surname, mothers_maiden_name y birthdate (formato DD/MM/AAAA) con lo que capturó el usuario. status_curp es el código de RENAPO tal cual; los que empiezan con B son bajas.
Node.js (fetch nativo, Node 18+)
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(() => ({})); 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); Python (requests)
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) -> dict: # timeout >= 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"]) Paso 3: errores y qué se cobra
Según la documentación de errores y el OpenAPI:
| Código | Qué significa |
|---|---|
401 | Llave faltante o inválida. |
402 | Sin créditos ni saldo. El cuerpo trae add_balance_url. |
422 | Entrada inválida. error es, por ejemplo, missing_rfc, invalid_rfc, missing_curp o invalid_curp. |
429 | Límite de peticiones. Espera y reintenta. |
504 | {"error": "request_timeout"}: no terminó en 90 s. No se cobra. |
Puntos que vale la pena tener presentes:
-
found: nullen CURP, INE, CFDI y constancia significa que el registro no respondió. No se cobra; reintenta. - Una CURP con formato, fecha, entidad o dígito verificador inválidos se rechaza con
422 invalid_curpantes de ir a RENAPO, y no se cobra. -
found: falsesí se cobra: el registro contestó, solo que no encontró nada. - 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.
Paso 4: conéctalo a tu agente de IA vía MCP
MexCheck tiene un servidor MCP remoto en https://mexcheck.com/mcp. Sirve para construir 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.
Claude Code:
claude mcp add --transport http mexcheck https://mexcheck.com/mcp Cursor (.cursor/mcp.json):
{ "mcpServers": { "mexcheck": { "url": "https://mexcheck.com/mcp" } } } No hay llave que pegar. Las herramientas de documentación (list_docs, read_doc, get_openapi_operation) funcionan sin iniciar sesión. La primera vez que el agente usa una herramienta que toca tu cuenta (por ejemplo rfc_verify o curp_lookup), 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.
Un prompt que funciona bien:
Lee la documentación de
/v1/curp/lookupcon el MCP de MexCheck y escribe un cliente en TypeScript con tipos generados desde su definición OpenAPI. Manejafound: nullcon reintentos.
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.
Precios
Al momento de escribir esto, según la página de precios:
- Pago por uso: $0.015 USD por crédito, sin suscripción, y $5 USD de bono al registrarte.
- Planes mensuales desde $99 USD/mes (Basic, 10,000 créditos).
- Costos por endpoint:
/rfc/verify1 crédito,/curp/lookup5,/rfc/validate10./rfc/sat-listses gratis con cualquier plan (1 crédito en pago por uso).
Resumen
- Filtra formato localmente con regex y el dígito verificador de la CURP.
- Confirma contra el registro:
/v1/rfc/verifypara el SAT y/v1/curp/lookuppara RENAPO. - Trata
nullcomo "reintenta", usa un timeout de al menos 90 s y lee el campoerroren los 4xx. - Si trabajas con Claude Code o Cursor, conecta
https://mexcheck.com/mcpy deja que el agente lea la documentación por ti.
Documentación completa: mexcheck.com/docs (en español en mexcheck.com/es/docs). Si tienes dudas o algo no te cuadra, déjalo en los comentarios.