Cómo integrar una API de cédulas de Ecuador

Qué endpoint usar para consultar una cédula

Para obtener los nombres asociados a una cédula usa GET /api/v1/cedulas/{cedula}/nombres. Cuando están disponibles, la respuesta separa nombres y apellidos, además de incluir el nombre completo y el identificador consultado.

Los demás datos disponibles tienen endpoints independientes. Así puedes solicitar únicamente lo que tu aplicación necesita y revisar el contrato exacto de cada campo en la documentación.

Antes de hacer la primera solicitud

• Crea una cuenta y genera una API key desde el panel.
• Guarda ECUADORAPI_KEY como variable de entorno en tu servidor; nunca la incluyas en JavaScript que se ejecute en el navegador.
• Valida que la cédula tenga 10 dígitos y un dígito verificador válido antes de enviarla.
• Define una finalidad legítima y solicita solo los datos necesarios para tu proceso.

Ejemplos para consultar una cédula desde código

Elige el lenguaje, copia el ejemplo y sustituye la cédula ficticia. Todos los ejemplos envían la API key con autenticación Bearer y leen el mismo formato de respuesta.

curl "https://api.ecuadorapi.com/api/v1/cedulas/1700000000/nombres" \
  -H "Authorization: Bearer $ECUADORAPI_KEY"

const response = await fetch("https://api.ecuadorapi.com/api/v1/cedulas/1700000000/nombres", {
  headers: {
    Authorization: "Bearer " + process.env.ECUADORAPI_KEY,
  },
})
const { data } = await response.json()

import os
import requests

response = requests.get(
    "https://api.ecuadorapi.com/api/v1/cedulas/1700000000/nombres",
    headers={"Authorization": f"Bearer {os.environ['ECUADORAPI_KEY']}"},
)
data = response.json()["data"]

$ch = curl_init("https://api.ecuadorapi.com/api/v1/cedulas/1700000000/nombres");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("ECUADORAPI_KEY")],
    CURLOPT_RETURNTRANSFER => true,
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
$data = $body["data"];

{
  "data": {
    "id": "1700000000",
    "full_name": "PÉREZ GARCÍA JUAN ANDRÉS",
    "first_name": "JUAN ANDRÉS",
    "last_name": "PÉREZ GARCÍA"
  },
  "error": null,
  "message": null
}

Cómo interpretar la respuesta JSON

• data.id contiene la cédula que enviaste.
• data.full_name devuelve nombres y apellidos completos cuando están disponibles; tu integración debe tolerar null.
• data.first_name y data.last_name permiten llenar campos separados sin dividir el texto por tu cuenta cuando están disponibles; también pueden ser null.
• error y message indican si la solicitud pudo completarse; en una respuesta exitosa llegan como null.

Errores que tu integración debe manejar

• 400: la cédula o la solicitud no tiene el formato esperado.
• 401 o 403: revisa la API key y el estado de verificación de la cuenta.
• 402: revisa el saldo y el mensaje incluido en la respuesta.
• 404: no se encontraron datos para el identificador enviado; no lo conviertas automáticamente en una afirmación sobre la persona.
• 429: espera el tiempo indicado en Retry-After antes de reintentar.
• 502 o 503: aplica espera progresiva y vuelve a intentar más tarde.

Checklist para producción

• Haz la solicitud desde tu backend y entrega al navegador solo la información necesaria.
• Configura un timeout y limita los reintentos para evitar solicitudes duplicadas.
• No guardes cédulas, respuestas completas ni API keys en logs innecesarios.
• Revisa el precio vigente en la ficha del endpoint; los errores y las consultas sin resultados no descuentan saldo.