Shori SDK — Multi-plataforma

SDK multi-plataforma desarrollado por Jerson Omar Ramírez Ortiz de NTT DATA para integrar aplicaciones con la plataforma Syntpony Process Management (Shori). Compatible con Java, TypeScript, JavaScript, python, NestJS, Express, React, Next.js, Node-RED y Axetflow.

¿Qué es Shori?

Shori es la plataforma Syntpony Process Management de NTT DATA — una solución empresarial completa para la gestión integral de procesos de negocio. Está diseñada para organizaciones BPO (Business Process Outsourcing) y para cualquier empresa que necesite orquestar, automatizar y dar trazabilidad a sus flujos operativos de extremo a extremo.

Con Shori puedes hacer prácticamente todo lo que ofrece una plataforma SPM completa:

📋 Gestionar casos — Crear, actualizar y hacer seguimiento de tickets, solicitudes, incidencias o cualquier unidad de trabajo dentro de un proceso.
🔄 Automatizar flujos — Definir estados, transiciones y reglas para guiar el ciclo de vida de cada caso según las reglas de negocio de tu organización.
📁 Centralizar documentos — Adjuntar, versionar y recuperar archivos y contratos asociados a cada caso desde un repositorio centralizado.
👥 Identificar usuarios — Consultar y validar los operadores, supervisores y agentes que participan en los procesos.
📊 Trazabilidad end-to-end — Registrar comentarios, auditar cambios de estado y obtener el historial completo de cada caso.
🔔 Orquestación de procesos — Conectar múltiples sistemas y equipos a través de un flujo de trabajo unificado.
📈 Visibilidad operativa — Conocer en tiempo real el estado de todos los procesos activos de la organización.

Casos de uso típicos

Industria	Caso de uso
BPO / Contact Center	Gestión de tickets de soporte, incidencias y reclamaciones
Banca y Seguros	Tramitación de solicitudes de crédito, siniestros y onboarding
Telecomunicaciones	Flujos de activación, portabilidad y atención al cliente
Retail y Logística	Seguimiento de pedidos, devoluciones y reclamaciones
Sector Público	Gestión de expedientes, trámites y servicios ciudadanos

¿Qué es este SDK?

El Shori SDK es un ecosistema de librerías desarrollado por Jerson Omar Ramírez Ortiz de NTT DATA para integrar cualquier plataforma con la API REST de Shori. Abstrae toda la complejidad del protocolo HTTP, la autenticación OAuth, la paginación automática y el manejo de errores.

SDKs disponibles

Plataforma	Paquete	Versión	Descripción
☕ Java	`shori-api-client`	`1.0.6`	SDK Java para Spring Boot, standalone y batch jobs
🔷 TypeScript / JavaScript	`shori-api-client-ts`	`1.2.7`	SDK para NestJS, Express, React, Next.js y Node.js
🌊 Axetflow / Node-RED	`axetflow-shori-nodes`	`1.3.5`	Nodos visuales — sin código, arrastra y conecta
🌊 Python	`shori-api-client-py`	`1.0.5`	SDK para puthon

Nota: Estos SDKs no son el cliente oficial de la plataforma Shori. Es una iniciativa creada para estandarizar y simplificar la integración con Shori en los proyectos de automatización.

Características principales

✅ API fluida — Builder pattern para configuración y llamadas encadenadas en todos los SDKs
✅ Thread-safe (Java) / async-native (TS) — Instancia única compartible en Java; async/await nativo en TypeScript
✅ Auto-renovación de tokens — El token Bearer se obtiene y renueva automáticamente en todos los SDKs
✅ Auto-paginación — searchAll() pagina automáticamente hasta obtener todos los resultados
✅ Tipado completo — Objetos y clases nativas en Java (Lombok); interfaces y DTOs en TypeScript; nodos configurables en Axetflow
✅ Manejo de errores estructurado — Excepciones específicas por tipo de error en Java y TypeScript
✅ Multi-ambiente — Soporte para DEV, UAT y PROD con URLs pre-configuradas en los tres SDKs
✅ Compatible con cualquier stack — Spring Boot, NestJS, Express, React, Next.js, standalone scripts, Axetflow y Node-RED

Arquitectura del SDK

Propósito: Un ecosistema de librerías multi-plataforma que unifica y encapsula todos los endpoints de Shori en componentes reutilizables para Java, TypeScript/JavaScript y Axetflow. El objetivo es evitar que cada proyecto configure peticiones HTTP, autenticación y manejo de errores de forma manual, aislando los cambios de la API externa en un único lugar.

Beneficios del SDK (Por qué usamos esta solución)

Cero código duplicado: Evita que cada microservicio o proyecto reescriba los mismos clientes HTTP, mapeos de JSON y configuraciones de red para Shori — independientemente del lenguaje o framework.
Mantenimiento en un solo punto: Si la API de Shori cambia un endpoint, una URL o un parámetro, solo se actualiza este SDK. Todos tus proyectos — Java, TypeScript o Axetflow — se benefician automáticamente sin cambios en su código.
Tipado estricto y autocompletado: Transforma respuestas JSON crudas en objetos y clases nativas: POJOs en Java, interfaces TypeScript en TS/JS, y nodos configurables en Axetflow — siempre con autocompletado del IDE.
Integración en minutos: Para usar Shori en un nuevo proyecto, basta con agregar la dependencia Maven, instalar el paquete npm, o instalar desde el Palette de Axetflow — y llamar a ShoriClient / ShoriClientBuilder.
Abstracción de errores: Centraliza el manejo de códigos de estado HTTP (400, 401, 403, 500), devolviendo excepciones tipadas en Java y TypeScript, y mensajes claros en los nodos de Axetflow.

Inicio rápido

☕ Java
🔷 TypeScript / JavaScript
🌊 Axetflow / Node-RED

1. Agregar la dependencia Maven

<!-- 1. Repositorio del SDK (GitLab Package Registry — público) -->
<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.com/api/v4/projects/84253138/packages/maven</url>
  </repository>
</repositories>

<!-- 2. Dependencia -->
<dependency>
  <groupId>com.nttdata.shori</groupId>
  <artifactId>shori-api-client</artifactId>
  <version>{SDK_VERSIONS.java}</version>
</dependency>

2. Inicializar el cliente

ShoriClient client = ShoriClient.builder()
    .environment(ShoriEnvironment.PROD)
    .portalId("tu-portal-id")
    .tenantId("tu-tenant-id")
    .apiKey("tu-api-key")
    .build();

3. Crear y buscar casos

// Crear un caso
CasoCreateResponse nuevo = client.caso().create(
    CasoCreateRequest.builder()
        .casoTypeId("tipo-solicitud-uuid")
        .formId("formulario-uuid")
        .priority("prioridad-uuid")
        .submittedData(Map.of(
            "nombreCliente", "Ana García",
            "tipoServicio",  "PORTABILIDAD"
        ))
        .build()
);
System.out.println("Caso creado: " + nuevo.getCaso());

// Buscar todos los casos abiertos de un tipo
ProductResponse tipo = client.caso().casoType().findById("tipo-solicitud-uuid");
List<String> estadosAbiertos = ShoriUtils.openStatesIds(tipo);

List<CasoSearchResponse> casos = client.caso().searchAll(
    CaseFilter.builder()
        .casoTypeId(FilterOperator.EQ, "tipo-solicitud-uuid")
        .workingSubStateId(FilterOperator.IN, estadosAbiertos.toArray(new String[0]))
        .build()
);
System.out.println("Casos abiertos: " + casos.size());

// Cerrar el cliente al finalizar
// - Script/test: usar try-with-resources → close() automático
// - Spring Boot: @Bean(destroyMethod = "close") → Spring lo gestiona
// - Manual: client.close()
client.close();

📖 Guía completa de instalación y configuración Java →

1. Instalar el paquete

npm install shori-sdk-ts
# o con pnpm
pnpm add shori-sdk-ts

2. Inicializar el cliente

import { ShoriClientBuilder, ShoriEnvironment } from "shori-sdk-ts";

const client = new ShoriClientBuilder()
  .environment(ShoriEnvironment.PROD)
  .portalId("tu-portal-id")
  .tenantId("tu-tenant-id")
  .apiKey("tu-api-key")
  .build();

3. Crear y buscar casos

// Crear un caso
const nuevo = await client.caso().create({
  casoTypeId: "tipo-solicitud-uuid",
  formId: "formulario-uuid",
  submittedData: {
    nombreCliente: "Ana García",
    tipoServicio: "PORTABILIDAD",
  },
});
console.log("Caso creado:", nuevo.casoId);

// Buscar todos los casos abiertos
const casos = await client.caso().searchAll(
  CaseFilter.builder()
    .casoTypeId("tipo-solicitud-uuid")
    .build()
);
console.log("Casos abiertos:", casos.length);

📖 Guía completa de instalación y configuración TypeScript →

+33 nodos visuales para integrar Shori en Axetflow y Node-RED sin escribir una sola línea de código — arrastra, configura y conecta.

1. Instalar el paquete

# Desde Manage Palette → Install → busca: axetflow-shori-nodes
# O por línea de comandos:
cd ~/.node-red
npm install axetflow-shori-nodes

2. Configurar el nodo de conexión

Arrastra el nodo shori-config a tu flujo y rellena las credenciales:

Campo	Descripción	Ejemplo
`portalId`	UUID del portal en Shori	`0306444E-38B1-...`
`tenantId`	UUID del tenant/organización	`80ff134a-cae2-...`
`apiKey`	Clave de API para autenticación	`sk-live-xxxxx`
`ambiente`	Selecciona DEV, UAT o PROD en el desplegable	`PROD`

Todos los demás nodos referencian este shori-config — configúralo una sola vez.

3. Crear casos y avanzar estados

Conecta los nodos de acción al flujo. Los datos se pasan por msg.payload:

[inject]
  └─► [shori-config]
        └─► [shori-create-case]   ← msg.payload: { casoTypeId, formId, submittedData }
              └─► [shori-next-state]  ← msg.payload: { casoId, stateId }
                    └─► [debug]       ← msg.payload: resultado

Nodos más usados:

Nodo	Acción
`shori-create-case`	Crea un nuevo caso
`shori-search-cases`	Busca casos con filtros avanzados
`shori-get-case`	Obtiene el detalle de un caso por ID
`shori-next-state`	Avanza el estado del caso
`shori-add-comment`	Agrega un comentario al caso
`shori-upload-document`	Sube un documento al repositorio

📖 Ver documentación completa de Axetflow Nodes →

Compatibilidad

Plataforma	Requisito mínimo
☕ Java	Java 17+, Maven 3.6+
🔷 TypeScript / JavaScript	Node.js 18+, npm 9+
🌊 Axetflow / Node-RED	Node.js 18+, Node-RED / Axetflow ≥ 3.0.0

Reportar un Bug

¿Encontraste un error o tienes una sugerencia de mejora? Contacta directamente al equipo:

📧 Jerson Ramírez Ortiz — jersonomar.ramirezortiz@emeal.nttdata.com

Al reportar un bug, incluye:

Descripción del problema
Versión del SDK (shori-sdk-ts, axetflow-shori-nodes o shori-api-client)
Pasos para reproducir el error
Stack trace o mensaje de error completo
Ambiente (DEV, UAT, PROD)

Equipo

Este SDK es desarrollado y mantenido por Jerson Omar Ramírez Ortiz de NTT DATA, como parte de las iniciativas de automatización e integración de la plataforma Syntpony Process Management (Shori).

Cargando equipo...

Changelog

v1.2.2 — Axetflow Nodes — Cobertura completa de módulos

Lanzamiento del paquete axetflow-shori-nodes v1.2.2 — Jerson Omar Ramírez Ortiz, NTT DATA.

+33 nodos disponibles — cobertura total de todos los módulos del SDK:

Grupo	Nodos nuevos
Casos CRUD	`shori-create-case` ✦, `shori-update-case` ✦, `shori-count-cases` ✦, `shori-change-priority` ✦
Estados	`shori-next-state-massive` ✦ (filas dinámicas), `shori-next-state-by-int` ✦, `shori-search-states` ✦, `shori-search-working-substates` ✦
Operaciones masivas	`shori-create-case-massive` ✦ (filas dinámicas)
Comentarios	`shori-search-comments` ✦
Usuarios	`shori-assign-user` ✦, `shori-unassign-user` ✦
Tipo de caso	`shori-get-case-type-lite` ✦
Primary Level	`shori-search-primary-levels` ✦ (operadores), `shori-get-primary-level` ✦, `shori-create-primary-level` ✦, `shori-toggle-primary-level` ✦, `shori-get-working-substates` ✦
Secondary Level	`shori-search-secondary-levels` ✦ (operadores), `shori-get-secondary-level` ✦, `shori-create-secondary-level` ✦, `shori-toggle-secondary-level` ✦
Archivos y Repo	`shori-search-case-files` ✦, `shori-upload-document` ✦

Mejoras UX:

Todos los campos soportan modo formulario (estático) + fallback dinámico desde msg.payload
Esquema de colores por módulo para identificación visual rápida en la paleta
Nodos de búsqueda con selectores de operador (EQ, IN, LIKE, LIKE_AFTER, NOT IN, etc.)
Nodos masivos con tablas de filas dinámicas (agregar/eliminar filas en el formulario)

v1.0.0 — Primera versión estable

Lanzamiento inicial del SDK para Java — Jerson Omar Ramírez Ortiz, NTT DATA.

Módulo de Casos (client.caso())

CRUD: findById, create, update
Búsqueda: search(CaseFilter), searchAll(CaseFilter) con auto-paginación
Búsqueda con adjuntos: searchWithAttachments, searchAllWithAttachments
Sub-módulos:
- files() — search, getAttachments, update, delete
- state() — next, nextMassive, nextByCasoIdInt, nextMassiveByCasoIdInt, search (con StateFilter), searchWorkingSubState (con WorkingSubStateFilter)
- comment() — add, search, searchAll (con CommentFilter)
- casoType() — findById, findByIdLite
- primaryLevel() — findById, search, create, update, getWorkingSubstates, updateWorkingSubstates, updateCasoDataField, activate, deactivate, activateWorkingSubstates, deactivateWorkingSubstates
- secondaryLevel() — findById, search, create, update, activate, deactivate
- fileTypology() — getByCasoType, getCategoriesByTypology, getCategoryById, addCategory
- user() — assign, assignResponsible, unassign, unassignResponsible, unassignOfProduct
Operaciones adicionales en CaseModule: count, createMassive, changePriority, deleteFiles

Módulo de Repositorio (client.repo())

Sub-módulos:
- document() — upload, delete
- download() — byDocument, byDocumentAndVersion, exportDocument

Módulo de Identificación (client.identify())

Búsqueda de usuario por ID interno: getUserById

Módulo de Formulario (client.form())

Creación de formularios
Actualización de formularios
Búsqueda de formularios por ID : formId
Búsqueda de usuario por request: FormFilter

Sistema base

Builder fluido con validación: ShoriClient.builder()
Soporte multi-ambiente: DEV, UAT, PROD
Autenticación Bearer con lazy-loading y renovación automática
Filtros avanzados: CaseFilter con operadores EQ, IN, LIKE, GE, LE, NE, BETWEEN, IS_NULL
Jerarquía de excepciones: ShoriException, ApiException, AuthenticationException, ResourceNotFoundException, ValidationException
Pool de conexiones HTTP con configuración SSL y timeouts configurables

¿Qué es Shori?​

Casos de uso típicos​

¿Qué es este SDK?​

SDKs disponibles​

Características principales​

Arquitectura del SDK​

Beneficios del SDK (Por qué usamos esta solución)​

Inicio rápido​

1. Agregar la dependencia Maven​

2. Inicializar el cliente​

3. Crear y buscar casos​

1. Instalar el paquete​

2. Inicializar el cliente​

3. Crear y buscar casos​

1. Instalar el paquete​

2. Configurar el nodo de conexión​

3. Crear casos y avanzar estados​

Compatibilidad​

Reportar un Bug​

Equipo​

Changelog​

v1.2.2 — Axetflow Nodes — Cobertura completa de módulos​

v1.0.0 — Primera versión estable​

¿Qué es Shori?

Casos de uso típicos

¿Qué es este SDK?

SDKs disponibles

Características principales

Arquitectura del SDK

Beneficios del SDK (Por qué usamos esta solución)

Inicio rápido

1. Agregar la dependencia Maven

2. Inicializar el cliente

3. Crear y buscar casos

1. Instalar el paquete

2. Inicializar el cliente

3. Crear y buscar casos

1. Instalar el paquete

2. Configurar el nodo de conexión

3. Crear casos y avanzar estados

Compatibilidad

Reportar un Bug

Equipo

Changelog

v1.2.2 — Axetflow Nodes — Cobertura completa de módulos

v1.0.0 — Primera versión estable