Web Services Mensajería ISO 20022

Versión 1.0

Julio de 2019

Contenido

Ilustraciones ............................................................................................................................. 3

Glosario.................................................................................................................................... 3

1. Alcance del documento .................................................................................................... 4

2. Introducción ..................................................................................................................... 5

3. Servicios Web ................................................................................................................... 6

3.1. Tipos de servicios. ............................................................................................................... 6

- Servicios Web mensajería ISO ................................................................................................. 6

- Servicios Web consulta de información .................................................................................. 6

3.2. Flujo global del consumo de servicios. ................................................................................ 6

4. Autenticación ................................................................................................................... 8

5. Servicios Web mensajería ISO 20022 ................................................................................. 9

5.1. Contrato y especificación técnica...................................................................................... 11

6. Control de cambios del documento ................................................................................. 12

Anexos ................................................................................................................................... 12

Ilustraciones Ilustración 1. Diagrama de contexto técnico. ..................................................................................... 5 Ilustración 2. Flujo de consumo de servicios web ............................................................................... 6 Ilustración 3. Diagrama de flujo, solicitud de cliente asíncrono. ........................................................ 9 Ilustración 4. Tratamiento de respuestas del servidor. .................................................................... 10

Glosario

1. JSON: JavaScript Object Notation.

2. YAML: Formato de serialización de datos.

3. J2EE: Java Platform Enterprise Edition.

4. API: Application Programming Interface.

5. FTP: Protocolo de transferencia de archivos en red. J2EE

6. Rest: Arquitectura de servicios web.

7. Response: Respuesta de un servicio web.

8. Request: Petición a un servicio web.

9. HTTP: Hyper Text Transfer Protocol, o protocolo de transferencia de datos utilizado en la

web.

10. Header: Estructura de datos parte del contenido de peticiones a servicios web o paquetes

de datos.

11. JWT: JSON Web Token.

1. Alcance del documento El propósito de este documento es proveer un acercamiento a la estrategia de consumo que tendrán los clientes sobre los servicios web publicados por el nuevo core de deceval (BaNCS -CSD). Se describe en este documento el flujo de consumo de dichos servicios web y la estrategia de autenticación implementada. Además de una descripción general de los servicios web expuestos y su funcionalidad referenciando sus respectivas especificaciones. El alcance de este documento está limitado a describir la interacción por medio de servicios web. No se comprende el envío de archivos por medio de protocolo FTP, el acceso a través de GUI - Interfaz gráfica de usuario u otros métodos de integración.

2. Introducción

El nuevo sistema, BaNCS - CSD es una solución J2EE con una arquitectura basada en componentes. Esta solución cuenta con la capacidad de exponer sus servicios web independientemente a la plataforma de consumo. Los servicios web expuestos están basados en un esquema REST soportando así mismo solicitudes y respuestas por medio de protocolos seguros. En la ilustración 1 se muestra el diagrama de contexto del nuevo sistema core de deceval. Ilustración 1. Diagrama de contexto técnico.

3. Servicios Web

3.1. Tipos de servicios.

Los servicios web a ser expuestos por el nuevo sistema BaNCS – CSD se pueden clasificar en dos grandes grupos:

- Servicios Web mensajería ISO

Por medio de este tipo de servicios el sistema BaNCS – CSD permitirá a terceros interactuar con la mensajería ISO20022 expuesta. Por medio de estos servicios web los terceros podrán entregar u obtener (según corresponda) cada uno de los 28 mensajes ISO20022 contemplados en el proyecto Amarú.

- Servicios Web consulta de información

Mediante estos servicios web se podrá consultar información de interés recurrente para los terceros, por ejemplo consultas de saldos de clientes, detalle de ISIN o información y detalle de las cuentas de clientes inversionistas.

3.2. Flujo global del consumo de servicios.

Podemos segmentar el flujo de consumo de servicios en dos pasos: el primero referente a la autenticación del cliente, y el segundo, al envío y solicitud de información de negocio (ej. mensajería ISO20022).

Ilustración 2. Flujo de consumo de servicios web

1. Servicio de autenticación: 1.1. Como se puede apreciar en el flujo, los sistemas clientes accederán a los servicios

al enviar un request a un “authorization endpoint”, indicando sus credenciales de acceso.

1.2. Los sistemas clientes recibirán un JWT (JSON Web Token) que garantizará su identidad. Mientras el token esté vigente podrá ser utilizado por el cliente; una vez este se haya vencido, el cliente deberá consumir nuevamente el servicio de autenticación.

2. Servicios de negocio:

2.1. Los sistemas clientes realizarán un request HTTPS tipo GET o POST. Como parte del header incluirán su token JWT (JSON Web Token). Para los mensajes ISO20022, en el body se indicará el tipo de mensaje a tratar y el contenido del mensaje. En otros casos se indicará como parámetro la información requerida por el servicio.

2.2. Los sistemas clientes recibirán como respuesta la información entregada por el servidor. Para los mensajes ISO20022 recibirán un acknowledgment (Reconocimiento o admisión) de la solicitud (para solicitudes POST) o un mensaje ISO20022 de respuesta (para solicitudes GET).

4. Autenticación En términos de autenticación se ha implementado un mecanismo que prioriza la protección de información sensible. Por medio de la tecnología de tokens JWT (JSON Web Token) los clientes establecerán su autenticación con el sistema BaNCS - CSD.

- ¿Qué es JWT? JSON Web Token (JWT, https://jwt.io/) es un estándar de código abierto basado en JSON para crear tokens de acceso que nos permiten asegurar las comunicaciones entre cliente y servidor.

- ¿Cómo funciona? El cliente se autentica y garantiza su identidad haciendo una petición al servidor de autenticación. Esta petición puede ser mediante usuario y contraseña, mediante proveedores externos o mediante otros servicios como LDAP, Active Directory, etc. Una vez que el servidor de autenticación garantiza la identidad del cliente, se genera un token de acceso (JWT). El cliente usa ese token para acceder a los recursos protegidos que se publican mediante API. En cada petición, el servidor desencripta el token y comprueba si el cliente tiene permisos para acceder al recurso haciendo una petición al servidor de autorización.

- Composición del token:

Estos tokens están compuestos por tres partes:

o Header: Contiene el hash que se usa para encriptar el token. o Payload: Contiene una serie de atributos (clave, valor) que se encriptan en el token. o Firma: Contiene header y payload concatenados y encriptados (Header + “.” +

Payload + Secret key).

Este token tendrá un periodo de validez predefinido, durante el cual los clientes podrán realizar peticiones sin solicitar nuevamente su generación. Una vez se alcance el momento de vencimiento del token, el cliente deberá validar nuevamente sus credenciales con el fin de recibir un nuevo token.

5. Servicios Web mensajería ISO 20022 Estos servicios web exponen principalmente la recepción y consulta de la mensajería ISO 20022. Por este medio los clientes podrán enviar los mensajes ISO y consultar la respuesta a los mismos. Ilustración 3 Diagrama de flujo, solicitud de cliente asíncrono.

Como se muestra en la ilustración anterior el flujo de consumo de la mensajería ISO consiste en los siguientes servicios web:

1. /signIn: Un servicio web de autenticación el cual pide como parámetros el conjunto usuario y contraseña y retorna un JWT (JSON Web Token) el cual será necesario para el consumo de los siguientes servicios.

2. /produceMessage: Un servicio web encargado de recibir los mensajes ISO a entregar por los terceros, que serán procesados o almacenados en el sistema. Este servicio también requiriere de un JWT que autentica al usuario e indica al sistema que es una solicitud válida en cuanto a seguridad y autorización. Los mensajes entregados por terceros por medio de esta petición, deberán ser binarios codificados en base 64.

3. /enquireMessage: Un servicio web que expone la mensajería ISO de respuesta. Este servicio al igual que el anterior requiere que el usuario se autentique con un JWT. Los mensajes entregados por BaNCS -CSD a los terceros por medio de este servicios web, serán binarios codificados en base 64, lo que requiere una decodificación de parte del cliente.

El envío de cada una de las solicitudes al servidor tiene una respuesta la cual indicará si fue satisfactoria la transacción o si se tiene que generar un nuevo intento; por lo tanto, las solicitudes que fueron tomadas de forma exitosa en el servidor obtienen una respuesta con un estatus http 200, de lo contrario se retornaran los distintos casos que se muestran en la siguiente ilustración: Ilustración 4 Tratamiento de respuestas del servidor.

5.1. Contrato y especificación técnica.

Se indica a continuación la URL de acceso a la especificación técnica, publicada mediante la plataforma Swagger Hub. (Para más información sobre la herramienta referirse al anexo “SwaggerHub Paso a Paso”). Servicio de autenticación, /signIn:

- https://app.swaggerhub.com/apis/bvc-amaru/bvc-amaru-ws-signin/1.0.0 Servicios de negocio, /produceMessage y /enquireMessage:

- https://app.swaggerhub.com/apis/bvc-amaru/bvc-amaru-ws-ISO20022-produce-enquire/1.0.0

6. Control de cambios del documento

Versión Fecha Observaciones

1.0 09 de Julio del 2019 Publicación Original

Anexos

1. Manual: SwaggerHub Paso a Paso:

https://proyectos.bvc.com.co/documentos/296_Manual%20SwaggerHub%20-

%20Paso%20a%20Paso.pdf

DISCLAIMER

La información aquí contenida es preliminar a la implementación del proyecto, por lo cual puede ser actualizada, eliminada o modificada de cualquier manera por posteriores presentaciones, reportes y/o cualquier comunicación realizada por bvc y deceval

http://www.bvc.com.co Copyright Bolsa de Valores de Colombia 2018

Principal Bogotá: Carrera 7 No. 71-21 Torre B Piso 12. Edificio BVC. PBX (57-1) 3139800