Developers · API REST + SSE
API de verificación de cédula en Colombia. cURL en 30 segundos.
Endpoint POST /v1/verificar que recibe una cédula colombiana y devuelve, en menos de 10 segundos, el resultado consolidado de 9 fuentes oficiales: Registraduría, Policía Nacional, Procuraduría, SIRI, INPEC, Rama Judicial, SECOP, listas OFAC/ONU/UE/OFSI y PEPs. Autenticación con X-Api-Key, streaming SSE, webhooks firmados HMAC.
- Llaves sk_live + sk_test
- SSE en tiempo real
- Webhooks HMAC
- Postman incluido
Referencia técnica
POST /v1/verificar
Endpoint principal de la API de Simple Verify. Recibe un número de cédula colombiana y devuelve la verificación consolidada.
Request
curl -X POST https://api.estansimple.com/v1/verificar \
-H "X-Api-Key: sk_live_TUAPIKEY" \
-H "Content-Type: application/json" \
-d '{"documento": "1234567890"}'Response (200 OK)
{
"exitoso": true,
"data": {
"nombreCompleto": "CARLOS ANDRÉS GÓMEZ",
"documento": "1234567890",
"nivelRiesgo": 0,
"alertas": [],
"fuentes": {
"registraduria": { "estado": "vigente", "alerta": false },
"policia": { "estado": "sin_antecedentes","alerta": false },
"procuraduria": { "estado": "sin_sanciones", "alerta": false },
"rama_judicial": { "estado": "sin_procesos", "alerta": false },
"siri": { "estado": "sin_inhabilidades","alerta": false },
"inpec": { "estado": "sin_registros", "alerta": false },
"secop": { "estado": "consultado", "alerta": false },
"listas_ofac": { "estado": "sin_coincidencias","alerta": false },
"peps": { "estado": "no_pep", "alerta": false }
}
}
}Esquema
Parámetros y campos de respuesta
Parámetros del request
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
documento | string | Sí | Número de cédula colombiana (sin puntos ni guiones). |
callback_url | string | No | URL para webhook al completar (Pro+). |
Campos clave de la respuesta
| Campo | Tipo | Descripción |
|---|---|---|
exitoso | boolean | Indica si la verificación se completó. |
data.nombreCompleto | string | Nombre completo según la Registraduría. |
data.nivelRiesgo | integer (0–3) | Semáforo: 0=sin riesgo, 1=bajo, 2=medio, 3=alto. |
data.alertas | array | Lista de alertas activas (OFAC, antecedentes, etc.). |
data.fuentes | object | Detalle por cada una de las 9 fuentes oficiales. |
Autenticación
Llaves sk_live_ y sk_test_
Cada cuenta recibe dos pares de llaves: una para producción (sk_live_) y otra para sandbox (sk_test_). Las llaves de test no consumen tu cuota mensual y se usan contra datos sintéticos.
Header X-Api-Key
Envía tu llave en el header HTTP X-Api-Key. No la pongas en query strings.
Rotación de llaves
Rotas cualquier llave desde tu panel sin downtime. Las llaves expiradas devuelven 401 explícito.
Rate limiting documentado
Headers X-RateLimit-Remaining y X-RateLimit-Reset en cada respuesta.
HMAC en webhooks
Webhooks firmados con HMAC-SHA256. Header X-Signature con tu secret. Reintentos exponenciales.
Preguntas frecuentes
API de verificación de cédula
¿Qué es una API de verificación de cédula en Colombia?
Es un endpoint HTTP que recibe un número de cédula y devuelve, en una sola respuesta JSON, el estado de esa cédula en múltiples fuentes oficiales (Registraduría, Policía Nacional, Procuraduría, INPEC, Rama Judicial, etc.). Permite integrar verificación de identidad directamente en el flujo de onboarding o backoffice de una empresa, sin que el usuario tenga que abrir un portal externo.
¿Cómo autentico mis llamadas a la API de Simple Verify?
Las llamadas se autentican con el header HTTP "X-Api-Key" usando una de tus llaves: "sk_live_" para producción o "sk_test_" para sandbox. Las llaves se generan desde tu panel en /settings/api. Cada llave puede revocarse de forma independiente.
¿La API soporta streaming en tiempo real?
Sí. Además del endpoint POST tradicional, exponemos un endpoint Server-Sent Events (SSE) que emite el resultado de cada fuente a medida que llega. Esto es útil para UIs donde el usuario ve la verificación progresar en vivo, sin esperar a que las 9 fuentes terminen.
¿Qué rate limits tiene la API?
El plan Starter permite 3 requests por segundo (RPS). El plan Pro permite 10 RPS. El plan Enterprise no tiene límite por defecto. Si necesitas más capacidad puntual, comprar packs express está disponible desde tu cuenta.
¿Hay snippets de código disponibles?
Sí. La documentación incluye snippets listos para cURL, JavaScript (fetch), Python (requests), Node.js, Go y .NET. También entregamos una colección de Postman y otra de Insomnia para que puedas probar la API sin escribir código.
¿La API entrega webhooks cuando hay alertas?
Sí, en los planes Pro y Enterprise. Cuando una verificación detecta una alerta crítica (por ejemplo: coincidencia OFAC, antecedente activo, persona expuesta políticamente), enviamos un POST a tu webhook firmado con HMAC-SHA256. El evento principal es "alert.detected"; también soportamos "report.completed" para procesamiento asíncrono.
¿La API cumple con la Ley 1581 de habeas data en Colombia?
Sí. Cumplimos con la Ley 1581 de 2012 y la normativa de la SIC. La responsabilidad de obtener autorización del titular del dato recae en quien realiza la consulta. Nuestros Términos de Uso detallan el modelo de corresponsabilidad.
Obtén tu API key en 2 minutos.
Empieza con llaves de test gratis. Primera consulta de producción gratis al confirmar el correo.