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

Información General

Personal Involucrado

Ventajas, límites y alcances

Proceso de Implementación

Descripción API

Guate ACH

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:

• Guate ACH

Guate ACH es el servicio de envío de transferencias a otros bancos del sistema nacional, que permite agilizar los pagos a empleados o proveedores desde Bi Banking

Para dicha funcionalidad se encuentran habilitada las siguiente opción 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 Guate ACH

• 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 Guate ACH

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 Guate ACH (transferencias entre cuentas de otros bancos del sistema nacional)

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 Guate ACH

Para el envío de lotes de Guate ACH (transferencias a otros bancos) se debe consumir la API de Banco Industrial, S A y se adjunta el archivo cifrado con formato XML de la información proporcionada por el sistema del cliente (ERP)

El formato del documento XML a transmitir por medio del método Transferencia ACH del Servicio Web será el siguiente:

|MÓDULO DE GUATE ACH

Módulo de Guate ACH

Estructura de encabezado

Nombre del Campo Tipo Longitud Máxima

<usuario> Alfanumérico 10

<clave> Alfanumérico 10

<idCliente> Numérico 9

<idConvenio> Numérico 9

<descripcion> Alfanumérico 25

<numeroLote> Numérico 9

<numeroOperaciones> Numérico 9

<montoTotal> Monto 15

Estructura de detalle

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.

Descripción del pago a realizar. (Campo no permite 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 Guate ACH

Sumatoria del monto de las operaciones contenidas en el lote de Guate ACH.

Nombre del Campo Tipo Longitud Máxima

<codigoBancoDestino> Numérico 2

<tipoCuentaDestino> Numérico 1

<numeroCuentaDestino> Numérico 17

<correoNotificacion> Alfanumérico 50

<monto> Numérico 15

Observaciones

Código de Entidad Financeira receptora

Tipos de cuenta: 1 – Cuenta de cheques. 2 – Cuenta de ahorros. 3 – Préstamos 4 – Tarjeta de crédito

Variable por cada banco receptor. (Anexo: Diccionario de cuentas otros Bancos)

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

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

Nombre del Campo

<descripcion> Alfanumérico 25

<referencia> Numérico 6

<idProveedor> Numérico 15

Observaciones

Descripción de la transacción. . (Campo no permite caracteres especiales)

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

Código de identificación del proveedor. (campo opcional- se puede omitir)

<nombreProveedor> Alfanumérico 22 Nombre del proveedor.

NOTA:se maneja una sola moneda de pago por cada lote de Guate ACH.

Detalle de códigos de entidades bancarias

Código

Nombre de la Entidad Financiera

Método

de Procesamiento

Banco Industrial, S A será el encargado de procesar cada operación contenida dentro del lote de Guate ACH, de acuerdo a la compensación diaria, actualmente existen ventanas de tiempo detalladas a continuación:

Métodos de Notificación

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

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 Guate ACH, 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.

2 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

Descripción

XML no encriptado

Archivo enviado sin cifrado.

Error al validar de datos del participante Inconveniente de participantes no adicionados al convenio. (Guate ACH)

17 Error al validar datos del banco

Códigos de Retorno API

Código de Retorno

9999

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 Guate ACH (Respuesta detallada)

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

lotes de Guate ACH se envia la respuesta el día siguiente, del proceso de la transacción en el banco destino, dará inicio a partir de las 6:00 a m

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

ACHDDMMAAAAHHMMSS Lotes de Guate ACH (transferencias a otros bancos del sistema nacional)

El archivo se encuentra compuesto por las siguientes secciones:

• Encabezado del archivo

• Encabezado del lote

• Detalle del lote

Estructura de encabezado del archivo (Guate ACH)

Nombre del Campo Tipo Longitud Máxima

Identificador de registro

Número de registros

Numérico 1

Numérico 9

Estructura de encabezado del lote (Guate ACH)

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

Numérico 1

Numérico 9

Numérico 12

Numérico 2

Observaciones

Valor constante "0" en el encabezado del archivo.

Número de lotes que contiene el archivo.

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 y/o Guate ACH.

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

Código de retorno del encabezado del lote.

Mensaje de retorno Alfanumérico 50 Mensaje de retorno del lote

Códigos de retorno de encabezado del lote (Guate ACH)

Código de Retorno

Descripción

Lote rechazado

Lote de pago no operado.

Lote autorizado

Lote de pago autorizado (autorizaciones predefinidas)

Lote enviado Pendiente de resolución de cámara de compensación.

Lote procesado

Aplicación exitosa del lote.

7 Error al enviar el lote hacia PayBank Rechazo del lote de pago por proceso interno.

Lote cancelado Rechazo del lote de pago por proceso interno.

9 La cuenta principal del lote tiene algún problema Cuenta débito presenta inconvenientes al operar el lote de pago.

10 Lote procesado parcialmente Transacciones del lote de pago aplicadas parcialmente.

Estructura de detalle del lote

Nombre del Campo Tipo

Identificador de registro

ID cliente

ID convenio

Numero lote

Referencia

Autorización

Longitud Máxima

Numérico 1

Numérico 9

Numérico 6

Código de retorno Numérico 2

Mensaje de retorno Alfanumérico 50

Fecha de aplicación 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

PÁGINA | 21 | MÉTODOS

Códigos de retorno del detalle del lote (Guate ACH)

Con autorización Web

Código de Retorno

Descripción

1 Registro Activo

2 Registro procesado exitosamente

3 Registro con error

4 Registro con participante no autorizado

5 Registro cancelado Cuenta crédito en estatus cancelada en la entidad bancaria receptora.

6 Registro en reserva Pendiente liberación de fondos para aplicación de lote de pago.

82 Registro con error, fondos insuficientes Saldo insuficiente para efectuar lote de pago.

Todas las operaciones de Guate ACH se contestarán una vez al día (a partir de las 6:00 p m ) y las de Banco Industrial, S A tantas veces como sea necesario

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 Guate ACH (transferencias a cuentas de otros bancos ACH)

La adición de participantes en convenios de Guate ACH 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

Para el procesamiento de archivos de Guate ACH, 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