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:
- Ten tu token. Gratis en Token gratis o el que te entregamos con tu plan. Es un texto largo que empieza con
eyJ. - Envíalo en la cabecera
Authorization: Bearer TU_TOKENen cada petición, siempre por HTTPS. - Lee el JSON. Código 200 con los datos, o 200 con
nullsi 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
- La palabra
Bearer, un espacio y tu token. Sin comillas ni saltos de línea. - Un token de RUC no abre la API de cédula, ni al revés, salvo que tu token sea válido para las dos.
- Usa siempre
https://. Una petición sin HTTPS expondría tu token. - Trátalo como una contraseña: guárdalo en una variable de entorno o un gestor de secretos, nunca en el código, en repositorios ni en el navegador de tus usuarios.
| Tipo | Cédula | RUC | Vigencia y límites |
|---|---|---|---|
| Gratis | Solo nombres (/free/{cedula}) | Solo razón social | 7 días, renovable · 40 consultas al mes |
| Demo | Según lo acordado | Vigencia corta | |
| Premium | Ficha completa con foto y código dactilar | Ficha completa y establecimientos | Mientras 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.
| API | Ruta | Qué devuelve |
|---|---|---|
| Cédula | https://apicedula.datecu.link/consulta-cedula/consulta/{cedula} | Identificación, nombres, código dactilar y foto |
| Cédula completa | https://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ínea | https://apiruc.datecu.link/api/ruc/consulta/live/{ruc} | Ficha consultada al momento, con representantes y establecimientos |
| RUC rápida | https://apiruc.datecu.link/api/ruc/consulta/{ruc} | La misma ficha desde la base; más veloz, puede no reflejar cambios muy recientes |
| RUC gratis | https://apiruc.datecu.link/api/ruc/consulta/free/{ruc} | Razón social (plan gratis) |
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…"
}
| Campo | Tipo | Descripción |
|---|---|---|
| identificacion | texto | Número de cédula consultado |
| nombres | texto | Apellidos y nombres completos, en mayúsculas |
| codigoDactilar | texto | Código dactilar de la cédula |
| foto | texto base64 | Fotografí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"
}
- No todos los campos llegan siempre: los que la fuente oficial no entrega llegan vacíos (
"") o no llegan. Lee cada campo con un valor por defecto. - Una cédula inexistente responde 200 con
null; una que no tiene exactamente 10 dígitos responde 404. - Cuenta como dos consultas en el límite de velocidad de la API de cédula.
API de RUC
GEThttps://apiruc.datecu.link/api/ruc/consulta/live/{ruc}
GEThttps://apiruc.datecu.link/api/ruc/consulta/{ruc}
| Ruta | Cuándo usarla | Tiempo típico |
|---|---|---|
/live/{ruc} | Cuando necesitas el dato al momento: alta de clientes, facturación, validar proveedores | 1 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"
}
]
}
| Campo | Tipo | Descripción |
|---|---|---|
| numeroRuc | texto | RUC consultado (13 dígitos) |
| razonSocial | texto | Razón social o nombres del contribuyente |
| estadoContribuyenteRuc | texto | Ej.: ACTIVO o SUSPENDIDO |
| actividadEconomicaPrincipal | texto | Actividad económica principal |
| tipoContribuyente | texto | Ej.: SOCIEDAD o PERSONA NATURAL |
| regimen | texto | Ej.: GENERAL o RIMPE |
| obligadoLlevarContabilidad, agenteRetencion, contribuyenteEspecial, contribuyenteFantasma, transaccionesInexistente | texto "SI"/"NO" | Banderas del contribuyente. Llegan como texto: compara con "SI" |
| informacionFechasContribuyente | objeto | Fechas de inicio, reinicio, cese y actualización; vacías si no aplican |
| representantesLegales | lista | Cada elemento trae identificacion y nombre. Puede venir vacía |
| establecimientos | lista | Todos 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ódigo | Cuerpo | Significado | Qué hacer |
|---|---|---|---|
| 200 | objeto JSON | Consulta correcta | Procesa los datos |
| 200 | null | El número no existe o no tiene formato correcto | Trátalo como «no encontrado». No reintentes |
| 403 | JSON con error y plan | Token no aceptado o límite alcanzado | Revisa el token y tu plan. No reintentes sin corregir |
| 429 | JSON con error | Superaste el límite de velocidad de la API de cédula | Espera lo que indique Retry-After y reintenta |
| 503 | JSON con reintentar: true | Servicio momentáneamente no disponible, o ruta mal escrita | Reintenta 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
- Consulta desde tu servidor, no desde el navegador ni desde una app móvil: ahí tu token quedaría expuesto.
- Valida el formato antes de consultar (ver cómo).
- Guarda en caché lo que repitas: una persona o un RUC no cambian minuto a minuto.
- Evita ráfagas. La API de cédula admite 150 consultas cada 5 minutos por IP (≈ 30 por minuto sostenidas).
- Timeout de 60 segundos y reintentos solo ante 429, 503 y errores de red, con espera creciente.
- No reintentes un 403 ni un
null. - Conserva el mínimo de datos. Si no necesitas la foto o el código dactilar, no los almacenes.
| Concepto | Valor |
|---|---|
| Protocolo | HTTPS (TLS). No uses http:// |
| Formato | JSON en UTF-8 |
| Plan gratis | 40 consultas al mes, token de 7 días, solo nombres |
| Premium · consultas al mes | Sin tope |
| Velocidad API de cédula | 150 consultas cada 5 minutos por IP. Cabeceras RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset; al superarlo, 429 con Retry-After |
| Velocidad API de RUC | Sin límite fijo por IP; la consulta en línea depende de la fuente oficial |
| Timeout recomendado | 60 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
- Cédula: 10 dígitos; los dos primeros son la provincia (01 a 24, o 30); el tercero es menor a 6; el último es un dígito verificador (módulo 10).
- RUC: 13 dígitos. En persona natural, los 10 primeros son una cédula válida y los 3 últimos suelen ser 001.
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.
- Finalidad: consulta solo con un motivo legítimo (facturación, verificación de identidad, validación de proveedores).
- Minimización: guarda únicamente lo que necesitas.
- Seguridad: protege el token y la información obtenida.
- Transparencia: informa a las personas cuyos datos tratas y atiende sus solicitudes.
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.
- WhatsApp: 096 372 2580
- Horario: lunes a viernes, 9:00 a 18:00 (hora de Ecuador)
- Token gratis y renovación: datecu.link/registro.html