curpify
Docs/Referencia de API
v1.0.0 · REST API

Referencia de API

Endpoints para validar CURP, cédulas profesionales SEP y gestionar jobs asincrónicos. Todos los endpoints requieren una API Key.

API Key

Header x-api-key en cada solicitud

REST

JSON sobre HTTPS, respuestas consistentes

TLS

Solo HTTPS — sin excepciones

Autenticación: Todos los endpoints requieren el header x-api-key con una clave que empiece con ck_. Obtén la tuya en el dashboard.

Inicio rápido

bash
curl -X POST https://api.curpify.mx/v1/curp/validate \
  -H "x-api-key: ck_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"curp": "LOOA531113HTCPBN07"}'

Formato de respuesta

Todas las respuestas exitosas usan el mismo envoltorio. meta.source indica si el resultado vino de caché o del proveedor oficial — útil para monitoreo de latencia.

json
{
  "data": { ... },
  "meta": {
    "source": "cache",   // "cache" | "provider"
    "jobId": null        // string cuando es asíncrono, null en síncrono
  }
}

Headers de control

Cache-Control: no-cache

Cuándo usarlo: Necesitas el estado actual del registro en RENAPO o SEP, no el último resultado guardado.

Sin este header la respuesta puede venir de caché (Redis 30 días → Postgres → proveedor).

x-async: true

Cuándo usarlo: Quieres disparar la consulta sin esperar el resultado (útil en workers, colas, o cuando el timeout de 30 s es un problema).

El servidor responde 202 + jobId de inmediato. Sin este header el endpoint bloquea hasta recibir el resultado.

Endpoints asíncronos

Envía x-async: true en cualquier endpoint para recibir un jobId de inmediato sin esperar el resultado. Consulta GET /v1/jobs/{id} hasta que el estado sea completed o failed.

javascript
// 1. Inicia el job
const { jobId } = await fetch('https://api.curpify.mx/v1/curp/download', {
  method: 'POST',
  headers: { 'x-api-key': 'ck_live_...', 'Content-Type': 'application/json' },
  body: JSON.stringify({ curp: 'HEGG560427MVZRRL04' }),
}).then(r => r.json());

// 2. Consulta hasta completarse
async function waitForJob(id) {
  while (true) {
    const job = await fetch(`https://api.curpify.mx/v1/jobs/${id}`, {
      headers: { 'x-api-key': 'ck_live_...' },
    }).then(r => r.json());
    if (job.status === 'completed') return job.result;
    if (job.status === 'failed') throw new Error(job.failedReason);
    await new Promise(r => setTimeout(r, 1000));
  }
}

const result = await waitForJob(jobId);
// result.pdf → base64 del PDF oficial

Conceptos clave

CURP

Clave Única de Registro de Población — 18 caracteres que identifican a cada ciudadano mexicano ante RENAPO.

RENAPO

Registro Nacional de Población — autoridad oficial que emite y valida las CURPs.

Cédula profesional

Número de 7-8 dígitos emitido por la SEP que acredita un título universitario ante el Estado.

Job asíncrono

Operación que tarda más de un request (ej. descargar un PDF). La API devuelve un jobId y debes hacer polling para obtener el resultado.

Endpoints