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

  1. Crea tu cuenta y activa el producto: se abre el ambiente de pruebas.
  2. En Llaves, saca una llave de pruebas. Empieza con idl_prueba_.
  3. Crea una verificación desde tu servidor:
Pedido
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"
  }'
Respuesta · 201
{
  "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
}
  1. Manda a la persona a url. En pruebas, la pantalla te deja elegir el resultado a simular.
  2. Lee el resultado con GET /v1/identidad/verificaciones/{id}, o espera el webhook.
Respuesta · verificación aprobada
{
  "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.

AmbienteLlaveQué hace
Pruebasidl_prueba_…Resultados simulados con datos de fantasía. Sin costo y sin límite de tiempo.
Producciónidl_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.

CampoTipoDescripción
tipotextoonboarding (por defecto) o validacion.
basetextoSolo en una validación: el id del onboarding aprobado contra el que se compara.
empresatextoRUT de la empresa por la que se hace. Solo importa si tu cuenta usa crédito individual.
referenciatextoTu identificador de la persona. Vuelve en el resultado, el comprobante y el webhook.
pasoslistadocumento, rostro, chip. Por defecto documento y rostro. El documento es obligatorio.
paistextoPaís del documento, ISO de dos letras (CL).
urlRetornotextoA dónde vuelve la persona al terminar. Acepta https y esquemas de app (miapp://).
metadatosobjetoLo 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

creadaNadie abrió el enlace todavía.
en_cursoLa persona abrió el enlace.
aprobadaTodos los controles pedidos pasaron.
rechazadaAlgún control falló. Mira resultado.motivo.
revisionNo se pudo decidir sola; la decide una persona y te llega otro aviso.
vencida · canceladaNo terminó. Crea otra.

Onboarding y validación

Son dos operaciones distintas, con precios distintos:

TipoPara quéQué pide a la persona
onboardingConocer a una persona por primera vez.Documento, rostro con prueba de vida y, si lo pides, el chip.
validacionConfirmar 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.
Validar a alguien que ya hizo su onboarding
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.

Consultar el 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_ilegibleNo se pudo leer el documento.
documento_vencidoEl documento está vencido.
documento_no_admitidoEse tipo de documento o país no se admite.
rostro_no_coincideEl rostro no corresponde al del documento.
prueba_de_vida_fallidaNo se confirmó que hubiera una persona presente.
chip_no_verificadoEl chip no se pudo leer o no es auténtico.
requiere_revisionQuedó 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.

Contenido del comprobante
{
  "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.

Lo que recibes
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.

Con el SDK
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.

Descargar el SDK (0.3.1)

Instalar
npm install ./idelia-identidad-0.3.1.tgz
En tu servidor
import { 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
}
En tu página (opcional)
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.

HTTPCódigoQué pasó
401api_key_invalidaLa llave no existe, fue revocada o la organización está suspendida.
403llave_sin_alcanceLa llave no incluye este producto.
400paso_desconocido · falta_paso_documento · pais_invalido · url_retorno_invalidaRevisa el pedido.
402saldo_insuficienteNo alcanza el saldo. Recarga en la consola.
409base_invalidaLa base no existe, no es un onboarding o no está aprobada.
404verificacion_no_encontradaNo existe en este ambiente o no es de tu organización.
503motor_no_disponibleProducción aún no está habilitada para verificar.