Preguntas frecuentes
Para obtener información detallada sobre los lineamientos para APIs gestionadas o servicios, te invitamos a consultar nuestro Portal de Documentación y Lineamientos. Aquí encontrarás todo lo que necesitas saber.
Sí, contamos con un catálogo de fichas que incluye uno o más escenarios de Arquitectura de Integración. Este catálogo está diseñado para habilitar el inicio del diseño por parte del Arquitecto de la Solución (AS). Puedes acceder al catálogo de escenarios de integración en el siguiente enlace: Catálogo de Escenarios de Integración.
Te invitamos a explorar este enlace para profundizar en el tema: SharePoint.
Te compartimos este enlace para que puedas informarte mejor a través de este podcast: Monetización de APIs.
Te invitamos a navegar sobre cada uno de los entornos para que descubras nuestros equipos productores: Equipos productores.
Los roles participantes en los equipos alineados a la estrategia son: Dueño de Producto, líder funcional de EVC, experto técnico, analista SOA, arquitecto empresarial, si deseas conocer mas acerca de como participan los roles te invitamos a ver el siguiente video.
Luego de ingresar al Portal interno de APIs, crear la APP, consultar las credenciales y suscribirte a un producto, debes revisar en la información técnica del producto de APIs que quieres consumir, cuál o cuáles son los mecanismos de seguridad disponibles para este producto y al que previamente debes hacer el llamado, como lo es OAauth, API Key o JWT.
No requieres un certificado firmado para realizar tus pruebas en Sandbox.
En producción, para algunas soluciones será́ requerido y en ese caso te proporcionaremos un certificado y requeriremos la implementación de TLS 1.2.
Una API Key actúa como un TOKEN de autenticación secreto, o como un identificador único. Estas claves vienen junto con un conjunto de derechos de acceso para la API asociada y lograr el respectivo consumo.
Te presentamos una guía práctica para generar y validar JWTs.
JWT (JSON Web Tokens) es un estándar abierto que define una forma compacta y autocontenida para compartir información entre dos componentes como objetos JSON. Esta información puede ser verificada ya que se encuentra firmada digitalmente. Los JWTs pueden ser firmados usando un secreto (con el algoritmo HMAC) o con un par de llaves privada y pública usando RSA o ECDSA.
Un JWT puede ser firmado o cifrado, para este escenario usamos JWTs firmados y en su forma compacta. Un JWT tiene tres elementos:
- Header: Es el que contiene la información de qué algoritmo se usa para firmar el mensaje.
- Payload: Es la información a compartir que se quiere firmar y verificar digitalmente.
- Signature: Es la firma resultado del procesamiento del header y el payload con el algoritmo definido en el header y la llave privada o secreto establecido.
La forma compacta del JWT se conforma de los 3 elementos anteriores separados por punto de la siguiente manera: base64URL(Header).base64URL(Payload).Signature.
Donde el Signature es la firma y se genera firmando el header y el payload.
Ejemplo:
Signature = RSASHA256(base64UrlEncode(header) + "." +base64UrlEncode(payload), llavePrivada)
Y al final queda una cadena similar a esta:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.POstGetfAytaZS82wHcjoTyoqhMyxXiWdR7Nn7A29DNSl0EiXLdwJ6xC6AfgZWF1bOsS_TuYI3OG85AmiExREkrS6tDfTQ2B3WXlrr-wp5AokiRbz3_oB4OxG-W9KcEEbDRcZc0nH3L7LzYptiy1PtAylQGxHTWZXtGz4ht0bAecBgmpdgXMguEIcoqPJ1n3pIWk_dUZegpqx0Lka21H6XxUTxiy8OcaarA8zdnPUnV6AmNP3ecFawIFYdvJB_cm-GvpCSbr8G8y_Mllj8f4x9nBH8pQux89_6gUY618iYv7tuPWBFfEbLxtF2pZS6YC1aSfLQxeNe8djT9YjpvRZA
Instalación y configuración SSL
Para iniciar con la generación de un JWT es necesario tener instalado OpenSSL, aquí veremos el paso a paso de su instalación para el sistema operativo Windows.
- Descargaremos el instalador desde la página SHINING LIGTH PRODUCTIONS desde aquí escogeremos la versión para desarrolladores y el tipo de sistema operativo según sea el caso (win32 o win64).
- Ejecutar el archivo de instalación descargado y seguir las instrucciones como lo muestra las siguientes imágenes:
Al finalizar la instalación nos mostrara la siguiente ventana, desmarcamos las casillas y damos click en Finish.
Para comprobar la correcta instalación del OpesSSL y su versión instalada, procedemos a abrir una ventana de comandos (CMD) y escribimos la siguiente instrucción: openssL version y presionamos la tecla Enter.
Luego de comprobar que la instalación fue correcta procedemos con la generación del JWT.
Generar el JWT
Para generar un JWT usando el algoritmo RS256 se debe contar con una llave privada para firmarlo y con un certificado para verificarlo. Este proceso implica generar una llave privada y certificado de prueba, generar un JWT de prueba y verificar si un JWT es válido con el certificado.
Llave privada y llave pública
Para pruebas
Para pruebas se puede usar un certificado auto firmado, para generarlo se puede usar openssl, el git bash tiene esta herramienta:
Comando:
openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem
Información de EJEMPLO:
- Country Name: CO
- State or Province: ANTIOQUIA
- Locality Name: MEDELLIN
- Organization Name: Mi Organization S.A
- Organizational Unit Name: BANCOLOMBIA
- Common Name: nombreapp.apps.ambientesbc.com
El Common Name es el nombre de dominio de la app para la que se genera el certificado, este nombre es el que se le asigna a la app al momento de crearla en nuestro portal, para efectos de prueba en este caso se asignó el valor nombreapp.apps.ambientesbc.com.
Como resultado se generan dos archivos, la llave privada y el certificado, el primer archivo es el que se usa para firmar el JWT y el segundo es el que se puede usar como llave publica con la cual verificamos la firma del JWT. Al abrirlas con un editor de texto
Key.pem (llave privada).
Certificate.pem (Certificado que contiene llave pública).
Herramienta de prueba para generar y validar JWT
Para generar un JWT con la llave privada de prueba se puede usar la herramienta online https://jwt.io/.
Generar JWT
Para las pruebas se deben ingresan los datos:
Algorithm: RS256
Generar un nuevo Payload con los siguientes pasos.
Donde:
- iss: Es un el nombre de quien genera el JWT, para el caso del banco se debe asignar el AW de la aplicación que genera el JWT.
- sub: Identifica para quien se genera el token, debe ser el client_id de la APP en el portal.
- aud: Identifica el grupo o la audiencia para quien se genera el JWT, este dato puede ser un arreglo, para API Connect debe ser APIGateway_XXX (Donde el xxx son las letras del API GW donde está expuesta la API: LAN, DMZ, AWS).
- exp: Es la fecha en la cual el token expira. Es un número en formato NumericDate. Es un timestamp en segundos. Ejemplo: 1588628816.194 o 1588628816. El JWT deja de ser valido una vez se pase de esta fecha. Para el ambiente productivo este valor no puede ser mayor a 1 minuto después de la fecha de generación del token.
- iat: Es la fecha en la cual se genera el token. Es un número en formato NumericDate. Es un timestamp en segundos. Ejemplo: 1588628816.194 o 1588628816.
Nota: Ejemplo para generar estos valores en Javascript.
var iat = new Date()/1000; //1588630053.851 var exp = iat + 60*60; //1588633653.851
- nonce: Es un valor aleatorio de más de 10 caracteres hexadecimales o 20 numéricos.
- Ejemplo para generar estos valores en Javascript con nonce de 12 de longitud, el exp en el ejemplo es de 1 hora después de la fecha de generación del token para efectos de prueba:
let iat = new Date()/1000;
let exp = iat + 60*60;
let min = 17592186044416;//Hex 1000000000000
let max = 281474976710655;//Hex ffffffffffff
let nonce = Math.floor((Math.random() * (max - min + 1)) + min).toString(16);
let jwtPayload = {
iss: "AW1234001",
sub: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
aud: "APIGateway_DMZ",
exp: exp,
iat: iat,
nonce: nonce
}
console.log(JSON.stringify(jwtPayload));
- Este código se pude ejecutar en cualquier navegador en la consola de inspeccionar (dando f12 o clic derecho->inspeccionar). En la consola ejecutas el Script y obtendrás un resultado similar al siguiente.
Se pega en la sección de payload lo que se imprime en consola.
Y en verify signature donde dice private Key se pega el texto de la llave privada.
Esto hace que en la sección que dice Encoded se genere un JWT válido que se puede enviar a la API.
El JWT generado:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJOb21icmVBUFAiLCJzdW0iOiJiY2Y3ODM1NC1jMDdhLTQyNzMtYTI2YS00OWIyMGFjZDhlNDUiLCJhdWQiOiJCYW5jb2xvbWJpYSIsImV4cCI6MTU4ODYzNDUxOC41NTMsImlhdCI6MTU4ODYzMDkxOC41NTN9.lFnJ0JdgLXYYjHxLVfsmi1crRnVTzpbpfBatQwQpSuGIuekSc9oGvRekVGQeL5so4qr2_7h1mlLN7JkT4s8YUzJiDwy7dIFfs_ebYj5oDqAVTVJN_6KgZUtAdaIaP5pcDX7WOstSZNXfeAcOiXBy4kG-DiRW8KHoNrNN9-pnPOKv4wrhpDTTgAzoILlMwgiakA3ayXXoUUIARnrj7emyJ6DDuT1DDFwPMj64tD4db_8xDKf7Pwb7VWUIXb4HxGUY4cuXIuIO4SW7J9T1JCeBQLTmo6_ttrZaFLfyzlJnGAd_Cp5-gE5K1A-iMp77f7VyaXZctjj8eEP6JYB5OlJoBg
Verificar JWT
Si se desea verificar un JWT se deben ingresar el JWT a verificar en el campo “Encoded” e ingresar en donde dice Public Key or Certificate el certificado con el que se va a verificar el JWT.
Ahora, debe enviarnos el certificado público para poder adjuntarlo a su aplicación, poder autenticarse y realizar el consumo de nuestras APIs. Puede hacerlo a través del chat o formulario contáctanos del Centro de Ayuda.
⚠️ Aquí te hemos brindado unos consejos generales sobre cómo crear y validar certificados y tokens JWT (JSON Web Tokens) en entornos de desarrollo. No es una guía definitiva ni asesoría legal o de seguridad. Es esencial entender que las prácticas recomendadas aquí son para pruebas y desarrollo, no se sugiere aplicarlas en entornos reales sin primero revisarlas con expertos en seguridad. Así mismo, generar tokens JWT involucra información delicada y claves privadas, compartirlas acá o en otro lado es un riesgo.
Cualquier acción que tomes basada en esta información es bajo tu responsabilidad.
La Open Authorization, más conocida como OAuth, es un estándar de seguridad que administra la identidad y el acceso de los consumidores a los productos API. Este protocolo autoriza a una aplicación el consumo de un servicio (aplicación consumidora) sin requerir las credenciales, nombres o contraseñas de los usuarios.
Este mecanismo de autorización puede variar de acuerdo con las condiciones bajo las que se implemente, sin embargo, este mecanismo consiste comúnmente en:
- La aplicación consumidora solicita permisos para acceder a los servicios de la aplicación proveedora, en este caso el producto de API.
- Si el servicio proveedor acepta la solicitud, la aplicación consumidora obtendrá una concesión de autorización.
- Con la concesión de autorización que previamente se ha obtenido, la aplicación consumidora solicita un access token al authorization server.
- El servidor de autenticación confirma la identidad de la aplicación consumidora y valida que la concesión de autorización sea legitima. Si se validan correctamente ambos aspectos el servidor le entrega un access token a la aplicación consumidora.
El access token que obtiene el consumidor, será enviado en la próxima petición que haga a los servicios de la aplicación proveedora y de esta forma, al garantizar que el access token es válido, el servidor que almacena los recursos le dará acceso al servicio.
Es por ello que, en el estándar OAuth, se identifican cuatro roles: el cliente o aplicación consumidora, el dueño del recurso o dueño de la aplicación proveedora, el servidor de autorización y el servidor que almacena y entrega los recursos.
Así mismo, es importante diferenciar la autenticación de la autorización. La primera, por su parte, busca identificar la identidad que un usuario dice ser, mientras que la segunda, concede permisos de acceso a los usuarios autenticados sobre ciertos recursos. El estándar OAuth opera bajo el mecanismo de autorización, determinando quien puede, o no, acceder a las capacidades ofrecidas por los productos de API.
Los beneficios percibidos con este mecanismo de seguridad son varios, por un lado, desde el frente proveedor ofrece un mecanismo eficaz para controlar el permiso y el acceso a sus servicios. Por otro lado, las aplicaciones consumidoras podrán acceder a los servicios solicitados sin la necesidad de revelar sus credenciales a la capa proveedora.
A continuación, te brindamos el paso a paso que debes seguir en Insomnia para configurar el OAuth:
- Ubícate en la pestaña de Auth types.
- Selecciona en type: OAuth 2.0.
- En el campo Grant Type selecciona la opción de acuerdo con el flujo de la API.
- En el campo Access Token URL, verifica que la url sea la correspondiente.
- Registra tus credenciales de Client ID y Cliente Secret, que debes tener generadas al crear la aplicación en el portal.
- Registra el scope correspondiente a la capacidad a consumir, éste lo encuentras en el path de la operación.
-
Para obtener el token, da clic en el botón Fetch Tokens que encontrarás en la parte inferior (cada token tiene una vigencia de 20 minutos).
-
En la casilla access token obtendrás el token generado
Te invitamos hacer uso de este mecanismo durante el consumo de los productos API que así lo requieran, y recuerda, si tienes alguna duda sobre cómo generarlo o cómo usar tu acces token te puedes comunicar con el Centro de Ayuda APIs.
Por un lado, oAuth es un framework que autoriza accesos a recursos de diversas aplicaciones por medio de un token. Mientras que JWT es un protocolo de autenticación que genera, envía y valida el token de acceso.
Es decir, que cumplen objetivos diferentes en el proceso de seguridad y protección de datos.
En la Versión 10 requerirás VPN para los ambientes Desarrollo (DEV) y Certificación (QA), pero para los ambientes de Sandbox y Producción no necesario.
Sin embargo, si te presenta el error de la siguiente imagen, conéctate en la VPN para corregirlo.
Si por tu rol, requieres tener acceso a la plataforma, puedes solicitar acceso siguiendo los pasos descritos en esta guía disponible en la wiki.
Los scopes son un mecanismo de OAauth 2.0 que limita a las aplicaciones el acceso a las cuentas de los usuarios. En el caso de que el API de tu interés tenga uso de una API de seguridad dicho scope debe estar inscrito.
El tiempo de vigencia es de 1200 segundos, es decir 20 minutos.
El Modelo de Reúso es el paso a paso que debes seguir para consumir una API; este modelo te explica en qué ambientes debes consumir y cómo impactar de manera adecuada a los dueños de esas capacidades.
Puedes visitar el artículo donde te explicamos cuál es el paso a paso para realizar la solicitud y las herramientas habilitadas para esto.
Para evitar problemas con tus solicitudes y evitar devoluciones o rechazos, asegúrate de:
- Tener en cuenta en qué etapas del proyecto necesitas ayuda para pruebas y reutilización en la fase de producción.
- Solicitar el reúso con al menos 2 sprints de antelación, ya que la aprobación depende de la capacidad del equipo que provee el servicio.
- Tener muy claras tus necesidades técnicas y de calidad para que, con ayuda del equipo productor, puedas contrastarlas con lo que te ofrece el producto de API.
- Contar con el blueprint, draft de arquitectura y el código único de tu aplicación (encuentra aquí cómo solicitarlo), antes de crear diligenciar el formulario de reúso.
- Si surgen problemas, asegúrate de comunicárselos al equipo proveedor a tiempo para que puedan ajustar sus recursos y ayudar a otros usuarios. Mantener una comunicación fluida es clave para un trabajo exitoso en equipo.
Te invitamos a explorar ¿Qué debes hacer para consumir y reusar una API?
Nuestro canal oficial de comunicación es el Centro de Ayuda, donde podrás acceder a documentación de soporte que te ayudará con la autogestión rápida y sencilla de tus dudas y consultas. Además, ahí mismo puedes usar el chat en vivo o el formulario de contáctanos para conversar con nuestro equipo de soporte de APIs.
Durante el proceso de pruebas te sugerimos revisar el contrato de la API así como los escenarios de pruebas, para comprender en su totalidad las capacidades que te brinda. Esta información la encuentras en el API Portal y en el portal de documentación como código.
Conoce el analista SOA de cada equipo productor y/o EVC en el siguiente enlace: Analistas SOA asignados a cada EVC.
Los portales de APIs, así como el Centro de Ayuda APIs internas está integrado con el directorio activo, por esta razón, los usuarios no requieren un registro o creación de una cuenta y cualquier persona con credenciales banco (correo + contraseña de red), puede acceder a cada uno de ellos. Inclusive nuestro método de autenticación es con Microsoft y con “Single SignOn”, esto quiere decir que si ya estás autenticado en otra de las herramientas de office, cuando ingreses al portal de APIs internas o Centro de Ayuda APIs internas, se tomará la autenticación que ya tienes activa y no tendrás que iniciar sesión nuevamente.
Para poder delegar la organización a otra persona, primero debes añadirlo como usuario a tu organización con algún rol, como administrador, desarrollador o visor; luego de que tenga acceso a tu organización puedes delegársela a este usuario.
Si ya no estarás participando en el proyecto, equipo o presente en la organización, es muy importante que seas precavido y delegues la organización con tiempo a otro compañero del equipo para que puedan seguir gestionando las credenciales de las aplicaciones creadas bajo la misma, sin ningún inconveniente.
Se puede gestionar desde API Connect la delegación de una organización de una persona que ya no está a otro usuario, realizando la solicitud oficial mediante la generación de una OC que gestionará directamente el equipo de IBM, es importante que esta solicitud la realice directamente el responsable o líder técnico del equipo consumidor.
Al final de este artículo puedes conocer los pasos para gestionar la OC.
Insomnia es una aplicación de software que se utiliza para probar y depurar APIs (Interfaz de Programación de Aplicaciones). Permite a los desarrolladores interactuar con APIs, enviar solicitudes HTTP, ver las respuestas, realizar pruebas de rendimiento y depurar problemas de comunicación entre aplicaciones.
Esta herramienta es valiosa para desarrolladores y equipos de desarrollo que trabajan en proyectos que involucran la creación y el uso de APIs, pues facilita la colaboración y permite verificar que estas funcionen según lo previsto. Algunas de sus características más relevantes son: permite configurar solicitudes, administrar colecciones de API, realizar seguimiento de historiales de solicitudes y respuestas, y realizar pruebas automatizadas, entre otras funciones.
Podrás conseguir su versión gratuita aquí
¿Cómo puedes probar nuestras API desde Insomnia?
- Crear proyecto
Para crear un nuevo proyecto, debes ingresar a la aplicación y dar clic en el signo + ubicado en la pestaña projects, allí debes nombrar tu proyecto y dar clic en el botón crear.
2. Desactivar SSL
Realiza la desactivación del SSL para evitar errores durante el consumo de la API.
- Da clic en application
- Luego clic en preferences
- Desactiva la casilla validate certificates
3. Importa colecciones y firmas
- Selecciona el proyecto que previamente se ha creado y en la parte derecha da clic en +. Después dar clic en import
- Se abrirá una nueva ventana donde podremos seleccionar las colecciones previamente descargadas del portal API market
- Selecciona la colección de tu interés y da clic en el botón scan
- Llegarás a otra ventana donde podrás ver la información de la colección. Confirma dando clic en el botón import
- La colección quedará agregada con el nombre por defecto Imported Workspace
- Para personalizar el nombre de la colección dirígete a los 3 puntos que se encuentra en la parte superior derecha de la colección y da clic en rename.
5. Autorización de solicitudes
Las API utilizan la autorización para garantizar que las solicitudes de los clientes accedan a los datos de forma segura. Esto puede implicar la autenticación del remitente de una solicitud y la verificación de que tiene permiso para acceder o manipular los datos relevantes.
En nuestras APIs podrá encontrar el método de autorización en los parámetros de seguridad. Estos son Oauth2.0 (Authorization) o JWT.
5. Realizar consumo
- Configuración campos de token
En el apartado AUTH TYPES debes escoger la opción OAuth 2
Completa los campos con la información correspondiente:
- Grant type: Client Credentials
- Access token url: Aquí se ingresa el endpoint del token (Información que podrás encontrar en el portal API market)
- client ID: Identificador único proporcionado al momento de registrar la aplicación en el portal API market
- Client secret: Clave confidencial proporcionada junto con el Client ID al momento de registrar la aplicación en el portal API market
- En la parte inferior del campo client secret se encuentra la pestaña Advanced Options. Al desplegar, encontrarás un campo que debes llenar con la información del scope (ten en cuenta que cada API cuenta con su propio scope. Esta información la puedes verificar previamente en el API market)
- Para obtener el token, da clic en el botón Fetch Tokens que encontrarás en la parte inferior (cada token tiene una vigencia de 20 minutos)
- En la casilla access token obtendrás el token generado
- Ubícate en la pestaña Headers y verifica que estén todos asignados según la firma y la documentación del portal API market
- Ubícate en la pestaña Other o JSON y revisa que estén todos los campos asignados con los valores a probar.
- En la casilla POST debes ingresar el End Point perteneciente a la API que quieres probar (puedes consultar distintos End Points en la documentación del portal API market)
- Da clic en el botón send
- En la parte derecha obtendrás la respuesta de la petición
¡Excelente! Ahora que has consumido tu API, estás un paso más cerca de desbloquear un mundo de posibilidades. No dudes en repetir este proceso para explorar y aprovechar diversas APIs y enriquecer tus aplicaciones con datos y funcionalidades sorprendentes. El universo de las APIs está repleto de recursos por descubrir, así que ¡adelante y sigue explorando!
Primero debemos buscar el producto y su API, haremos un ejemplo con el producto Accounts y la API de Fund Transfers:
Desplazamos la página hacía abajo y consultamos las operaciones:
Seleccionamos la primera y hay que revisar los apartados de seguridad y Header:
En el apartado de seguridad se indica que es necesario enviar client id y client secret como cabeceras de la petición; adicional en el apartado de header se nos indica que requiere de un JWT y un Certificado para poder consumir.
Un ejemplo con otro producto, en este caso Electronic Signature - Composite Signature, igualmente revisamos los apartados de seguridad y header:
El apartado seguridad solamente nos pide client id y secret, pero ahora en el apartado de header adicional nos pide un usuario y token.
Los features y las colecciones son archivos que utilizan los consumidores para realizar peticiones al sandbox de un api particular y obtener información de esta. Se cargan al bucket y a la plataforma cuando se ejecuta el pipeline de build.
Si estás experimentando errores en la construcción o configuración del sandbox, te invitamos a leer la siguiente información: Errores comunes en la configuración del sandbox.
Puede servirte de ayuda para solucionarlos.
En el siguiente sitio te explicaremos cómo consumir el sandbox una vez que se ha creado para cada API con todos sus escenarios y su despliegue ha finalizado correctamente: ¿Cómo consumir el sandbox?
A continuación podrán encontrar información detallada sobre la manera de configurar y desplegar el sandbox para las APIs de API Connect 10: Construcción y despliegue del sandbox.
Conoce cómo construir y publicar la documentación de negocio de tus productos APIS en el siguiente sitio.
La Hoja de orientación para la construcción de APIs es una herramienta que te ayudará como punto de partida. Detalla cada paso, proceso, tarea y resultado necesario para completar la construcción total de APIs y servicios. Puedes utilizar esta hoja de orientación para guiar tus primeros pasos en el desarrollo de APIs de manera efectiva.
Consiste en la automatización de la generación de contratos a partir de un nuevo formato de descripción de operaciones (DO) y la ejecución de un pipeline. Este procedimiento es aplicable tanto a la creación de un nuevo producto API, una API o una operación, así como a su modificación.
Verifique la guía rápida para analistas SOA : Guía rápida proceso de industrialización APIS.
Al equipo de desarrollo, se sugiere compartirles la rama donde ejecutamos la generación del pipeline para que tomen lo que puedan necesitar. Ejemplo, los .feature que se llaman "contractTest" es lo que aprovechan los desarrolladores para agilizar las pruebas.
Sin embargo, ten presente que en el repo "Template_ServiciosIntegracionAPIs_Documentacion" los insumos que se suben son el contrato de la(s) API y las acceptanceTest.feature.
Revisa que no le hayas cambiado el formato al archivo, específicamente que las celdas del DO estén con todos los bordes.
Cuando este mensaje está asociado a la longitud máxima o mínima de un campo, significa que hay un campo en el DO que tiene filas compartidas, por allí debes buscar la corrección.
Este error se muestra en el stage de API Contract relacionado con esta descripción "409nombreFuncionalOperación", soluciónalo borrando los caracteres como espacios, tabs o saltos de línea al inicio o final del nombre funcional en la portada del DO.
Si, es necesario montar el contrato beta generado y los escenarios .feature.
¡Nos alegra que estés en proceso de vinculación al Modelo de Soporte a Desarrolladores! como tus capacidades comenzarán a ser soportadas por el Centro de Ayuda APIs internas, será necesario que nos brindes información relevante y precisa sobre tus productos para transferir este conocimiento a los agentes de primer nivel. Ellos serán quienes brinden la atención y el soporte en primer contacto con los usuarios.
Es por ello que necesitamos que realices algunos videos (máximo de 20 minutos) donde expongas la siguiente información:
- Del negocio: cuéntales acerca de tus productos, para qué son, cómo los utiliza tu consumidor y cuál es la lógica de los productos de APIs.
- El equipo: a veces obviamos cosas, sin embargo, saber quiénes conforman el equipo, en que EVC se encuentran, si hay stand-by o cómo manejar los horarios en los que se reciben los casos, es un complemento perfecto para saber escalar correctamente los casos en segundo nivel.
- Los requerimientos no funcionales: ayúdales a entender dónde se encuentra la información que debe tener en cuenta en el consumo de APIs.
- Sandbox: toma las APIs de más demanda y consúmelas en Insomnia, con el fin de hacer práctica la capacitación.
- Para tus productos de APIs internas, el proceso de reúso: indícales si dentro del proceso realizan actividades adicionales o diferentes al proceso estandarizado.
Aquí te dejamos un video, para que puedas grabar sin inconvenientes el tuyo. Una vez los tengas entra a esta carpeta, busca el nombre de tu equipo y cárgalos.
En el sitio de gobierno encontrarás el paso a paso para generar el reúso de las APIs del equipo productor. Te dejamos una guía gráfica:
Ten presente estos prerrequisitos durante el proceso:
1. Para crear la aplicación debes contar con un identificador UN o AW.
2. Cuando llenes el formulario de reúso, debes tener definidos los RNF, Blueprint y aplicación (AW o NU).
3. En caso de que tu aplicación no tenga conexión con API Connect debes hacer el pedido de reglas de firewall.
4. Si se requiere adaptar data de prueba se debe crear dependencia en VSTS al back para el sprint en el que se espera estar en certificación.
Para consumir la grabación (creación o actualización) de LME, se hace por límite de endeudamiento, es decir, si se requiere grabar el limite de varios productos de un mismo cliente, se debe enviar la misma cantidad de peticiones a la API.
Dentro de los campos de la petición se encuentra los campos de paginado:
| Nombre del Campo | Descripción | Dominio de Valores | Cardinalidad | Tipo de Dato |
| requestPagination |
Datos de control de paginación. | -------------- | 0...1 | Object |
| pageSize |
Cantidad de registros a ser retornados por página. | NA | 1...1 | Number |
| pageNumber | Número de página a consultar. | NA | 1...1 | Number |
El objeto de paginación, como dato de entrada, es opcional y depende del consumidor, es decir, que depende de cómo lo requieran visualizar y si se requiere la información en una misma página.
Es importante tener presente que en el back si se tiene una restricción de visualización el cuál es máximo de 46 registros por página, es decir que, si son más de 46 registros, se irán mostrando en la página siguiente.
Los mensajes de error los consolidamos en el BP400, los 404 y los errores 500, teniendo en cuenta la naturaleza del error.
Tal y como está definido en el modelo de reúso primero debes hacer pruebas en sandbox, después diligenciar el formulario y una vez este aprobado el reúso se valida el blueprint, RNF (requisitos no funcionales) y que si hayan tenido pruebas en sandbox. Después de eso, el equipo productor te aprueba la suscripción en los otros ambientes.
Desde la API no es necesario controlarlo; sin embargo, en las políticas de riesgo para créditos de vivienda dice que el monto mínimo es de 40 SMMLV.
Si tienes alguna inquietud de vivienda en cuanto a la política de riesgos lo puedes hablar con Leidy Johana Barco.
Conoce más sobre el crédito de vivienda aquí.
Si necesitas hacer adecuación de datos para tus consultas, deberás solicitar al PO de la célula CCRED01: Ecosistema de Riesgo Transversal Sergio Andrés Henao Betancur la adecuación de los clientes en el ambiente de certificación del Ecosistema.
- El responsable debe enviar un correo al PO CCRED01 (Sergio Andrés Henao Betancur) con copia a la PO Célula CCRED02 (Lucy Vargas Muñoz) y PO Célula CCRED14 (Juliana Medina Martínez)
- El asunto: “Solicitud de datos Ecosistema – Descripción según la necesidad”.
- Este correo se debe enviar mínimo 20 días antes de la fecha. Se deben enviar antes de la planeación del sprint.
- Adjuntar la información requerida para cada cliente y por cada llamado del Ecosistema (CI, CE, Precálculos, Llave MDM).
- Especificar la fecha en la que se requiere la información disponible.
Las tasas de interés que nos devuelven las APIs de Ecosistema de Riesgo de Crédito son tasas EA (efectivo anual).
Únicamente tendrás que solicitar la adecuación de los datos cuando tus consultas o pruebas sean muy especificas y el set de clientes que se tiene adecuado no cuenta con la información que requieres.
El horario en el que la API funciona puede ser parametrizable en MAP (Modulo Administrativo del producto).
Se debe avisar con anticipación debido a que las APIs funcionan con recursos limitados en ambientes preproductivos.
No se replica sino que se toma el mismo que viaja en la petición del consumidor para enviar a MDM.
Sí, nuestras APIs se encuentran disponibles para ser reusadas, consulta el proceso ingresando a nuestro sitio de gobierno de APIs.
Para hacer uso de SSO es necesario que el canal origen se encuentre habilitado para delegar sesión en la parametrización de SUA, si es así, solo se requerirá el token de sesión para autenticar nuevamente al cliente en el canal destino.
El flujo actual modelo objetivo de FUA/SUA se encuentra desplegado en nube AWS. Las versiones onprimises serán deprecadas y por ende no se darán más reúsos sobre las mismas.
El redirectUri es la URL de redirección al front al cual se direccionará al cliente una vez la autenticación haya sido exitosa y se haya generado el correspondiente token de sesión.
Un pinblock es una cadena cifrada en formato hexadecimal de 512 caracteres que contiene la clave principal y algunos datos sensibles del cliente que está realizando el proceso de autenticación.
Para generar un pinblock, se debe primero tener un usuario de prueba proporcionado por el equipo de EMMA, que se pueda autenticar por APP o SVP o en su defecto por el FUA (Front).
Teniendo los datos de dicho usuario se procede a crear un HA en el tablero del equipo Avengers 2.0 cuyo fin sea la solicitud de generación del pinblock.
En la mesa técnica se revisan los RNF del consumidor interesado en reusar las capacidades. Internamente se valida si actualmente desde los equipos se soporta dicha transaccionalidad o no.
El código de autorización tiene una duración de cinco (5) minutos para todos los ambientes (DEV, QA y PDN).
- En ambiente de desarrollo debes enviar correo con la solicitud al buzón: datosmaestros@bancolombia.com.co
- En ambiente de certificación debes realizar la solicitud con EMMA: Proceso solicitar datos certificación (debes estar conectado a la vpn)
Debe solicitar la capacidad a través del formulario de reuso. Una vez se recibamos la solicitud te enviaremos un correo solicitando la siguiente información:
- Confirmación funcional de cada una de las API (validación del uso de los campos en la API): acá debes confirmar que se validaron los campos (mencionar los campos) y que se están obteniendo de forma correcta (imagen con la evidencia, donde se observe la respuesta con los campos requeridos).
- Plan de pruebas en ambientes previos (DEV, QA): es necesario que nos compartas tu Plan de Pruebas en VSTS tanto DEV como QA. Así como el resultado de pruebas de estrés o carga, en caso de no haberlas realizado, compártenos el motivo porque el que no se hicieron.
Dado que MDM es el maestro de clientes para el banco y que contiene información sensible, confidencial y que puede impactar varios procesos, tenemos unos pasos exclusivos para los reúsos de nuestros productos APIs: solicitar la aprobación de la GSIC.
Para conocer nuestro proceso de reúso puedes ingresar al Portal Funcional de MDM (debes estar conectado a la VPN)
- Ten en cuenta que MDM tiene alta demanda de reúso por sprint, por lo que la reserva de capacidad que se realiza se hace por sprint y por ambiente, es decir, en un sprint solo atendemos un ambiente (DEV, QA, PDN). Por lo tanto, si requieres pasar a otro ambiente en el siguiente sprint o continuar con el apoyo debes diligenciar el formulario de reúso .
- Las solicitudes se reciben hasta el viernes antes del inicio del sprint, dado que el lunes se analizamos la capacidad del equipo.
- Si el consumidor no requiere la capacidad solicitada en el sprint, nos debe informar mediante correo para poder asignar esa capacidad a otro consumidor que se encuentre en espera.
Las APIs de MDM devuelven los valores de catálogos en formato MDM (APIC10) por lo tanto, si requieres la descripción para mostrarlo en la experiencia (Ejemplo: La API le retorna ROLNEG_01 y el consumidor requiere saber la descripción) contamos con servicios batch y online para consultar los catálogos y sus descripciones.
Por lo tanto:
- Si requieres consultar una descripción de un catálogo puntual (1 a 1) puede hacer uso del API de catálogos maestros “Reference Data Management - Master Catalogue”. Ejemplo: requiere consultar a que equivale el ROLNEG_01 para un cliente.
- Si requieres consultar todos los valores de catálogos de MDM o todos los valores de un catálogo (Ejemplo: requiere consultar la descripción de todos los códigos CIIU) debe hacer uso del servicio batch de catálogos del back de MDM (PKG_CATALOGOS).
- Si requieres consultar la descripción de Países, Departamentos y Ciudades debes hacer uso del servicio batch de Catálogo Geográfico del back de MDM (PKG_CATALOGOS_GEOGRAFICOS.
Es común que los consumidores conozcan los nombres funcionales de los campos, pero cuando van al DO o a la documentación no identifican la API que contiene el campo.
En MDM contamos con un portal funcional para que los consumidores puedan revisar en que API se encuentra el campo que requieren, para posteriormente solicitar la asesoría con el Analista SOA y mapearlo al API y al nombre técnico.
- Portal Funcional MDM (debes estar logueado en la VPN).
En este caso la definición de la regla depende del proceso, por lo que te recomendamos que solicites una asesoría con la GSIC en caso de que tengas dudas. Con ellos podrás revisar el proceso y definir cuál sería el criterio de selección. La asesoría debe solicitarse a través del siguiente formulario de teams: Portal de Asesorías GSIC.
-
Proceso Impactado: Administrar información de clientes
Tipo de Asesoría: Asesoría Funcional de MDM
Puedes realizar llamados a las APIs, en ambiente productivo, 7x24.
La API entregará la respuesta, en la que se indica si la persona consultada se encuentra reportada o no en la lista de control y el tipo de reporte asociado a las listas.
- 0 = Datos Incompletos
- 2 = Alerta
- 3 = Bloqueo
- 5 = Sistema / Producto no autorizado a consultar Listas de control
- 6 = No está en Listas de Control
Sí, en el campo state retornará estado No Vigente que se refiere a que la persona estuvo reportada previamente, pero a la fecha de la consulta, no se encuentra vigente en las categorías consultadas.
La API te devolverá el código 6 en el campo alerts, el cual indica que la persona consultada NO se encuentra reportada en lista de control.
Sí, la API responderá la(s) categoría(s) en las cuales se encuentra la persona reportada, separadas por coma.
Los catálogos se utilizan en la gestión de oportunidades, creación de intenciones y gestión de intenciones ya que hay campos tipo catálogos en la API que tienen verificaciones y que exigen que sea un valor válido, por ello el consumidor tiene 2 opciones:
- Utilizar la API de catálogos para conocer las opciones de cada catálogo.
- Generar una equivalencia del valor que presenta en el front vs el valor del catálogo.
Este producto les ofrece a los consumidores la posibilidad de crear, consultar y gestionar necesidades que los clientes manifiestan y que no fueron entregadas a partir de las oportunidades comerciales y nacen desde los deseos de los clientes por medio de los diferentes canales de la Entidad, dependiendo de su segmento (Personas o Empresas, pyme y corporativo).
Nuestro reto parte de buscar una solución que permita a los consumidores crear, consultar y gestionar intenciones comerciales habilitando 6 Apis que permita realizar dichas acciones, clasificadas de la siguiente manera:
| Personas | Pyme, empresas y corporativo | |
| Creación | X | X |
| Consulta | X | X |
| Gestión | X | X |
Es el deseo de algo que el cliente quiere pero que no ha pasado por el proceso de generación, priorización y distribución y no sabemos si tiene la viabilidad o no del producto y por lo tanto no ha sido enviada por del modelo de oportunidades comerciales. Puede ser generada por un comercial o por el mismo cliente.
Es el identificador único de la oportunidad y esta compuesto por:
- Documento del cliente
- Tipo de documento del cliente
- Código de acción
- Indicador de numero de gestiones
- Fecha de vencimiento.
¿Por qué es importante el OportunityID?
El Oportunity ID se entrega en cada respuesta que se entrega del Api de consulta y es necesario para devolver la gestión ya que con este dato se identifica claramente a cual oportunidad del cliente es a la que hay que realizarle una gestión.
Un código de producto puede estar en varias oportunidades, ejemplo:
| CODIGO_ACCION | PRODUCTO_CONSOLIDADO |
CODIGO_ PRODUCTO_ CONSOLIDADO |
OFERTA |
| 5013 | Crédito libre inversión | 14 | Cuenta con preaprobado disponible para Retanqueo libre inversión |
| 5068 | Crédito libre inversión | 14 | Cuenta con preaprobado disponible para Retanqueo libre inversión plan P12 |
| 5072 | Crédito libre inversión | 14 | Cuenta con preaprobado disponible de Libre inversión en digital |
| 5004 | Compra de cartera crédito libre inversión | 14 | Cuenta con preaprobado disponible de compra de Cartera de Consumo |
¿Qué es un código de acción?
Es el código que se asigna para identificar una oportunidad comercial
¿Qué es un código de producto?
Es el código del producto asociado a una oportunidad, ejemplo: una oportunidad asociada a tarjeta de crédito
No es necesario, puesto que el productor controla las peticiones según los lineamientos del banco.
No. Las APIs envían la información a depósitos o medios de pagos y ellos rechazan la operación por diferentes motivos: No tener fondos suficientes, estados de tarjeta, estado de la cuenta, entre otros.
La referencia es obligatoria para cualquier operación de recaudos, y puede tener hasta 3 referencias en una operación.
Tenemos varios filtros, uno de ellos es obligatorio: el estado del convenio, es decir, que se muestren todos los convenios o solo los activos. También se pueden filtrar los convenios por canal, numero de convenio, tipo y número de identificación.