Estado Situación

Para obtener la información necesaria para armar un estado de situación, se extraen los datos de las siguientes entidades y acciones:

• AFC (Administradora de Fondos de Cesantía de Chile)
  • Información Personal
  • Últimas cotizaciones al fondo de cesantía
  • Listado de empleadores
• SII (Servicios de Impuestos Internos)
  • Carpeta tributaria
• CMF (Comisión del Mercado Financiero)
  • Reporte de deudas
• Banco (Mas adelante se detalla como obtener el listado de bancos disponibles)
  • Análisis financiero bancario

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 usando la API key solicitada, en respuesta, se obtiene el 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)
• SII
  • sii:tax-folder (Carpeta tributaria usando login con Clave tributaria)
  • sii:tax-folder-clave-unica (Carpeta tributaria usando login con Clave Única)
• CMF
  • cmf:debt (Reporte de deudas)
• Banco
  • {entity_id}:financial-report (Análisis financiero bancario)

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 usando las credenciales del usuario.

cURL

curl --request POST 'https://${URL}/api/v1/tasks' \
--header 'Authorization: Bearer ${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.

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 ${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 y que vuelva a intentar, si vuelve a ocurrir una segunda vez consecutiva, nuestro servicio bloquea al usuario por seguridad. 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"
      }
    ]
  }
}

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

Proteccion 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 ${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"
}