Saltar al contenido
Klevy.

La API de Klevy

Klevy ejecuta operaciones contra portales y organismos chilenos, medido por uso. Hay una sola primitiva, el run, y todo lo demás —widget, catálogo, webhooks— es empaque sobre ella. 

run = (flujo, credencial, parámetros) → resultado normalizado + documento + evento de uso

Las dos puertas de entrada

Cuál usar lo decide una sola pregunta: ¿hace falta la clave del titular? Ambas caen en el mismo núcleo de ejecución, así que el resultado es idéntico.

Servidor a servidor

Cuando el flujo sólo necesita un RUT, o ya tienes un credential_ref de una captura anterior. Llamas a POST /v1/runs y listo. 

curl -X POST https://api.klevy.cl/v1/runs \
  -H 'authorization: Bearer sk_live_tu_api_key' \
  -H 'idempotency-key: pedido-4821' \
  -H 'content-type: application/json' \
  -d '{
    "flow": "registro_civil.anotaciones_vehiculo",
    "params": { "patente": "KXJT52" },
    "wait_ms": 10000
  }'

Responde 200 si alcanzó a terminar dentro de wait_ms y 202 si sigue en la cola — en ese caso el resultado llega por webhook.

Widget

Cuando el titular tiene que entregar su clave. Abres una sesión, llevas a la persona al widget_url, y el widget hace una sola cosa: convertir la clave en un credential_ref. Una captura, N runs. 

curl -X POST https://api.klevy.cl/v1/sessions \
  -H 'authorization: Bearer sk_live_tu_api_key' \
  -H 'content-type: application/json' \
  -d '{
    "flows": [
      { "flow": "sii.rcv_resumen",
        "params": { "rut": "76192083-9", "periodo": "202607", "operacion": "compra" } },
      { "flow": "sii.rcv_detalle",
        "params": { "rut": "76192083-9", "periodo": "202607", "operacion": "compra" } }
    ],
    "subject_rut": "76192083-9",
    "credential_policy": "stored",
    "webhook_url": "https://tu-sistema.cl/webhooks/klevy"
  }'

La credencial que exigen los flujos decide qué pantalla se abre: los de CT abren el widget de empresas (RUT de la empresa + Clave Tributaria del SII), los de CU el de personas (ClaveÚnica).

Las tres reglas que sostienen el diseño

  1. La credencial nunca circula. Sólo circula el credential_ref. El secreto se descifra en el instante del login y vive en memoria hasta que termina el run.
  2. La cola es transporte, no estado. La fuente de verdad es la base de datos; un run no se pierde aunque se vacíe la cola.
  3. Un run fallido no se factura. El evento de uso se escribe en la misma transacción que marca el run como exitoso, y un índice único impide cobrarlo dos veces.

Ambientes

No hay dos infraestructuras: el ambiente es una propiedad de la API key. sk_test_… ejecuta con datos de prueba y no toca ningún portal; sk_live_… ejecuta de verdad. El contrato de respuesta es el mismo, así que puedes construir tu integración completa contra el sandbox.

Por dónde seguir