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:
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.
| Catálogo | Endpoint |
|---|---|
| Tipos de Organizaciones | https://api.syncfy.com/v1/catalogues/site_organization_types |
| Países | https://api.syncfy.com/v1/catalogues/countries |
| Organizaciones | https://api.syncfy.com/v1/catalogues/site_organizations |
| Sitios | https://api.syncfy.com/v1/catalogues/sites |
| Sitios agrupados por Organizaciones | https://api.syncfy.com/v1/catalogues/organizations/sites |
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:
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 |
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:
Ejemplo de respuesta:
A continuación se presentan los flujos más comunes de una conexión:
Flujo de una conexión que no requiere TWO-FA
Flujo de una conexión que requiere TWO-FA
Nota: Es importante considerar que hay sitios que requieren más de un two-fa, por lo que es necesario implementar una lógica que soporte más de un 410.
Flujo de una conexión que presenta error con los datos del usuario
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:
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
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.