Métodos HTTP

GET

Obtiene los registros.

POST

Agrega registros.

DELETE

Elimina los registros.

PUT

Edita los registros.

Parámetros

Los parámetros que recibirán la URL son:

model

Cadena con el nombre del modelo. Perteneciente a la ruta de la URL esta será el hincapié para mostrar los resultados; model es el nombre de la tabla que se encuentra en la base de datos; no todas las tablas estarán habilitadas para operarlas.

id

El identificador del modelo. Entero positivo mayor a uno y llave primaria del modelo. Perteneciente a la ruta de la URL y en algunas operaciones será opcional y otras no será tomado en cuenta.

type

Una cadena con el tipo de consulta de registros que se necesite mostrar. Se ingresará en el query de la URL. Aquí, se encuentran el tipo árbol, el lineal y el normal. Este campo es requerido cuando el método de la solicitud sea GET.

‘tree’: Tipo árbol. Mostrará los registros con tantos niveles que tenga el modelo en conjunto a sus relaciones.
‘lineal’: Tipo líneal. Mostrará los registros en un solo nivel de array usando la notación

punto. Cada punto indica la profundidad de la misma. Va acompañado con las relaciones.

‘normal’: Tipo normal. Mostrará las columnas del modelo y las relaciones adyacentes.

columns

Un conjunto de cadenas con los nombres de las columnas a mostrar. Se Parametriza en el query de la URL cuando el método de la solicitud es GET. Necesita de las siguientes condiciones y estructuras para operar:

{Array}.length > 0

Si no tiene contenido el array o es nulo, muestra todas las columnas disponibles del modelo.

Con tipo de consulta de registros tree o lineal es necesario los nombres de la columna del modelo de la siguiente manera:

{String} column [ , … ]

Si el tipo de consulta de registros es normal es necesario poner de prefijo el nombre del modelo si hay relaciones con otros modelos (Para evitar ambigüedades, solo si hay relaciones). Seguir la siguiente estructura

{String} model.column [ , … ]

relations

Un JSON con las relaciones que se unirán con el modelo. Se Parametriza en el query de la URL cuando el método de la solicitud es GET. Pueden tener uno a más niveles de relaciones solo siguiendo la siguiente estructura:

{Object} relations

Parámetro para los métodos GET. Si no tiene contenido o es nulo no asignará ninguna relación.

Si el tipo de consulta de registros es tree o lineal debe tener la siguiente estructura:

complexRelations : {Array} columns [ , … ]

La llave es el nombre de la relación y el valor es un array de las columnas de la relación que se quieran mostrar.

Si el valor de la relación es vacío se pondrán todas las columnas disponibles.
Si la relación a agregar es de uno a muchos deben expresar obligatoriamente el ID tanto de la relación como el relacionado. Si no se hace, no mostrará ninguna información.
Por convención, los nombres de las relaciones de uno a muchos y de muchos a muchos, serán en plural, mientras que las relaciones inversas de muchos a uno son en singular.
Para las relaciones que denominamos complexRelations, cada relación se divide por puntos y deben relacionarse unas con otras para que la consulta se genere.
Si el tipo de consulta de registros es normal deberá tener la siguiente estructura:

{Object} model : {Array} columns [ , … ]

La llave es el nombre de la tabla y el valor es un array de las columnas de la relación que se requieran

Si el valor de la relación es vacío se pondrán todas las columnas disponibles.

...

{Integer}: > = 1;

El número de página. Se Parametriza en el query de la URL cuando el método de la solicitud es GET

y cuando el id en la ruta de la URL no exista. Por defecto asignado a 1.

searchText

{String}

Texto de búsqueda. Buscará en el contenido de las columnas. Se Parametriza en el query de la URL cuando el método de la solicitud es GET y cuando el id en la ruta de la URL no exista.

Buscará en el contenido de las columnas de model.
Si el tipo de consulta de registros es normal, podrá realizar búsquedas a las columnas de las relaciones también.
Por defecto, no realizará búsquedas hasta asignarle un valor.

sizePerPage

{Integer}: >= 1.

Tamaño por página. Comúnmente llamado Límite. Se Parametriza en el query de la URL cuando el método de la solicitud es GET y cuando el id en la ruta de la URL no exista. Limita la cantidad de registros para cada página o visualización. Por defecto asignará 50.

sortName

{String|Integer}: {string} column || {string} model.column || {Integer} numberColumn

Organizar los registros por el nombre de la columna. Se Parametriza en el query de la URL cuando el método de la solicitud es GET y cuando el id en la ruta de la URL no exista.

Se utiliza el nombre de la columna que exista en model.
Se utiliza, adicionalmente, las columnas añadidas en las relaciones, siempre y cuando el tipo de consulta sea normal.
Número entero de la posición de la columna. Por defecto se elegirá la primera columna escogida. La posición de las columnas se elige a partir de cómo se hayan ingresado primero en el parámetro columns y, si el tipo de consulta de registros es normal, tomará en cuenta la ocurrencia de las columnas en el parámetro relations.
En el caso de que el tipo de consulta de registros sea normal es necesario poner de prefijo el nombre del modelo si hay relaciones con otros modelos (Para evitar ambigüedades).

sortOrder

{String}: ‘asc’|| ‘desc’

Cadena con la orientación del ordenamiento de los registros. Ascendente o Descendentemente. Se Parametriza en el query de la URL cuando el método de la solicitud es GET y cuando el id en la ruta de la URL no exista. Por defecto asignará asc

enabled

{Boolean}: true || false || null

Opción Habilitado perteneciente a los registros. Se Parametriza en el query de la URL cuando el método de la solicitud es GET. Por defecto mostrará la opción true. Se filtran si:

true: Solo habilitados.
false: Inhabilitados.
null: Se mostrarán todos.

deleted

{Boolean}: true || false || null

Opción eliminado perteneciente a los registros. Se Parametriza en el query de la URL cuando el método de la solicitud es GET y cuando el id en la ruta de la URL no exista. Por defecto mostrará la opción false. Se filtran si:

true: Solo eliminados.
false: No eliminados.
null: Se mostrarán todos.

grouping

{Array}

Agrupación de los registros. Conjunto de cadenas con las columnas a agrupar. Se Parametriza en el query de la URL cuando el método de la solicitud es GET y cuando el id en la ruta de la URL no exista. Por defecto es null. Utiliza la siguiente estructura para cada una de las cadenas:

{array} [ model . ] column

En el caso de que el tipo de consulta de registros sea normal es necesario poner de prefijo el nombre del modelo si hay relaciones con otros modelos (Para evitar ambigüedades).

conditions

Una cadena para realizar filtrados condicionales dentro del modelo y sus relaciones. Si el parámetro no tiene información no tendrá condiciones. conditions disponible para el método GET y cuando el id en la ruta de la URL no exista. Debe cumplir la siguiente estructura:

Si el tipo de consulta de registros es tree o lineal deberá tener la siguiente estructura (column [ = | != ] value) [AND|OR] […]
Si es de tipo normal es necesario poner de prefijo el nombre del modelo si hay relaciones con otros modelos (Para evitar ambigüedades).

(model.column [ = | != ] value) [AND|OR] […]

resources

Estructura en formato JSON con la información de las columnas a editar y crear en el modelo.

...

Para los métodos POST y PUT, será necesario un objeto o un conjunto con las columnas y valores.

...

Tabla de contenidos

minLevel	1
maxLevel	6
outline	false
type	flat
separator	brackets
printable	true

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 HTTP 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.

Método	Acción	Ejemplos
GET	Obtiene uno o más registros	Obtener el listado de casos de una campaña. Obtener los clientes creados entre un rango de fechas específico. Obtener el listado de gestiones asociadas a un caso específico.
POST	Agrega un nuevo registro	Agregar un nuevo caso a la plataforma. Agregar un nuevo dato de contacto (teléfono) a un cliente existente.
PUT	Actualiza o edita un registro específico	Actualizar un dato de contacto existente para un cliente. Actualizar la información de una cuenta específica.
DELETE	Elimina un registro especifico	Eliminar un cliente específico.

Endpoints y Parámetros

A continuación, se detallan los principales endpoints de la API de Sagicc, así como los parámetros aceptados para cada uno. Estos endpoints y parámetros permiten llevar a cabo diversas operaciones utilizando los métodos HTTP disponibles. Cada método está diseñado para realizar diferentes acciones sobre los recursos y modelos gestionados por la API, facilitando una interacción eficiente y flexible con los datos.

Método	Endpoint	Parámetros
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}/`	`resources`
	`{model}/{id}`	`resources`
POST	`{model}/`	`resources`

model
- Descripción: Indica el nombre del modelo sobre el cual la API realizará la acción. Cada modelo se encuentra asociado a un módulo o funcionalidad específica de la plataforma.
- Método para el cual es requerido: GET, POST, PUT, DELETE.
- Condiciones específicas: Los valores aceptados para este parámetro son los siguientes:

adjunto
agente_campana_canal
agente_estado_agente
bolsa_clientes
calificacion
campana
campana_canal
campana_estado_caso
campana_supervisor
campo
canal
caso
ciudad
cliente
cliente_etiqueta_cliente
cliente_dato_contacto
cola_campana_canal
conexion
cuenta
cuenta_campana

cuenta_caso
encuesta_pregunta
encuesta_resultado
desuscripcion_email
etiqueta_cliente
formulario
gestion
lista_bloqueo
pais
registro_canal
skill
tipo_campo
tipo_canal
tipo_canal_tipo_dato_contacto
tipo_caso
tipo_dato_contacto
tipo_documento
usuario
usuario_skill

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 que se desean obtener.
- 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 retornará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 formato JSON que define las relaciones a agregar en el modelo que se desea consultar.
- Método para el cual es requerido: GET.
- Condiciones específicas:
  - Si está vacío o es nulo, no se agregará 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"]}

conditions
- Descripción: Permite filtrar los registros a obtener a través de condicionales que se aplicarán al 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

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 se buscará coincidencias 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. Puede ser 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

disabled
- 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: Se mostrarán todos los registros.
  - false: Solo registros habilitados.
  - null: Se mostrarán todos los registros.
  - Por defecto, se muestra false.
- Ejemplo: ?disabled=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"]

resources
- Descripción: Consiste en un array con objetos tipo JSON que contienen las columnas y valores para crear nuevos registros del modelo especificado o editar un registro existente. Debe ser incluido en el cuerpo (body) de la petición.
- 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.

...

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

...

El objeto relation.

- - Se puede incluir la llave relation para agregar

...

- - registros relacionados con el modelo que se ha añadido.

...

tenga una relación adyacente con el modelo. Cada relación puede agregar múltiples registros.

{Object} relation {

{Array} simpleRelation :

{Object} column: value [, …]

[, …]

}

ids

Estructura JSON con identificadores para eliminar en el modelo. Para el método DELETE se necesitará de este parámetro en body de la solicitud. Si la URL proporcionada posee el id y el método es DELETE, no se tomará en cuenta dicho JSON.

...

- Ejemplo:

Bloque de código
{ "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).

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

...

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

Relaciones

En la siguiente tabla, encontrarás una lista de los diferentes modelos disponibles en la API, junto con sus relaciones con otros modelos dentro de la misma. Esta información te permitirá realizar peticiones más avanzadas y obtener, en una sola solicitud, datos de múltiples modelos que están relacionados entre sí.

Modelo	Relaciones
agente_campana_canal	"agente" "campanaCanal"
agente_estado_agente	"agente" "estadoAgente"
campana	"estadoCasos" "casos" "formulario" "usuarioResponsable" "canales" "cuentas" "supervisores" "campanaCanales"
campana_canal	"usuarios" "agentes" "canal" "campana"
campana_estado_caso	"campana"
campana_supervisor	"supervisor" "campana"
campo	"conexion" "tipo" "formulario"
canal	"registros" "tipo" "campanas" "campanaCanales"
caso	"gestiones" "documentos" "registros" "cliente" "tipo" "campana" "usuario" "cuentas"
ciudad	"pais" "datoContactos"
cliente	"datoContactos" "casos" "cuentas" "tipoDocumento"
cliente_dato_contacto	"cliente" "tipo" "ciudad"
cola_campana_canal	"agente" "campanaCanal"
conexion	"campo"
cuenta	"cliente" "casos" "campanas"
cuenta_campana	"cuenta" "campana"
cuenta_caso	"cuenta" "caso"
encuesta_pregunta	“encuesta”
encuesta_resultado	“encuesta” “caso”
formulario	"campos" "campanas" "gestiones"
gestion	"caso" "formulario" "usuario"
pais	"ciudades"
registro_canal	"caso" "canal"
skill	"usuarios"
tipo_campo	"campos"
tipo_canal	"canales" tipoDatoContactos
tipo_canal_tipo_dato_contacto	"tipoCanal" "tipoDatoContacto"
tipo_caso	"casos"
tipo_dato_contacto	"datoContactos" "tipoCanales"
tipo_documento	"clientes"
usuario	"estados" "roles" "skills" "campanasCanales" "campanasSupervisadas"
usuario_skill	"usuario" "skills"

Versiones comparadas

Versión anterior 1

Nueva versión Actual

Clave

Métodos HTTP

Parámetros

model

id

type

columns

relations

sizePerPage

sortName

sortOrder

enabled

deleted

grouping

conditions

resources

Acceso y Tokens

Métodos

Endpoints y Parámetros

ids

Variables

Diccionario

Estructura

Relaciones

Relaciones

Comparación de páginas

Versiones comparadas

Versión anterior 1

Nueva versión Actual

Clave

<span class="diff-html-removed" data-a11y-before="Start of deleted content" data-a11y-after="End of deleted content" id="removed-diff-0">[data-colorid=hryo92itbi]{color:#bf2600} html[data-color-mode=dark] [data-colorid=hryo92itbi]{color:#ff6640}</span>Métodos HTTP

Parámetros

model

id

type

columns

relations

sizePerPage

sortName

sortOrder

enabled

deleted

grouping

conditions

resources

Acceso y Tokens

Métodos

Endpoints y Parámetros

ids

Variables

Diccionario

Estructura

Relaciones

Relaciones

Métodos HTTP