{"openapi":"3.0.3","info":{"title":"Klevy API","version":"0.1.0","description":"Ejecutor de operaciones contra portales y organismos chilenos, medido por uso. La primitiva única es el run: (flujo, credencial, parámetros) → resultado normalizado."},"servers":[{"url":"https://api.klevy.cl"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key secreta del integrador: `sk_live_…` / `sk_test_…`."},"sessionToken":{"type":"http","scheme":"bearer","description":"Token efímero de sesión del widget: `pk_sess_…`."}},"schemas":{"CreateRunRequest":{"type":"object","properties":{"flow":{"type":"string"},"params":{"default":{},"type":"object","additionalProperties":{}},"credential_ref":{"type":"string"},"rut":{"type":"string"},"execution_token":{"type":"string"},"wait_ms":{"type":"integer","minimum":0,"maximum":60000},"metadata":{"type":"object","additionalProperties":{"type":"string"}}},"required":["flow"],"additionalProperties":false},"RunResponse":{"type":"object","properties":{"run_id":{"type":"string"},"flow":{"type":"string"},"flow_version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["queued","running","awaiting_confirmation","succeeded","failed","expired","cancelled"]},"data":{"nullable":true},"document":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["pdf","json","screenshot","html"]},"download_url":{"type":"string"},"expires_at":{"type":"string"},"sha256":{"type":"string"},"bytes":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["type","download_url","expires_at","sha256","bytes"]},"documents":{"default":[],"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["pdf","json","screenshot","html"]},"download_url":{"type":"string"},"expires_at":{"type":"string"},"sha256":{"type":"string"},"bytes":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["type","download_url","expires_at","sha256","bytes"]}},"source_meta":{"nullable":true,"type":"object","properties":{"driver":{"type":"string"},"obtained_at":{"type":"string"},"portal":{"type":"string"},"portal_ref":{"type":"string"},"duration_ms":{"type":"integer","minimum":0,"maximum":9007199254740991},"attempts":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":9007199254740991}},"required":["driver","obtained_at","portal"]},"error":{"nullable":true,"type":"object","properties":{"code":{"type":"string","enum":["invalid_params","credential_invalid","credential_expired","portal_unavailable","portal_changed","not_found","rate_limited","flow_disabled","internal_error","authentication_error","permission_denied","conflict"]},"message":{"type":"string"}},"required":["code","message"]},"execution_token":{"type":"string"},"execution_token_expires_at":{"type":"string"},"session_id":{"nullable":true,"type":"string"},"parent_run_id":{"nullable":true,"type":"string"},"created_at":{"type":"string"},"finished_at":{"nullable":true,"type":"string"}},"required":["run_id","flow","flow_version","status","data","document","source_meta","error","created_at","finished_at"]},"ListRunsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"run_id":{"type":"string"},"flow":{"type":"string"},"flow_version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["queued","running","awaiting_confirmation","succeeded","failed","expired","cancelled"]},"data":{"nullable":true},"document":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["pdf","json","screenshot","html"]},"download_url":{"type":"string"},"expires_at":{"type":"string"},"sha256":{"type":"string"},"bytes":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["type","download_url","expires_at","sha256","bytes"]},"documents":{"default":[],"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["pdf","json","screenshot","html"]},"download_url":{"type":"string"},"expires_at":{"type":"string"},"sha256":{"type":"string"},"bytes":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["type","download_url","expires_at","sha256","bytes"]}},"source_meta":{"nullable":true,"type":"object","properties":{"driver":{"type":"string"},"obtained_at":{"type":"string"},"portal":{"type":"string"},"portal_ref":{"type":"string"},"duration_ms":{"type":"integer","minimum":0,"maximum":9007199254740991},"attempts":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":9007199254740991}},"required":["driver","obtained_at","portal"]},"error":{"nullable":true,"type":"object","properties":{"code":{"type":"string","enum":["invalid_params","credential_invalid","credential_expired","portal_unavailable","portal_changed","not_found","rate_limited","flow_disabled","internal_error","authentication_error","permission_denied","conflict"]},"message":{"type":"string"}},"required":["code","message"]},"execution_token":{"type":"string"},"execution_token_expires_at":{"type":"string"},"session_id":{"nullable":true,"type":"string"},"parent_run_id":{"nullable":true,"type":"string"},"created_at":{"type":"string"},"finished_at":{"nullable":true,"type":"string"}},"required":["run_id","flow","flow_version","status","data","document","source_meta","error","created_at","finished_at"]}},"next_cursor":{"nullable":true,"type":"string"}},"required":["data","next_cursor"]},"CreateSessionRequest":{"type":"object","properties":{"flows":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"flow":{"type":"string"},"params":{"default":{},"type":"object","additionalProperties":{}}},"required":["flow"]}},"subject_ref":{"type":"string","maxLength":200},"subject_rut":{"type":"string"},"redirect_uri":{"type":"string","format":"uri"},"webhook_url":{"type":"string","format":"uri"},"credential_policy":{"default":"one_time","type":"string","enum":["one_time","stored"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}}},"required":["flows"],"additionalProperties":false},"SessionResponse":{"type":"object","properties":{"session_id":{"type":"string"},"status":{"type":"string","enum":["created","credential_pending","verifying","authorized","in_progress","completed","failed","expired","revoked"]},"session_token":{"type":"string"},"widget_url":{"type":"string"},"webhook_secret":{"type":"string"},"credential_ref":{"nullable":true,"type":"string"},"verification":{"default":null,"nullable":true,"type":"object","properties":{"status":{"type":"string","enum":["no_iniciada","en_curso","verificada","rechazada","bloqueada","sin_clave_unica","no_concluyente"]},"message":{"default":null,"nullable":true,"type":"string"},"checked_at":{"default":null,"nullable":true,"type":"string"}},"required":["status"]},"runs":{"default":[],"type":"array","items":{"type":"object","properties":{"run_id":{"type":"string"},"flow":{"type":"string"},"flow_version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["queued","running","awaiting_confirmation","succeeded","failed","expired","cancelled"]},"data":{"nullable":true},"document":{"nullable":true,"type":"object","properties":{"type":{"type":"string","enum":["pdf","json","screenshot","html"]},"download_url":{"type":"string"},"expires_at":{"type":"string"},"sha256":{"type":"string"},"bytes":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["type","download_url","expires_at","sha256","bytes"]},"documents":{"default":[],"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["pdf","json","screenshot","html"]},"download_url":{"type":"string"},"expires_at":{"type":"string"},"sha256":{"type":"string"},"bytes":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["type","download_url","expires_at","sha256","bytes"]}},"source_meta":{"nullable":true,"type":"object","properties":{"driver":{"type":"string"},"obtained_at":{"type":"string"},"portal":{"type":"string"},"portal_ref":{"type":"string"},"duration_ms":{"type":"integer","minimum":0,"maximum":9007199254740991},"attempts":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":9007199254740991}},"required":["driver","obtained_at","portal"]},"error":{"nullable":true,"type":"object","properties":{"code":{"type":"string","enum":["invalid_params","credential_invalid","credential_expired","portal_unavailable","portal_changed","not_found","rate_limited","flow_disabled","internal_error","authentication_error","permission_denied","conflict"]},"message":{"type":"string"}},"required":["code","message"]},"execution_token":{"type":"string"},"execution_token_expires_at":{"type":"string"},"session_id":{"nullable":true,"type":"string"},"parent_run_id":{"nullable":true,"type":"string"},"created_at":{"type":"string"},"finished_at":{"nullable":true,"type":"string"}},"required":["run_id","flow","flow_version","status","data","document","source_meta","error","created_at","finished_at"]}},"expires_at":{"type":"string"},"created_at":{"type":"string"}},"required":["session_id","status","credential_ref","expires_at","created_at"]},"SessionContext":{"type":"object","properties":{"session_id":{"type":"string"},"status":{"type":"string","enum":["created","credential_pending","verifying","authorized","in_progress","completed","failed","expired","revoked"]},"tenant_name":{"type":"string"},"credential":{"type":"string","enum":["RUT","CU","CT","CD"]},"portals":{"type":"array","items":{"type":"string"}},"subject_rut":{"nullable":true,"type":"string"},"requested":{"type":"array","items":{"type":"object","properties":{"flow":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["C","T"]},"params":{"default":{},"type":"object","additionalProperties":{}}},"required":["flow","title","kind"]}},"credential_policy":{"type":"string","enum":["one_time","stored"]},"campos_titular":{"default":[],"type":"array","items":{"type":"string","enum":["numero_documento"]}},"redirect_uri":{"nullable":true,"type":"string"},"expires_at":{"type":"string"},"error":{"default":null,"nullable":true,"type":"object","properties":{"code":{"type":"string","enum":["invalid_params","credential_invalid","credential_expired","portal_unavailable","portal_changed","not_found","rate_limited","flow_disabled","internal_error","authentication_error","permission_denied","conflict"]},"flow":{"nullable":true,"type":"string"}},"required":["code","flow"]},"verification":{"default":null,"nullable":true,"type":"object","properties":{"status":{"type":"string","enum":["no_iniciada","en_curso","verificada","rechazada","bloqueada","sin_clave_unica","no_concluyente"]},"message":{"default":null,"nullable":true,"type":"string"},"checked_at":{"default":null,"nullable":true,"type":"string"}},"required":["status"]}},"required":["session_id","status","tenant_name","credential","portals","subject_rut","requested","credential_policy","redirect_uri","expires_at"]},"SubmitCredentialRequest":{"type":"object","properties":{"rut":{"type":"string"},"password":{"type":"string","minLength":1,"maxLength":200},"acepta_terminos":{"type":"boolean"},"terminos_version":{"type":"string","maxLength":40},"numero_documento":{"type":"string","pattern":"^[A-Z0-9]{6,15}$"},"label":{"type":"string","maxLength":120}},"required":["rut","password"],"additionalProperties":false},"CatalogResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["live","test"]},"flows":{"type":"array","items":{"type":"object","properties":{"flow":{"type":"string"},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"kind":{"type":"string","enum":["C","T"]},"credential":{"type":"string","enum":["RUT","CU","CT","CD"]},"portal":{"type":"string"},"status":{"type":"string","enum":["live","beta","degraded","down"]},"title":{"type":"string"},"description":{"type":"string"},"price_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"requires_widget":{"type":"boolean"},"params_schema":{}},"required":["flow","version","kind","credential","portal","status","title","description","price_cents","requires_widget","params_schema"]}}},"required":["environment","flows"]},"CreateWebhookEndpointRequest":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"minItems":1,"type":"array","items":{"type":"string","enum":["run.succeeded","run.failed","run.awaiting_confirmation","session.completed","session.failed","credential.revoked","flow.degraded"]}},"description":{"type":"string","maxLength":200}},"required":["url","events"],"additionalProperties":false},"WebhookEndpointResponse":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["run.succeeded","run.failed","run.awaiting_confirmation","session.completed","session.failed","credential.revoked","flow.degraded"]}},"status":{"type":"string","enum":["active","disabled"]},"secret":{"type":"string"},"created_at":{"type":"string"}},"required":["id","url","events","status","created_at"]},"ErrorBody":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_params","credential_invalid","credential_expired","portal_unavailable","portal_changed","not_found","rate_limited","flow_disabled","internal_error","authentication_error","permission_denied","conflict"]},"message":{"type":"string"},"run_id":{"type":"string"},"session_id":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Reintentar con la misma clave devuelve el run existente; no crea otro ni factura de nuevo."}}},"paths":{"/v1/runs":{"post":{"summary":"Crear un run","operationId":"createRun","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRunRequest"}}}},"responses":{"200":{"description":"Run terminado dentro de `wait_ms`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunResponse"}}}},"202":{"description":"Run encolado; el resultado llega por webhook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunResponse"}}}},"400":{"description":"Parámetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"API key inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"Flujo deshabilitado o conflicto de idempotencia","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}},"get":{"summary":"Listar runs","operationId":"listRuns","responses":{"200":{"description":"Listado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListRunsResponse"}}}}}}},"/v1/runs/{run_id}":{"get":{"summary":"Obtener un run","operationId":"getRun","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunResponse"}}}},"404":{"description":"No existe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/runs/{run_id}/cancel":{"post":{"summary":"Cancelar un run encolado","operationId":"cancelRun","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Run cancelado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunResponse"}}}}}}},"/v1/sessions":{"post":{"summary":"Crear una sesión de widget","operationId":"createSession","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSessionRequest"}}}},"responses":{"201":{"description":"Sesión creada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionResponse"}}}},"400":{"description":"Parámetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/sessions/{session_id}":{"get":{"summary":"Estado de la sesión","operationId":"getSession","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sesión","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionResponse"}}}},"404":{"description":"No existe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/connect/context":{"get":{"summary":"Contexto de la sesión para el widget","operationId":"getConnectContext","security":[{"sessionToken":[]}],"responses":{"200":{"description":"Contexto","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionContext"}}}}}}},"/v1/connect/credentials":{"post":{"summary":"Entregar la credencial del titular y disparar los runs","operationId":"submitCredential","security":[{"sessionToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitCredentialRequest"}}}},"responses":{"200":{"description":"Sesión en ejecución","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionResponse"}}}},"400":{"description":"Credencial inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/catalog":{"get":{"summary":"Catálogo de flujos disponibles","operationId":"getCatalog","responses":{"200":{"description":"Catálogo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogResponse"}}}}}}},"/v1/webhook_endpoints":{"post":{"summary":"Registrar un endpoint de webhooks","operationId":"createWebhookEndpoint","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookEndpointRequest"}}}},"responses":{"201":{"description":"Endpoint creado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointResponse"}}}}}}}}}