API v1 RESTful
- 1 Visión general
- 2 Cómo usar la API v1
- 2.1 Uso rápido
- 3 Acceda a Athento Explorer
- 4 Especificaciones generales
- 5 Documento — Document Entity
- 6 Comentario — Comment Entity
- 7 Usuarios — User Entity
- 7.1 Crear un usuario
- 8 Grupos — Group Entity
- 8.1 Crear un grupo
- 9 Búsqueda de documentos — Query & ResultSet Entities
- 9.1 ResultSet
- 9.2 Query
- 9.3 ATQL
- 9.3.1 Sintaxis
- 9.3.2 Campos fijos de consulta vs metadatos
- 9.3.3 Búsqueda por metadatos
- 9.3.4 Ordenación
- 9.3.5 Join
- 9.3.6 Funciones
- 9.3.7 Datos resumidos y funciones de agregación
Visión general
La API v1 RESTful es la vía de comunicación de Athento para conectar con toda la funcionalidad del sistema. Provee un modelo unificado de llamadas para cualquier tipo de operación sobre el modelo documental ofreciendo flexibilidad y seguridad.
Cómo usar la API v1
La API v1 de Athento es una RESTful Web API que permite acceder a todas las funcionalidades del modelo documental de Athento.
Uso rápido
A continuación se listan los endpoints
actuales de la API v1.
Modo | Endpoint | Descripción |
---|---|---|
Documento | ||
POST |
| Crea un nuevo documento. |
GET |
| Obtiene un documento en formato JSON indicando su |
PUT |
| Modifica un documento indicando su |
DELETE |
| Elimina un documento indicando su |
GET |
| Descarga el contenido de un documento. |
POST |
| Descarga el contenido de un listado de documentos. |
POST |
| Ejecuta una transición sobre el ciclo de vida de un documento. |
Comentario | ||
GET |
| Obtiene los comentarios de un documento indicando el |
POST |
| Crea un nuevo comentario sobre un documento. |
GET |
| Obtiene un comentario de un documento indicando el uuid de ambos. |
PUT |
| Modifica un comentario indicando su |
DELETE |
| Borra un comentario indicando su |
Búsqueda | ||
POST |
| Busca documentos ejecutando una query ATQL y obteniendo los documentos como entidad. |
POST |
| Busca documentos ejecutando una query ATQL y obteniendo las columnas incluidas en la cláusula |
Usuario | ||
POST |
| Crea un nuevo usuario. |
GET |
| Obtiene un usuario en formato JSON indicando su |
PUT |
| Modifica un usuario existente. |
POST |
| Activa un usuario. |
POST |
| Desactiva un usuario. |
Grupo | ||
POST |
| Crea un nuevo grupo. |
GET |
| Obtiene un grupo en formato JSON indicando su |
Acceda a Athento Explorer
Use Athento Explorer para poder gestionar las llamadas a los endpoints de la API v1 en la ruta /api/v1/explorer
de su instancia. Por ejemplo en https://demo.athento.com/api/v1/explorer.
Para usar Athento Explorer debe iniciar sesión.
Especificaciones generales
Formatos
Cabeceras
Nombre | Valores | Opcional |
---|---|---|
Content-Type |
| False |
Fetch-Mode |
| True |
Descripción
Content-Type
: es el tipo de contenido que se usará en las llamadas a la API v1.Fetch-Mode
: es el tipo modo de obtención de la entidad que se pretende consultar donde:default
: es la obtención por defecto, con la información mínima suficiente.extended
: obtención extendida de la entidad y sus relaciones, donde se informa de atributos más destacados de la misma.Incluye las entidades de los documentos relacionados al propio documento.
full
: obtención completa de la entidad y sus relaciones.
Petición
{
"<KEY>": "<VALUE>",
"<OBJECT>": {
"<KEY>": "<VALUE>", ...
}
}
Respuesta
El formato de respuesta de la API v1 tendrá siempre un formato estándar representado con tipo de contenido JSON y con la siguiente estructura:
{
"request-id": "<UUID>",
"response": {
"message": "<EXECUTION MESSAGE>",
"code": <EXECUTION CODE>
},
"result": {
"entity": "<ENTITY>",
<REST OF JSON RESPONSE>
}
}
Documento — Document Entity
El documento es la pieza fundamental de almacenamiento en Athento. La API v1 ofrece la posibilidad de operar con ellos para crear, modificar, eliminar y consultarlos.
A continuación se muestra la representación de un documento por defecto.
{
"entity": "Document",
"uuid": "a8b16f41-65a0-481c-bb1a-e094011fee14",
"filename": "PDF-Athento.pdf",
"creation_date": "2022-12-07T16:45:03.302424+01:00",
"modified_date": "2022-12-07T16:45:06.048175+01:00",
"state": "pending",
"version": "0.0",
"author": "benchmark",
"serie": "my_space",
"doctype": "my_form",
"container": false,
"file": {
"url": "uploads/.../2d/9c/2d9c09cdb21fd0a56eefd627240d554f.pdf",
"extension": ".pdf",
"hash": "2d9c09cdb21fd0a56eefd627240d554f",
"size": 34073,
"content_type": "application/pdf"
},
"life_cycle_state": "started"
}
Cuando un documento tiene contenido binario, el atributo file
aparece en la representación de la entidad. Otros elementos como el life_cycle_state
, etc. se comportan del mismo modo.
Crear un documento
Llamada genérica de creación:
POST https://demo.athento.com/api/v1/file/
Crear documento
Un documento en Athento es una entidad de un cierto tipo documental, o también llamado formulario, que se aloja en un Espacio —también llamado Serie documental— concreto. Dicho documento, puede tener o no un contenido principal —archivo binario— asociado. En este caso, comenzamos con la creación de un documento de Athento, donde no se especifica un binario asociado.
POST /api/v1/file/
Content-Type: application/json
Petición:
{
"filename": "My new document name",
"doctype": "MyFormType",
"serie": "MySerie",
"metadatas": {
"metadata.contract_number": "12345"
}
}
Respuesta:
{
"request-id": "1f1ec0af-aa65-4d44-942f-48ae8eecb639",
"response": {
"message": "Execution success",
"code": "ok"
},
"result": {
"entity": "Document",
"uuid": "f1f0d872-f32f-4585-8a47-a59f6ed02b0b",
"filename": "My new document name",
"creation_date": "2022-12-24T10:17:56.251169+01:00",
"modified_date": "2022-12-24T10:17:56.835331+01:00",
"state": "pending",
"version": "0.0",
"author": "admin",
"serie": "MySerie",
"doctype": "MyFormType",
"container": false,
"life_cycle_state": "Inicio"
}
}
Metadatos
El documento se puede componer con un conjunto de metadatos —o campos— de diferentes tipos. Dichos metadatos serán definidos por el formulario —o tipo documental— que describe al documento, aunque podrán añadirse otros que estén fuera de dicho formulario documental de manera que puedan quedar permanentes y trazados si el propio documento cambia de tipo.
A continuación se enumeran los diferentes tipos de metadatos que pueden ser incluidos en el documento.
Tipo | Descripción | Ejemplos |
---|---|---|
Text | Cadena de texto |
|
Number | Número (Moneda, Porcentaje, …) |
|
Boolean | Booleano |
|
Date | Fecha |
|
Datetime | Fecha y hora |
|
Table of items | Lista de items |
|
Document | Referencia a documento (UUID) |
|
Document list | Referencias a documento (Lista de UUIDs) |
|
Choice | Valor seleccionable |
|
Multichoice | Valores seleccionables múltiples |
|
Los tipos de metadatos que puedan definirse en tiempo de configuración podrán ser añadidos como tipo texto, es decir, con un valor reflejado como cadena de caracteres. Por ejemplo, si tenemos un campo de tipo Choice, el valor incluido podrá ser incluido como texto.
Crear documento con contenido
A continuación el servicio de creación de nuevo documento con un binario asociado.
POST /api/v1/file/
Content-Type: multipart/form-data
Petición:
{
"filename": "My new document name",
"serie": "MySerie",
"doctype": "MyFormType",
"metadatas": {
"metadata.contract_number": "12345"
},
"file": <File>
}
Respuesta:
{
"request-id": "7d20a5e6-cb1b-4949-abcf-51ecf99939f9",
"response": {
"message": "Execution success",
"code": "ok"
},
"result": {
"entity": "Document",
"uuid": "0bbc79ba-6b14-4074-8f8e-6701a4ec995a",
"filename": "My new document name",
"creation_date": "2022-12-26T20:00:02.448476+01:00",
"modified_date": "2022-12-26T20:00:03.227150+01:00",
"validation_date": null,
"validator": null,
"state": "pending",
"version": "0.0",
"author": "admin",
"serie": "MySerie",
"doctype": "MyFormType",
"container": false,
"file": {
"url": "uploads/Athento_ysvozgijse/Contratos_msphd/2d/9c/2d9c09cdb21fd0a56eefd627240d554f_e2jQcGS.pdf",
"extension": ".pdf",
"hash": "2d9c09cdb21fd0a56eefd627240d554f",
"size": 34073,
"content_type": "application/pdf"
},
"life_cycle_state": "Inicio"
}
}
Crear documento a partir de plantilla
Creación de un documento a partir de una plantilla. En primer (por defecto) o segundo plano.
POST /api/v1/file/
Content-Type: multipart/form-data
Nombre | Valores | Opcional |
---|---|---|
template | Nombre o UUID de la plantilla | True |
background | Realizar la generación del binario en segundo plano | True |
Petición:
{
"filename": "My new document name",
"serie": "MySerie",
"doctype": "MyFormType",
"template": "MyTemplate",
"background": true|false,
"metadatas": {
"metadata.contract_number": "12345"
}
}
Respuesta:
{
"request-id": "7d20a5e6-cb1b-4949-abcf-51ecf99939f9",
"response": {
"message": "Execution success",
"code": "ok"
},
"result": {
"entity": "Document",
"uuid": "0bbc79ba-6b14-4074-8f8e-6701a4ec995a",
"filename": "My new document name",
"creation_date": "2022-12-26T20:00:02.448476+01:00",
"modified_date": "2022-12-26T20:00:03.227150+01:00",
"validation_date": null,
"validator": null,
"state": "pending",
"version": "0.0",
"author": "admin",
"serie": "MySerie",
"doctype": "MyFormType",
"container": false,
}
Actualizar un documento
Llamada genérica de actualización:
PUT https://demo.athento.com/api/v1/file/{file-uuid}/?{rest—query}
Actualizar documento
Para actualizar un documento, se hace uso del identificador del mismo y los atributos o metadatos asociados que pretenden actualizarse.
PUT /api/v1/file/{file-uuid}/
Content-Type: application/json
Petición:
{
"filename": "New name",
"metadatas": {
"metadata.contract_number": "12345"
}
}
Respuesta:
{
"request-id": "ebcc21ca-893c-4f34-9e8b-90a3c87edb1d",
"response": {
"message": "Execution success",
"code": "ok"
},
"result": {
"entity": "Document",
"uuid": "77bd8d16-66bb-45fd-ace4-638257f665b8",
"filename": "New name",
"creation_date": "2022-12-26T20:07:23.321660+01:00",
"modified_date": "2022-12-26T20:07:24.017370+01:00",
"validation_date": null,
"validator": null,
"state": "pending",
"version": "0.0",
"author": "admin",
"serie": "MySerie",
"doctype": "MyFormType",
"container": false,
"life_cycle_state": "Inicio"
}
}
Actualizar contenido
La actualización del contenido de un documento, donde se le asocia un archivo binario.
Nombre | Valores | Opcional |
---|---|---|
Content-Type |
| False |
PUT /api/v1/file/{file-uuid}/
Content-Type: multipart/form-data
Nombre | Valores | Opcional |
---|---|---|
file-uuid | Identificador del documento a modificar. | False |
Petición:
"file": <File>
Respuesta:
{
"request-id": "23bbefc6-12da-452a-a061-bfda1dc359b5",
"response": {
"message": "Execution success",
"code": "ok"
},
"result": {
"entity": "Document",
"uuid": "69d5b65b-212b-4a54-b995-c22007f9d6da",
"filename": "My new document name",
"creation_date": "2022-12-26T20:03:46.128262+01:00",
"modified_date": "2022-12-26T20:03:46.205468+01:00",
"validation_date": null,
"validator": null,
"state": "pending",
"version": "0.0",
"author": "admin",
"serie": "MySerie",
"doctype": "MyFormType",
"container": true,
"file": {
"url": "uploads/Athento_ysvozgijse/Contratos_msphd/2d/9c/2d9c09cdb21fd0a56eefd627240d554f_Idc6YiZ.pdf",
"extension": ".pdf",
"hash": "2d9c09cdb21fd0a56eefd627240d554f",
"size": 34073,
"content_type": "application/pdf"
},
"life_cycle_state": "Inicio"
}
}
Eliminar un documento
Llamada genérica de eliminación:
DELETE https://demo.athento.com/api/v1/file/{file-uuid}/
Eliminar documento
La eliminación de un documento siempre se hace de forma lógica, manteniendo la posibilidad de localizar, y/o recuperar su información. En la respuesta se obtiene el atributo removed
con valor true
.
DELETE /file/{file-uuid}/
Respuesta:
{
"request-id": "ebcc21ca-893c-4f34-9e8b-90a3c87edb1d",
"response": {
"message": "Execution success",
"code": "ok"
},
"result": {
"entity": "Document",
"uuid": "77bd8d16-66bb-45fd-ace4-638257f665b8",
"filename": "Mi documento3",
"creation_date": "2022-12-26T20:07:23.321660+01:00",
"modified_date": "2022-12-26T20:07:24.017370+01:00",
"validation_date": null,
"validator": null,
"state": "pending",
"version": "0.0",
"author": "admin",
"serie": "MySerie",
"doctype": "MyFormType",
"removed": true,
"container": false,
"life_cycle_state": "Inicio"
}
}
Descargar el contenido de un documento
Llamada genérica de descarga:
GET https://demo.athento.com/api/v1/file/{file-uuid}/download/
Descarga del contenido
GET /file/{file-uuid}/download/
Descargar el contenido de un listado documentos
Llamada genérica de descarga:
GET+POST https://demo.athento.com/api/v1/file/bulk_download/
Content-Type: application/json
Nombre | Descripción | Opcional |
---|---|---|
| Lista de UUIDs de los documentos a descargar. Límite de descargar | False |
| Nombre del fichero obtenido en la descarga. Default: | True |
| Ignora los UUID de documentos que no sean localizados. Por defecto | True |
Petición GET:
GET https://demo.athento.com/api/v1/file/bulk_download/?documents=fdcc5e33-57cd-47ef-8af4-bddcee23d124,1ae1567e-11cd-c933-811a-beee1367d301&filename=my-favorite-download.zip&ignore_not_found=true
Petición POST:
{
"documents": ["fdcc5e33-57cd-47ef-8af4-bddcee23d124", "1ae1567e-11cd-c933-811a-beee1367d301"],
"filename": "my-favorite-download.zip",
"ignore_not_found": true
}
Respuesta:
<Bytes del fichero descargado>
Ejecutar transición de estado para un documento
Llamada genérica de transición:
POST https://demo.athento.com/api/v1/file/{file-uuid}/lifecycle/transition/
Ejecución de la transición
Un documento puede tener un ciclo de vida asociado y, desde este servicio, es posible ejecutar una transición desde el estado donde se encuentre. Para ello, basta con informar del nombre de la transición que se quiere ejecutar (o el propio uuid
).
Además, si el documento incluye varios ciclos de vida asociados (parallel lifecycles) es posible indicar sobre qué ciclo de vida será ejecutada la transición, informando del nombre (o del uuid
) y del parámetro parallel
con valor true
.
POST /file/{file-uuid}/lifecycle/transition/
Content-Type: application/json
Petición:
{
"transition": "Completar",
"comment": "Finalización manual sobre ciclo de vida único."
}
{
"transition": "Completar",
"lifecycle": "Basico",
"parallel": true,
"comment": "Finalización manual sobre ciclo de vida paralelo."
}
Respuesta:
{
"request-id": "23bbefc6-12da-452a-a061-bfda1dc359b5",
"response": {
"message": "Execution success",
"code": "ok"
},
"result": {
"entity": "Document",
"uuid": "b3a35e9a-ebb2-475c-a43e-7d896eb6cee2",
"filename": "My document with lifecycle",
"creation_date": "2022-12-26T20:03:46.128262+01:00",
"modified_date": "2022-12-26T20:03:46.205468+01:00",
"validation_date": null,
"validator": null,
"state": "pending",
"version": "0.0",
"author": "admin",
"serie": "MySerie",
"doctype": "MyFormType",
"container": true,
"life_cycle_state": "Finalizado"
}
}
Comentario — Comment Entity
Athento permite crear, consultar, editar y borrar comentarios sobre los documentos.
A continuación se muestra la representación de un documento por defecto.
{
"entity": "Comment",
"uuid": "a3cc99a7-88ed-4cd2-8b30-2a8a25df1b27",
"comment": "Comentario de prueba.",
"author": "apm@athento.com",
"life_cycle_state": "started",
"creation_date": "2025-01-13T16:02:47.999059+01:00",
"modified_date": "2025-01-13T16:02:47.999067+01:00",
"version": "0.0"
}
Listar los comentarios de un documento
Un documento puede tener comentarios realizados por los usuarios.
Al listar los documentos estos vendrán siempre paginados. Por defecto si no se le especifica nada se listará la página 1 y el tamaño de página será de 20 elementos. Esto se puede modificar especificando los parámetros “page” para el número de página y “page_size” para el tamaño de la página.
Llamada genérica de listar:
GET https://demo.athento.com/api/v1/file/{file_uuid}/comment/
Listar comentarios
GET /api/v1/file/{file_uuid}/comment/
Respuesta:
{
"request-id": "c758bd33-a275-4b11-962a-cbe68eb8dc93",
"response": {
"message": "Execution success",
"code": "ok"
},
"result": {
"entity": "Comments",
"page": 1,
"pageSize": 20,
"totalCount": 34,
"totalPages": 1,
"maxPageSize": 200,
"entries": [
{
"entity": "Comment",
"uuid": "932c60fd-cfc4-4f4d-924e-7f92be007c09",
"comment": "Revisa este documento por favor @user1@athento.com",
"author": "apm@athento.com",
"life_cycle_state": null,
"creation_date": "2025-01-17T16:40:02.530539+01:00",
"modified_date": "2025-01-17T16:40:02.530546+01:00",
"version": "0.0"
},
{
"entity": "Comment",
"uuid": "35c5764c-535e-430f-9563-47816c7720d0",
"comment": "Este documento debe ser revisado cuanto antes",
"author": "apm@athento.com",
"life_cycle_state": null,
"creation_date": "2025-01-17T16:40:03.666513+01:00",
"modified_date": "2025-01-17T16:40:03.666520+01:00",
"version": "0.0"
}
],
...
}
}
Petición con página y tamaño de página especificados
GET /api/v1/file/{file_uuid}/comment/?page=5&page_size=10
Se listaría la página 5 usando un tamaño de página de 10 elementos.
Crear comentario
Para crear un comentario debemos indicar el texto del comentario. Se pueden mencionar tanto usuarios como grupos usando el carácter “@“.
Para mencionar usuarios debemos escribir el nombre de usuario después del carácter “@”. Ejemplo: Con @apm@athento.com se estaría mencionando al usuario con nombre de usuario “apm@athento.com“.
Para mencionar grupos debemos escribir la etiqueta representativa del grupo después del carácter “@. Ejemplo: Con @Lectura se estaría mencionando al grupo “Lectura”.
Si se quiere mencionar a un grupo que contiene espacios en su etiqueta debemos escribirlo entre comillas después del carácter “@”. Ejemplo: Con @"Grupo lectura” se estaría mencionando al grupo “Grupo lectura”.
Llamada genérica de creación:
POST https://demo.athento.com/api/v1/file/{file_uuid}/comment/
Creación de comentario
POST /api/v1/file/{file_uuid}/comment/
Content-Type: application/json
Petición:
{
"comment": "Revisa este documento por favor @apm@athento.com y grupo @\"Grupo lectura\""
}
El carácter “\“ se usa para escapar las comillas dobles y poder enviar la petición correctamente.
Respuesta:
{
"request-id": "9946cde5-ff23-4680-a223-273fa0d01c59",
"response": {
"message": "Execution success",
"code": "ok"
},
"result": {
"entity": "Comment",
"uuid": "3dfaee70-8ced-4c72-909c-2d807669f40a",
"comment": "Revisa este documento por favor @apm@athento.com y grupo @\"Grupo lectura\"",
"author": "apm@athento.com",
"life_cycle_state": null,
"creation_date": "2025-01-13T18:16:33.716791+01:00",
"modified_date": "2025-01-13T18:16:33.716812+01:00",
"version": "0.0"
}
}
Obtener un comentario de un documento
Llamada genérica de obtención:
GET https://demo.athento.com/api/v1/file/{file_uuid}/comment/{uuid}/
Obtención de comentario
GET /api/v1/file/{file_uuid}/comment/{uuid}/
Respuesta:
{
"request-id": "9d482720-55b9-4e46-b38f-815fbf9606d1",
"response": {
"message": "Execution success",
"code": "ok"
},
"result": {
"entity": "Comment",
"uuid": "8e1d37ec-62e7-4331-b103-6d33c3e94ed2",
"comment": "Comentario de prueba",
"author": "apm@athento.com",
"life_cycle_state": null,
"creation_date": "2025-01-10T10:19:04.504838+01:00",
"modified_date": "2025-01-10T10:19:04.504873+01:00",
"version": "0.0"
}
}
Actualizar un comentario
Para actualizar un comentario debemos indicar el texto del comentario. Se pueden mencionar tanto usuarios como grupos usando el carácter “@“.
Para mencionar usuarios debemos escribir el nombre de usuario después del carácter “@”. Ejemplo: Con @apm@athento.com se estaría mencionando al usuario con nombre de usuario “apm@athento.com“.
Para mencionar grupos debemos escribir la etiqueta representativa del grupo después del carácter “@. Ejemplo: Con @Lectura se estaría mencionando al grupo “Lectura”.
Si se quiere mencionar a un grupo que contiene espacios en su etiqueta debemos escribirlo entre comillas después del carácter “@”. Ejemplo: Con @"Grupo lectura” se estaría mencionando al grupo “Grupo lectura”.
Llamada genérica de actualización:
PATCH https://demo.athento.com/api/v1/file/{file_uuid}/comment/{uuid}/
Actualizar comentario
PATCH /api/v1/file/{file_uuid}/comment/{uuid}/
Content-Type: application/json
Petición:
{
"comment": "Revisen este documento por favor @Agrupacion"
}
Respuesta:
{
"request-id": "9d482720-55b9-4e46-b38f-815fbf9606d1",
"response": {
"message": "Execution success",
"code": "ok"
},
"result": {
"entity": "Comment",
"uuid": "8e1d37ec-62e7-4331-b103-6d33c3e94ed2",
"comment": "Revisen este documento por favor @Agrupacion",
"author": "apm@athento.com",
"life_cycle_state": null,
"creation_date": "2025-01-10T10:19:04.504838+01:00",
"modified_date": "2025-01-10T10:19:04.504873+01:00",
"version": "0.0"
}
}
Borrado de un comentario
Llamada genérica de actualización:
DELETE https://demo.athento.com/api/v1/file/{file_uuid}/comment/{uuid}/
Borrar comentario
DELETE /api/v1/file/{file_uuid}/comment/{uuid}/
Respuesta:
{
"request-id": "9d482720-55b9-4e46-b38f-815fbf9606d1",
"response": {
"message": "Execution success",
"code": "ok"
},
"result": {
"entity": "Comment",
"uuid": "8e1d37ec-62e7-4331-b103-6d33c3e94ed2",
"comment": "Comentario de prueba.",
"author": "apm@athento.com",
"life_cycle_state": null,
"creation_date": "2025-01-10T10:19:04.504838+01:00",
"modified_date": "2025-01-10T10:19:04.504873+01:00",
"version": "0.0"
}
}
Usuarios — User Entity
Athento permite la gestión de usuarios desde la API v1 para crear nuevos, consultar, editar y operaciones asociadas.
A continuación se muestra la representación de un usuario.
{
"entity": "User",
"uuid": "fe1d49d0-dd0f-44db-b436-7857545560bb",
"username": "admin",
"email": "vs@athento.com",
"first_name": "Victor",
"last_name": "Sánchez",
"identification_number": "12345678X",
"phone_number": "+34600123456",
"job_title": "TI",
"is_active": true,
"teams": [{
"name": "Athento_ysvozgijse",
"label": "Athento"
}],
"date_joined": "2022-05-16T23:43:05.548400+02:00",
"language": "es"
}
Crear un usuario
Llamada genérica de creación:
POST https://demo.athento.com/api/v1/user/
Crear usuario
POST /api/v1/user/
Content-Type: application/json
Nombre | Valores | Opcional |
---|---|---|
| Nombre del usuario | False |
| Email del usuario | False |
| Nombre de la persona | True |
| Apellidos de la persona | True |
| Puesto | True |
| JSON con los atributos custom de la persona. | True |
| Listado de Equipos a los que pertenecerá el usuario. | True |
| Listado de Groups a los que pertenecerá la persona. | True |
Petición:
{
"username": "johnfoo",
"email": "jf@athento.com",
"first_name": "John",
"last_name": "Foo",
"job_title": "TI",
"custom_fields": {
"phone_number": "+34600123456",
"zona_de_trabajo": "Este"
},
"teams": [
"Athento_ysvozgijse"
],
"groups": [
"devops",
"colaboradores"
]
}
Respuesta:
{
"request-id": "5ba3aa4a-170e-4d92-80d5-e69c05bfb529",
"response": {
"message": "Execution success",
"code": "ok"
},
"result": {
"entity": "User",
"uuid": "8f165dd2-d8aa-4f0b-9a00-90ff60098e9b",
"username": "johnfoo",
"email": "jf@athento.com",
"first_name": "John",
"last_name": "Foo",
"identification_number": "00000000X",
"phone_number": "",
"job_title": "TI"
"teams": [{
"name": "Athento_ysvozgijse",
"label": "Athento"
}],
"is_active": true,
"date_joined": "2023-01-01T12:12:12",
"language": "en"
}
}
Modificar usuario
PUT /api/v1/user/
Content-Type: application/json
Petición:
{
"custom_fields": {
"department": {
"TI-Level2"
},
"groups": [
"devops",
"member"
]
}
}
Respuesta:
{
"request-id": "2e0fed76-74a9-43fe-8427-f4508e99fcbe",
"response": {
"message": "Execution success",
"code": "ok"
},
"result": {
"entity": "User",
"uuid": "8f165dd2-d8aa-4f0b-9a00-90ff60098e9b",
"username": "johnfoo",
"email": "jf@athento.com",
"first_name": "John",
"last_name": "Foo",
"identification_number": "00000000X",
"phone_number": "",
"job_title": "TI"
"is_active": true,
"date_joined": "2023-01-01T12:12:12",
"language": "en"
}
}
Activar usuario
POST /api/v1/user/{username}/activate/
Content-Type: application/json
Nombre | Valores | Opcional |
---|---|---|
| Nombre del usuario a activar. | False |
Respuesta:
{
"request-id": "2e0fed76-74a9-43fe-8427-f4508e99fcbe",
"response": {
"message": "Execution success",
"code": "ok"
},
"result": {
"entity": "User",
"uuid": "8f165dd2-d8aa-4f0b-9a00-90ff60098e9b",
"username": "johnfoo",
"email": "jf@athento.com",
"first_name": "John",
"last_name": "Foo",
"identification_number": "00000000X",
"phone_number": "",
"job_title": "TI"
"is_active": true,
"date_joined": "2023-01-01T12:12:12",
"language": "en"
}
}
El campo is_active
se encuentra actualizado a true
.
Desactivar usuario
POST /api/v1/user/{username}/deactivate/
Content-Type: application/json
Nombre | Valores | Opcional |
---|---|---|
| Nombre del usuario a activar. | False |
Respuesta:
{
"request-id": "2e0fed76-74a9-43fe-8427-f4508e99fcbe",
"response": {
"message": "Execution success",
"code": "ok"
},
"result": {
"entity": "User",
"uuid": "8f165dd2-d8aa-4f0b-9a00-90ff60098e9b",
"username": "johnfoo",
"email": "jf@athento.com",
"first_name": "John",
"last_name": "Foo",
"identification_number": "00000000X",
"phone_number": "",
"job_title": "TI"
"is_active": false,
"date_joined": "2023-01-01T12:12:12",
"language": "en"
}
}
El campo is_active
se encuentra actualizado a false
.
Grupos — Group Entity
Athento permite la gestión de grupos desde la API v1 para crear nuevos grupos y consultarlos.
A continuación se muestra la representación de un usuario.
{
"entity": "Group",
"name": "Members"
}
Crear un grupo
Llamada genérica de creación:
POST https://demo.athento.com/api/v1/group/
Crear grupo
POST /api/v1/group/
Content-Type: application/json
Nombre | Valores | Opcional |
---|---|---|
| Nombre del grupo | False |
| Listado de Equipos a los que pertenecerá el grupo. | True |
Petición:
{
"name": "MyGroup",
}
Si en la petición no se informa del Team o de los Teams donde será creado el grupo, se tomará por defecto el Team del usuario que realiza la petición.
Petición (con Teams):
{
"name": "MyGroup",
"teams": [
"Athento_ysvozgijse"
]
}
Respuesta:
{
"request-id": "bc9fb79b-b29c-4c25-aac6-4328d49f11c6",
"response": {
"message": "Execution success",
"code": "ok"
},
"result": {
"entity": "Group",
"name": "MyGroup_pnyxlfbupbyvibcuoajajp"
}
}
Búsqueda de documentos — Query & ResultSet Entities
Para realizar búsquedas de documentos sobre Athento es necesario usar servicios de query
para la obtención de columnas específicas en modo resultset
, o para obtener las entidades de documento completas. Éstos dos tipos de consulta son: resultset
y query
respectivamente.
Llamada genérica de consulta:
POST https://demo.athento.com/api/v1/search/{query—type}/?{rest—query}
Nombre | Valores | Opcional |
---|---|---|
query-type |
| False |
rest-query |
| True |
page
: es la página de documentos que se quiere obtener, por defecto, el valor depage
es 1.page_size
: es el tamaño de página de la ventana de documentos que se pretende obtener. Por defecto, el valor depage_size
es 20.
ResultSet
El servicio de resultset
devuelve el listado de columnas indicadas en la cláusula SELECT de la consulta realizada. Las columnas obtenidas pueden ser atributos del documento o metadatos del formulario asociado.
Ver la parte de creación de consultas usando lenguaje ATQL para más información de fabricación de consultas.
POST /api/v1/search/resultset/?page=1&page_size=20
Petición
{
"query": "SELECT uuid, filename, space FROM MyForm WHERE \
(((filename = 'PDF-Athento.pdf' or filename = 'PDF-Athento-Other.pdf') \
AND (form IN ('MyForm', 'OtherForm'))) \
AND (metadata.numero_contrato = '12345'))"
}
Respuesta:
{
"request-id": "220f74b7-0ab4-4c02-bf2f-2e40142e1c09",
"response": {
"message": "Execution success",
"code": "ok"
},
"result": {
"entity": "ResultSet",
"page": 1,
"pageSize": 20,
"totalCount": 1,
"totalPages": 1,
"maxPageSize": 200,
"entries": [
{
"uuid": "a39f0360-dba0-4586-a9e2-480eec7a9f6c",
"filename": "PDF-Athento.pdf",
"serie": {
"name": "MySerie"
}
},
{
"uuid": "f4435660-dba0-4586-a9e2-480eec7a9f6c",
"filename": "PDF-Athento-Other.pdf",
"serie": {
"name": "MySerie"
}
}
]
}
}
Use la cláusula GROUP BY
en el servicio de ResultSet
para obtener datos agrupados mediante funciones de agregación.
POST /api/v1/search/resultset/?page=1&page_size=20
Petición
{
"query": "SELECT count(space), count(doctype), count(metadata.numero_contrato), sum(metadata.total) FROM Document WHERE \
metadata.numero_contrato IN ('12345', '67890') GROUP BY space, doctype, metadata.numero_contrato, metadata.total"
}
Respuesta:
{
"request-id": "5664b7-4b22-98cb-1143-fe55442e3c01",
"response": {
"message": "Execution success",
"code": "ok"
},
"result": {
"entity": "ResultSet",
"totalCount": 10,
"entries": [
{
"space": [
{
"MySerie": 10
}
]
},
{
"doctype": [
{
"MyForm": 8
},
{
"MyOtherForm": 2
}
]
},
{
"metadata.numero_contrato": [
{
"12345": 3
},
{
"67890": 7
}
]
},
{
"metadata.total": [
{
"value": 445346.0,
"metric": "sum"
}
]
}
]
}
}
Query
El servicio de query
devuelve el listado de entidades de documento completas para la consulta realizada.
POST /api/v1/search/query/?page=1&page_size=20
Petición:
{
"query": "SELECT * FROM MyForm WHERE (((title = 'PDF-Athento.pdf' \
or title = 'PDF-Athento-Other.pdf') \
AND (form IN ('MyForm', 'OtherForm'))) \
AND (metadata.numero_contrato = '12345'))"
}
Respuesta:
{
"request-id": "d070d5a4-d30f-4238-8454-d4480ed17d67",
"response": {
"message": "Execution success",
"code": "ok"
},
"result": {
"entity": "Query",
"page": 1,
"pageSize": 20,
"totalCount": 1,
"totalPages": 1,
"maxPageSize": 200,
"entries": [
{
"entity": "Document",
"uuid": "a39f0360-dba0-4586-a9e2-480eec7a9f6c",
"filename": "PDF-Athento.pdf",
"creation_date": "2022-08-11T18:24:54.293897+02:00",
"modified_date": "2022-08-11T18:32:07.992000+02:00",
"state": "pending",
"version": "0.0",
"author": "admin",
"serie": "MySerie",
"doctype": "MyForm",
"container": true,
"file": {
"url": "uploads/Athento_ysvozgijse/Expedientes_nsyzx/2d/9c/2d9c09cdb21fd0a56eefd627240d554f.pdf",
"extension": ".pdf",
"hash": "2d9c09cdb21fd0a56eefd627240d554f",
"size": 34073,
"content_type": "application/pdf"
},
"life_cycle_state": "Inicio"
}
]
}
}
Consultas sobre documentos eliminados
Para consultar documentos eliminados debe indicarse el parámetro "removed": true
en tanto en resultset
como en query
del siguiente modo. Por defecto, las búsquedas se realizan sobre documentos que no están eliminados, pero con esta opción se ofrece la posibilidad de consultar sobre la papelera.
{
"query": "SELECT * FROM MyForm WHERE (((title = 'PDF-Athento.pdf' \
or title = 'PDF-Athento-Other.pdf') \
AND (form IN ('MyForm', 'OtherForm'))) \
AND (metadata.numero_contrato = '12345'))"
"removed": true
}
Ver la parte de creación de consultas usando lenguaje ATQL para mas información de fabricación de consultas.
ATQL
ATQL (Athento Query Language) es un lenguaje definido por Athento para realizar consultas simples o complejas basadas en su modelo documental, de manera que se pueda establecer una consulta que formalice qué campos del formulario se desean obtener, sobre qué tipos de formularios concretos y haciendo sobre qué condiciones establecidas sobre los propios campos —metadatos— incluidos en dichos formularios.
El formato ATQL es similar a SQL en cuanto a su estructura y cuenta con la capacidad de realizar datos resumidos mediante la cláusula GROUP BY
.
Ejemplos de consultas ATQL.
SELECT uuid, filename FROM MyForm WHERE (filename = 'Athento1.pdf' \
OR filename = 'Athento2.pdf') AND (metadata.contract_number = '123456' \
AND not metadata.ciudad_firma IN ('Málaga', 'Madrid')) ORDER BY uuid DESC
SELECT count(author), count(doctype) FROM MyForm WHERE serie = 'mi-serie') GROUP BY author, doctype
Sintaxis
La consulta ATQL es una expresión basada en cláusulas para la consulta de campos de un documento o entidades completas.
La sintaxis general de la consulta es:
SELECT (*|<select-clause>) FROM <from-clause> \
[ EXLUDE JOIN|JOIN <join-clause> ON <join-on-clause> ]
[ WHERE <where-clause> ] [ ORDER BY <order-by-clause> | GROUP BY <group-by-clause>]
La cláusula SELECT
es una lista de campos fijos y metadatos separados por coma, o el asterisco (SELECT * FROM ...
) para devolver la entidad documento completa.
La cláusula del FROM
es una lista de nombres de formularios separada por coma sobre el que se quiere consultar. Puede usarse el valor Document
para realizar la consulta sobre todos los tipos de formulario disponibles.
La cláusula JOIN
establece un enlace entre distintos formularios según una regla de vinculación incluida en la directiva ON
anexa.
La cláusula WHERE
es en general un predicado que contiene una lista de condiciones por las que se filtrarán los documentos. Dichas condiciones pueden ser anidadas en forma de expresión usando operadores lógicos AND
, OR
o NOT
.
La cláusula ORDER BY
permite realizar ordenaciones para campos del documento o metadatos.
La cláusula GROUP BY
permite también realizar agrupaciones y recuentos de documentos por campos o metadatos, además de aplicar funciones de agregación. Utilice la cláusula GROUP BY
en el servicio de ResultSet
para indicar la función de agregación.
Ejemplos de condiciones en forma de expresión:
expression
NOT
expressionexpression
<operator>
expression
Un operador puede ser:
AND
OR
=
!=
<
<=
>
>=
IN
BETWEEN
LIKE
ILIKE
IS
(el operadorIS
es similar al operador=
, salvo que puede usarse para localizar documentos con el valor del metadato anull
)
Campos fijos de consulta vs metadatos
En ATQL puede hacerse uso de campos nominales fijos que ayudan a obtener información del documento. Por ejemplo, la consulta sobre el título (title
ó filename
) o el identificador interno (uuid
).
Campo | Descripción | |
---|---|---|
| Identificador del documento | |
| Título del documento | |
| Creador del documento | |
| Fecha de creación del documento | |
| Fecha de modificación del documento | |
| Fecha de validación del documento | |
| Espacio donde se encuentra el documento | |
| Nombre del formulario | |
| Ciclo de vida del documento | |
| Estado del documento | |
| Tamaño del documento | |
| Documentos relacionados | |
| Documentos hijos |
Ejemplos:
SELECT filename, form, space, state FROM my_form WHERE \
((filename = 'PDF-Athento-One.pdf') \
AND space = 'Documentos_aeuxa') OR filename = 'PDF-Athento.pdf'
SELECT uuid, creation_date FROM my_form WHERE \
(creation_date BETWEEN '2022-01-01' AND '2022-12-31' \
OR modified_date > '2022-12-01') \
AND NOT state = 'pending' ORDER BY creation_date
SELECT * FROM my_form WHERE life_cycle_state = 'Iniciado' ORDER BY uuid DESC
SELECT count(life_cycle_state) FROM my_form WHERE life_cycle_state != 'Iniciado' GROUP BY life_cycle_state
Búsqueda por metadatos
Para la búsqueda de documentos usando metadatos del formulario, es necesario aplicar las condiciones con el nombre del metadatos. Ejemplos:
SELECT metadata.my_metadata FROM Document WHERE metadata.my_metadata IN ('1', '2')
SELECT uuid, metadata.my_metadata FROM my_form WHERE NOT metadata.my_metadata = '10'
SELECT uuid, metadata.my_metadata, metadata.my_other_metadata FROM form \
WHERE NOT metadata.my_metadata = '10' \
AND (metadata.my_other_metadata = '20' OR filename = 'PDF-Athento.pdf')
SELECT uuid, filename FROM form WHERE metadata.my_metadata is null
Ordenación
Para ordenar las búsquedas se deben hacer uso de la directiva ORDER BY, con el listado de campos fijos, o metadatos por los que queramos ordenar. Además, podemos establecer el tipo de ordenación, ascendente o descendente con ASC o DESC respectivamente.
Si no se especifica el tipo de ordenación, por defecto será ascendente.
Ejemplos:
SELECT uuid FROM Document ORDER BY uuid
SELECT filename FROM my_form WHERE filename LIKE 'pdf' ORDER BY filename, uuid DESC
SELECT uuid, metadata.my_metadata FROM my_form \
WHERE NOT metadata.my_metadata = '10' ORDER BY metadata.my_metadata ASC
Join
Para realizar búsquedas sobre documentos enlazados, ATQL permite el uso de la cláusula JOIN ... ON
y EXCLUDE JOIN ... ON
.
Los tipos de vinculación para JOIN
son:
Relación entre documentos, donde podemos indicar que un documento pueda ser hijo ó padre de otro.
Metadatos, donde podemos indicar la conexión entre metadatos iguales.
El orden de las formularios en el JOIN debe respetarse en la igualdad definida en ON. El formulario base debe estar en la parte izquierda de la igualdad y el formulario enlazado en la parte derecha.
Ejemplo:
SELECT * FROM my_form JOIN my_other_form ON my_form.parent = my_other_form.uuid
En el ejemplo, se obtienen los documentos de tipo my_form
y my_other_form
donde existe una relación padre-hijo entre ellos, y donde documentos de tipo my_other_form
son padres de documentos my_form
.
Si por al contrario, queremos obtener los documentos my_form
que no tienen relación con los documentos de tipo my_other_form
podemos usar el operador !=
en la directiva ON
.
Ejemplo:
SELECT * FROM my_form JOIN my_other_form ON my_form.parent != my_other_form.uuid
Si, queremos excluir en el resultado los documentos del tipo enlazado, debemos usar la directiva EXCLUDE
para el JOIN
.
Ejemplo:
SELECT * FROM my_form EXCLUDE JOIN my_other_form ON my_form.parent = my_other_form.uuid
Para el uso de JOIN
con metadatos, simplemente debemos indicar qué metadatos queremos usar para enlazar en la directiva ON
.
Los metadatos deben tener como prefijo el nombre del formulario seguido de un punto, por ejemplo:
... JOIN my_other_form ON my_form.metadata.my_form_metadata = my_other_form.metadata.my_other_form_metadata
Ejemplo:
SELECT * FROM my_form EXCLUDE JOIN my_other_form ON my_form.metadata.my_form_metadata = my_other_form.metadata.my_other_form_metadata
Funciones
ATQL permite el uso de funciones dinámicas para filtrar. A continuación se muestran las funciones disponibles.
Función | Parámetros | Descripción | |
---|---|---|---|
| Sí | Obtiene la fecha actual en formato Ejemplo: | |
| No | Obtiene la fecha del día actual en formato | |
| No | Obtiene la fecha del día anterior a hoy en formato | |
| No | Obtiene la fecha del día siguiente a hoy en formato | |
| No | Obtiene el nombre de usuario actual. |
Ejemplos:
Obtener los documentos creados en la última semana:
SELECT * FROM my_form WHERE creation_date > NOW(-1w)
Obtener los documentos creados hoy:
SELECT * FROM my_form WHERE creation_date > TODAY
Obtener los documentos creados desde ayer:
SELECT * FROM my_form WHERE creation_date > YESTERDAY
Obtener documentos creados por el usuario actual:
SELECT * FROM my_form WHERE author = CURRENT_USER
Obtener documentos creados entre hace una semana y mañana:
SELECT * FROM my_form WHERE created_date BETWEEN NOW(-1w) AND TOMORROW
Datos resumidos y funciones de agregación
ATQL permite el uso de GROUP BY
para realizar agregaciones sobre campos del documento. Recuerde incluir la función de agregación y la definición de la propiedad del documento en al propia cláusula GROUP BY
.
Por defecto, el número de resultados obtenidos para la agrupación de datos es 20. Puede usar el parámetro
page_size
para establecer un número mayor de resultados.
Las funciones de agregación disponibles son:
Función | Descripción | |
---|---|---|
| Cuenta el número de documentos distribuido por el valor. | |
| Sumatorio de los valores del metadato sobre el resultado de la consulta. | |
| Valor máximo del metadato sobre el resultado de la consulta. | |
| Valor mínimo del metadato sobre el resultado de la consulta. | |
| Media ponderada del metadato sobre el resultado de la consulta. | |
| Valor máximo y valor mínimo del metadato obtenidos al tiempo sobre el resultado de la consulta. |
Ejemplos:
Obtener el total de documentos agrupados por autor y serie.
SELECT count(author), count(serie), max(metadata.total_factura) FROM my_form WHERE creation_date > YESTERDAY GROUP BY author, serie, metadata.total_factura