Documentación · v1

API del Padrón Electoral

Consulta y validación de cédulas dominicanas contra el padrón. Todas las respuestas son JSON.

URL basehttps://adminservicesrd.online/v1

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
Guarda la llave en tu servidor. No la pongas en JavaScript del navegador, apps móviles ni repositorios: cualquiera que la vea puede consumir tu cuota. Llama a la API desde tu backend y entrega a tu frontend solo lo que necesite.

2. Endpoints

MétodoRutaPermisoDescripción
POST/cedula/consultarconsultarPerfil completo del elector: nombre, sexo, fecha de nacimiento, provincia, municipio, recinto y colegio.
POST/cedula/validarvalidarSolo indica si la cédula existe en el padrón y devuelve el nombre.
GET/catalogos/provinciascatalogosListado de provincias.
GET/catalogos/provincias/{id}/municipioscatalogosMunicipios 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"}'

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.

HTTPerrors.codigoQué significa
200—Correcto.
401sin_llaveNo enviaste el header X-API-Key.
401llave_invalidaLa llave no existe o fue regenerada.
403llave_deshabilitada / cliente_deshabilitadoTu acceso está suspendido. Contacta al administrador.
403llave_expiradaLa llave venció.
403sin_permisoTu llave no tiene permiso para ese endpoint.
403ip_no_permitidaTu servidor llama desde una IP no autorizada para esta llave.
403dominio_no_permitidoEl sitio web desde donde se llama no está autorizado.
404no_encontradoLa cédula no está en el padrón (solo /consultar).
422cedula_invalidaEl body no es válido. Revisa errors.
429—Límite por minuto o cuota diaria alcanzada. Respeta Retry-After.
503bd_no_disponibleEl padrón no responde en este momento. Reintenta en unos minutos.

7. Buenas prácticas

Prueba rápida

Verifica que tu llave funciona:

curl "https://adminservicesrd.online/v1/estado" -H "X-API-Key: TU_API_KEY"