Crear una sesión de widget
post /v1/sessions
Abre una sesión del widget. Devuelve el widget_url al que llevas al titular para que entregue su clave, y el session_token que esa página usa.
Una sesión captura una sola credencial y puede disparar N runs con ella. Si pides flujos que exigen credenciales distintas (ClaveÚnica y Clave Tributaria), la petición se rechaza: crea una sesión por tipo.
La credencial decide la pantalla: los flujos con
credential: CT abren el widget de empresas, los de CU el de personas.Con
credential_policy: "stored" la clave se guarda cifrada para reusarla después, y el titular tiene que aceptarlo explícitamente en el widget.Autenticación
Requiere API key (sk_live_… · sk_test_…) en la cabecera
authorization: Bearer …. Ver autenticación.
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
Idempotency-Key | header | string | Reintentar con la misma clave devuelve el run existente; no crea otro ni factura de nuevo. |
Cuerpo de la petición
flows object[] obligatorio
flow string obligatorio
params object
Por omisión: {}
subject_ref string
subject_rut string
redirect_uri string
webhook_url string
credential_policy enum
Por omisión: "one_time"
one_timestored
metadata object
Respuesta 201
Sesión creada
session_id string obligatorio
status enum obligatorio
createdcredential_pendingverifyingauthorizedin_progresscompletedfailedexpiredrevoked
session_token string
widget_url string
webhook_secret string
credential_ref string | null obligatorio
verification object | null
Por omisión: null
status enum obligatorio
no_iniciadaen_cursoverificadarechazadabloqueadasin_clave_unicano_concluyente
message string | null
Por omisión: null
checked_at string | null
Por omisión: null
runs object[]
Por omisión: []
run_id string obligatorio
flow string obligatorio
flow_version integer obligatorio
status enum obligatorio
queuedrunningawaiting_confirmationsucceededfailedexpiredcancelled
data object | null obligatorio
document object | null obligatorio
type enum obligatorio
pdfjsonscreenshothtml
download_url string obligatorio
expires_at string obligatorio
sha256 string obligatorio
bytes integer obligatorio
documents object[]
Por omisión: []
type enum obligatorio
pdfjsonscreenshothtml
download_url string obligatorio
expires_at string obligatorio
sha256 string obligatorio
bytes integer obligatorio
source_meta object | null obligatorio
driver string obligatorio
obtained_at string obligatorio
portal string obligatorio
portal_ref string
duration_ms integer
attempts integer
error object | null obligatorio
code enum obligatorio
invalid_paramscredential_invalidcredential_expiredportal_unavailableportal_changednot_foundrate_limitedflow_disabledinternal_errorauthentication_errorpermission_deniedconflict
message string obligatorio
execution_token string
execution_token_expires_at string
session_id string | null
parent_run_id string | null
created_at string obligatorio
finished_at string | null obligatorio
expires_at string obligatorio
created_at string obligatorio
Errores
| Código | Cuándo |
|---|---|
400 | Parámetros inválidos |
El cuerpo de cualquier error sigue la misma forma y su code viene de un
catálogo cerrado. Ver errores.