Resumen

Los servicios parametricos son una nueva funcionalidad incorporada en el API Ceibo ( o API Tarjeta habientes ) .

Esta funcionalidad permite crear nuevos servicios dentro del API de Ceibo tan solo configurando datos en tablas parametricas.

La esencia de esta funcionalidad es poder agilizar los procesos de desarrollo, automatizando la comunicacion entre el consumidor de un servicio (Ej: Frontend) y la base de datos (Ceibo), sin la necesidad de tener que programar por cada nuevo procedure un nuevo servicio que lo invoque.

En resumen, esta funcionalidad permite convertir un Procedimientos Almacenados en Servicios RESTFull que retornen JSON y que pueden ser invocados por cualquier programa.

Restricciones y Limitaciones

El uso de esta funcionalidad tiene unas de restricciones y limitaciones las cuales detallaremos a continuacion.

Servicios

Request:

Los servicios que son disponibilizados a traves de las parametrizaciones SOLO pueden recibir JSON como parametro de entrada.
Los unicos tipos de datos aceptados son NUMERO/TEXTO/FECHA. El tipo de dato FECHA debe enviarse como un texto en formato dd/mm/yyyy o dd/mm/yyyy hh24:mi:ss.
Mas adelante se detallarán ejemplos de como invocar a los servicios.

Response:

La respuesta del servicio siempre sera un JSON.
El API no evalua, ni evaluará el resultado exitoso o no, de lo retornado por SP. Solo se limita a ejecutar el procedure y devolver el resultado.
- Si deben hacer controles adicionales de lo retornado por el Servicio, esta actividad queda a responsabilidad del invocador del Servicio.
Para los diferentes tipos de datos que puedan ser retornados desde el procedure, el api SIEMPRE devolverá una representacion de un STRING del dato.
El Servicio siempre devolverá una representacion de un STRING de cada dato retornado desde el Stored Procedure

Procedimientos Almacenados

Los procedimientos almacenados configurados deben cumplir obligatoriamente con los siguientes criterios:

Criterios Generales

Los procedimientos almacenados deben existir en @BAPY o en @OLPY. El API no se conecta a ninguna otra Base de Datos.
Los procedimientos deben poder ser vistos e invocados por el usuario: CREDITOPY.
Los procedimientos configurados deben estar programados de tal manera que PRIMERO se definan los parametros de ENTRADA , luego los de SALIDA.

Parametros de Entrada / Salida:

Entrada:

Solo son soportados los siguientes tipos de datos para los parametros de entrada:

Número (Number, Double, Decimal, etc. )
Texto (Varchar, CHAR, CLOB )
Fecha (Date)
Obs: Cuaquier otro tipo de dato será tratado como por el API como un String.

Salida:

Solo son soportados los siguientes tipos de datos para los parametros de salida:

Número
Texto
Fecha
Cursor
Obs: Cuaquier otro tipo de dato será tratado como por el API como un String. Con los eventuales errores que esto pueda conllevar.

Plataforma de los Servicios Paramétricos

Diagrama

Los servicios paramétricos son consumidos desde un servicio principal que recibe los parámetros de acceso (ruta o path del Servicio) y los datos de entrada (de enviarse) , busca los datos parametrizados para el servicio, y luego ejecuta el SP configurado, retornando la respuesta.

SISTEMAS > Servicios Parametricos / SP Services > DiagramaAPICeibo.png

API Ceibo / API Tarjeta Habientes

Todos los servicios habilitados o ha habilitarse serán invocados a través de un servicio principal o raíz que se encuentra en el API. Este servicio se encarga de las validaciones, verificaciones, configuración, ejecución y retorno de la respuesta de la ejecución del procedimiento almacenado que fue configurado

Link raíz del Servicio

http://host/ws-tarjetahabiente/prmservices/v1/sprunner/prmGroup/prmVersion/prmServicio

Donde:

prmGroup: Parámetro de grupo del Servicio Habilitado
prmVersion: Parámetro de grupo de la Versión del Servicio
prmServicio: Parámetro del Nombre del Servicio

Invocación del Servicio

Request:

La

Response:

La.

Base de Datos

Todas las configuraciones para los Servicios paramétricos se hacen en la base de datos BAPY CEIBO

Paquete PL/SQL

CREDITOPY.PKG_API_CEIBO

Todas los métodos necesarios para que los servicios otorgados por el API Paramétrico funcionen se encuentran en este PKG.

Observaciones IMPORTANTES !!:

La idea de este PKG es ser un package aislado, por lo cual dentro de este package SOLO deben existir los métodos relacionados al funcionamiento de la parametrizacion del SPs como servicios
En resumen, NO INCLUIR AQUI:
- Códigos PARTICULARES, PROPIOS del Proyecto en si y NO de este PKG
  - No agregar procedures, funciones, types, referencias, etc.
- No tocar este PCK salvo si sea para hacer ajustes en el API Paramétrico

Tablas de Configuracion

DER:

Detalle de Tablas:

CAMPOS
Tabla:	API_CEIBO_PROCEDURES
Descripcion:	Tabla principal de configuraciones de los servicios parametricos. En esta tabla se configuran los procedures que seran invocados, la base de datos donde esta alojado el SP y el path de accesion en el API
id_api_sp	Id único de la tabla
categoria	Dato informativo sobre la categoria en la que estan divididos los servicios o endpoints. (comercios / autorizaciones / entidades / ceibo / etc. )
descripcion	Descripcion del proposito del servicio / procedure
api_path_group	El grupo o bloque en el que esta agrupado el servicio. Ej: {group}/v1/getDatos
api_path_version	La version del servicio disponibilizado. Ej: tarjetas/{version}/getDatos
api_path_name	El nombre del servicio. Ej: tarjetas/v1/{servicio}
procedure_database	La base de datos en las que es ejecutado el Procedure (BAPY / OLPY)
procedure_schema	El nombre del esquema en el que se encuentra el procedure. Obs: El usuario que ejecuta el SP es CREDITOPY, asi que debe tener permisos de ejecucion sobre el esquema.pkg.procedure
procedure_name	El nombre del procedimiento almacenado a ejecutar. Obs: Configurar aqui el procedure procedure_name o pkg_name.procedure_name, sin el esquema. El API concatenará durante la ejecucion el esquema.sp_name o esquema.pkg_name.sp_name
simplificar_response_s_n	S/N. Indicador que permite simplificar el response del API en el caso de que tenga un solo item de respuesta
fecha_hora_ins	Fecha / hora de insercion del registro
usuario_ins	Usuario de Insercion
fecha_hora_upd	Fecha Hora de Actualizacion del registro.
usuario_upd	Usuario de Actualizacion del registro.

CAMPOS
Tabla:	API_CEIBO_PROCEDURES_PRMS_IN
Descripcion:	Tabla hija de la tabla anterior y tiene como funcion registrar el detalle de los parametros de entrada con los que cuenta el procedure configurado
id_api_sp	Id del SP del API. FK a la tabla: API_CEIBO_PROCEDURES
param_name	Nro de Orden en el que se encuentra el parametro de entrada
param_name	Nombre del parametro recibido desde el API
tipo_dato	Especifica el tipo de dato permitido. Valores permitidos: NUMERO TEXTO FECHA Obs: Fecha en formato: dd/mm/yyyy o dd/mm/yyyy hh24:mi:ss
requerido_api_s	S/N. Indicador si el dato debe ser enviado o no desde el request del servicio
nulable_s_n	S/N. Indicador que especifica si el valor puede ser enviado como nulo
default_value	El valor por defecto del parametro. Los datos deben ponerse en lenguaje SQL. Ejemplo para los TEXTOs se debe por el valor entre comillas ej: 'some text'

CAMPOS
Tabla:	API_CEIBO_PROCEDURES_PRMS_OUT
Descripcion:	Tabla que registra el detalle de los parametros de salida con los que cuenta el procedure configurado
id_api_sp	Id del SP del API. FK a la tabla: API_CEIBO_PROCEDURES
param_name	Nro de Orden en el que se encuentra el parametro de salida
param_name	Nombre del parametro de salida con el que se retornara el dato en el API
tipo_dato	Mapeo del tipo de dato que es retornado por el SP. Este dato se utiliza para la creacion del statement de ejecucion del SP contra la base de datos. Especifica el tipo de dato permitido. Valores permitidos: NUMERO TEXTO FECHA CURSOR ESTRUCTURA Obs: El tipo de dato "ESTRUCTURA" es un tipo de dato personalizado que representa el primer registro retornado por un Cursor. El API toma este tipo de dato y lo devuelve como un objeto JSON en lugar de como un Array JSON.
retornar_api_s_n	S/N. Indicador que especifica si el valor de este parametro de salida debe ser o no retornado dentro del response del API

CAMPOS
Tabla:	API_CEIBO_USERS
Descripcion:	En esta tabla se registran los usuarios de aplicacion/login que es utilizado por el API para autenticarse y luego ejecutar los procedimientos almacenados
id_usuario	Id único de la tabla
usuario	Sigla del Usuario
password	contraseña
fecha_alta	fecha de alta

Configuracion de Servicios

Configurando Nuevos Servicios

Segun lo expuesto mas arriba para agregar nuevos servicios se debe:

Contar con Procedimiento Almacenado (en BAPY/OLPY, parametros de entrada, luego salida, etc.)
Configurar el mismo en las tablas de configuraciones

Consumir Servicios Configurados

Segun lo expuesto mas arriba agregar nuevos servicios