Documentación de las APIs

API de cédula y API de RUC del Ecuador. REST · JSON · HTTPS · autenticación Bearer.

Inicio rápido

Dos APIs independientes, una sola forma de autenticarse. En tres pasos haces tu primera consulta:

  1. Ten tu token. Gratis en Token gratis o el que te entregamos con tu plan. Es un texto largo que empieza con eyJ.
  2. Envíalo en la cabecera Authorization: Bearer TU_TOKEN en cada petición, siempre por HTTPS.
  3. Lee el JSON. Código 200 con los datos, o 200 con null si el número no existe.
# Cédula
curl -H "Authorization: Bearer TU_TOKEN" \
  https://apicedula.datecu.link/consulta-cedula/consulta/1712345675

# RUC en línea
curl -H "Authorization: Bearer TU_TOKEN" \
  https://apiruc.datecu.link/api/ruc/consulta/live/1790000000001

Autenticación

Todas las consultas se autentican con tu token. No hay usuario ni contraseña: el token identifica tu cuenta y los productos que tienes activos.

Authorization: Bearer TU_TOKEN
De gratis o demo a premium sin cambiar nada: sigues usando el mismo token y solo se activa el servicio completo.
TipoCédulaRUCVigencia y límites
GratisSolo nombres (/free/{cedula})Solo razón social7 días, renovable · 40 consultas al mes
DemoSegún lo acordadoVigencia corta
PremiumFicha completa con foto y código dactilarFicha completa y establecimientosMientras tu servicio esté vigente · sin tope mensual

Endpoints

Todos son GET, sin cuerpo, y devuelven JSON. El número va al final de la ruta.

APIRutaQué devuelve
Cédulahttps://apicedula.datecu.link/consulta-cedula/consulta/{cedula}Identificación, nombres, código dactilar y foto
Cédula completahttps://apicedula.datecu.link/consulta-cedula/completa/{cedula}Todos los campos en una sola respuesta
Cédula · variantes…/consulta/info/{cedula}
…/consulta/free/{cedula}
…/consulta/datebirth/{cedula}
Ficha sin foto · solo nombres · fecha de nacimiento
RUC en líneahttps://apiruc.datecu.link/api/ruc/consulta/live/{ruc}Ficha consultada al momento, con representantes y establecimientos
RUC rápidahttps://apiruc.datecu.link/api/ruc/consulta/{ruc}La misma ficha desde la base; más veloz, puede no reflejar cambios muy recientes
RUC gratishttps://apiruc.datecu.link/api/ruc/consulta/free/{ruc}Razón social (plan gratis)
Una ruta mal escrita responde 503 y no 404. Si recibes un 503 constante, revisa primero que la URL sea exactamente una de las anteriores.

API de cédula

GEThttps://apicedula.datecu.link/consulta-cedula/consulta/{cedula}

cedula: 10 dígitos, sin guiones ni espacios. Ej.: 1712345675.

Respuesta correcta (valores ficticios):

{
  "identificacion": "1712345675",
  "nombres": "APELLIDO1 APELLIDO2 NOMBRE1 NOMBRE2",
  "codigoDactilar": "V0000V0000",
  "foto": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBD…"
}
CampoTipoDescripción
identificaciontextoNúmero de cédula consultado
nombrestextoApellidos y nombres completos, en mayúsculas
codigoDactilartextoCódigo dactilar de la cédula
fototexto base64Fotografía (normalmente JPEG). Para mostrarla: data:image/jpeg;base64, + el valor

Cédula inexistente: responde 200 con el cuerpo null. Compruébalo antes de leer campos.

Variantes sin foto: /info/{cedula} (ficha sin foto), /free/{cedula} (solo nombres), /datebirth/{cedula} (fecha de nacimiento). Úsalas si no necesitas la foto: la respuesta es más liviana.

Tiempos: lo habitual es 1 a 4 segundos. Una cédula consultada por primera vez puede tardar más. Configura un timeout de 60 segundos.

Cédula completa

GEThttps://apicedula.datecu.link/consulta-cedula/completa/{cedula}

Junta en un solo JSON la foto y el código dactilar con los datos civiles. Requiere plan premium con foto: con un token sin ese permiso responde igual que /consulta/{cedula}.

{
  "identificacion": "1712345675",
  "nombres": "APELLIDO1 APELLIDO2 NOMBRE1 NOMBRE2",
  "codigoDactilar": "V0000V0000",
  "foto": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBD…",
  "nacionalidad": "ECUATORIANA",
  "lugarNacimiento": "PICHINCHA/QUITO/GONZALEZ SUAREZ",
  "fechaNacimiento": "01/01/1990",
  "estadoCivil": "CASADO",
  "conyuge": "APELLIDO1 APELLIDO2 NOMBRE1 NOMBRE2",
  "genero": "",
  "sexo": "HOMBRE",
  "domicilio": "PICHINCHA/QUITO/IÑAQUITO",
  "calle": "AV. EJEMPLO N00-00",
  "fechaCedulacion": "01/01/2020",
  "nombreMadre": "APELLIDO NOMBRE",
  "nombrePadre": "APELLIDO NOMBRE",
  "condicionCedulado": "CIUDADANO",
  "fechaInscripcionDefuncion": "",
  "instruccion": "SUPERIOR",
  "profesion": "INGENIERO"
}

API de RUC

GEThttps://apiruc.datecu.link/api/ruc/consulta/live/{ruc}

GEThttps://apiruc.datecu.link/api/ruc/consulta/{ruc}

RutaCuándo usarlaTiempo típico
/live/{ruc}Cuando necesitas el dato al momento: alta de clientes, facturación, validar proveedores1 a 5 s
/{ruc}Cuando priorizas velocidad (listados, validaciones masivas)menos de 1 s

ruc: 13 dígitos, solo números. En personas naturales es la cédula seguida de 001.

{
  "numeroRuc": "1790000000001",
  "razonSocial": "EMPRESA DE EJEMPLO S.A.",
  "estadoContribuyenteRuc": "ACTIVO",
  "actividadEconomicaPrincipal": "ACTIVIDADES DE CONSULTORIA INFORMATICA",
  "tipoContribuyente": "SOCIEDAD",
  "regimen": "GENERAL",
  "obligadoLlevarContabilidad": "SI",
  "agenteRetencion": "NO",
  "contribuyenteEspecial": "NO",
  "informacionFechasContribuyente": {
    "fechaInicioActividades": "2010-03-15 00:00:00.0",
    "fechaCese": "",
    "fechaReinicioActividades": "",
    "fechaActualizacion": "2025-11-20 00:00:00.0"
  },
  "representantesLegales": [
    { "identificacion": "1712345675", "nombre": "APELLIDO1 APELLIDO2 NOMBRE1" }
  ],
  "contribuyenteFantasma": "NO",
  "transaccionesInexistente": "NO",
  "establecimientos": [
    {
      "numeroEstablecimiento": "001",
      "nombreFantasiaComercial": "EJEMPLO MATRIZ",
      "tipoEstablecimiento": "MAT",
      "direccionCompleta": "AV. EJEMPLO N10-20 Y CALLE B",
      "estado": "ABIERTO",
      "matriz": "SI"
    }
  ]
}
CampoTipoDescripción
numeroRuctextoRUC consultado (13 dígitos)
razonSocialtextoRazón social o nombres del contribuyente
estadoContribuyenteRuctextoEj.: ACTIVO o SUSPENDIDO
actividadEconomicaPrincipaltextoActividad económica principal
tipoContribuyentetextoEj.: SOCIEDAD o PERSONA NATURAL
regimentextoEj.: GENERAL o RIMPE
obligadoLlevarContabilidad, agenteRetencion, contribuyenteEspecial, contribuyenteFantasma, transaccionesInexistentetexto "SI"/"NO"Banderas del contribuyente. Llegan como texto: compara con "SI"
informacionFechasContribuyenteobjetoFechas de inicio, reinicio, cese y actualización; vacías si no aplican
representantesLegaleslistaCada elemento trae identificacion y nombre. Puede venir vacía
establecimientoslistaTodos los establecimientos (puede haber cientos): número, nombre comercial, tipo, dirección, estado y matriz

La consulta rápida puede incluir un campo interno _id en establecimientos y representantes: ignóralo. Un RUC inexistente o mal formado responde 200 con null.

Respuestas y errores

CódigoCuerpoSignificadoQué hacer
200objeto JSONConsulta correctaProcesa los datos
200nullEl número no existe o no tiene formato correctoTrátalo como «no encontrado». No reintentes
403JSON con error y planToken no aceptado o límite alcanzadoRevisa el token y tu plan. No reintentes sin corregir
429JSON con errorSuperaste el límite de velocidad de la API de cédulaEspera lo que indique Retry-After y reintenta
503JSON con reintentar: trueServicio momentáneamente no disponible, o ruta mal escritaReintenta con espera creciente; si persiste, revisa la URL

Error 403 · acceso denegado

{
  "error": "Acceso denegado o límite de consultas alcanzado. Necesitas un token válido y un plan vigente.",
  "plan": "premium",
  "mas_info": "https://datecu.link/registro.html"
}

Cualquier rechazo responde igual. Revisa en orden: (1) que envías la cabecera Authorization; (2) que tiene el formato exacto Bearer TOKEN; (3) que el token está completo; (4) que tu servicio o token gratis está vigente; (5) que el token no fue revocado; (6) que corresponde a esa API; (7) en el plan gratis, que no superaste las 40 consultas del mes.

Error 503 · servicio no disponible

Es transitorio. Reintenta hasta 3 veces esperando 2, 4 y 8 segundos. Si sigue igual tras varios minutos, comprueba la URL y escríbenos.

Límites y buenas prácticas

ConceptoValor
ProtocoloHTTPS (TLS). No uses http://
FormatoJSON en UTF-8
Plan gratis40 consultas al mes, token de 7 días, solo nombres
Premium · consultas al mesSin tope
Velocidad API de cédula150 consultas cada 5 minutos por IP. Cabeceras RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset; al superarlo, 429 con Retry-After
Velocidad API de RUCSin límite fijo por IP; la consulta en línea depende de la fuente oficial
Timeout recomendado60 segundos

Ejemplos de código

Cada ejemplo lee el token de la variable de entorno DATECU_TOKEN, usa timeout de 60 s, reintenta ante 429/503 y devuelve null si el número no existe.

Node.js 18+

const TOKEN = process.env.DATECU_TOKEN;
const CEDULA = "https://apicedula.datecu.link/consulta-cedula/consulta";
const RUC = "https://apiruc.datecu.link/api/ruc/consulta";
const esperar = (ms) => new Promise((r) => setTimeout(r, ms));

async function consultar(url, intentos = 3) {
  for (let i = 1; i <= intentos; i++) {
    const r = await fetch(url, {
      headers: { Authorization: `Bearer ${TOKEN}` },
      signal: AbortSignal.timeout(60000),
    });
    if (r.status === 429 || r.status === 503) { await esperar(1000 * 2 ** i); continue; }
    if (r.status === 403) throw new Error("403: token no aceptado");
    if (!r.ok) throw new Error(`HTTP ${r.status}`);
    return await r.json(); // puede ser null
  }
  throw new Error("Servicio no disponible tras varios intentos");
}

const persona = await consultar(`${CEDULA}/1712345675`);
console.log(persona ? persona.nombres : "Cédula no encontrada");

const ficha = await consultar(`${RUC}/live/1790000000001`);
if (ficha) console.log(ficha.razonSocial, ficha.estadoContribuyenteRuc);

Python 3 · requests

import os, time, requests

TOKEN = os.environ["DATECU_TOKEN"]
HEAD = {"Authorization": f"Bearer {TOKEN}"}
CEDULA = "https://apicedula.datecu.link/consulta-cedula/consulta"
RUC = "https://apiruc.datecu.link/api/ruc/consulta"

def consultar(url, intentos=3):
    for i in range(1, intentos + 1):
        r = requests.get(url, headers=HEAD, timeout=60)
        if r.status_code in (429, 503):
            time.sleep(2 ** i)
            continue
        if r.status_code == 403:
            raise PermissionError("403: token no aceptado")
        r.raise_for_status()
        return r.json()  # puede ser None
    raise RuntimeError("Servicio no disponible tras varios intentos")

persona = consultar(f"{CEDULA}/1712345675")
print(persona["nombres"] if persona else "Cédula no encontrada")

ficha = consultar(f"{RUC}/live/1790000000001")
if ficha:
    print(ficha["razonSocial"], ficha["estadoContribuyenteRuc"])

PHP 8 · cURL

<?php
const CEDULA = 'https://apicedula.datecu.link/consulta-cedula/consulta';
const RUC = 'https://apiruc.datecu.link/api/ruc/consulta';

function consultar(string $url, int $intentos = 3): ?array
{
    $token = getenv('DATECU_TOKEN');
    for ($i = 1; $i <= $intentos; $i++) {
        $ch = curl_init($url);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 60,
            CURLOPT_HTTPHEADER => ['Accept: application/json', "Authorization: Bearer $token"],
        ]);
        $cuerpo = curl_exec($ch);
        $http = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        if ($cuerpo === false || $http === 429 || $http === 503) { sleep(2 ** $i); continue; }
        if ($http === 403) { throw new RuntimeException('403: token no aceptado'); }
        if ($http !== 200) { throw new RuntimeException("HTTP $http"); }
        return json_decode($cuerpo, true); // null si el número no existe
    }
    throw new RuntimeException('Servicio no disponible tras varios intentos');
}

$persona = consultar(CEDULA . '/1712345675');
echo $persona === null ? "Cédula no encontrada\n" : $persona['nombres'] . "\n";

C# · .NET 6+

using System.Net.Http.Headers;
using System.Text.Json;

const string Cedula = "https://apicedula.datecu.link/consulta-cedula/consulta";
var http = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("DATECU_TOKEN"));

var r = await http.GetAsync($"{Cedula}/1712345675");
r.EnsureSuccessStatusCode();
using var doc = JsonDocument.Parse(await r.Content.ReadAsStringAsync());
Console.WriteLine(doc.RootElement.ValueKind == JsonValueKind.Null
    ? "Cédula no encontrada"
    : doc.RootElement.GetProperty("nombres").GetString());

Mostrar la foto en una página

<img alt="Foto de la cédula" src="data:image/jpeg;base64,VALOR_DEL_CAMPO_foto">

Validar antes de consultar

function cedulaValida(c) {
  if (!/^\d{10}$/.test(c)) return false;
  const provincia = Number(c.slice(0, 2));
  if (provincia < 1 || (provincia > 24 && provincia !== 30)) return false;
  if (Number(c[2]) > 5) return false;
  let suma = 0;
  for (let i = 0; i < 9; i++) {
    let n = Number(c[i]) * (i % 2 === 0 ? 2 : 1);
    if (n > 9) n -= 9;
    suma += n;
  }
  return (10 - (suma % 10)) % 10 === Number(c[9]);
}
const rucFormatoValido = (r) => /^\d{13}$/.test(r);

Uso responsable de los datos (LOPDP)

Las APIs entregan datos personales. Al consumirlos, tu empresa actúa como responsable del tratamiento frente a la Ley Orgánica de Protección de Datos Personales del Ecuador.

Orientación general; no constituye asesoría legal.

Soporte

Escríbenos con el código HTTP que recibes y, si puedes, la hora aproximada de la consulta. Nunca envíes tu token completo por correo o chat.