Saltar al contenido principal

Evaluación Financiera con Clave Unica

Para obtener la información necesaria y armar una evaluación financiera, se extraen los datos de las siguientes entidades y acciones:

Una vez obtenida la API Key, podremos realizar el siguiente flujo para obtener cada uno de los datos anteriormente mencionados:

  1. Obtener el token de sesión.
  2. Consultar Entidades y acciones disponibles (Opcional).
  3. Iniciar proceso de extracción.
  4. Consultar estado de extracción y obtención de datos.

Obtener token de sesión

Para poder iniciar un proceso de extracción y obtención de datos, es necesario autenticarse utilizando la API key entregada por nosotros previamente, en respuesta, se obtiene un token de sesión.

cURL

curl --request POST 'https://${URL}/api/v1/auth/login/' \
--header 'x-api-key: {API_KEY}'

Response 200

{
"token": "******************************************************************"
}

Consultar entidades y acciones disponibles

Para poder iniciar una extracción, de antemano es necesario conocer el id de la entidad y el tipo de acción. Para ello podemos consultar el listado de entidades y acciones disponibles.

cURL

curl --request GET 'https://${URL}/api/v1/entities/' \
--header 'x-api-key: {API_KEY}'

Response 200

[
{
"name": "afc",
"enabled": true,
"actions": [
{
"enabled": true,
"name": "afc:contribution",
"actionType": "contribution"
},
{
"enabled": true,
"name": "afc:job",
"actionType": "job"
},
{
"enabled": true,
"name": "afc:all",
"actionType": "all"
},
{
"enabled": true,
"name": "afc:personal-information",
"actionType": "personal-information"
}
],
"id": "afc"
},
...
]

La respuesta será similar a esta, donde cada entidad posee un listado de acciones posibles, el valor que necesitaremos será el nombre de la acción, la cual esta compuesta de la siguiente estructura:

"{entity_id}:{action_type}"

Para el estado de situación, las acciones que nos interesan son las siguientes:

  • AFC
    • afc:personal-information (Información Personal)
    • afc:contribution (Últimas cotizaciones)
    • afc:job (Empleadores)
  • CMF
    • cmf:debt (Reporte de deudas)
  • SII
    • sii:tax-folder-clave-unica (Carpeta tributaria usando login con Clave Única)

Iniciar proceso de extracción

Ya teniendo el token de sesión, el id de la entidad y el tipo de acción, podemos iniciar un proceso de extracción utilizando las credenciales del usuario.

cURL

curl --request POST 'https://${URL}/api/v1/tasks/' \
--header 'Authorization: Bearer {SESSION_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
"action": "{ENTITY_ID}:{ACTION_TYPE}",
"args": {
"username": "{USERNAME}",
"password": "{PASSWORD}"
}
}'

Response 200

{ "taskId": "**********************************************" }

Debido a que un proceso de extracción puede tomar varios segundos, este proceso se realiza de forma paralela, en respuesta se retorna el taskId, con el cual se puede consultar el estado de la extracción y los resultados cuando haya terminado el proceso.

Uso de credenciales de usuario

En el sandbox, se puede usar cualquier RUT válido como username. En cuanto al uso de contraseñas, puede ser cualquier clave que tenga el formato válido para la entidad, esto debido a que cada entidad posee distintos requerimientos en cuanto a la seguridad de las contraseñas, el servicio realiza una comprobación previa a la extracción en base a esto para evitar errores de login y bloqueos en las cuentas de usuario. Se recomienda verificar los requerimientos de las claves antes de realizar pruebas.

/api#tag/Extraccion

Si la contraseña no cumple con el esquema de la entidad, se muestra el siguiente mensaje:

Response 422

{
"message": "password doesn't meet entity schema"
}

Consultar estado de extracción y obtención de datos

Una vez iniciado el proceso de extracción, usando el taskId se puede consultar el estado del proceso

cURL

curl --request GET 'https://${URL}/api/v1/tasks/{TASK_ID}' \
--header 'Authorization: Bearer {SESSION_TOKEN}'

Si el proceso aun está ejecutándose, la respuesta será la siguiente:

Response 200 - taskStatusCode 202

{
"taskStatus": "running",
"taskStatusCode": 202,
"results": {}
}

Si hubo algún error en la entidad durante el proceso, será similar a lo siguiente:

taskStatusCode 401

En este caso, la entidad esta indicando que la contraseña ingresada no es correcta, si vuelve a ingresar una contraseña incorrecta por segunda vez consecutiva, nuestro servicio bloquea al par usuario entidad por 24 horas. Consultar la siguiente sección para más detalles.

Response 200

{
"taskStatus": "wrong_login",
"taskStatusCode": 401,
"results": {}
}

statusCode 500

Cuando se retorna statusCode 500 quiere decir que la entidad esta indisponible.

Response 200

{
"status": "error",
"statusCode": 500,
"message": {
"name": "TimeoutError"
}
}

Si la extracción fue completada con éxito, la respuesta será similar a la siguiente:

Response 200 - taskStatusCode 200

{
"taskStatusCode": 200,
"taskStatus": "success",
"results": {
"username": "11.111.111-1",
"entityId": "afc",
"data": [
{
"subscriptionDate": "09-06-2021",
"employerRut": "74.014.885-0",
"employerName": "LOYA - ACUÑA",
"contractType": "DURACIÓN INDEFINIDA",
"startDate": "09-04-2021",
"endDate": ""
},
{
"subscriptionDate": "09-03-2020",
"employerRut": "74.158.398-4",
"employerName": "JÁQUEZ, BORREGO AND CORREA",
"contractType": "DURACIÓN INDEFINIDA",
"startDate": "09-02-2020",
"endDate": "09-03-2021"
},
{
"subscriptionDate": "09-11-2017",
"employerRut": "81.218.535-7",
"employerName": "FAJARDO HERMANOS",
"contractType": "A PLAZO",
"startDate": "09-09-2017",
"endDate": "09-11-2019"
}
]
}
}

En el sandbox, independiente del username ingresado al iniciar la extracción, como respuesta retorna siempre el mismo username (11.111.111-1). En desarrollo y producción siempre será el mismo username ingresado originalmente.

Para ver ejemplos de respuestas de cada entidad, consultar a la documentación de la api

/api

Protección anti bloqueo

En el ambiente sandbox las contraseñas siempre serán correctas mientras cumplan con el esquema de la entidad, pero hay que tener en consideración que en ambiente de beta y producción, si se ingresa una contraseña incorrecta por segunda vez consecutiva, nuestro sistema bloquea al usuario por 24 horas para evitar que la entidad bloquee al usuario por causa de nuestro servicio.

En caso que el usuario sea bloqueado por nuestro servicio, se puede consultar su estado y el tiempo restante para un nuevo intento.

cURL

curl --request POST 'https://${URL}/api/v1/users/status/by-entity' \
--header 'Authorization: Bearer {SESSION_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
"username": "{USERNAME}",
"entity": "{ENTITY_ID}"
}'

Response 200 - Usuario habilitado

{
"enabled": true,
"retryAfter": null
}

Response 200 - Usuario deshabilitado

{
"enabled": false,
"retryAfter": "2022-06-10T15:36:35.380Z"
}