1 Visión general
2 Cómo usar la API v1
- 2.1 Uso rápido
3 Acceda a Athento Explorer
4 Especificaciones generales
- 4.1 Formatos
  - 4.1.1 Cabeceras
  - 4.1.2 Petición
  - 4.1.3 Respuesta
- 4.2 Control de Errores
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

Modo	Endpoint	Descripción
Documento
POST	`/api/v1/file/`	Crea un nuevo documento.
GET	`/api/v1/file/{uuid}/`	Obtiene un documento en formato JSON indicando su `uuid`.
PUT	`/api/v1/file/{uuid}/`	Modifica un documento indicando su `uuid`.
DELETE	`/api/v1/file/{uuid}/`	Elimina un documento indicando su `uuid`.
GET	`/api/v1/file/{uuid}/download/`	Descarga el contenido de un documento.
POST	`/api/v1/file/download/`	Descarga el contenido de un listado de documentos.
POST	`/api/v1/file/{uuid}/lifecycle/transition`	Ejecuta una transición sobre el ciclo de vida de un documento.
POST	`/api/v1/file/{uuid}/run-operation/{operation_uuid}`	Ejecuta una operación sobre un documento.
Comentario
GET	`/api/v1/file/{file_uuid}/comment/`	Obtiene los comentarios de un documento indicando el `file_uuid` del documento.
POST	`/api/v1/file/{file_uuid}/comment/`	Crea un nuevo comentario sobre un documento.
GET	`/api/v1/file/{file_uuid}/comment/{uuid}/`	Obtiene un comentario de un documento indicando el uuid de ambos.
PUT	`/api/v1/file/{file_uuid}/comment/{uuid}/`	Modifica un comentario indicando su `uuid` y el `file_uuid` del documento.
DELETE	`/api/v1/file/{file_uuid}/comment/{uuid}/`	Borra un comentario indicando su `uuid` y el `file_uuid` del documento.
Búsqueda
POST	`/api/v1/search/query`	Busca documentos ejecutando una query ATQL y obteniendo los documentos como entidad.
POST	`/api/v1/search/resultset`	Busca documentos ejecutando una query ATQL y obteniendo las columnas incluidas en la cláusula `SELECT`.
NOTA los servicios de búsqueda usan el motor por defecto, sin embargo, en la llamada al servicio puede especificarse.
Usuario
POST	`/api/v1/user/`	Crea un nuevo usuario.
GET	`/api/v1/user/{username}/`	Obtiene un usuario en formato JSON indicando su `username`.
PUT	`/api/v1/user/{username}/`	Modifica un usuario existente.
POST	`/api/v1/user/{username}/activate`	Activa un usuario.
POST	`/api/v1/user/{username}/deactivate`	Desactiva un usuario.
Grupo
POST	`/api/v1/group/`	Crea un nuevo grupo.
GET	`/api/v1/group/{name}/`	Obtiene un grupo en formato JSON indicando su `name`.

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.

<p><p>&lt;p&gt;Athento Explorer&lt;/p&gt;</p></p>

Especificaciones generales

Formatos

Cabeceras

Nombre	Valores	Opcional

Nombre

Valores

Opcional

Accept-Type

*/*

True

Content-Type

application/json

multipart/form-data

False

X-Fetch-Mode

default

extended

full

True

Descripción

Accept-Type: es el tipo de contenido aceptado por el cliente.
Content-Type: es el tipo de contenido que se usará en las llamadas a la API v1.
X-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.
- NOTA

El modo de obtención de la entidad también puede establecerse desde el parámetro de request fetch_mode.

Ejemplo: https://{host}/api/v1/{service}/?fetch_mode=extended

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>
   }
}

Control de Errores

La API de Athento devuelve diferentes códigos de estado HTTP junto con un cuerpo JSON que detalla el tipo de error y su descripción.
A continuación se muestra una tabla con los códigos más habituales:

Código de estado (status_code)	Código de Error (interno)	Descripción	Posible Causa / Solución

Código de estado (status_code)	Código de Error (interno)	Descripción	Posible Causa / Solución
`200 OK`	—	Petición procesada correctamente.	—
`201 Created`	`ok` ó `created`	Recurso creado con éxito.	—
`400 Bad Request`	`invalid_request` ó `invalid` ó `error`	Error de sintaxis o parámetros inválidos.	Revisar los campos enviados; formato JSON incorrecto o datos faltantes.
`401 Unauthorized`	`authentication_failed`	Autenticación fallida.	BasicAuth incorrecto, Token JWT caducado o incorrecto; o cualquier forma de autenticación con error.
`403 Forbidden`	`permission_denied`	No tiene permisos para la acción solicitada.	Revisar permisos del usuario o rol asociado.
`404 Not Found`	`resource_not_found`	El recurso solicitado no existe.	Verificar identificador del documento o endpoint.
`405 Method Not Allowed`	`method_not_allowed`	El método no está permitido en el servicio.	Verificar el método en la llamada al endpoint.
`409 Conflict`	`conflict_error`	Conflicto con el estado actual del recurso.	El recurso ya existe o hay duplicidad de datos.
`415 Unsupported Media Type`	`unsupported_media_type`	Recurso no permitido	El recurso no está permitido en el sistema.
`422 Unprocessable Entity`	`validation_error`	Error de validación de campos.	Revisar que los datos cumplan las reglas del modelo.
`429 Too Many Requests`	`rate_limit_exceeded`	Se ha superado el límite de peticiones permitido.	Esperar antes de volver a enviar la solicitud.
`500 Internal Server Error`	`server_error` ó `error`	Error interno en el servidor.	Contactar con soporte Athento o revisar logs.
`501 Not Implemented`	`not_implemented`	El servicio no está implementado	—
`503 Service Unavailable`	`service_unavailable`	Servicio temporalmente no disponible.	Puede deberse a mantenimiento o sobrecarga temporal.

Por seguridad, Athento se reserva el derecho de no ampliar el detalle de errores que devuelve la API. Por favor, solicite a soporte si necesita más información sobre alguno de los errores y le indicarán cómo conocer el detalle.

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",
        "hash": "b7557e686681f32118ae0993ccbcd249",
        "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"
    }
}

Los documentos pueden ser creados dentro de Espacios documentales (Series) o bien, dentro de contenedores documentales, como Carpetas (Folder), que se encuentran en rutas dentro de un Espacio documental.

Para crear un documento dentro de un Espacio documental (Serie), se debe usar el parámetro serie en el payload de la llamada, para poder indicar el nombre del espacio o su UUID. Para crearlo dentro de un documento contenedor, se debe usar el parámetro folder que indique el UUID del dicho documento en el espacio.

En el siguiente ejemplo, se creará un documento en el Espacio documental con nombre MySerie:

{
    "filename": "My new document name",
    "doctype": "MyFormType",
    "serie": "MySerie",
    "metadatas": {
        "metadata.contract_number": "12345"
    } 
}

Y en el siguiente se creará en un documento contenedor, con UUID 391c097b-39f8-42d8-8af6-03696f114055. Es importante destacar, que, para este ejemplo, el Espacio destino será aquel en el que el documento contenedor 391c097b-39f8-42d8-8af6-03696f114055 se encuentre.

{
    "filename": "My new document name",
    "doctype": "MyFormType",
    "folder": "391c097b-39f8-42d8-8af6-03696f114055",
    "metadatas": {
        "metadata.contract_number": "12345"
    } 
}

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

Tipo	Descripción	Ejemplos
Text	Cadena de texto	`'Mi valor de metadato'`
Number	Número (Moneda, Porcentaje, …)	`50` `4.34` `0.21…`
Boolean	Booleano	`true` `false`
Date	Fecha	`'01-01-2025'` `'01/01/2025'` `'2025-01-01'` …
Datetime	Fecha y hora	`'01-01-2025 00:01:30'` `'2025-01-01 00:01:30'` ……
Table of items	Lista de items	`'[{"key1": "value1", "key2", "value2", ...]'`
Document	Referencia a documento (UUID)	`'dac466fd-a238-4dcc-8ba5-c30a4c2c57af'`
Document list	Referencias a documento (Lista de UUIDs)	`('dac466fd-a238-4dcc-8ba5-c30a4c2c57af', '5ac433f1-b2b1-4dc0-9bf5-ddd14c5c574f', 'dacdddfd-b218-4dee-8b15-c30a4c24dc0f', ...)`
Choice	Valor seleccionable	`'1'` `'John Smith'` `'Aprobado'` …
Multichoice	Valores seleccionables múltiples	`('1' ,'5', '4', ...)`

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 ó application/json

Petición:

{
  "filename": "My new document name",
  "serie": "MySerie",
  "doctype": "MyFormType",
  "metadatas": {
      "metadata.contract_number": "12345"
  }, 
  "file": <File> | <Base64-string>
}

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"
    }
}

Formato para incluir el binario en Base64: data:application/pdf;base64,JVBERi0xLjQKMSAwIG9ia...

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

Nombre	Valores	Opcional
template	Nombre o UUID de la plantilla	True
background	Realizar la generación del binario en segundo plano `true\|false`	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 documento con incremento de versión

Para crear una versión del documento puede usarse el parámetro versioning con valor true.

{
    "filename": ...
    "metadatas": { ... },
    "versioning": true
}

Actualizar contenido

La actualización del contenido de un documento, donde se le asocia un archivo binario. Puede incluirse en la petición como multipart/form-data o como cadena codificada en Base64.

Nombre	Valores	Opcional

Nombre	Valores	Opcional
Content-Type	`multipart/form-data` `application/json`	False

PUT /api/v1/file/{file-uuid}/

Content-Type: multipart/form-data ó application/json