Documento Negocio API- PE con AUTO 3 by Corporación BI

Información General

Personal Involucrado

Ventajas, límites y alcances

Proceso de Implementación

Descripción API

Pago Electrónico

Métodos de Notificación

Generalidades

Lecciones Aprendidas

Glosario

Soporte

Conexión API

(Interfaz de Programación de Aplicaciones)

versión 1.0

Interconexión Bi brinda comunicación entre Banco Industrial ,S A y “Nuestro Cliente” para integrar su sistema de envío de pagos, utilizando una estructura API SOAP ya definida, con estándares internacionales

API SOAP (Simple Object Access Protocol) es un protocolo de mensajería estándar que facilita la comunicación entre sistemas y aplicaciones mediante HTTP y XML.

SOAP se distingue por su estructura rigurosa y formal, lo que lo convierte en una opción ideal para entornos empresariales distribuidos y aplicaciones que gestionan datos sensibles, como los servicios bancarios.

Los módulos de Bi Banking habilitados para esta integración son:

• Pago Electrónico

Pago Electrónico es el servicio para clientes empresariales de envío de transferencias a cuentas de Banco Industrial, S A

Para dicha funcionalidad se encuentran habilitadas las siguientes opciones de autorización:

• Con autorización Web : La aplicación del lote requerirá de las autorizaciones correspondientes en la página web de Bi Banking, de acuerdo a los niveles de autorización definidos

Esta comunicación se originó en BANCO INDUSTRIAL, S.A. contiene información confidencial y es para el uso exclusivo del destinatario La distribución, copia u otro uso de este mensaje por terceras personas está prohibida y puede ser ilegal Si usted no es el destinatario, favor notificar al remitente

Datos del Proyecto

Amilkar Rodriguez

Luis Gomez

Jorge Mario Perez

EJECUTIVOBIBANKING

Áreas Operativas

Encargado

Banca Moderna Jefe de Unidad

Banca Moderna Coordinador de Proyectos

Banca Moderna Jefe de Departamento de Negocios

VENTAJAS

• Seguridad, al contar con una conexión con la plataforma API Connect y nuestro SFTP, así como, el uso de llaves públicas y privadas de autenticación

• Elimina el riesgo de fraudes, los pagos se realizan sin intervención humana

• Reducción de procesos manuales por medio de la automatización de pagos

• Rapidez en la transmisión de información al contar con una comunicación directa entre servidores

LÍMITES Y ALCANCES

• Aplicación de transferencias de los módulos de Pago Electrónico

• Habilitación de una nueva instalación para la integración de pagos

• Aplicación de transacciones únicamente en quetzales y dólares

IMPLEMENTACIÓN

Proceso de IMPLEMENTACIÓN

1. Actualización del servicio de Bi Banking para la creación de nuevas credenciales, incluyendo el proceso de afiliación a la API

2. Finalizar desarrollo de la conexión a la API SOAP por parte de cliente

3. Enviar “Carta de compromiso” con firmas registradas y en hoja membretada

4. Efectuar pruebas de integración:

• Validación de Comunicación

• Correcta aplicación de los lotes de Pago Electrónico

5 Realizar pruebas técnicas: Análisis del equipo de Control de Calidad de Banca Moderna (QA)

6 Ejecutar pruebas de certificación: Revisión de cuadres contables en los pagos efectuados

7. Emisión de Carta de Certificación y solicitud de pase para Instalación en producción

8. Instalación en Producción

9. Monitoreo

PROPÓSITO

La propuesta tecnológica para las operaciones financieras entre Banco Industrial, S A y nuestro cliente, se orienta a resolver los servicios específicos de Pago Electrónico (transferencias entre cuentas Bi)

Para dicha funcionalidad existirán dos opciones de aplicación de lotes de pago:

AUTORIZACIÓN WEB

Para esta opción se requiere de las autorizaciones correspondientes en la página web de Bi Banking (https://www bibanking bi com gt) de acuerdo a los niveles de autorización previamente definidos, con el fin de autorizar el lote recién enviado para que éste sea procesado

Por este medio no se permite el envío de lotes programados, quedando la aplicación del lote sujeta a la última autorización brindada

FUNCIONAMIENTO

La API SOAP que ofrecemos está diseñada para manejar de manera segura la transferencia de mensajes encriptados utilizando GPG (GNU Privacy Guard) A continuación, se detalla el proceso:

Recepción de Mensajes Encriptados: La API recibe el mensaje de transferencia del cliente en un formato encriptado (GPG) Este método asegura que los datos sensibles se mantengan protegidos durante la transmisión

Procesamiento del Mensaje: Una vez recibido, el mensaje encriptado se procesa internamente El archivo encriptado sigue una estructura definida por etiquetas específicas, lo que permite una revisión y validación precisa de su contenido

Envío de Respuesta Encriptada: Tras la revisión y procesamiento del mensaje, la API genera una respuesta que también se encripta utilizando GPG Esta respuesta encriptada se envía de vuelta al cliente, garantizando que toda la comunicación se mantenga segura y confidencial

Este enfoque asegura que tanto la transferencia inicial como la respuesta se manejen de manera segura, cumpliendo con los estándares de seguridad y confidencialidad requeridos

Autenticación y Seguridad

Para garantizar la seguridad y el acceso controlado a nuestra API, se requiere un proceso de autenticación basado en Client ID, Client Secret y tokens de acceso A continuación, se describe el proceso en detalle:

1.Client ID y Client Secret:

• Client ID: Un identificador único proporcionado a cada cliente que utiliza la API. Este ID permite identificar la aplicación que realiza la solicitud.

• Client Secret: Una clave secreta asociada al Client ID. Esta clave debe mantenerse confidencial y se utiliza para autenticar la identidad del cliente junto con el Client ID.

2. Proceso de Obtención del Token:

• Solicitud de Token: El cliente debe enviar una solicitud de token al servidor de autenticación utilizando el Client ID y el Client Secret. Esta solicitud se realiza a través de un endpoint específico de autenticación.

• Recepción del Token: Si las credenciales son válidas, el servidor de autenticación devuelve un token de acceso. Este token es un identificador temporal que permite al cliente realizar solicitudes a la API.

• Uso del Token: El cliente debe incluir el token de acceso en el encabezado de cada solicitud a la API. Esto asegura que solo las solicitudes autenticadas sean procesadas.

Ejemplo de Solicitud de Token

Ejemplo de Uso del Token

Seguridad Adicional

Expiración del Token: Los tokens de acceso tienen una vida útil limitada y deben ser renovados periódicamente para mantener la seguridad.

En ambiente QA : 10 minutos

En ambiente productivo: 1 Hora

Revocación de Tokens: En caso de que se sospeche un uso indebido, los tokens pueden ser revocados para prevenir accesos no autorizados.

Este proceso asegura que solo los clientes autenticados puedan acceder a los recursos de la API, protegiendo así la integridad y confidencialidad de los datos.

Importante:

la información detallada de la API, donde se indican los enpoint´ s para la generación del token y la ruta para el envío de los archivos de las transacciones, será proporcionada por el personal de Banco Industrial, SA, al haber firmado la documentación de confidencialidad necesaria para concretar la conexión entre el banco y nuestro cliente

Método de Envío

Módulo de Pago Electrónico

Para el envío de lotes de Pago Electrónico (transferencias a cuentas de Banco Industrial, S A ) se debe consumir la API de Banco Industrial, S A , donde se adjunta el archivo XML con la información generada por el sistema del cliente, dicho archivo se debe cifrar con el utilitario GPG entre el cliente y Banco Industrial, S A

A continuación, se detalla la estructura XML de la cadena de texto a enviar para la instrucción de pago:

Módulo de Pago Electrónico

Nombre del Campo Tipo

Longitud Máxima

<usuario> Alfanumérico 10

<clave> Alfanumérico 10

<idCliente> Numérico 9

<idConvenio> Numérico 9

<fechaAplicacion> Fecha 8

<descripcion> Alfanumérico 25

<numeroLote> Numérico 9

<numeroOperaciones> Numérico 9

<montoTotal> Monto 15

Estructura de detalle

Estructura de encabezado

Observaciones

Usuario asignado a nuestro cliente (generado por Banco Industrial, S. A.)

Contraseña del usuario de nuestro cliente (generado por Banco Industrial, S.A.)

Código de la plataforma de Bi Banking

ID proporcionado por Banco Industrial, S.A., el cual asocia cuenta débito y moneda.

Fecha de aplicación del lote con el formato YYYYMMDD

Descripción del pago a realizar, ( No agregar caracteres especiales)

Número secuencial de lote por identificador de convenio. (No podrá repetirse éste ID por convenio)

Número de operaciones o pagos contenidos en el lote de Pago Electrónico.

Sumatoria del monto de las operaciones contenidas en el lote de Pago Electrónico.

Nombre del Campo Tipo Longitud Máxima

<tipoCuentaDestino> Numérico 1

<numeroCuentaDestino> Numérico 10 Cuenta de cheques 7 Cuenta de ahorros

<correoNotificacion> Alfanumérico 50

<monto> Numérico 15

<descripcion> Alfanumérico 25

<referencia> Numérico 6

Observaciones

Tipos de cuenta: 1 – Para cuenta de cheques. 2 – Para cuenta de ahorros.

Número de cuenta crédito incluyendo los ceros a la izquierda.

Correo electrónico para notificación de crédito al participante.

Monto de la operación de pago, debe incluir dos decimales.

Descripción de la operación de pago. ( No agregar caracteres especiales)

Número secuencial de transacción por lote e identificador de convenio.

NOTA:semanejaunasolamonedadepagoporcadalotedePagoElectrónico.

El No de referencia enviado en los lotes de Pago Electrónico será el mismo que Bi Banking retornará en cada operación realizada en los reportes y archivos de resultados de operaciones Se debe considerar que éste número deberá incluirse en el campo referencia, de igual forma es necesario que contenga 6 bytes El número de referencia no será incluido en las operaciones de pago de cheque en caja, ni en compensación

En los casos que se requiera incluir facturas dentro del detalle de pagos, se deberá adicionar dentro de cada operación el tag Facturas, el cual se detalla a continuación:

Estructura XML de Facturas

</facturas>

Detalle de campos de Facturas

Nombre del Campo Tipo Longitud Máxima

Observaciones

<numero> Varchar 20 Número de factura a pagar.

<montoFactura> numérico 15 Monto de la factura a pagar.

Métodos de Notificación

Notificación inmediata sobre el envío de lotes de Pago Electrónico

Posterior al consumo de la API de Banco Industrial, S A se devuelve un archivo con formato XML en respuesta al resultado, dicha información se envía cifrada con la llave pública del cliente al SFTP proporcionado por la empresa

</Resultado>

</MensajeRespuesta>

Códigos de Retorno de la validación del archivo

Se valida la integridad de los lotes de Pago Electrónico, rechazo total en caso presentar código de retorno diferente a 0

Código de Retorno

Descripción

Lote recibido exitosamente

Lote incompleto Campo <numeroOperaciones> no coincide con la cantidad de operaciones del detalle.

Lote descuadrado Campo <montoTotal> es diferente a la sumatoria de transacciones en el detalle.

Lote duplicado Campo <numeroLote> ya existe en lo lotes enviados anteriormente

4 Lote con error de sintaxis

5 Fecha inválida Campo de <fechaAplicacion> ya se encuentra vencida, o bien, el formato se encuentra incorrecto.

Cliente inválido Campo de <idCliente> diferente al indicado por Banco Industrial, S. A.

7 Convenio inválido Campo de <idConvenio> diferente al indicado por Banco Industrial, S. A.

Usuario Web Services invalido Campo de <usuario> diferente al indicado por Banco Industrial, S. A.

| MÉTODOS DE NOTIFICACIÓN

Código de Retorno

Códigos de Retorno API

Código de Retorno

9999

Descripción

XML no encriptado

Archivo enviado sin cifrado.

Error al validar datos del banco

Descripción

Error Inesperado consultar con personal encargado

10000 Acceso denegado

200 Petición Exitosa XML

400 Petición inválida (formato json inválido)

401 Credenciales API Inválidas

429 Excedido el límite de peticiones al API

422 El cuerpo de la petición no cumple con el esquema de definición

500 El servidor backend no disponible

502 Error consultado el Backend(Se dio un error interno consultando el backend)

504 Tiempo de espera del API excedido

| MÉTODOS DE NOTIFICACIÓN

Notificación sobre el resultado de las transacciones enviadas en los lotes de Pago Electrónico (Respuesta detallada)

Este proceso de notificación funciona diferente para cada tipo de transacción

lotes de Pago Electrónico se realizará 45 minutos después del proceso de la transacción dentro del sistema de Banco Industrial SA

Para la notificación de las transacciones se genera el archivo de retorno cifrado con la llave pública del cliente en formato de texto delimitado por pipes

Encabezado del archivo

Encabezado del lote

Detalle del lote

Representación gráfica con fines de ejemplo

El envío del archivo de respuesta se realizará al servidor SFTP de Banco Industrial S A en una carpeta privada Dicho archivo será nombrado por medio de prefijos predefinidos según el tipo de lote que se haya operado:

Formato de Nombre

Descripción

BIDDMMAAAAHHMMSS Lotes de Pago Electrónico (transferencias a cuentas de Banco Industrial, S. A.)

El archivo se encuentra compuesto por las siguientes secciones:

• Encabezado del archivo

• Encabezado del lote

• Detalle del lote

Estructura de encabezado del archivo (Pago Electrónico)

Nombre del Campo Tipo Longitud Máxima

Identificador de registro

Número de registros

Numérico 1

Numérico 9

Observaciones

Valor constante "0" en el encabezado del archivo.

Número de lotes que contiene el archivo.

Estructura de encabezado del lote (Pago Electrónico)

Nombre del Campo Tipo Longitud Máxima

Identificador de registro

ID cliente

ID convenio

Número de lote

Número de operaciones

Autorización

Código de retorno

Mensaje de retorno

Numérico 1

Numérico 9

Numérico 12

Numérico 2

Alfanumérico 50

Observaciones

Valor Constante "1" para los registros de encabezado del lote.

Código de la plataforma de Bi Banking

ID proporcionado por Banco Industrial, S.A., el cual asocia cuenta débito y moneda.

Número secuencial de lote por identificador de convenio. (No podrá repetirse éste ID por convenio)

Número de operaciones o pagos contenidos en el lote de Pago Electrónico

Número de autorización de Banco Industrial, S. A.

Código de retorno del encabezado del lote.

Mensaje de retorno del lote

Códigos de retorno de encabezado del lote (Pago Electrónico)

Código de Retorno

Descripción

Rechazado

Lote de pago no operado.

6 No aceptado

Rechazo interno del lote.

Procesado

Aplicación exitosa del lote.

Instalación no válida

Campo <idCliente> no corresponde a la indicada por Banco Industrial, S. A.

9 Convenio no válido

Campo de <idConvenio> diferente al indicado por Banco Industrial, S. A.

No existe CP del lote

Cuenta débito no se encuentra registrada para la operatoria del lote de pago.

CP Con problemas

Cuenta débito presenta inconvenientes al operar el lote de pago.

Lote cancelado

Lote no operado.

15 Fecha inválida

Campo de <fechaAplicacion> ya se encuentra vencida, o bien, el formato se encuentra incorrecto

16 Monto inválido

Campo <monto> se encuentra con formato incorrecto.

20 Error ingreso detalle

Estructura de detalle del lote

Nombre del Campo Tipo

Identificador de registro

ID cliente

ID convenio

Numero lote

Referencia

Autorización

Código de retorno

Mensaje de retorno

Fecha de aplicación

Longitud Máxima

Numérico 1

Numérico 9

Numérico 6

Numérico 2

Alfanumérico 50

Numérico 8

Observaciones

Valor Constante "2" para los registros incluidos en el detalle del lote.

Código de la plataforma de Bi Banking

ID proporcionado por Banco Industrial, S.A., el cual asocia cuenta débito y moneda.

Número secuencial de lote por identificador de convenio.

(No podrá repetirse éste ID por convenio)

Número secuencial enviado por el cliente.

Número de autorización de Banco Industrial, S. A.

Código de retorno del lote.

Mensaje de retorno del lote.

Fecha de aplicación de la transacción u operación con formato YYYYMMDD

Códigos de retorno del detalle del lote (Pago Electrónico)

Código de Retorno

Descripción

Registro operado exitosamente

Transacción aplicada exitosamente

Participante deshabilitado

Cuenta crédito deshabilitada en plataforma de Bi Banking.

Monto no autorizado

Monto supera el límite de crédito registrado.

Participantes no existe

Cuenta crédito no se encuentra registrada en el convenio.

Problemas 390

Crédito rechazada por proceso interno.

Cuenta no existe

Cuenta crédito no existe.

Saldo insuficiente

Falta de disponibilidad de fondos para realizar crédito.

Cuenta con problemas

Transacción rechazada por proceso interno.

Error de datos

Transacción rechazada por proceso interno.

Error desconocido

Transacción rechazada por proceso interno.

Generalidades en envío de archivos

Los archivos de datos enviados a Banco Industrial, S A deben estar debidamente supervisados para la aplicación de lotes de Pago Electrónico (transferencia entre cuentas de Banco Industrial, S A )

La adición de participantes en convenios de Pago Electrónico debe efectuarse de la misma forma en que se realiza actualmente dentro de la plataforma de Bi Banking (manual o por archivo) Los convenios de pago de planilla pueden ser de tipo consolidado (un débito por el monto total del lote de pago) o detallado (débito por operación realizada en el lote), éste último es utilizado para pago de proveedores

En las descripciones de pago no se debe utilizar minúsculas, tampoco letras con tildes y la letra “Ñ” se cambiará por el carácter numeral “#” Para pago a proveedores el cliente puede proveer un número de referencia (6 bytes), el cual se desplegará en el estado de cuenta (MT-940)

Se podrá utilizar como contingencia los servicios de Bi Banking Web para la consulta del proceso de aplicación de los lotes de pago

PÁGINA |21 |

Para el procesamiento de archivos de Pago Electrónico, la comunicación se realizará mediante la API, donde se adjuntará un archivo cifrado con la llave pública proporcionada por Banco Industrial, S. A., con la herramienta GNUPG

La versión de GnuPG que se utiliza es 2 2 1, o bien, si se utiliza otra versión debe de cumplir con las siguientes características de cifrado:

• Cifrar con: GnuPG (otras versiones tienen otros métodos de cifrado)

• Pubkey: ELG-E

• Cipher: BLOWFISH

• Método de compresión: ZLIB

Los mecanismos de cifrado deberán utilizarse en el siguiente orden:

• Cifrado a nivel de texto utilizando las librerías de GPG

• Cifrado a nivel de archivo utilizando GPG, enviando el archivo adjunto en las peticiones y respuestas del Servicio Web

• Cifrado a nivel de texto utilizando otro algoritmo de cifrado

Importante:

1. Para dar inicio formalmente al proyecto de integración vía API, nuestro cliente debe entregar la documentación proporcionada y firmar el convenio de confidencialidad.

2. Es Importante que, en el proceso del proyecto, se cuente con la participación del equipo de IT de nuestro cliente y las áreas contables o relacionadas con el proceso de las transacciones, con el fin de que el proceso establecido en el desarrollo sea el ideal y funcional.

3. No es posible Programar transacciones, todo archivo recibido en el sistema de Banco Industrial, se enviará a proceso el mismo día de su recepción.

4. Los tokens de acceso tienen una vida útil limitada y deben ser renovados periódicamente para mantener la seguridad.

En ambiente QA : 10 minutos

En ambiente productivo: 1 Hora

5. Se genera una carpeta SFTP por Instalación cliente. Si el cliente posee varias empresas, se debe generar una instalación y una carpeta SFTP individual por cada empresa.

6. La IP a utilizar para la conexión al SFTP de Banco industrial, debe ser pública y estática.

7. Se acepta un rango de IPs con un máximo de 5 Host.

8. El cliente debe conectarse a nuestro SFTP para recoger sus archivos de respuesta.

9. Banco Industrial le brindará al cliente los siguientes datos para su conexión y transmisión de archivos por medio de la API, posterior a la firma del convenio de confidencialidad.

• Conexión API

✓ Client ID

✓ Cliente Sercret

✓ Enpoint de conexión a la API

✓ Enpoint para solicitar token.

• Proceso de transacciones

✓ ID cliente

✓ Usuario

✓ Clave

✓ ID convenio (también conocido en BIBanking como carpeta)

• Encriptación

✓ Llave pública de Banco Industrial

✓ Correo asociado a la llave

• Acceso al SFTP

✓ IP de conexión

✓ Usuario

✓ Clave de acceso

✓ directorios

1. API (Application Programming Interface): Conjunto de reglas y protocolos que permite a diferentes aplicaciones comunicarse entre sí.

2. API Connect: Plataforma de IBM para la creación, gestión y seguridad de APIs.

3. API SOAP (Simple Object Access Protocol): Protocolo de mensajería basado en XML para intercambiar información estructurada en la implementación de servicios web.

4. Client ID: Identificador único asignado a una aplicación cliente cuando se registra en un servicio de autenticación.

5. Client Secret: Clave secreta asignada a una aplicación cliente para autenticar su identidad ante un servicio de autenticación.

6. Convenio: Es una carpeta creada para clasificar las cuentas o los identificadores ingresados como participantes para próximamente poder realizar pagos o transferencias.

7. Endpoint: URL específica donde un servicio web puede ser accedido por aplicaciones cliente.

8. ERP (Enterprise Resource Planning): Sistema de software que integra y gestiona las principales funciones de negocio de una organización.

9. GPG (GNU Privacy Guard): Herramienta de cifrado que permite la firma y cifrado de datos y comunicaciones.

10. GnuPG (GNU Privacy Guard): Implementación libre de OpenPGP que permite cifrar y firmar datos y comunicaciones.

11. Guate ACH: Sistema de Cámara de Compensación Automatizada en Guatemala, utilizado para transferencias electrónicas de fondos entre bancos.

12. idCliente: Identificador único de un cliente en un sistema.

13. Llave Privada: Clave criptográfica que se utiliza para descifrar datos y que debe mantenerse en secreto.

14. Llave Pública: Clave criptográfica que se utiliza para cifrar datos y que puede ser compartida públicamente.

15. Pago Electrónico: modulo que permite realizar transferencias entre cuentas de banco Industrial.

16. Pruebas de Certificación: Proceso de validación para asegurar que un sistema o componente cumple con los estándares y requisitos especificados.

17. Pruebas de Integración: Evaluación de la interacción entre diferentes módulos o sistemas para asegurar que funcionen correctamente juntos.

18. Pruebas Técnicas: Evaluaciones que se centran en aspectos técnicos del software, como el rendimiento, la seguridad y la compatibilidad.

19. Referencia: Código o número utilizado para identificar una transacción o documento específico.

20. SFTP (Secure File Transfer Protocol): Protocolo de red que proporciona acceso a archivos, transferencia y gestión de archivos sobre una conexión segura.

21. Tokens de Acceso: Credenciales temporales que permiten a una aplicación acceder a recursos protegidos en nombre de un usuario.

Hilcias Contreras

Rigoberto González