1. Autenticación
Cada request debe incluir tu API key en el header X-API-Key (también se acepta Authorization: Bearer <key>).
X-API-Key: jce_xxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
X-Sistema: NombreDeTuSistema # opcional, identifica tu sistema en los reportes
2. Endpoints
| Método | Ruta | Permiso | Descripción |
|---|---|---|---|
| POST | /cedula/consultar | consultar | Perfil completo del elector: nombre, sexo, fecha de nacimiento, provincia, municipio, recinto y colegio. |
| POST | /cedula/validar | validar | Solo indica si la cédula existe en el padrón y devuelve el nombre. |
| GET | /catalogos/provincias | catalogos | Listado de provincias. |
| GET | /catalogos/provincias/{id}/municipios | catalogos | Municipios de una provincia. |
| GET | /estado | — | Verifica tu llave: permisos, límites y consumo de hoy. |
Tu llave puede no tener todos los permisos; consulta GET /estado para ver cuáles tienes.
3. Consultar una cédula
POST https://adminservicesrd.online/v1/cedula/consultar
Body
{ "cedula": "00112345678" }
Acepta la cédula con o sin guiones (001-1234567-8). Debe tener 11 dígitos.
curl -X POST "https://adminservicesrd.online/v1/cedula/consultar" \
-H "X-API-Key: TU_API_KEY" \
-H "Content-Type: application/json" \
-d '{"cedula":"00112345678"}'
$ch = curl_init('https://adminservicesrd.online/v1/cedula/consultar');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('ADMINSERVICES_API_KEY'),
'Content-Type: application/json',
'X-Sistema: MiSistema',
],
CURLOPT_POSTFIELDS => json_encode(['cedula' => '00112345678']),
]);
$respuesta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status === 200) {
echo $respuesta['data']['nombre_completo'];
} elseif ($status === 404) {
echo 'No está en el padrón';
} else {
echo 'Error: ' . $respuesta['message'];
}
// Node 18+ (en tu backend, nunca en el navegador)
const res = await fetch('https://adminservicesrd.online/v1/cedula/consultar', {
method: 'POST',
headers: {
'X-API-Key': process.env.ADMINSERVICES_API_KEY,
'Content-Type': 'application/json',
'X-Sistema': 'MiSistema',
},
body: JSON.stringify({ cedula: '00112345678' }),
});
const json = await res.json();
if (res.ok) console.log(json.data.nombre_completo);
else if (res.status === 404) console.log('No está en el padrón');
else console.error(json.message);
// padron.ts — cliente tipado (Node 18+ / Deno / Bun, en tu backend)
export interface Recinto {
id: number | null;
codigo: string | null;
nombre: string | null;
direccion: string | null;
}
export interface Elector {
cedula: string;
nombre_completo: string;
nombres: string;
apellidos: string;
sexo: 'M' | 'F' | null;
fecha_nacimiento: string | null; // "YYYY-MM-DD"
edad: number | null;
provincia_id: number | null;
provincia: string | null;
municipio_id: number | null;
municipio: string | null;
region: string | null;
recinto: Recinto;
colegio: { codigo: string | null; nombre: string | null };
inscrito_exterior: boolean | null;
}
interface Respuesta<T> {
status: 'success' | 'error';
data: T | null;
message: string;
errors: { codigo?: string; [campo: string]: string | undefined };
}
export class PadronError extends Error {
constructor(public status: number, public codigo: string | undefined, mensaje: string) {
super(mensaje);
}
}
const BASE = 'https://adminservicesrd.online/v1';
async function llamar<T>(ruta: string, body: unknown): Promise<T | null> {
const res = await fetch(`${BASE}${ruta}`, {
method: 'POST',
headers: {
'X-API-Key': process.env.ADMINSERVICES_API_KEY ?? '',
'Content-Type': 'application/json',
'X-Sistema': 'MiSistema',
},
body: JSON.stringify(body),
signal: AbortSignal.timeout(15_000),
});
const json = (await res.json()) as Respuesta<T>;
if (res.status === 404) return null; // no está en el padrón
if (!res.ok) throw new PadronError(res.status, json.errors?.codigo, json.message);
return json.data;
}
/** Perfil completo; null si la cédula no está en el padrón. */
export const consultarCedula = (cedula: string) =>
llamar<Elector>('/cedula/consultar', { cedula });
/** Solo si existe y su nombre. */
export const validarCedula = (cedula: string) =>
llamar<{ existe: boolean; cedula: string; nombre_completo: string | null }>('/cedula/validar', { cedula });
// Uso
try {
const elector = await consultarCedula('001-1234567-8');
console.log(elector ? `${elector.nombre_completo} — ${elector.provincia}` : 'No está en el padrón');
} catch (e) {
if (e instanceof PadronError && e.status === 429) console.warn('Límite alcanzado, reintenta más tarde');
else throw e;
}
// Desde el navegador: SOLO con una llave restringida a tu dominio (pídela así al administrador).
// Cualquiera puede ver una llave puesta en código del navegador; si puedes, llama desde tu backend.
async function consultarCedula(cedula) {
const res = await fetch('https://adminservicesrd.online/v1/cedula/consultar', {
method: 'POST',
headers: {
'X-API-Key': 'TU_API_KEY_RESTRINGIDA_A_TU_DOMINIO',
'Content-Type': 'application/json',
'X-Sistema': 'MiSitioWeb',
},
body: JSON.stringify({ cedula }),
});
const json = await res.json();
if (res.status === 404) return null;
if (!res.ok) throw new Error(json.message);
return json.data;
}
// Ejemplo: autocompletar un formulario al salir del campo cédula
document.querySelector('#cedula').addEventListener('change', async (e) => {
try {
const elector = await consultarCedula(e.target.value);
document.querySelector('#nombre').value = elector ? elector.nombre_completo : '';
if (!elector) alert('La cédula no está en el padrón');
} catch (err) {
console.error(err.message);
}
});
import os, requests
r = requests.post(
"https://adminservicesrd.online/v1/cedula/consultar",
headers={"X-API-Key": os.environ["ADMINSERVICES_API_KEY"], "X-Sistema": "MiSistema"},
json={"cedula": "00112345678"},
timeout=15,
)
if r.status_code == 200:
print(r.json()["data"]["nombre_completo"])
elif r.status_code == 404:
print("No está en el padrón")
else:
print("Error:", r.json()["message"])
using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-API-Key", Environment.GetEnvironmentVariable("ADMINSERVICES_API_KEY"));
http.DefaultRequestHeaders.Add("X-Sistema", "MiSistema");
var res = await http.PostAsJsonAsync("https://adminservicesrd.online/v1/cedula/consultar", new { cedula = "00112345678" });
var json = await res.Content.ReadAsStringAsync();
Console.WriteLine($"{(int)res.StatusCode}: {json}");
Respuesta 200
{
"status": "success",
"data": {
"cedula": "00112345678",
"nombre_completo": "Juan Carlos Pérez Rodríguez",
"nombres": "Juan Carlos",
"apellidos": "Pérez Rodríguez",
"sexo": "M",
"fecha_nacimiento": "1985-04-12",
"edad": 41,
"provincia_id": 1,
"provincia": "Distrito Nacional",
"municipio_id": 1,
"municipio": "Santo Domingo de Guzmán",
"region": "Ozama",
"recinto": { "id": 1520, "codigo": "00125", "nombre": "Escuela Básica ...", "direccion": "C/ ..." },
"colegio": { "codigo": "0662A", "nombre": null },
"inscrito_exterior": false
},
"message": "Elector encontrado.",
"errors": []
}
Los campos que el padrón no trae vienen en null; no se inventan datos. sexo es "M", "F" o null.
Respuesta 404 (no está en el padrón)
{ "status": "error", "data": null, "message": "Cédula no encontrada en el padrón.", "errors": { "codigo": "no_encontrado" } }
4. Validar una cédula
POST https://adminservicesrd.online/v1/cedula/validar
Más liviano que consultar. Siempre responde 200 con existe en true o false.
Body
{ "cedula": "001-1234567-8" }Respuesta 200
{
"status": "success",
"data": {
"existe": true,
"cedula": "00112345678",
"nombre_completo": "Juan Carlos Pérez Rodríguez"
},
"message": "Cédula encontrada en el padrón.",
"errors": []
}5. Límites de uso
Cada llave tiene un máximo de requests por minuto y de consultas por día. Cada respuesta incluye tu consumo:
X-RateLimit-Limit: 60 # requests por minuto X-RateLimit-Remaining: 57 X-Quota-Limit: 5000 # consultas por día X-Quota-Remaining: 4870
Al pasarte recibes 429 con el header Retry-After (segundos). Espera ese tiempo antes de reintentar; no reintentes en bucle.
6. Códigos de respuesta
Los errores siempre traen message legible y errors.codigo para tu lógica.
| HTTP | errors.codigo | Qué significa |
|---|---|---|
| 200 | — | Correcto. |
| 401 | sin_llave | No enviaste el header X-API-Key. |
| 401 | llave_invalida | La llave no existe o fue regenerada. |
| 403 | llave_deshabilitada / cliente_deshabilitado | Tu acceso está suspendido. Contacta al administrador. |
| 403 | llave_expirada | La llave venció. |
| 403 | sin_permiso | Tu llave no tiene permiso para ese endpoint. |
| 403 | ip_no_permitida | Tu servidor llama desde una IP no autorizada para esta llave. |
| 403 | dominio_no_permitido | El sitio web desde donde se llama no está autorizado. |
| 404 | no_encontrado | La cédula no está en el padrón (solo /consultar). |
| 422 | cedula_invalida | El body no es válido. Revisa errors. |
| 429 | — | Límite por minuto o cuota diaria alcanzada. Respeta Retry-After. |
| 503 | bd_no_disponible | El padrón no responde en este momento. Reintenta en unos minutos. |
7. Buenas prácticas
- Guarda la llave en una variable de entorno de tu servidor, nunca en el código fuente.
- Envía
X-Sistemacon el nombre de tu aplicación: ayuda a diagnosticar problemas. - Guarda en tu propia base de datos el resultado de una cédula ya consultada en lugar de repetir la consulta.
- Usa
/validarcuando solo necesites saber si la cédula existe. - Pon un timeout de 10–15 segundos y maneja el
503mostrando un mensaje amable. - Toda consulta queda registrada (llave, cédula, IP, sitio y fecha) para auditoría.
Prueba rápida
Verifica que tu llave funciona:
curl "https://adminservicesrd.online/v1/estado" -H "X-API-Key: TU_API_KEY"