Acceso y Tokens

Para utilizar la API de Sagicc y tener acceso a todos sus métodos, es imprescindible que dispongas de una instancia activa de Sagicc. El punto de acceso general, requerido para todas las solicitudes de métodos de la API, es el siguiente:

https://miinstancia.sagicc.co/api

La API de Sagicc opera a través de tokens de acceso, los cuales son esenciales para autenticar y autorizar cada solicitud efectuada. Desde el módulo Credenciales de la API, puedes acceder a las credenciales con el propósito de generar nuevos tokens de acceso. Cada petición realizada a la API debe ir acompañada del encabezado “Authorization”, a través del cual debes enviar el token de acceso. El formato adecuado es el siguiente:

Authorization: Bearer tu-token-de-acceso

Métodos

La API de Sagicc se basa en varios métodos HTTPS que permiten comprender la acción que deseas llevar a cabo con la información. Para obtener o leer datos, se utiliza el método GET. Para crear o agregar nueva información, se emplea el método POST. Cuando se requiere actualizar o editar información, se utiliza el método PUT, y para eliminar información se recurre al método DELETE.

Parámetros

A continuación, se detallan los parámetros aceptados por el endpoint de la API de Sagicc para llevar a cabo diversas acciones:

• model

  • Descripción: Indica el nombre del modelo sobre el cual la API realizará la acción.

  • Método para el cual es requerido: GET, POST, PUT, DELETE

  • Condiciones específicas: Los valores aceptados para este parámetro son los siguientes:

• type

  • Descripción: Indica el tipo de consulta o la estructura de los registros que se desea obtener. Los valores aceptados son tree, lineal, y normal, cada uno retornando la información en una estructura específica.

  • Método para el cual es requerido: GET.

  • Condiciones específicas:

    • tree: Retorna los registros en forma de árbol, mostrando todos los niveles del modelo y sus relaciones.

    • lineal: Retorna los registros en un único nivel de matriz utilizando la notación de puntos para indicar la profundidad, incluyendo las relaciones.

    • normal: Retorna las columnas del modelo junto con las relaciones adyacentes.

  • Ejemplo: ?type=tree

• columns

  • Descripción: Consiste en una cadena con los nombres de las columnas a retornar en la respuesta.

  • Método para el cual es requerido: GET.

  • Condiciones específicas:

    • Debe ser una cadena separada por comas, con al menos un elemento.

    • Si el parámetro está vacío o es nulo, se mostrarán todas las columnas disponibles del modelo.

    • Si el modelo tiene relaciones, se debe anteponer el nombre del modelo al nombre de la columna para evitar ambigüedades.

  • Ejemplo: ?columns=id,descripcion,cliente.nro_documento

• relations

  • Descripción: Consiste en un objeto en formado JSON que define las relaciones a unir con el modelo a consultar.

  • Método para el cual es requerido: GET.

  • Condiciones específicas:

    • Si está vacío o es nulo, no se asignará ninguna relación.

    • Para consultas de tipo tree o lineal, utilizar la estructura: { "complexRelations": { "relationName": ["column1", "column2"] } }

    • Para relaciones de uno a muchos, es obligatorio incluir el ID tanto de la relación como del objeto relacionado.

    • Para consultas de tipo normal, utilizar la estructura: { "model": ["column1", "column2"] }

  • Ejemplo: ?relations={"caso":["id","cliente_id"]}

• searchtext

  • Descripción del parámetro: Consiste en una cadena de búsqueda que se utilizará para encontrar coincidencias en las columnas del modelo a consultar.

  • Método para el cual es requerido: GET.

  • Condiciones específicas:

    • Si está vacío, no se realiza ninguna búsqueda.

    • Si la consulta es de tipo normal, también buscará en las columnas de las relaciones.

  • Ejemplo: ?searchText=john

• page

  • Descripción: Especifica el número de la página del resultado que se desea obtener. Este parámetro es esencial para la funcionalidad de paginación, permitiendo consultar eficientemente grandes volúmenes de información.

  • Método para el cual es requerido: GET.

  • Condiciones específicas:

    • Debe ser un número entero mayor o igual a 1.

    • Por defecto, se asigna 1 si no se especifica.

  • Ejemplo: ?page=2

• sizePerPage

  • Descripción: Especifica el tamaño de las páginas que se desean obtener, es decir, la cantidad de registros mostrados por página. Este parámetro es esencial para la funcionalidad de paginación, permitiendo consultar eficientemente grandes volúmenes de información.

  • Método para el cual es requerido: GET.

  • Condiciones específicas:

    • Debe ser un número entero mayor o igual a 1.

    • Por defecto, se asigna 50 si no se especifica.

  • Ejemplo: ?sizePerPage=20

• sortName

  • Descripción: Especifica el nombre de la columna por la cual se ordenarán los registros a consultar. Este parámetro es esencial para la funcionalidad de paginación, permitiendo consultar eficientemente grandes volúmenes de información.

  • Método para el cual es requerido: GET.

  • Condiciones específicas:

    • Se puede utilizar el nombre de la columna en el modelo o en una relación.

    • Si el tipo de consulta es normal, se debe anteponer el nombre del modelo si hay relaciones.

    • Se puede utilizar el número de la columna según su posición en la lista de columns.

  • Ejemplo: ?sortName=id

• sortOrder

  • Descripción: Especifica el orden en que se retornarán los registros teniendo en cuenta el parámetro sortName, ya sea ascendente (asc) o descendente (desc).

  • Método para el cual es requerido: GET.

  • Condiciones específicas:

    • Por defecto, se asigna asc si no se especifica.

  • Ejemplo: ?sortOrder=desc

• enabled

  • Descripción: Permite filtrar los registros a consultar, según su estado de habilitación.

  • Método para el cual es requerido: GET.

  • Condiciones específicas:

    • true: Solo registros habilitados.

    • false: Solo registros inhabilitados.

    • null: Se mostrarán todos los registros.

    • Por defecto, se muestra true.

  • Ejemplo: ?enabled=false

• grouping

  • Descripción: Permite agrupar los registros a consultar por columnas específicas.

  • Método para el cual es requerido: GET.

  • Condiciones específicas:

    • Debe ser un array de cadenas con los nombres de las columnas.

    • Si la consulta es de tipo normal, se debe anteponer el nombre del modelo si hay relaciones.

    • Por defecto, es null.

  • Ejemplo: ?grouping=["prioridad"]

• conditions

  • Descripción: Filtrados condicionales dentro del modelo y sus relaciones.

  • Método para el cual es requerido: GET.

  • Condiciones específicas:

    • Para consultas de tipo tree o lineal, utilizar la estructura: column=value AND column!=value

  • Para consultas de tipo normal, anteponer el nombre del modelo si hay relaciones, de la siguiente forma: model.column=value AND model.column!=value

  • Ejemplo: ?conditions=cliente.nro_documento=1234567 AND cliente.primer_nombre!=Jane

• resources

  • Descripción: Consiste en un objeto tipo JSON que contiene las columnas y valores para crear un nuevo registro del modelo especificado o editar un registro existente.

  • Método para el cual es requerido: POST, PUT.

  • Condiciones específicas:

    • En el método POST, debe contener un conjunto de objetos con las columnas y valores.

    • En el método PUT, si existe el id en la URL, debe ser un objeto con las columnas y sus valores.

    • Si no existe el id en la URL, debe ser un conjunto de objetos que contengan el id para distinguir los cambios en cada uno.

    • Se puede incluir la llave relation para agregar registros relacionados con el modelo que se ha añadido.

  • Ejemplo:

    {
        "resources": [
            {
                "cliente_id": "154472",
                "tipo_dato_contacto_id": "3",
                "etiqueta": "Personal",
                "valor": "3002255845",
                "indicativo": "57",
                "extension": null,
                "barrio": null,
                "ciudad_id": null
            }
        ]
    }

• ids

  • Descripción: Consiste en un objeto tipo JSON que contiene los identificadores de los registros del modelo que serán eliminados.

  • Método para el cual es requerido: DELETE.

  • Condiciones específicas:

    • Si la URL proporcionada tiene un id, no se tomará en cuenta el JSON.

    • El JSON debe contener un conjunto de valores enteros (ID).

  • Ejemplo: { "ids": [1, 2, 3] }

Variables

• simpleRelation = relation

simpleRelation será la relación de nivel 1, es decir que no será multinivel.

• complexRelations = relation [ .internalRelationship [ .deepInternalRelationship … ] ] complexRelation serán las relaciones de nivel n, es decir serán multinivel. Se necesita de la relación directa con el modelo y luego, separados por puntos, se irá profundizando con las demás relaciones de cada uno de las relaciones anteriores.

Diccionario

• column = La columna del modelo o relación.

• model = Nombre del Modelo.

• relation = El nombre de la relación que dependerá de cada uno de los modelos y del tipo de relación, es decir, si son uno a muchos, muchos a uno, y muchos a mucho. Las relaciones uno a mucho, se representarán en plural, al igual que muchos a muchos, mientras que de muchos a uno serán en singular.

• internarRelationship = Cadena con el nombre de la relación que se relaciona con la anterior.

• deepInternalRelationship = Cadena con el nombre de la relación que se relaciona aún más con la anterior.

• numberColumn = Número entero de la posición de la columna. La posición de las columnas se elige a partir de cómo se hayan ingresado primero en los select de la consulta.

• value = El contenido de, por lo general, una llave, un array o variable.

Estructura

La estructura del API será de la siguiente manera

• GET

  • {model}/

    • type

    • columns

    • relations

    • page

    • searchText

    • sizePerPage

    • sortName

    • sortOrder

    • enabled

    • deleted

    • grouping

    • conditions

  • {model}/{id}

    • type

    • columns

    • relations

• DELETE

  • {model}/

    • ids

  • {model}/{id}

• PUT

  • {model}/ || {model}/{id}

    • resources

• POST

  • {model}/

    • resources

  • {service}/{name}

Relaciones

Presentaremos el mapa de cómo los modelos se relacionan con otros modelos.