Desarrolladores
Verificación de identidad
Tu servidor crea una verificación, la persona la completa en un enlace nuestro y tú lees la decisión. No recibes fotos ni datos biométricos, y no necesitas cámara, permisos ni librerías de reconocimiento en tu app.
Guía rápida
- Crea tu cuenta y activa el producto: se abre el ambiente de pruebas.
- En Llaves, saca una llave de pruebas. Empieza con
idl_prueba_. - Crea una verificación desde tu servidor:
curl https://api.idelia.cl/v1/identidad/verificaciones \
-H "x-api-key: $IDELIA_LLAVE" \
-H "content-type: application/json" \
-d '{
"referencia": "cliente-42",
"pasos": ["documento", "rostro"],
"urlRetorno": "https://tu-sitio.cl/verificado"
}'{
"id": "ver_8ZqT1nK4w0c2LxYp",
"ambiente": "prueba",
"estado": "creada",
"referencia": "cliente-42",
"pasos": ["documento", "rostro"],
"url": "https://idelia.cl/verificar/vft_…",
"venceEn": "2026-11-18T15:00:00.000Z",
"resultado": null,
"comprobante": null
}- Manda a la persona a
url. En pruebas, la pantalla te deja elegir el resultado a simular. - Lee el resultado con
GET /v1/identidad/verificaciones/{id}, o espera el webhook.
{
"id": "ver_8ZqT1nK4w0c2LxYp",
"estado": "aprobada",
"referencia": "cliente-42",
"resultado": {
"decision": "aprobada",
"controles": { "documento": "ok", "rostro": "ok", "pruebaDeVida": "ok", "chip": "no_realizado" },
"documento": {
"pais": "CL", "tipo": "cedula", "numero": "11111111-1",
"nombres": "Persona", "apellidos": "De Prueba",
"fechaNacimiento": "1990-01-01", "venceEn": "2035-01-01"
}
},
"comprobante": "eyJhbGciOiJFZERTQSIs…"
}Llaves y ambientes
La llave va en la cabecera x-api-key, siempre desde tu servidor. Nunca la pongas en una página ni dentro de una app: quien la tenga puede leer los resultados de tu organización.
| Ambiente | Llave | Qué hace |
|---|---|---|
| Pruebas | idl_prueba_… | Resultados simulados con datos de fantasía. Sin costo y sin límite de tiempo. |
| Producción | idl_prod_… | Personas reales. Se habilita a pedido desde la consola. |
Los ambientes no se mezclan: una llave de pruebas no ve verificaciones de producción, ni al revés. El código de tu integración es el mismo; solo cambia la llave.
Referencia de la API
Base: https://api.idelia.cl. Todo es JSON.
POST /v1/identidad/verificaciones
Crea una verificación. El enlace vence en una hora.
| Campo | Tipo | Descripción |
|---|---|---|
tipo | texto | onboarding (por defecto) o validacion. |
base | texto | Solo en una validación: el id del onboarding aprobado contra el que se compara. |
empresa | texto | RUT de la empresa por la que se hace. Solo importa si tu cuenta usa crédito individual. |
referencia | texto | Tu identificador de la persona. Vuelve en el resultado, el comprobante y el webhook. |
pasos | lista | documento, rostro, chip. Por defecto documento y rostro. El documento es obligatorio. |
pais | texto | País del documento, ISO de dos letras (CL). |
urlRetorno | texto | A dónde vuelve la persona al terminar. Acepta https y esquemas de app (miapp://). |
metadatos | objeto | Lo que quieras guardar junto a la verificación (hasta 2.000 caracteres). |
GET /v1/identidad/verificaciones/{id}
Estado, resultado y comprobante. Es la fuente de verdad: confirma siempre acá antes de dar por verificada a una persona.
GET /v1/identidad/verificaciones
Las más recientes primero. Filtros: referencia, limite (hasta 100) y antesDe (fecha ISO, para paginar).
POST /v1/identidad/verificaciones/{id}/cancelar
Cierra una verificación que no terminó. El enlace deja de servir.
Estados
creada | Nadie abrió el enlace todavía. |
en_curso | La persona abrió el enlace. |
aprobada | Todos los controles pedidos pasaron. |
rechazada | Algún control falló. Mira resultado.motivo. |
revision | No se pudo decidir sola; la decide una persona y te llega otro aviso. |
vencida · cancelada | No terminó. Crea otra. |
Onboarding y validación
Son dos operaciones distintas, con precios distintos:
| Tipo | Para qué | Qué pide a la persona |
|---|---|---|
onboarding | Conocer a una persona por primera vez. | Documento, rostro con prueba de vida y, si lo pides, el chip. |
validacion | Confirmar que quien está ahora es la misma persona de un onboarding anterior: entrar a la cuenta, autorizar una operación. | Solo el rostro, con prueba de vida. |
curl https://api.idelia.cl/v1/identidad/verificaciones \
-H "x-api-key: $IDELIA_LLAVE" \
-H "content-type: application/json" \
-d '{ "tipo": "validacion", "base": "ver_8ZqT1nK4w0c2LxYp", "referencia": "cliente-42" }'La base tiene que ser un onboarding aprobada de tu organización, en el mismo ambiente. El resultado de una validación no trae datos de documento.
Saldo y prepago
Tu cuenta tiene un saldo en pesos. En producción, cada uso descuenta su precio al crearse: un onboarding $690 y una validación $120 (netos). Si la verificación no termina —la cancelas o el enlace vence— el cobro vuelve solo. Una verificación rechazada sí se cobra: el trabajo se hizo. El ambiente de pruebas no consume saldo.
curl https://api.idelia.cl/v1/identidad/saldo -H "x-api-key: $IDELIA_LLAVE"
{ "saldo": 482300, "modo": "comun", "nivel": "negocio", "precios": { "onboarding": 621, "validacion": 108 } }Sin saldo, crear una verificación responde 402 saldo_insuficiente y no crea nada. Recargas desde $10.000 en la consola. El precio es fijo; si tu cuenta tiene un convenio de volumen, precios en la respuesta de saldo trae los tuyos.
Integradores: una cuenta, varias empresas
Si trabajas por cuenta de varias empresas, inscríbelas en la consola y elige cómo gastan: en común (un solo saldo) o individual (cada empresa, lo que le asignes). En modo individual indica la empresa en cada llamada con empresa (su RUT); sin ese campo, el uso sale del saldo general. Puedes sacar llaves limitadas a las empresas que elijas.
Resultado y motivos
resultado.controles dice qué se comprobó: cada uno vale ok, fallo o no_realizado. Cuando la decisión no es aprobada, motivo trae un código estable que puedes traducir a tu idioma y a tu tono:
documento_ilegible | No se pudo leer el documento. |
documento_vencido | El documento está vencido. |
documento_no_admitido | Ese tipo de documento o país no se admite. |
rostro_no_coincide | El rostro no corresponde al del documento. |
prueba_de_vida_fallida | No se confirmó que hubiera una persona presente. |
chip_no_verificado | El chip no se pudo leer o no es auténtico. |
requiere_revision | Quedó para revisión manual. |
Los datos del documento son personales. Guarda solo los que tu proceso necesite, y por el tiempo que los necesite.
Comprobante firmado
Cada verificación terminada trae un comprobante: un JWS firmado por IDELIA (EdDSA) que prueba qué se decidió y cuándo. Puedes guardarlo y mostrárselo a un auditor o a un banco, que lo valida con nuestra llave pública sin tener que confiar en tu base de datos.
{
"iss": "https://api.idelia.cl",
"sub": "ver_8ZqT1nK4w0c2LxYp",
"aud": "<id de tu organización>",
"iat": 1795000000,
"ambiente": "produccion",
"referencia": "cliente-42",
"decision": "aprobada",
"motivo": null,
"controles": { "documento": "ok", "rostro": "ok", "pruebaDeVida": "ok", "chip": "ok" },
"documento_huella": "9f2c…"
}No lleva el nombre ni el número de documento de la persona: lleva una huella. Llave pública: https://api.idelia.cl/v1/identidad/.well-known/jwks.json.
Webhooks
Configura la dirección en la consola. Te avisamos cuando una verificación termina; si tu servidor no responde 2xx, reintentamos durante un día con espera creciente.
POST https://tu-sitio.cl/idelia/webhook
idelia-firma: t=1795000000,v1=5b1c…
{
"id": "evt_1042",
"tipo": "identidad.verificacion.terminada",
"ambiente": "prueba",
"datos": { "id": "ver_8ZqT1nK4w0c2LxYp", "estado": "aprobada", "referencia": "cliente-42" }
}La cabecera idelia-firma es t=<segundos>,v1=<hmac>, con HMAC-SHA256 del texto <t>.<cuerpo> y el secreto que te mostramos al configurar el webhook. Valídala siempre y descarta las entregas de más de cinco minutos.
import { verificarWebhook } from '@idelia/identidad';
// Usa el cuerpo CRUDO, tal como llegó: si lo lees como JSON y lo vuelves a
// escribir, la firma deja de coincidir.
app.post('/idelia/webhook', express.text({ type: '*/*' }), async (req, res) => {
const evento = await verificarWebhook(
req.body,
req.headers['idelia-firma'],
process.env.IDELIA_WEBHOOK_SECRETO,
);
// evento.datos = { id, estado, referencia }
const v = await idelia.leerVerificacion(evento.datos.id);
res.sendStatus(200);
});SDK
Para JavaScript y TypeScript, sin dependencias. Node 20 o superior en el servidor; cualquier navegador actual en la página.
npm install ./idelia-identidad-0.3.1.tgzimport { Idelia } from '@idelia/identidad';
const idelia = new Idelia({ llave: process.env.IDELIA_LLAVE });
// 1. Crea la verificación y manda a la persona a v.url
const v = await idelia.crearVerificacion({
referencia: 'cliente-42',
urlRetorno: 'https://tu-sitio.cl/verificado',
});
// 2. Cuando vuelva (o cuando llegue el webhook), lee el resultado
const final = await idelia.leerVerificacion(v.id);
if (final.estado === 'aprobada') {
const comprobante = await idelia.verificarComprobante(final.comprobante);
// guarda final.comprobante: es tu prueba firmada
}import { abrirVerificacion } from '@idelia/identidad/navegador';
// 'url' viene de tu servidor. Modos: 'ventana' (por defecto), 'marco' o 'redirigir'.
const r = await abrirVerificacion(url);
if (r) {
// r.estado es un aviso para tu interfaz. Confirma en tu servidor:
await fetch('/api/verificacion/' + r.id);
}En una app móvil, abre url en el navegador del sistema o en una vista web y usa un esquema propio en urlRetorno para volver a tu app.
Errores
Las respuestas de error traen un código estable en error.
| HTTP | Código | Qué pasó |
|---|---|---|
| 401 | api_key_invalida | La llave no existe, fue revocada o la organización está suspendida. |
| 403 | llave_sin_alcance | La llave no incluye este producto. |
| 400 | paso_desconocido · falta_paso_documento · pais_invalido · url_retorno_invalida | Revisa el pedido. |
| 402 | saldo_insuficiente | No alcanza el saldo. Recarga en la consola. |
| 409 | base_invalida | La base no existe, no es un onboarding o no está aprobada. |
| 404 | verificacion_no_encontrada | No existe en este ambiente o no es de tu organización. |
| 503 | motor_no_disponible | Producción aún no está habilitada para verificar. |