¿Cómo acceder, previsualizar o crear un documento desde otra aplicación vía URL?

Para facilitar las labores de integración, Athento ofrece la capacidad de usar URLs (que pueden enlazarse o embeberse en e-frames) para previsualizar documentos, crearlos o consultarlos.

Con estas URLs, es posible acceder a un documento indicando valores de sus metadatos para que Athento se encargue de localizarlo y presentarlo al usuario.

Previsualizar el archivo principal

Para ello, se usará el siguiente patrón en la URL:

https://app.athento.com/file/view/_/?filter=<filtro>

donde,

• <filtro>, es el el conjunto de campos (con sus valores) que usará Athento para localizar el documento que contenga esos valores en los campos indicados. 
  • Ej: metadata.mymetadata=123456&metadata.myothermetadata=5678
    NOTA: el valor del filtro deberá estar cifrado según la política de Athento.

Es importante destacar que, dado que existe la posibilidad de que varios documentos coincidan en el filtro indicado, los campos usados deben ser configurados como campos clave. Si ocurre que varios documentos coinciden en el filtro, Athento mostrará el primer documento localizado del resultado del filtro.

NOTA: Los campos clave son aquellos cuyo valor será único en cada documento de Athento.

Crear documentos

Además de poder únicamente filtrar para visualizar un documento por sus campos, esta funcionalidad ofrece distintos parámetros de URL que permiten, crear un nuevo documento si no se localiza en el filtrado, y/o visualizarlo en modo Carrousel y Lista.

Para el caso de crear el documento si no es localizado con los campos indicados en el filtro, se usará el parámetro create_if:

https://app.athento.com/file/view/_/?filter=<filtro>&create_if=true

donde tras el filtrado, si Athento no localiza el documento, lo creará y accederá a él con los campos. El documento se creará en el espacio por defecto del usuario y sobre el tipo de formulario por defecto de ese propio espacio.

Si queremos indicar sobre qué espacio y usando qué tipo de formulario usar para la creación en caso de que el filtro no localice ningún documento, tendríamos:

https://app.athento.com/file/view/_/?filter=<filtro>&create_if=true&serie=<serie>&type=<tipo>

donde,

• <serie>, es el nombre (o uuid) del espacio destino donde se pretende guardar el documento en caso de que no sea localizado por el filtro.
• <tipo>, es el nombre del tipo de formulario que se usará para crear el nuevo documento en caso de que no sea localizado por el filtro.

Previsualizar los documentos relacionados

Además de la visualización y/o creación del documento mediante el filtro de campos, Athento puede previsualizar los documentos relacionados. Esto es muy útil para casos de integración donde el cliente necesita previsualizar el ó los documentos relacionados embebiendo esta URL.

Para previsualizar un documento usando el filtro, usaremos el parámetro display, de esta manera:

https://app.athento.com/file/view/_/?filter=<filtro>&display=<modo>

donde,

• <modo>, es el modo de visualización que queremos mostrar. Existen dos tipos de previsualizaciones: "carrousel" ó "list".
  • El modo carrousel mostrará un carrousel con las previsualizaciones de los documentos relacionados.

• • El modo list (lista) mostrará una lista con los documentos relacionados y operaciones sobre los propios documentos.

NOTA: Es importante destacar que la previsualización puede ser usada en la URL adicionalmente a todas las funcionalidades anteriores, es decir, además de filtrar por metadatos para localizar el documento podríamos crearlo si no existe, usando el espacio, el tipo de formulario para finalmente previsualizarlo en el modo que queramos.

Seguridad

Para realizar la previsualización embebida, es necesario usar un token de seguridad adicional en la URL que controlará el acceso a Athento, quedando la URL de este modo:

https://app.athento.com/file/view/_/?token=<token>&filter=<filtro>&display=<modo>

donde,

• <token>, es el token de acceso de uso limitado.

Para obtener un token de seguridad para el uso de previsualización de un documento mediante el filtrado es necesario obtenerlo con la siguiente llamada a la API autenticada (puede usarse cualquier tipo de autenticación disponible en Athento para realizar la llamada, por ejemplo BasicAuth).

GET https://app.athento.com/users/api/access/access_token/?duration=<duracion>

donde,

• <duracion>, es la duración que tendrá el token antes de que expire y no pueda ser usado. El formato de duración se baso en unidades de tiempo, por ejemplo, usar "1d5h" para establecer una duración de 1 día y 5 horas. Las unidades posibles son: "s" para segundos, "m" para minutos, "h" para horas, "d" para días. Algunos ejemplos:
  • 5m: duración de 5 minutos
  • 10h: duración de 10 horas
  • 20d: duración de 20 días
  • 15d10m30s: duración de 15 días 10 minutos y 30 segundos.

Formato del filtro

El formato del filtro debe ser una cadena del estilo:

metadata.num_proveedor=12345&metadata.num_proyecto=987

Esta cadena debe codificarse en base 64.

Por favor, contacta con soporte@athento.com para concretar el formato definitivo ya que, por seguridad, este formato no se publica.

Extensiones previsualizables

Athento permite la previsualización de las extensiones.

• .pdf
• .eml
• .msg
• .png
• .jpg
• .jpeg
• .gif
• .svg
• .raw
• .tiff
• .tif