Sitom Basic (BPMN on the cloud)
Business productivity
Requires Cloud
Rating undefined ( ratings)
Price: $49.00
Activa tu plan de SITOM

API SITOM

Con el API de SITOM podrás integrar la experiencia de SITOM en tu página web, en tu aplicación o en tu dispositivo.

Introducción

Este documento está dirigido a programadores que deseen crear aplicaciones que puedan interactuar con SITOM. Aquí se explican conceptos básicos de SITOM y de la API. También proporciona una visión general de las diferentes funciones que la API admite.

Antes de comenzar

  • Necesitas una cuenta de OMOLDS, y tener una licencia de SITOM.
  • Crear un usuario super-administrador en tu SITOM.
  • Crear un Token General, esto lo puedes hacer ingresando a configuración de tu SITOM en /configuration. Aquí encontraras TOKEN GENERAL en NULL, esto nos indica que tenemos que generar un Token en el botón 🔁. Si ya hay un Token generado al hacer clic sobre el botón este generara un nuevo Token y todo lo que estaba conectado a tu Token anterior retornara un error 401.
  • Adjuntar el archivo .js que desarrollamos para que puedas encriptar y desencriptar los datos trabajados con el API. Lo puedes encontrar en: api.js.
  • Aprende los conceptos básicos del formato de datos JSON (JavaScript Object Notation). JSON es un formato de datos común e independiente del lenguaje que proporciona una representación de texto simple de estructuras de datos arbitrarias. Para obtener más información, visita la página json.org.

Funciones utilizadas (api.js)

Las funciones utilizadas en SITOM para la encriptar y desencriptar de los datos trabajados con el API es necesario utilizar las siguiente funciones para que los datos viajen seguros.

Función Uso Descripción
getDataOm getDataOm(response.data, response.key) Esta función permite la desencriptar de los datos retornados en SITOM los datos nos debemos enviarle son response.data y response.key
setDataOm setDataOm({"campo1":"data 1", "campo2":"data 2"}) Esta función encripta los datos enviado en formato JSON y retorna un encrypt.data y encrypt.key datos que espera el API

Método admitidos

HTTP define un conjunto de métodos de petición para indicar la acción que se desea realizar para un recurso determinado. Para mas información visita Methods

En la siguiente tabla se muestran los métodos más comunes que la API admite. Algunos recursos también admiten otros métodos que realizan funciones más específicas para esos recursos.

Tipo Descripción
GET Devuelve una lista de los registro consultados
POST Permite la creación de un registro
PUT Permite la actualización de un registro
DELETE Permite la eliminación de un registro

Cabeceras o Headers admitidos

Las cabeceras (en inglés headers) HTTP permiten al cliente y al servidor enviar información adicional junto a una petición o respuesta, para mayor información visita Headers.

En la siguiente tabla se muestran las cabeceras admitidas y necesarios para el consumo del API.

Cabecera Descripción
x-access-token-sitom Token general de SITOM, si el Token es regenerado todos los recursos retornaran un error 401
x-access-token Token generado cuando un usuario ingresa por el recurso login, solo se admiten usuario tipo API para el uso del login, un usuario creador por la plataforma no puede haceder por este medio, este tienen un tiempo de vencimiento que retorna un error 401

Recurso admitidos

En la siguientes tablas se identifican los recursos admitidos para diferentes métodos, utiliza la siguiente url:

https://sitom-api.0ms.app/api/databases +Recurso

Usuarios

La base de datos de usuarios es uno de los pilares mas importantes en SITOM, esta db de usuarios esta ligada al modulo de usuarios, a las acciones de registro, login y aquellas otras db relacionadas.

Recurso Método Parámetros Cabeceras Retorno Descripción
/users GET limit, page, sort_desc, sort_asc x-access-token-sitom, x-access-token msg, response Devuelve una lista de los usuarios tipo API consultados
/users POST email, first_name, last_name, password x-access-token-sitom, x-access-token msg, response Permite la creación de un usuario tipo API, no necesita login para crearlo, devuelve el x-access-token.
/users/$id_token PUT id_token, email, first_name, last_name, password, (passwordCurrent para actualizar el email y el password) x-access-token-sitom, x-access-token msg Permite la actualización de un usuario tipo API
/users/$id_token DELETE id_token, passwordCurrent x-access-token-sitom, x-access-token msg Permite la eliminación de un usuario tipo API
/login POST email, password x-access-token-sitom msg, response Permite el login con SITOM retornando un TOKEN
/checkSession POST id_token x-access-token-sitom, x-access-token msg, response Permite la renovación del TOKEN
/me POST id_token x-access-token-sitom, x-access-token msg, response Retorna los datos del usuario logueado

Parámetros

Para los parámetros que usen el método GET con ? para poder utilizar más parámetros utiliza & ejemplo: url/?limit=15&page=1

Parámetros Método Uso Descripción
limit GET url/?limit=15 Limita la cantidad de usuarios retornados como máximo 30
page GET url/?page=1 Es la pagina de la consulta
sort_desc GET url/?sort_desc=first_name Organiza de forma ascendente los resultados por email, first_name, last_name, date_time_om
sort_asc GET url/?sort_asc=last_name Organiza de forma descendente los resultados por email, first_name, last_name, date_time_om
id_token GET url/$id_token El id que identifica al usuario en SITOM
id_token, email, first_name, last_name, password, passwordCurrent POST formato Json pasado por la funcion setDataOm Son los parametros utilizados para crear o actualizar un usuario, el id_token es necesario para actualizar y passwordCurrent cuando se va actualizar el email o password

Bases de datos

La base de datos son tablas virtuales o tablOM, que son utilizados por SITOM para el manejo de las estructuras, estas nos permite crear todo tipo de flujo de datos o procesos de negocio, facilitando el crecimiento de tu empresa. Previamente se debe crear la estructura dentro de SITOM para poder utilizar las Bases de Datos, para esto se requiere contar con un usuario de estructura, recuerda habilitar el token general dentro de la estructura.

Recurso Método Parámetros Cabeceras Retorno Descripción
/data/$databases GET databases, parameters, limit, page, sort_asc, sort_desc, q x-access-token-sitom msg, response Devuelve una lista de los datos consultados
/data/$databases/$id_token GET databases, id_token, parameters x-access-token-sitom, x-access-token msg, response Retorna los datos del registro consultado
/data/$databases POST databases, JSON de los datos x-access-token-sitom, x-access-token msg, response Registra los datos enviados y encriptados en la función setDataOm
/data/$databases/$id_token PUT databases, id_token, JSON x-access-token-sitom, x-access-token msg, response Actualiza los datos enviados
/data/$databases/$id_token DELETE databases, id_token x-access-token-sitom, x-access-token msg, response Elimina el registro

Parámetros

Parámetros Método Uso Descripción
databases GET url/costos_nomina Es el name_db de la base de datos a consultas
parameters GET url/costos_nomina/?parameters=WydhcGVsbGlkbycsICdjZWR1bGEnXQ== Son los datos que queremos que nos devuelva la consulta esto es un arreglo ['apellido', 'cedula'] en base64
limit GET url/?limit=15 Limita la cantidad de datos retornados como máximo 30
page GET url/?page=1 Es la pagina de la consulta
sort_desc GET url/?sort_desc=first_name Organiza de forma ascendente los resultados por apellido, cedula, date_time_om, etc. Los nombres son los name_db del campo
sort_asc GET url/?sort_asc=last_name Organiza de forma descendente los resultados por apellido, cedula, date_time_om, etc. Los nombres son los name_db del campo
id_token GET url/$id_token El id que identifica al registro en SITOM
JSON de los datos POST {"encrypt":{"data":"U2FsdGVkX19UO9x","key":"EW7E2BU"}} Los datos enviados a SITOM deben ir encriptados, deben estar en formato JSON. Por defecto el SITOM no lee objetos dentro de objetos ejm: {"usuarios": "edad":26,"nombre":"Pedro"}}
q GET q=itemXconsultar: item_value Nos permite realizar una consulta especifica tomando el nombre del item a consultar + el valor del item que esperamos que nos retorne.

Procesos (Bpmn)

Para pegarte a un proceso dentro de Sitom es necesario enviar los siguientes parámetros al POST en la estructura.

Parámetros

Parámetros Método Uso Descripción
bpmnTask POST bpmnTask Es un arreglo que se adjunta al enviado de los datos al crear un registro
idTask POST bpmnTask['idTask'] Es el id de la Tarea que encontramos en el PAD dentro de Bpmn
nameTask POST bpmnTask['nameTask'] Es el nombre de la Tarea que encontramos en el PAD dentro de Bpmn
Ejemplo:
        async function saveSitom(){
            let dataForm = {
                'bpmnTask': {'idTask':'Task_10liz89', 'nameTask': 'cargo' }, 
                "nombre_de_la_tarea": ' Prueba api 🚨 Omolds',
            }
            console.log(setDataOm2(dataForm));
            let response = await fetch(`https://sitom-api.0ms.app/api/databases/data/mitabla`, {
                method: 'POST',
                headers: {
                    'Accept': 'application/json',
                    'Content-Type': 'application/json',
                    'x-access-token-sitom': "sP0llot0mWlhsS2FHSkhZMmxQYVVwSlZYcEpNVTVwU2prdVpYbEtNR0l5ZEd4aWFVazJTVzFHTVdO"
                },
                body: JSON.stringify(setDataOm(dataForm))
            });
            let data = await response.json();
            return data;
        }
        
    

Siempre use HTTPS

Para el uso de API de SITOM es extrictamente necesario que utilice el protocolo HTTPS, que es el Protocolo seguro de transferencia de hipertexto (en inglés: Hypertext Transfer Protocol Secure o HTTPS), es un protocolo de aplicación basado en el protocolo HTTP, destinado a la transferencia segura de datos de Hipertexto, es decir, es la versión segura de HTTP.

Códigos de estado HTTP

Los códigos de estado de respuesta HTTP indican si se ha completado satisfactoriamente una solicitud HTTP específica. Las respuestas se agrupan en cinco clases: respuestas informativas, respuestas satisfactorias, redirecciones, errores de los clientes y errores de los servidores. Para mas información visita HTTP

Códigos Respuesta Descripción
200 OK Todo esta funcionando
304 Not Modified El cliente puede usar datos en caché
400 Bad Request la solicitud no es válida o no se puede atender. El error exacto debe explicarse en la carga útil de error. Por ejemplo, "El JSON no es válido"
401 Unauthorized La solicitud requiere una autenticación de usuario
403 Forbidden El servidor entendió la solicitud, pero la rechazó o el acceso no está permitido.
404 Not found No hay ningún recurso detrás de la URI.
422 Unprocessable Entity Debe utilizarse si el servidor no puede procesar la entidad, por ejemplo, si no se puede formatear una imagen o faltan campos obligatorios en la carga útil.
500 Internal Server Error los desarrolladores de API deben evitar este error. Si se produce un error en el blog de captura global, el seguimiento de registros debe registrarse y no devolverse como respuesta.