Validador de RFC

API para verificar ante el SAT si un RFC está registrado y es susceptible de recibir facturas, y para cotejar que el nombre o razón social y el código postal coincidan con lo que el SAT tiene registrado. Cada consulta se hace en vivo contra el servicio oficial del SAT: no hay padrones cacheados ni copias locales.

URL base y autenticación

Todas las peticiones van al gateway de idoo.dev con tu API key:

https://idoo.dev/v1/valida-rfc/{accion}

curl -X POST "https://idoo.dev/v1/valida-rfc/validar" \
  -H "Authorization: Bearer {tu_api_key}" \
  -H "Content-Type: application/json" \
  -d '{"rfc": "FCA130603EX5"}'

También se acepta el header X-API-KEY: {tu_api_key}. Las keys se crean en tu panel de idoo.dev.

Ambientes: sandbox vs producción

El ambiente lo determina tu API key, no un parámetro:

Sandbox siempre responde que el RFC es válido, sin importar cuál mandes: sirve para integrar el contrato de la API, no para probar casos de negocio. Los formatos inválidos (422) sí se validan en sandbox.

validar es el único endpoint que descuenta cuota. salud es libre (aplica únicamente al rate limit de tu plan). El header X-Idoo-Cuota-Restante de cada respuesta cobrable te dice cuántas consultas te quedan en el periodo.

Formato de respuesta

Todas las respuestas (éxito o error) usan el mismo sobre JSON:

{
  "valid": true,
  "status": 200,
  "message": "RFC válido, y susceptible de recibir facturas",
  "data": { "...": "..." },
  "timestamp": "2026-09-09 07:26:07"
}

En los errores, valid es false y se agrega el campo error con un código estable, pensado para que lo compares en tu código — a diferencia de message, que es texto legible y puede cambiar.

status: 200 no significa "RFC válido". Significa que la consulta se realizó con éxito. El veredicto está en data.valido.

Tiempos de respuesta

Tarda típicamente entre 2 y 4 segundos, y puede llegar a 20 cuando se necesitan varios intentos. Configura el timeout de tu cliente en al menos 30 segundos y haz la llamada en segundo plano si tu interfaz no puede esperar. En sandbox la respuesta es inmediata.

Códigos de estado

Catálogo de endpoints

POST validar

Consulta un RFC ante el SAT.

Body:

{
  "rfc": "FON2010129P5",
  "nombre": "FONDO DE CULTURA ECONOMICA",
  "cp": "14738"
}

Enviar nombre o cp activa la validación cruzada del SAT: el RFC puede existir y aun así responder que los datos no coinciden. El cotejo del nombre es literal — el SAT compara contra la razón social exacta que tiene registrada, sin régimen de capital (SA DE CV) salvo que así esté inscrita.

Respuesta 200 — solo RFC:

{
  "valid": true,
  "status": 200,
  "message": "RFC válido, y susceptible de recibir facturas",
  "data": {
    "rfc": "FCA130603EX5",
    "nombre": null,
    "cp": null,
    "resultado": "RFC válido, y susceptible de recibir facturas",
    "valido": true,
    "simulado": false,
    "idoo": { "consumidor_id": 4242, "plan": "Pro", "ambiente": "produccion" }
  },
  "timestamp": "2026-09-09 07:26:07"
}

Respuesta 200 — con nombre y CP que no coinciden:

{
  "data": {
    "rfc": "FCA130603EX5",
    "nombre": "FONDO DE CULTURA ECONOMICA",
    "cp": "14738",
    "resultado": "EL Nombre o Razón Social y CP no coinciden con lo registrado en el RFC",
    "valido": false,
    "simulado": false
  },
  "message": "EL Nombre o Razón Social y CP no coinciden con lo registrado en el RFC"
}

Campos de data:

Errores específicos:

GET salud

Comprueba que el servicio responde. Útil para monitoreo; no consulta al SAT ni descuenta cuota.

curl "https://idoo.dev/v1/valida-rfc/salud" \
  -H "Authorization: Bearer {tu_api_key}"

Respuesta 200:

{
  "valid": true,
  "status": 200,
  "message": "Servicio operativo",
  "data": {
    "servicio": "valida-rfc",
    "idoo": { "consumidor_id": 4242, "plan": "Pro", "ambiente": "produccion" }
  },
  "timestamp": "2026-09-09 07:25:36"
}

Flujo recomendado de integración

1. Integra en sandbox con tu key idoo_sk_test_... — es gratis e ilimitado. Ahí armas el manejo del sobre JSON y de los errores 422 sin gastar consultas.
2. Valida el formato del RFC de tu lado antes de llamar. Una consulta con formato inválido te devuelve 422 y no descuenta cuota, pero te cuesta un viaje de red; validarlo en tu formulario es mejor experiencia.
3. Llama a validar con el RFC solo, o con nombre y cp si necesitas el cotejo completo (por ejemplo, para dar de alta a un cliente que va a recibir facturas).
4. Lee el veredicto en data.valido, no en el status. Un 200 con "valido": false es una respuesta correcta del SAT diciendo que ese RFC no sirve para facturar.
5. Maneja 502/503/504 con reintentos acotados y espera entre ellos: el SAT se cae seguido. Recuerda que cada reintento descuenta cuota.
6. Como cada consulta tarda segundos, guarda el resultado en tu sistema en vez de volver a consultar el mismo RFC en cada pantalla. Los datos del padrón cambian con poca frecuencia.
7. Cuando estés listo, crea tu key de producción y elige el plan según tu volumen de consultas.

Ejercicios guiados

Todos corren en sandbox y no consumen cuota. Sustituye {tu_api_key} por tu key idoo_sk_test_....

Ejercicio 1 — Validar un RFC

El caso más simple: ¿este RFC puede recibir facturas?

curl -X POST "https://idoo.dev/v1/valida-rfc/validar" \
  -H "Authorization: Bearer {tu_api_key}" \
  -H "Content-Type: application/json" \
  -d '{"rfc": "FCA130603EX5"}'

En producción, data.valido será true si el SAT lo tiene registrado y activo para facturación.

Ejercicio 2 — Cotejar nombre y código postal

Al dar de alta un cliente conviene verificar que los tres datos que te dio coinciden entre sí; es lo que evita rechazos al timbrar después.

curl -X POST "https://idoo.dev/v1/valida-rfc/validar" \
  -H "Authorization: Bearer {tu_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
        "rfc": "FCA130603EX5",
        "nombre": "FONDO DE CULTURA ECONOMICA",
        "cp": "14738"
      }'

Si el SAT responde que no coinciden, el status sigue siendo 200: la consulta funcionó. El problema está en data.valido: false y en data.resultado, que te dice qué falló.

Ejercicio 3 — Manejar un fallo transitorio

El SAT no siempre responde. Este es el patrón mínimo de reintento, en PHP:

$intentos = 0;
do {
    $respuesta = miCliente()->post('validar', ['rfc' => $rfc]);
    $codigo = $respuesta['status'];
    if ($codigo < 500) {
        break;                  // 200, 422, 400: no tiene caso reintentar
    }
    $intentos++;
    sleep(2 * $intentos);       // espera creciente
} while ($intentos < 3);

Tres intentos son suficientes: si el SAT sigue caído, avísale al usuario y guarda el RFC para reintentar más tarde. No lo pongas en un bucle infinito: cada vuelta descuenta cuota.

Errores frecuentes

• Tratar el status como el veredicto. 200 significa "consulté al SAT y esto es lo que dijo". El veredicto está en data.valido.
• Mandar la razón social con régimen de capital. Si el SAT tiene registrada FONDO DE CULTURA ECONOMICA y tú envías FONDO DE CULTURA ECONOMICA SA DE CV, el cotejo falla. Manda el nombre tal como está en la constancia de situación fiscal.
• Timeouts cortos. Un cliente con timeout de 5 segundos va a cortar consultas que iban a responder bien. Usa 30 segundos.
• Consultar el mismo RFC repetidamente. Cada llamada descuenta cuota y tarda segundos. Guarda el resultado.
• Reintentar un 422. Ese error es de tus datos, no del SAT: reintentar da exactamente lo mismo.