Categoría: Python

  • Clave de acceso SRI: 49 dígitos y módulo 11 en Python

    Cada comprobante electrónico que se envía al SRI lleva una clave de acceso de 49 dígitos. No es un detalle: en el esquema offline, esa clave es también el número de autorización del comprobante, y si está mal armada el SRI lo rechaza.

    Una aclaración antes de empezar, porque Google mezcla los dos temas: aquí no se habla de la contraseña para entrar a SRI en línea. La clave de acceso es un número que genera tu sistema para cada factura, nota de crédito o retención.

    Escribí esta función dos veces. En mi primer facturador, la clave se calculaba una sola vez y se guardaba. Funcionaba, pero tenía dos huecos: no revisaba la longitud de cada parte (un secuencial sin ceros a la izquierda habría dado una clave más corta sin ningún aviso) y no se volvía a calcular si después cambiaba la fecha del borrador. En el segundo, cada parte se valida y la clave se recalcula mientras el comprobante es borrador. Lo que sigue es una versión limpia de esa segunda función, en Python y en JavaScript, con pruebas.

    Lo que dice la ficha técnica

    La fuente es la Ficha Técnica de Comprobantes Electrónicos Esquema Offline del SRI, versión 2.34 (julio de 2026), sección 5.2. La clave tiene 9 partes:

    PosiciónParteLargoEjemplo
    1–8Fecha de emisión, ddmmaaaa814112026
    9–10Tipo de comprobante201
    11–23RUC del emisor131791234561001
    24Ambiente11
    25–30Serie: establecimiento + punto de emisión6001002
    31–39Secuencial9000000124
    40–47Código numérico812345678
    48Tipo de emisión11
    49Dígito verificador (módulo 11)16

    Los códigos que se usan en esas partes:

    Tipo de comprobanteCódigo
    Factura01
    Liquidación de compra de bienes y prestación de servicios03
    Nota de crédito04
    Nota de débito05
    Guía de remisión06
    Comprobante de retención07

    El ambiente es 1 para pruebas y 2 para producción. El tipo de emisión siempre es 1 (emisión normal): en el esquema offline no existe otro.

    Dos frases de la ficha que conviene tener presentes:

    • «Todos los campos deben completarse conforme a la longitud indicada»: un secuencial de menos de 9 dígitos deja la clave «mal conformada» y es motivo de rechazo.
    • El código numérico «es potestad absoluta del contribuyente emisor»: el SRI no dice cómo generarlo. Más abajo hay una forma razonable.

    Paso 1: el módulo 11

    El dígito verificador se calcula sobre los primeros 48 dígitos:

    1. Se recorren los dígitos de derecha a izquierda, multiplicando por los pesos 2, 3, 4, 5, 6, 7, y se vuelve a empezar en 2 al llegar a 7.
    2. Se suman los productos.
    3. Se calcula 11 - suma % 11.
    4. Si el resultado es 11, el dígito es 0. Si es 10, el dígito es 1.

    La ficha trae este ejemplo con la cadena 41261533:

    Dígito41261533
    Peso32765432
    Producto122143652096

    La suma es 104. 104 % 11 = 5 y 11 - 5 = 6. El dígito verificador es 6.

    import secrets
    from datetime import date, datetime
    from itertools import cycle
    
    TIPOS_COMPROBANTE = {
        "01": "Factura",
        "03": "Liquidación de compra",
        "04": "Nota de crédito",
        "05": "Nota de débito",
        "06": "Guía de remisión",
        "07": "Comprobante de retención",
    }
    AMBIENTES = {"1": "Pruebas", "2": "Producción"}
    
    
    def _solo_digitos(valor, largo):
        return len(valor) == largo and valor.isascii() and valor.isdigit()
    
    
    def modulo11(digitos):
        """Dígito verificador: pesos 2 a 7 desde la derecha; 11 -> 0 y 10 -> 1."""
        if not (digitos.isascii() and digitos.isdigit()):
            raise ValueError("El módulo 11 solo acepta dígitos.")
        suma = sum(int(d) * peso for d, peso in zip(reversed(digitos), cycle(range(2, 8))))
        resultado = 11 - suma % 11
        return {11: 0, 10: 1}.get(resultado, resultado)

    cycle(range(2, 8)) repite 2, 3, 4, 5, 6, 7 sin fin, y zip se detiene cuando se acaban los dígitos. El isascii() está por la misma razón que en el validador de cédula y RUC: "²".isdigit() es True en Python.

    Es el mismo módulo 11 de los RUC de sociedades, con una diferencia: allí un resultado de 10 invalida el número, y aquí se convierte en 1. Esa regla tiene un costo que se ve en las pruebas: el verificador ya no detecta todos los errores de un dígito.

    Paso 2: armar la clave

    def nuevo_codigo_numerico():
        """Los 8 dígitos libres. El algoritmo lo elige el emisor; aquí, azar seguro."""
        return f"{secrets.randbelow(100_000_000):08d}"
    
    
    def generar_clave_acceso(*, fecha_emision, tipo_comprobante, ruc, ambiente,
                             establecimiento, punto_emision, secuencial, codigo_numerico,
                             tipo_emision="1"):
        if tipo_comprobante not in TIPOS_COMPROBANTE:
            raise ValueError(f"Tipo de comprobante desconocido: {tipo_comprobante!r}")
        if ambiente not in AMBIENTES:
            raise ValueError("El ambiente es '1' (pruebas) o '2' (producción).")
        if tipo_emision != "1":
            raise ValueError("En el esquema offline solo existe la emisión normal ('1').")
        for nombre, valor, largo in [("ruc", ruc, 13), ("establecimiento", establecimiento, 3),
                                     ("punto_emision", punto_emision, 3),
                                     ("codigo_numerico", codigo_numerico, 8)]:
            if not _solo_digitos(valor, largo):
                raise ValueError(f"{nombre} debe tener exactamente {largo} dígitos.")
        if not 1 <= secuencial <= 999_999_999:
            raise ValueError("El secuencial va de 1 a 999999999.")
    
        base = (fecha_emision.strftime("%d%m%Y") + tipo_comprobante + ruc + ambiente
                + establecimiento + punto_emision + f"{secuencial:09d}" + codigo_numerico
                + tipo_emision)
        return base + str(modulo11(base))

    Tres decisiones que evitan errores:

    • El secuencial entra como número y se rellena con f"{secuencial:09d}". Así no depende de que alguien recuerde los ceros.
    • Todo lo demás entra como texto y se valida con su largo exacto. El establecimiento 001 como número sería 1.
    • Los argumentos son con nombre (el * del inicio). Con nueve parámetros seguidos, pasar el establecimiento donde va el punto de emisión es demasiado fácil.

    Con los datos de la primera tabla (RUC de sociedad ficticio, el mismo que usé para probar el validador de RUC), la clave queda así:

    14112026 01 1791234561001 1 001002 000000124 12345678 1 | 6

    Los 48 dígitos ponderados suman 489. 489 % 11 = 5 y 11 - 5 = 6.

    Paso 3: validar y leer una clave

    Para revisar una clave que llega de otro sistema, o para mostrar sus partes en pantalla:

    def validar_clave_acceso(clave):
        return _solo_digitos(clave, 49) and modulo11(clave[:48]) == int(clave[48])
    
    
    def leer_clave_acceso(clave):
        """Separa una clave válida en sus partes."""
        if not validar_clave_acceso(clave):
            raise ValueError("No es una clave de acceso válida.")
        return {
            "fecha_emision": datetime.strptime(clave[0:8], "%d%m%Y").date(),
            "tipo_comprobante": clave[8:10],
            "ruc": clave[10:23],
            "ambiente": clave[23],
            "establecimiento": clave[24:27],
            "punto_emision": clave[27:30],
            "secuencial": int(clave[30:39]),
            "codigo_numerico": clave[39:47],
            "tipo_emision": clave[47],
            "digito_verificador": clave[48],
        }

    validar_clave_acceso solo dice que la clave está bien formada. Si el comprobante existe y está autorizado lo dice el SRI, consultando su web service de autorización con esa clave.

    Paso 4: probarlo

    Estas comprobaciones fallan si alguna regla se rompe:

    assert modulo11("41261533") == 6          # ejemplo de la ficha técnica
    assert modulo11("0") == 0                 # resultado 11 -> 0
    assert modulo11("6") == 1                 # resultado 10 -> 1
    
    datos = dict(fecha_emision=date(2026, 11, 14), tipo_comprobante="01",
                 ruc="1791234561001", ambiente="1", establecimiento="001",
                 punto_emision="002", secuencial=124, codigo_numerico="12345678")
    clave = generar_clave_acceso(**datos)
    assert clave == "1411202601179123456100110010020000001241234567816"
    assert validar_clave_acceso(clave)
    assert leer_clave_acceso(clave)["secuencial"] == 124
    
    assert not validar_clave_acceso(clave[:48] + "9")       # verificador cambiado
    assert not validar_clave_acceso(clave[:48] + "²")       # dígito Unicode
    assert generar_clave_acceso(**{**datos, "secuencial": 123})[-1] == "0"
    
    # El costo de la regla 10 -> 1: con el secuencial 121 el verificador es 1, y
    # si alguien escribe 125 en lugar de 121 la clave sigue siendo "válida".
    c121 = generar_clave_acceso(**{**datos, "secuencial": 121})
    c125 = c121[:36] + "125" + c121[39:]
    assert c121[-1] == "1" and validar_clave_acceso(c125)
    
    for malo in [dict(secuencial=0), dict(establecimiento="1"), dict(ambiente="3"),
                 dict(tipo_comprobante="02"), dict(codigo_numerico="1234567")]:
        try:
            generar_clave_acceso(**{**datos, **malo})
        except ValueError:
            pass
        else:
            raise AssertionError(f"debió fallar: {malo}")
    print("ok")

    La prueba del 121 y el 125 no es un error del código: es cómo funciona el módulo 11 del SRI. Con el 121 la suma deja residuo 1 y el resultado es 10; con el 125 deja residuo 10 y el resultado es 1. Los dos terminan en 1. Por eso el verificador sirve para atrapar la mayoría de los errores de tipeo, no todos, y la clave nunca se escribe a mano: se genera y se copia.

    Paso 5: la misma clave en JavaScript

    En JavaScript sirve, por ejemplo, para leer o validar una clave en el navegador antes de consultarla:

    export const TIPOS_COMPROBANTE = ['01', '03', '04', '05', '06', '07'];
    
    const soloDigitos = (valor, largo) =>
      typeof valor === 'string' && new RegExp(`^\\d{${largo}}$`).test(valor);
    
    export function modulo11(digitos) {
      if (!/^\d+$/.test(digitos)) throw new Error('El módulo 11 solo acepta dígitos.');
      let suma = 0;
      let peso = 2;
      for (let i = digitos.length - 1; i >= 0; i--) {
        suma += Number(digitos[i]) * peso;
        peso = peso === 7 ? 2 : peso + 1;
      }
      const resultado = 11 - (suma % 11);
      return resultado === 11 ? 0 : resultado === 10 ? 1 : resultado;
    }
    
    export function generarClaveAcceso({
      fechaEmision, tipoComprobante, ruc, ambiente, establecimiento,
      puntoEmision, secuencial, codigoNumerico, tipoEmision = '1',
    }) {
      if (!TIPOS_COMPROBANTE.includes(tipoComprobante)) throw new Error('Tipo de comprobante desconocido.');
      if (!['1', '2'].includes(ambiente)) throw new Error("El ambiente es '1' o '2'.");
      if (tipoEmision !== '1') throw new Error("En el esquema offline solo existe la emisión normal ('1').");
      for (const [nombre, valor, largo] of [['ruc', ruc, 13], ['establecimiento', establecimiento, 3],
        ['puntoEmision', puntoEmision, 3], ['codigoNumerico', codigoNumerico, 8]]) {
        if (!soloDigitos(valor, largo)) throw new Error(`${nombre} debe tener exactamente ${largo} dígitos.`);
      }
      if (!Number.isInteger(secuencial) || secuencial < 1 || secuencial > 999_999_999) {
        throw new Error('El secuencial va de 1 a 999999999.');
      }
      // fechaEmision es 'AAAA-MM-DD' (texto): un Date se correría de día por la zona horaria.
      const [anio, mes, dia] = fechaEmision.split('-');
      const base = dia + mes + anio + tipoComprobante + ruc + ambiente + establecimiento
        + puntoEmision + String(secuencial).padStart(9, '0') + codigoNumerico + tipoEmision;
      if (!soloDigitos(base, 48)) throw new Error('La fecha debe venir como AAAA-MM-DD.');
      return base + modulo11(base);
    }
    
    export const validarClaveAcceso = (clave) =>
      soloDigitos(clave, 49) && modulo11(clave.slice(0, 48)) === Number(clave[48]);

    Dos detalles propios de JavaScript:

    • La fecha va como texto. new Date('2026-11-14') se interpreta como medianoche en UTC; en Ecuador (UTC−5) eso es el 13 de noviembre a las 19:00, y getDate() devuelve 13. Una clave con el día equivocado no coincide con la fecha del XML.
    • La clave nunca es un número. Number solo representa enteros exactos hasta 16 dígitos (Number.MAX_SAFE_INTEGER); con 49, los últimos se pierden. validarClaveAcceso rechaza todo lo que no sea texto.

    Las mismas pruebas, en un archivo aparte que se ejecuta con node:

    import assert from 'node:assert/strict';
    import { modulo11, generarClaveAcceso, validarClaveAcceso } from './clave-acceso.mjs';
    
    assert.equal(modulo11('41261533'), 6);
    const datos = {
      fechaEmision: '2026-11-14', tipoComprobante: '01', ruc: '1791234561001', ambiente: '1',
      establecimiento: '001', puntoEmision: '002', secuencial: 124, codigoNumerico: '12345678',
    };
    const clave = generarClaveAcceso(datos);
    assert.equal(clave, '1411202601179123456100110010020000001241234567816');
    assert.ok(validarClaveAcceso(clave));
    assert.ok(!validarClaveAcceso(Number(clave)));
    console.log('ok');

    Paso 6: cuándo generarla en tu sistema

    La función es lo fácil. Lo que más cuesta es decidir cuándo se llama:

    • El código numérico se genera una sola vez por comprobante y se guarda junto a él. secrets.randbelow (o crypto.getRandomValues en el navegador) es suficiente.
    • Mientras el comprobante es borrador, la clave se recalcula cada vez que cambian la fecha, la serie, el secuencial o el ambiente, con el mismo código numérico. Así la clave solo cambia cuando cambió algo de lo que la compone.
    • Desde que se envía al SRI, la clave no se toca. La ficha técnica (sección 5.10) dice que un comprobante rechazado por inconsistencias se corrige y se reenvía con la misma clave de acceso y el mismo secuencial.

    En Django, el modelo puede quedar así:

    from django.db import models
    
    
    class Comprobante(models.Model):
        secuencial = models.PositiveIntegerField()
        codigo_numerico = models.CharField(max_length=8, blank=True)
        clave_acceso = models.CharField(max_length=49, unique=True, null=True, blank=True)

    CharField para la clave, nunca un campo numérico; unique=True porque el SRI también la rechaza si ya está registrada (error 43); y null=True para que varios borradores sin clave no choquen con el índice único.

    Errores comunes

    Secuencial sin ceros a la izquierda. 124 en lugar de 000000124 deja una clave de 43 dígitos. La ficha lo menciona expresamente como motivo de rechazo. Rellenar en la función, no en quien la llama.

    Clave que no coincide con el comprobante. Si la fecha o el secuencial del XML cambian y la clave no se recalcula, el SRI responde con el error 58, «Error en la estructura de clave acceso», que describe así: la clave «tiene componentes diferentes a los del comprobante». Es el hueco que tenía mi primera versión.

    Generar un código numérico nuevo en cada intento. Cambia la clave en cada reenvío, y la ficha (sección 5.10) pide lo contrario: corregir el comprobante rechazado y reenviarlo con la misma clave y el mismo secuencial.

    Probar en pruebas y pasar a producción con la misma clave. El ambiente es la posición 24 de la clave. Un comprobante de pruebas reenviado a producción necesita una clave nueva.

    Guardar o transportar la clave como número. En JavaScript pierde dígitos; en una base de datos, ni INTEGER ni BIGINT (19 dígitos como máximo) alcanzan para 49.

    Confiar en el verificador como prueba de que la clave existe. El módulo 11 solo detecta errores de formato, y no todos (el caso 121/125). Si el comprobante está autorizado lo dice el SRI.

    Conclusión

    La clave de acceso son 48 dígitos que se arman con datos del propio comprobante, más un dígito verificador módulo 11 con pesos de 2 a 7. El cálculo cabe en diez líneas; lo que cuesta es el resto: validar el largo de cada parte, rellenar el secuencial, no tratarla nunca como número, y generarla en el momento correcto del ciclo del comprobante.

    El código completo, con las pruebas en Python y en JavaScript, está listo para copiar. Con la clave lista, el siguiente paso es firmar el XML y enviarlo a los web services de recepción y autorización del SRI.

  • 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ónSignificado
    1–2Provincia: de 01 a 24, o 30 para ecuatorianos en el exterior
    3Menor que 6 en una persona natural
    4–9Secuencial
    10Dí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:

    Tipo3.er dígitoAlgoritmoDígito verificadorEstablecimiento
    Persona natural0 a 5Módulo 10 (es la cédula)Posición 10Últimos 3, distinto de 000
    Sector público6Módulo 11, coeficientes 3 2 7 6 5 4 3 2Posición 9Últimos 4, distinto de 0000
    Sociedad privada9Módulo 11, coeficientes 4 3 2 7 6 5 4 3 2Posició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("-", "")

    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

    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ígito171234567
    Coeficiente212121212
    Producto27226410 → 1614 → 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])

    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

    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")

    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;

    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();
    });

    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])

    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.