DEV Community

Adrian Rangel
Adrian Rangel

Posted on Edited on

Cómo validar RFC y CURP con una API (y desde tu agente de IA vía MCP)

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:

  1. Validar el formato de RFC y CURP localmente, sin gastar una sola llamada.
  2. Confirmar contra el SAT y RENAPO con un API REST (curl, Node.js y Python).
  3. Manejar errores sin cobrar de más.
  4. 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 o A).
  • CURP: 18 caracteres: 4 letras, fecha AAMMDD, sexo (H, M o X), 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)
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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 son POST con 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í"
Enter fullscreen mode Exit fullscreen mode

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"}'
Enter fullscreen mode Exit fullscreen mode

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"
}
Enter fullscreen mode Exit fullscreen mode

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"}'
Enter fullscreen mode Exit fullscreen mode

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
  }
}
Enter fullscreen mode Exit fullscreen mode

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);
Enter fullscreen mode Exit fullscreen mode

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"])
Enter fullscreen mode Exit fullscreen mode

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: null en 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_curp antes de ir a RENAPO, y no se cobra.
  • found: false sí 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
Enter fullscreen mode Exit fullscreen mode

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "mexcheck": { "url": "https://mexcheck.com/mcp" }
  }
}
Enter fullscreen mode Exit fullscreen mode

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/lookup con el MCP de MexCheck y escribe un cliente en TypeScript con tipos generados desde su definición OpenAPI. Maneja found: null con 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/verify 1 crédito, /curp/lookup 5, /rfc/validate 10. /rfc/sat-lists es gratis con cualquier plan (1 crédito en pago por uso).

Resumen

  1. Filtra formato localmente con regex y el dígito verificador de la CURP.
  2. Confirma contra el registro: /v1/rfc/verify para el SAT y /v1/curp/lookup para RENAPO.
  3. Trata null como "reintenta", usa un timeout de al menos 90 s y lee el campo error en los 4xx.
  4. Si trabajas con Claude Code o Cursor, conecta https://mexcheck.com/mcp y 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.

Top comments (0)