Creación de credenciales sin Widget (Widget-less)

Para adentrarnos en este tema hay que entender como están estructurados los sitios.
Los sitios de los cuales Syncfy puede obtener información se encuentran organizados de la siguiente forma:
DiagramaSitios

Para una Organización siempre sé específica su naturaleza (Tipo de Organización), y cada Organización agrupa uno o más sitios, por ejemplo:

Organización BBVA Bancomer
Tipo de Organización Banco
Sitios BBVA Bancomer Personal
BBVA Bancomer Empresas BBVA Bancomer NetCash
BBVA Bancomer NetCash Llave Inteligente

A continuación se listan los endpoints para que el usuario pueda obtener los diferentes catálogos vinculados a los sitios, los catálogos están en constante actualización. Es necesario añadir un token de sesión (?token=TOKEN) o el api key (?api_key=API_KEY) en la URL.

Objeto Organización
Organización

Campo Tipo Descripción
id_site_organization String ID de la organización. Se encontrará en los sitios que agrupa.
id_site_organization_type String ID del tipo de la Organización.
id_country String ID del país a donde pertenece la organización.
name String Nombre de la Organización
avatar String Avatar de la Organización
small_cover String Small Cover de la Organización
cover String Cover de la Organización

Tanto Avatar, como Small Cover y Cover de la organización contienen un string que ayudará a obtener las imágenes del sitio para poder mostrarlas al usuario, sólo es necesario concatenarlo a la base https://s.syncfy.com
Por ejemplo el siguiente link entrega el avatar de BBVA Bancomer.

Objeto Sitio

Sitio

Campo Tipo Descripción
id_site String ID del sitio.
id_site_organization String ID de la Organización a la que pertenece.
id_site_organization_type String ID del tipo de la Organización a la que pertenece.
is_business Lógico Bandera que indica si el sitio soporta conexiones Empresariales
is_personal Lógico Bandera que indica si el sitio soporta conexiones Personales
name String Nombre del sitio
credentials Arreglo Arreglo de objetos que describen cada uno de los elementos a enviar en la creación de las credenciales. A continuación se describe el objeto en la tabla Elemento de autenticación.

Elemento de autenticación
Elemento que formará parte de la petición para crear la credencial.

Campo Tipo Descripción
name String Nombre del elemento
type String Tipo del elemento, puede ser: text, password o select. Si algún sitio lo requiere, se agregará otro tipo.
label String Etiqueta que aparece en el portal del sitio, se debe desplegar al usuario para que haga sentido el valor que debe enviar.
required Booleano Bandera que indica si el elemento es requerido
username Booleano Bandera que indica si el elemento es username.
token Booleano Bandera que indica si el elemento espera un token del usuario.
validation String OPCIONAL. Expresión dada por el sitio para validar la entrada del usuario antes de lanzar la conexión.
options Arreglo OPCIONAL, para los elementos de tipo select , se especifica un arreglo de objetos con la siguientes estructura:
{
“label”: “ETIQUETA”,
“value”: “01”
}
El desarrollador deberá construir un <SELECT> con las opciones entregadas por el elemento para que el usuario pueda indicar una opción válida.

Petición para construir credenciales

Se recomienda hacer una petición de la siguiente forma:
peticionCredenciales

Los PARÁMETROS DE PETICIÓN es un objeto, se incluye el ID del Sitio al que se conectarán las credenciales además de un objeto que define cada uno de los elementos de autenticación con los valores proporcionados por el usuario. Ejemplo:

Ejemplos de Parámetros para Creación de Credenciales

Credenciales del Sitio Banorte Personal id_site : 56cf5728784806f72b8b456e
[
      {
         “name”:“username”,
         “type”: “text”,
         “label”: “Tarjeta”,
         “required”: true,
         “username”: true,
         “token”: false,
         “validation”: null
       },
       {
         “password” : “12345678”,
         “name”:“password”,
         “type”: “password”,
         “label”: “Contraseña”,
         “required”: true,
         “username”: false,
         “token”: false,
         “validation”: null
       }
]

Elementos de autenticación:
{
       “id_site”: “56cf5728784806f72b8b456e”,
       “credentials”: {
                     “username” : “Usuario123”,
                     “password” : “12345678”,
       }
}

El nombre de las llaves del objeto credentials las define la propiedad name del elemento de autenticación. El type se utiliza para el formato del input, por ejemplo para el type password se recomienda un input que ofusque la entrada del usuario. El label es la leyenda que se le mostrará al usuario.

Al crear una credencial con la petición POST /credentials, se genera una conexión al sitio. Los datos para el monitoreo de la conexión se entregan en la respuesta de la petición.

Respuesta de HTTP POST /credentials

Campo Tipo Descripción
id_credential String ID de la credencial creada
username String Username ofuscado
ws String Dirección de Websocket para monitorear el estado de la credencial en tiempo real
status String URL para monitorear el estado de la credencial mediante una petición HTTP GET
twofa String URL para enviar el valor de los TWO-FA solicitados por la conexión. Para el envío construirá una petición HTTP POST

respuestaHTTP

Monitoreo de estado de conexión:

Información del job

Código Nombre Descripción
100 Register La API registra un nuevo proceso (a través de una solicitud REST)
101 Starting Sync obtuvo la información del proceso para empezar a opera
102 Running Sync se está ejecutando (inicio de sesión exitoso)
103 TokenReceived Sync recibió el token

Conexión exitosa

Código Nombre Descripción
200 Finish La información fue procesada correctamente
201 Pending La información fue procesada correctamente, la información pendiente se seguirá descargando en el fondo
202 NoTransactions El proceso concluyó correctamente, pero no se encontraron transacciones
203 PartialTransactions El proceso concluyó correctamente, pero una o más cuentas no tienen transacciones
204 Incomplete El trabajo concluyó correctamente, pero la información está incompleta
206 NoAccounts El proceso concluyó correctamente, pero no se encontraron Cuentas

Errores de usuario

Código Nombre Descripción
401 Unauthorized Credenciales no válidas (el usuario o la contraseña no son válidos)
403 Invalidtoken El Token enviado por el usuario no es válido
405 Locked La cuenta está bloqueada
406 Conflict El usuario ya está conectado
408 UserAction Se requiere intervención del usuario en el Sitio
409 WrongSite El proceso logró identificar que las credenciales pertenecen a un sitio diferente dentro de la misma Organización

Interacción de usuario

Código Nombre Descripción
410 WaitingTwofa El proceso se encuentra esperando TWO-FA por parte del usuario.
411 TwofaTimeout Tiempo excedido por el usuario para introducir TWO-FA

Errores

Código Nombre Descripción
500 Error El banco requiere atención (error de Sync)
501 Unavailable El sitio del tercero está temporalmente fuera de servicio.
504 ScriptTimeout Tiempo excedido de Sync
509 UndergoingMaintenance El sitio está en mantenimiento por parte de Sync

Mediante la petición HTTP GET /status es posible obtener el flujo por credencial:
flujoPeticion

Ejemplo de respuesta:
RespuestaCodes

A continuación se presentan los flujos más comunes de una conexión:
Flujo de una conexión que no requiere TWO-FA
image

Flujo de una conexión que requiere TWO-FA
image

Flujo de una conexión que presenta error con los datos del usuario
image

Manejo de Autenticación Two-factor

El desarrollador debe estar monitoreando cada uno de los cambios en el arreglo de la respuesta de /status y procesar el código, enviar un mensaje al usuario según sea el caso. Cuando el código es 410 deberá solicitar al usuario el segundo paso de la autenticación, en la misma respuesta de estado se proporcionan los detalles. La etapa con el código 410 tiene un objeto similar al siguiente:

CodeToken

Estado

Nombre Tipo Descripción
code Número Código del estado
address String URL donde se enviará el valor de two-factor mediante una petición HTTP POST
twofa Arreglo Arreglo de objetos que describen cada uno de los elementos de two-factor. Los atributos campos son:
(obligatorio) name : Es el nombre con el que se enviará el valor de two-factor
(obligatorio) type : Tipo de two-factor, puede ser text , password , options . Cuando es options se espera una propiedad options.
(obligatorio) label : Etiqueta del sitio para el two-factor (opcional) imgBase64File : StringBase64 de la imágen con el captcha o QRCode a validar por el usuario.
(opcional) imgURL : URL de la imágen con el captcha o QRCode a validar por el usuario cuando se encuentra público en el sitio.
(opcional) options : Arreglo con imgBase64File para desplegar una matriz de imágenes al usuario con la finalidad de que pueda seleccionar una.

Petición HTTP POST /twofa para enviar el two-factor
httpTwofa

En los parámetros del objeto twofa se debe enviar cada uno de los valores que el usuario proporcione con el nombre que se especifica en name.