DEV Community

Jasmany Andrés Sánchez Méndez
Jasmany Andrés Sánchez Méndez

Posted on Originally published at jasmany.com

Validar cédula y RUC de Ecuador en Python y JavaScript

Casi todo sistema que se usa en Ecuador pide una cédula o un RUC: un registro de clientes, un sistema de préstamos, un facturador electrónico. Y casi todos los validan mal: solo cuentan los dígitos, o copian un algoritmo que acepta 0000000000 como cédula válida.

Lo sé porque me pasó. En un sistema de préstamos que hice, la validación de la cédula calculaba bien el dígito verificador, pero no revisaba la provincia ni el tercer dígito. Diez ceros pasaban sin problema. En un facturador electrónico, más adelante, tuve que validar además los tres tipos de RUC, que no usan el mismo algoritmo.

En este artículo vas a escribir una validación completa de cédula y RUC, en Python y en JavaScript, con pruebas que puedes ejecutar. Al final hay una sección con los errores que más se repiten.

Lo que se valida (y lo que no)

Un validador comprueba que el número tiene un formato posible. No comprueba que exista: un número inventado puede cumplir el algoritmo. Para saber si un RUC está inscrito hay que consultar el catastro del SRI; eso queda para otro artículo.

La cédula tiene 10 dígitos:

Posición Significado
1–2 Provincia: de 01 a 24, o 30 para ecuatorianos en el exterior
3 Menor que 6 en una persona natural
4–9 Secuencial
10 Dígito verificador (módulo 10)

No olvides el 30: hay cédulas reales que empiezan así, y un validador que solo acepta 01 a 24 las rechaza.

El RUC tiene 13 dígitos y el tercer dígito dice de qué tipo es:

Tipo 3.er dígito Algoritmo Dígito verificador Establecimiento
Persona natural 0 a 5 Módulo 10 (es la cédula) Posición 10 Últimos 3, distinto de 000
Sector público 6 Módulo 11, coeficientes 3 2 7 6 5 4 3 2 Posición 9 Últimos 4, distinto de 0000
Sociedad privada 9 Módulo 11, coeficientes 4 3 2 7 6 5 4 3 2 Posición 10 Últimos 3, distinto de 000

El RUC de una persona natural es su cédula más el número de establecimiento. 001 es la matriz, que es lo que tiene cualquiera que factura.

Paso 1: limpiar la entrada

La gente escribe 171234567-5, deja espacios al final o pega el número desde un PDF. Conviene limpiar eso antes de validar, y nada más que eso: si queda una letra, el número es inválido y punto.

def limpiar(valor):
    """Quita espacios y guiones: '171234567-5 ' -> '1712345675'."""
    return (valor or "").replace(" ", "").replace("-", "")
Enter fullscreen mode Exit fullscreen mode

Y una función para comprobar que el texto tiene exactamente n dígitos:

def _digitos(valor, largo):
    # isascii() evita que '²' o '١' pasen como dígitos.
    return len(valor) == largo and valor.isascii() and valor.isdigit()


def _provincia_valida(valor):
    provincia = int(valor[:2])
    return 1 <= provincia <= 24 or provincia == 30
Enter fullscreen mode Exit fullscreen mode

El isascii() no es un adorno: "²".isdigit() devuelve True en Python, pero int("²") lanza ValueError. Sin esa comprobación, un carácter raro pegado en el formulario termina en un error 500.

Paso 2: la cédula con módulo 10

El algoritmo:

  1. Se multiplican los primeros 9 dígitos por 2 1 2 1 2 1 2 1 2.
  2. Si un producto pasa de 9, se le resta 9.
  3. Se suman los resultados.
  4. El dígito verificador es (10 - suma % 10) % 10.

Con la cédula ficticia 1712345675:

Dígito 1 7 1 2 3 4 5 6 7
Coeficiente 2 1 2 1 2 1 2 1 2
Producto 2 7 2 2 6 4 10 → 1 6 14 → 5

La suma es 35. 35 % 10 = 5, 10 - 5 = 5. El décimo dígito es 5: la cédula cumple.

COEF_CEDULA = (2, 1, 2, 1, 2, 1, 2, 1, 2)


def validar_cedula(cedula):
    if not _digitos(cedula, 10) or not _provincia_valida(cedula):
        return False
    if int(cedula[2]) >= 6:
        return False
    suma = 0
    for digito, coef in zip(cedula[:9], COEF_CEDULA):
        producto = int(digito) * coef
        suma += producto - 9 if producto > 9 else producto
    return (10 - suma % 10) % 10 == int(cedula[9])
Enter fullscreen mode Exit fullscreen mode

El % 10 final hace falta para el caso en que la suma ya es múltiplo de 10: sin él, el dígito esperado sería 10, que no existe.

Paso 3: el RUC según su tipo

El módulo 11 es parecido, con otros coeficientes y sin restar 9:

  1. Se multiplica cada dígito por su coeficiente y se suma.
  2. Se calcula residuo = suma % 11.
  3. Si el residuo es 0, el dígito es 0. Si no, es 11 - residuo.

Si el residuo es 1, el resultado es 10: ningún dígito puede valer 10, así que ese número no es un RUC válido. La función lo resuelve sola, porque 10 nunca coincide con un dígito.

Con el RUC ficticio de sociedad 1791234561001: los 9 primeros dígitos por 4 3 2 7 6 5 4 3 2 suman 120. 120 % 11 = 10 y 11 - 10 = 1, que es el décimo dígito.

COEF_SOCIEDAD = (4, 3, 2, 7, 6, 5, 4, 3, 2)
COEF_PUBLICO = (3, 2, 7, 6, 5, 4, 3, 2)


def _modulo11(digitos, coeficientes):
    residuo = sum(int(d) * c for d, c in zip(digitos, coeficientes)) % 11
    return 0 if residuo == 0 else 11 - residuo  # 10 nunca coincide: número inválido


def tipo_ruc(ruc):
    """'natural', 'publico', 'sociedad' o None si el formato no es válido."""
    if not _digitos(ruc, 13) or not _provincia_valida(ruc):
        return None
    tercero = int(ruc[2])
    if tercero < 6:
        ok = validar_cedula(ruc[:10]) and ruc[10:] != "000"
        return "natural" if ok else None
    if tercero == 6:
        ok = _modulo11(ruc[:8], COEF_PUBLICO) == int(ruc[8]) and ruc[9:] != "0000"
        return "publico" if ok else None
    if tercero == 9:
        ok = _modulo11(ruc[:9], COEF_SOCIEDAD) == int(ruc[9]) and ruc[10:] != "000"
        return "sociedad" if ok else None
    return None


def validar_ruc(ruc):
    return tipo_ruc(ruc) is not None
Enter fullscreen mode Exit fullscreen mode

Devolver el tipo, y no solo True o False, sirve después: un facturador necesita saber si el comprador es persona natural o sociedad, y así no se calcula dos veces.

Paso 4: probarlo

Estas comprobaciones fallan si alguna regla se rompe. Los números son ficticios: cumplen el algoritmo, pero no se buscaron en el catastro.

assert validar_cedula("1712345675")
assert validar_cedula("0923456784")              # empieza con 0: siempre texto
assert not validar_cedula("1712345674")          # dígito verificador mal
assert not validar_cedula("0000000000")          # provincia 00
assert not validar_cedula("2512345678")          # provincia 25 no existe
assert not validar_cedula("1772345678")          # tercer dígito 7
assert not validar_cedula("17123456²5")          # dígito Unicode
assert validar_cedula(limpiar(" 171234567-5 "))

assert tipo_ruc("1712345675001") == "natural"
assert tipo_ruc("1712345675000") is None         # establecimiento 000
assert tipo_ruc("1791234561001") == "sociedad"
assert tipo_ruc("1765432130001") == "publico"
assert tipo_ruc("1760123400001") is None         # residuo 1: no hay dígito posible
assert not validar_ruc("1712345675")             # una cédula no es un RUC
print("ok")
Enter fullscreen mode Exit fullscreen mode

Paso 5: la misma validación en JavaScript

En el navegador sirve para avisar al usuario mientras escribe. No reemplaza la validación del servidor: cualquiera puede saltarse el JavaScript.

const COEF_CEDULA = [2, 1, 2, 1, 2, 1, 2, 1, 2];
const COEF_SOCIEDAD = [4, 3, 2, 7, 6, 5, 4, 3, 2];
const COEF_PUBLICO = [3, 2, 7, 6, 5, 4, 3, 2];

export const limpiar = (valor) => String(valor ?? '').replace(/[\s-]/g, '');

// typeof: un número perdería el 0 inicial. En JavaScript, \d solo acepta 0-9.
const digitos = (valor, largo) =>
  typeof valor === 'string' && new RegExp(`^\\d{${largo}}$`).test(valor);

function provinciaValida(valor) {
  const provincia = Number(valor.slice(0, 2));
  return (provincia >= 1 && provincia <= 24) || provincia === 30;
}

function modulo11(valor, coeficientes) {
  const suma = coeficientes.reduce((acc, coef, i) => acc + Number(valor[i]) * coef, 0);
  const residuo = suma % 11;
  return residuo === 0 ? 0 : 11 - residuo;
}

export function validarCedula(cedula) {
  if (!digitos(cedula, 10) || !provinciaValida(cedula)) return false;
  if (Number(cedula[2]) >= 6) return false;
  let suma = 0;
  COEF_CEDULA.forEach((coef, i) => {
    const producto = Number(cedula[i]) * coef;
    suma += producto > 9 ? producto - 9 : producto;
  });
  return (10 - (suma % 10)) % 10 === Number(cedula[9]);
}

export function tipoRuc(ruc) {
  if (!digitos(ruc, 13) || !provinciaValida(ruc)) return null;
  const tercero = Number(ruc[2]);
  if (tercero < 6) {
    return validarCedula(ruc.slice(0, 10)) && ruc.slice(10) !== '000' ? 'natural' : null;
  }
  if (tercero === 6) {
    return modulo11(ruc, COEF_PUBLICO) === Number(ruc[8]) && ruc.slice(9) !== '0000' ? 'publico' : null;
  }
  if (tercero === 9) {
    return modulo11(ruc, COEF_SOCIEDAD) === Number(ruc[9]) && ruc.slice(10) !== '000' ? 'sociedad' : null;
  }
  return null;
}

export const validarRuc = (ruc) => tipoRuc(ruc) !== null;
Enter fullscreen mode Exit fullscreen mode

modulo11 recibe el número completo y usa solo tantos dígitos como coeficientes haya; por eso no hace falta cortar la cadena antes.

Para mostrar el error en el formulario basta con el evento input:

const campo = document.querySelector('#cedula');
campo.addEventListener('input', () => {
  const valor = limpiar(campo.value);
  campo.setCustomValidity(valor.length < 10 || validarCedula(valor) ? '' : 'La cédula no es válida');
  campo.reportValidity();
});
Enter fullscreen mode Exit fullscreen mode

Mientras el usuario no termina de escribir los 10 dígitos no se le muestra el error; nada molesta más que un aviso rojo en el primer número.

Paso 6: usarlo en Django

En Django, lo natural es un validator en el campo del modelo. Así lo usan el ModelForm, el admin y full_clean() sin repetir código:

from django.core.exceptions import ValidationError
from django.db import models

from .identificacion_ec import validar_cedula


def cedula_valida(valor):
    if not validar_cedula(valor):
        raise ValidationError("La cédula no es válida.", code="cedula_invalida")


class Cliente(models.Model):
    cedula = models.CharField(max_length=10, unique=True, validators=[cedula_valida])
Enter fullscreen mode Exit fullscreen mode

CharField, no IntegerField. Las cédulas de las provincias 01 a 09 empiezan con cero, y un número lo pierde.

Si el campo acepta cédula o RUC, como el de un comprador en una factura, decide por la longitud: 10 dígitos es una cédula, 13 es un RUC, y cualquier otra cosa (un pasaporte, por ejemplo) se valida por su lado o no se valida.

Errores comunes

Validar solo el dígito verificador. Es el error que yo tenía. Con 0000000000 la suma es 0 y el dígito esperado es 0: pasa. La provincia y el tercer dígito filtran eso.

Guardar la cédula como número. 0923456784 se convierte en 923456784 y deja de tener 10 dígitos. Pasa en la base de datos (IntegerField) y en JavaScript (Number). Por eso el validador de JavaScript rechaza todo lo que no sea texto.

Usar isdigit() a secas. En Python acepta dígitos Unicode como ², que después revientan en int(). Usa isascii() and isdigit() o una expresión regular.

Aplicar módulo 10 a todos los RUC. Solo el de persona natural usa el algoritmo de la cédula. Las sociedades y el sector público usan módulo 11, con coeficientes distintos y el dígito verificador en otra posición.

Confundir «válido» con «existe». El algoritmo deja pasar números inventados. Si el sistema factura, consulta el catastro del SRI. Un detalle práctico: el catastro no conoce cédulas, conoce RUC; para buscar a una persona natural se consulta su cédula más 001.

Bloquear un RUC de sociedad solo por el dígito verificador. El SRI no publica el algoritmo de verificación del RUC de sociedades, y una guía no oficial señala que hay RUC recientes que no cumplen el módulo 11. No lo pude confirmar en una fuente oficial, pero equivocarse aquí significa rechazar a un cliente real. Si tu sistema puede consultar el catastro, cuando tipo_ruc devuelva None para un RUC con tercer dígito 9, muestra una advertencia y deja que el catastro decida.

Creer que el validador del modelo corre al guardar. En Django, save() no llama a los validators. Corren en el ModelForm, en el admin y cuando llamas a full_clean(). Si creas registros desde un script o una API, llama a full_clean() antes de guardar.

Validar solo en el navegador. El JavaScript ayuda al usuario; la regla vive en el servidor.

Conclusión

Validar una cédula o un RUC ecuatoriano son unas 50 líneas sin contar las pruebas: limpiar la entrada, revisar longitud, provincia y tercer dígito, y aplicar módulo 10 o módulo 11 según el tipo. Lo que hace la diferencia son los detalles: guardar siempre como texto, no confiar en isdigit(), y recordar que un número válido no es lo mismo que un número inscrito.

El código completo, con las pruebas en Python y en JavaScript, está listo para copiar. Las mismas ideas sirven para generar la clave de acceso de 49 dígitos de un comprobante electrónico del SRI, que también termina en un dígito verificador módulo 11.


Publicado originalmente en jasmany.com.

Top comments (0)