Documentación · API Cédula y RUC

Integra la API de Cédula y la de RUC en tu sistema

Todo lo necesario para consumir la API de Cédula con foto y la API de RUC en línea: autenticación, endpoints, respuestas correctas, errores, límites y ejemplos listos para copiar.

REST · JSON HTTPS obligatorio Autenticación Bearer Respuestas en español
Contenido de la guía
  1. Inicio rápido
  2. Autenticación
  3. Endpoints
  4. API de Cédula con foto
  5. API de RUC en línea
  6. Respuestas y errores
  7. Límites y buenas prácticas
  8. Ejemplos de código
  9. Validar antes de consultar
  10. Uso responsable (LOPDP)
  11. Soporte

Inicio rápido

Dos APIs independientes, un mismo token y una sola forma de autenticarse. En tres pasos haces tu primera consulta.

Ten tu token

Te lo entregamos al activar tu cuenta. Es un texto largo que empieza con eyJ.

Envíalo en la cabecera

Authorization: Bearer TU_TOKEN en cada petición, siempre por HTTPS.

Lee el JSON

Código 200 con los datos, o 200 con null si el número no existe.

Primera consulta de cédula

bash · cURL
curl -H "Authorization: Bearer TU_TOKEN" \
  https://apicedula.datecu.link/consulta-cedula/consulta/1712345675

Primera consulta de RUC en línea

bash · cURL
curl -H "Authorization: Bearer TU_TOKEN" \
  https://apiruc.datecu.link/api/ruc/consulta/live/1790000000001

Cambia TU_TOKEN por tu token y el número por la cédula o el RUC que quieres consultar.

Autenticación

Todas las consultas se autentican con tu token personal. No hay usuario ni contraseña: el token identifica a tu empresa y los productos que contrataste.

HEADERAuthorization: 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 te entreguemos uno válido para las dos.
  • Usa siempre https://. Una petición sin HTTPS expondría tu token.
  • Trata el token 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.

De demo a premium sin cambiar nada. Cuando tu cuenta pasa de demostración a premium, sigues usando el mismo token: no hay que enviarte otro ni tocar tu código. Solo se activa el servicio completo.

Qué incluye cada tipo de token

TipoCédulaRUCVigencia y límites
GratisSolo el nombre (/free/{cedula})Solo la razón social7 días · hasta 40 consultas al mes
DemoSegún lo acordado con tu ejecutivoVigencia corta (de uno a pocos días)
Premium con fotoFicha completa con foto y código dactilarFicha completa y establecimientosMientras tu servicio esté vigente · sin tope de consultas al mes · ver límites de uso

Endpoints

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

APIRutaQué devuelve
Cédula con fotohttps://apicedula.datecu.link/consulta-cedula/consulta/{cedula}Identificación, nombres, código dactilar y foto. Para todos los datos civiles usa Cédula completa.
Cédula completa (nuevo)https://apicedula.datecu.link/consulta-cedula/completa/{cedula}Todos los campos en una sola respuesta: foto, código dactilar, estado civil, cónyuge, padres, domicilio, instrucción y profesión. Ver detalle.
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 del contribuyente consultada al momento, con representantes y todos los establecimientos.
RUC · consulta rápidahttps://apiruc.datecu.link/api/ruc/consulta/{ruc}La misma ficha desde nuestra base. Más veloz, pero puede no reflejar cambios muy recientes.

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 con foto

Devuelve los datos de una persona a partir de su número de cédula de 10 dígitos, incluida su fotografía.

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

Parámetro

NombreDóndeTipoDescripción
cedulaRutatexto, 10 dígitosNúmero de cédula, solo dígitos, sin guiones ni espacios. Ej.: 1712345675.

Respuesta correcta

Código 200 y un objeto JSON con la identificación, los nombres, el código dactilar y la foto de la persona. Los valores de ejemplo son ficticios.

200 OK · application/json
{
  "identificacion": "1712345675",
  "nombres": "APELLIDO1 APELLIDO2 NOMBRE1 NOMBRE2",
  "codigoDactilar": "V0000V0000",
  "foto": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBD…"
}

¿Necesitas también estado civil, cónyuge, padres, nacimiento, domicilio o profesión? Usa /completa/{cedula}: trae estos cuatro campos y todos los demás en una sola respuesta.

Campos de la respuesta

Los cuatro primeros llegan en /consulta/{cedula}. La tabla completa es la de /completa/{cedula}. El formato de las fechas y de los textos es el que entrega la fuente oficial y puede variar entre registros.

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 codificada en base64 (normalmente JPEG). Para mostrarla: data:image/jpeg;base64, + el valor.
fechaNacimientotextoFecha de nacimiento, tal como la entrega la fuente oficial.
lugarNacimientotextoLugar de nacimiento.
nacionalidadtextoNacionalidad.
estadoCivil, conyugetextoEstado civil y, si corresponde, nombre del cónyuge.
genero, sexotextoGénero / sexo registrado.
nombrePadre, nombreMadretextoNombres de los padres.
instruccion, profesiontextoNivel de instrucción y profesión registrados.
fechaCedulaciontextoFecha en que se emitió la cédula.
condicionCedulado, fechaInscripcionDefunciontextoCondición del cedulado y, si aplica, fecha de inscripción de defunción.

No asumas que todos los campos vienen siempre. Los datos provienen de fuentes oficiales y algunas no entregan todos los campos: los que falten llegan vacíos ("") o no llegan. Lee cada campo con un valor por defecto y no dependas del orden.

Cuando la cédula no existe

La API responde 200 con el cuerpo null (la palabra, sin objeto). Compruébalo antes de leer campos:

200 OK · application/json
null

Variantes sin foto

  • /info/{cedula}: la misma ficha, sin foto.
  • /free/{cedula}: solo los nombres.
  • /datebirth/{cedula}: fecha de nacimiento.

Úsalas cuando no necesites la fotografía: la respuesta es más liviana.

Cédula completa (todos los campos en una sola consulta)

Si necesitas la ficha entera, usa esta ruta. Junta en un solo JSON la foto y el código dactilar con los datos civiles: estado civil, cónyuge, padres, lugar y fecha de nacimiento, domicilio, instrucción y profesión. Así no tienes que hacer dos consultas ni unir respuestas.

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

Usa el mismo token y la misma cabecera Authorization: Bearer que las demás rutas. Requiere un plan premium con foto: con un token sin permiso de foto responde igual que /consulta/{cedula}.

200 OK · application/json
{
  "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"
}
  • Los campos son los de la tabla de arriba, con el mismo significado y formato.
  • Foto y código dactilar no siempre existen. Si la fuente oficial no los tiene, llegan vacíos (""), igual que cualquier otro campo.
  • estadoCivil trae el estado (por ejemplo SOLTERO, CASADO, DIVORCIADO, VIUDO, UNION DE HECHO) y conyuge el nombre de la pareja cuando corresponde.
  • Si la cédula no existe, responde 200 con el cuerpo null, como la ruta normal. Una cédula 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 (150 cada 5 minutos por IP).
  • Tarda lo mismo que la más lenta de las dos consultas que reúne, no la suma. Usa el mismo timeout de 60 segundos.

Tiempos de respuesta

Lo habitual es entre 1 y 4 segundos. Una cédula que se consulta por primera vez puede tardar más porque se pide a las fuentes oficiales; las siguientes salen de caché. Configura un timeout de 60 segundos.

API de RUC en línea

Devuelve la ficha del contribuyente a partir del RUC de 13 dígitos: estado, régimen, obligaciones, representantes legales y todos sus establecimientos.

GEThttps://apiruc.datecu.link/api/ruc/consulta/live/{ruc}
GEThttps://apiruc.datecu.link/api/ruc/consulta/{ruc}
RutaCuándo usarlaTiempo típico
/live/{ruc} · en líneaCuando necesitas el dato al momento: al dar de alta un cliente, emitir una factura o validar un proveedor.1 a 5 segundos
/{ruc} · consulta rápidaCuando basta con el dato de nuestra base y priorizas velocidad (listados, validaciones masivas).Menos de 1 segundo

Parámetro

NombreDóndeTipoDescripción
rucRutatexto, 13 dígitosRUC completo, solo dígitos. Ej.: 1790000000001. En personas naturales es la cédula seguida de 001.

Respuesta correcta

Código 200 y un objeto JSON. Valores de ejemplo ficticios; establecimientos se recorta aquí por espacio.

200 OK · application/json
{
  "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"
    }
  ]
}

Campos de la respuesta

CampoTipoDescripción
numeroRuctextoRUC consultado (13 dígitos).
razonSocialtextoRazón social o nombres del contribuyente.
estadoContribuyenteRuctextoEstado del RUC, por ejemplo ACTIVO o SUSPENDIDO.
actividadEconomicaPrincipaltextoDescripción de la actividad económica principal.
tipoContribuyentetextoPor ejemplo SOCIEDAD o PERSONA NATURAL.
regimentextoRégimen tributario, por ejemplo GENERAL o RIMPE.
obligadoLlevarContabilidad
agenteRetencion
contribuyenteEspecial
contribuyenteFantasma
transaccionesInexistente
texto "SI" / "NO"Banderas del contribuyente. Llegan como texto, no como booleano: compara con "SI".
informacionFechasContribuyenteobjetofechaInicioActividades, fechaReinicioActividades, fechaCese y fechaActualizacion. Formato AAAA-MM-DD HH:MM:SS.s; vacío ("") si no aplica.
representantesLegaleslistaCada elemento trae identificacion y nombre. Puede venir vacía.
establecimientoslistaTodos los establecimientos del RUC (puede haber cientos). Cada uno trae numeroEstablecimiento (ej. "001"), nombreFantasiaComercial, tipoEstablecimiento (código de 3 letras), direccionCompleta, estado (ABIERTO o CERRADO) y matriz ("SI" / "NO").

La consulta rápida (/{ruc}) puede incluir además un campo _id interno dentro de cada establecimiento y representante. Ignóralo. Por la misma razón, el número de establecimientos puede diferir entre la consulta en línea y la rápida: la en línea es la más actual.

Cuando el RUC no existe o no es válido

Igual que en cédula, la API responde 200 con el cuerpo null. Esto ocurre tanto con un RUC inexistente como con uno mal formado, por eso conviene validar el formato antes de consultar.

200 OK · application/json
null

Las fichas de contribuyentes con muchos establecimientos pueden pesar decenas de KB. Configura un timeout de 60 segundos y no las pidas en cada pantalla: guarda lo que necesites.

Respuestas y errores

Maneja siempre el código HTTP y el cuerpo: un 200 puede traer null.

CódigoCuerpoQué significaQué hacer
200Objeto JSONConsulta correcta.Procesa los datos.
200nullEl número no existe o no tiene el formato correcto.Trátalo como «no encontrado». No reintentes.
403JSON con error, plan, mas_infoEl token no fue aceptado, o se alcanzó un límite. Ver causas.Revisa el token y el estado de tu cuenta. No reintentes sin corregir.
429JSON con status y errorSuperaste el límite de velocidad de la API de Cédula, que nos protege de ataques: 150 consultas cada 5 minutos por IP. Ver límites.Espera los segundos que indica la cabecera Retry-After (máximo 5 minutos) y reintenta. Baja el ritmo.
503JSON con reintentar: trueServicio momentáneamente no disponible, o ruta mal escrita.Reintenta con espera creciente; si persiste, revisa la URL.
5xxVariableError temporal del servicio.Reintenta más tarde, sin bucles inmediatos.

Error 403 · acceso denegado

Es el error más frecuente. Cualquier rechazo de acceso —token ausente, inválido, vencido o que no corresponde a esa consulta— responde con el mismo cuerpo, así que no puedes distinguir la causa por el texto. Revisa esta lista en orden:

403 Forbidden · application/json
{
  "error": "Acceso denegado o límite de consultas alcanzado. Necesitas un token válido y un plan premium vigente. Revisa los planes en https://socket-studio.com/api-cedula-ruc.html",
  "plan": "premium",
  "mas_info": "https://socket-studio.com/api-cedula-ruc.html"
}
#Causa probableCómo comprobarlo / solucionarlo
1No se envió la cabecera Authorization.Confirma que tu cliente HTTP la incluye en cada petición, también en redirecciones.
2Cabecera mal formada.Debe ser exactamente Bearer + token. Sin comillas, sin salto de línea al final, sin espacios de más.
3Token alterado o incompleto.Vuelve a copiarlo completo desde el original que recibiste.
4Servicio vencido o cuenta inactiva.Renueva desde tu panel o escríbenos.
5Token revocado.Si cambiamos o revocamos tu token, te entregaremos uno nuevo.
6El token no corresponde a esa consulta.Un token solo de RUC no abre la API de cédula, y viceversa. Si crees que tu token debería servir, escríbenos.
7Plan gratis: se superaron las 40 consultas del mes.Espera al mes siguiente o pasa a premium.

Error 503 · servicio no disponible

503 Service Unavailable · application/json
{
  "error": "Servicio temporalmente no disponible. Intenta de nuevo en unos momentos.",
  "reintentar": true
}

Es transitorio. Reintenta hasta 3 veces esperando 2, 4 y 8 segundos. Si después de varios minutos sigue igual, comprueba que la URL sea correcta 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 a cualquiera.
  • Valida el formato antes de consultar (ver cómo). Evitas peticiones inútiles y respuestas null.
  • Guarda en caché lo que repitas. Una persona o un RUC no cambian minuto a minuto.
  • Evita ráfagas. Un ritmo constante es más seguro que muchas peticiones simultáneas en pocos segundos. Si procesas un archivo grande, consulta de forma secuencial o con pocas consultas en paralelo. La API de Cédula admite 150 consultas cada 5 minutos por IP (≈ 30 por minuto de forma sostenida).
  • Usa timeout de 60 segundos y reintenta solo ante 429, 503 y errores de red, con espera creciente.
  • No reintentes un 403 ni un null: no se arreglan solos.
  • Una variable de entorno para el token, y avísanos si crees que se filtró para revocarlo y entregarte otro.
  • Conserva el mínimo de datos. Si no necesitas la foto o el código dactilar, no los almacenes.

¿Por qué hay límites? Los límites de velocidad existen para evitar ataques (abuso automatizado, intentos masivos y uso de tokens filtrados) y proteger tanto tus datos como la estabilidad del servicio para todos los clientes. Respétalos y tu integración funcionará sin sobresaltos.

ConceptoValor
ProtocoloHTTPS (TLS). Las peticiones por HTTP se redirigen, pero tu token ya habría viajado sin cifrar: no uses http://.
FormatoJSON en UTF-8.
Plan gratis40 consultas al mes, token de 7 días, solo nombres.
Premium · consultas al mesSin tope de consultas al mes.
Premium · velocidad en la API de Cédula150 consultas cada 5 minutos por IP (ventana fija). Cada respuesta trae las cabeceras RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset. Al superarlo responde 429 con Retry-After y se libera al terminar la ventana.
Premium · velocidad en la API de RUCSin límite fijo por IP. La consulta en línea depende de la fuente oficial (de 1 a 5 segundos por consulta): evita ráfagas.
Consultas simultáneasSin tope fijo, pero cuentan para el límite de velocidad de arriba. Mantén pocas en paralelo.
Timeout recomendado60 segundos.

Ejemplos de código

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

¿Prefieres Postman? Descarga las colecciones listas para importar: Cédula con foto · RUC en línea. Al importarlas, pega tu token en la variable token de la colección y pulsa Send.

Node.js 18+
const TOKEN = process.env.SOCKET_API_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 o no corresponde a esta consulta");
    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");
}

// Cédula con foto
const persona = await consultar(`${CEDULA}/1712345675`);
if (persona === null) console.log("Cédula no encontrada");
else console.log(persona.nombres, persona.foto ? "(con foto)" : "(sin foto)");

// RUC en línea
const ficha = await consultar(`${RUC}/live/1790000000001`);
if (ficha) {
  console.log(ficha.razonSocial, ficha.estadoContribuyenteRuc);
  const obligado = ficha.obligadoLlevarContabilidad === "SI";
  const abiertos = (ficha.establecimientos ?? []).filter((e) => e.estado === "ABIERTO");
  console.log({ obligado, abiertos: abiertos.length });
}

Mostrar la foto en una página

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

Para guardarla como archivo, decodifica el texto base64 y escribe los bytes a un .jpg.

Validar antes de consultar

Comprobar el número en tu sistema es gratis e inmediato, y evita consultas que terminarían en null.

  • Cédula: 10 dígitos; los dos primeros son la provincia (01 a 24, o 30); el tercer dígito es menor a 6; y el último es un dígito verificador (módulo 10).
  • RUC: 13 dígitos solo numéricos. En persona natural, los 10 primeros son una cédula válida y los 3 últimos suelen ser 001.
JavaScript
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 cuando tengas un motivo legítimo y puedas justificarlo (verificar identidad al emitir una factura, validar un proveedor, un trámite autorizado).
  • Minimización. Pide y guarda únicamente lo que necesitas. Evita conservar la foto y el código dactilar si no son indispensables.
  • Seguridad. Protege el token y la información obtenida; restringe quién en tu empresa puede consultar.
  • Transparencia. Informa a las personas cuyos datos tratas y atiende sus solicitudes de acceso o rectificación.

Esta es una orientación general y no constituye asesoría legal. Ante dudas sobre tu caso, consulta con tu delegado de protección de datos o un abogado.

Soporte

¿Algo no funciona o necesitas ampliar tu servicio? Escríbenos con el código HTTP que recibes y, si puedes, la hora aproximada de la consulta. Nunca nos envíes tu token completo por correo o chat.