> ## Documentation Index > Fetch the complete documentation index at: https://docs.tess.im/llms.txt > Use this file to discover all available pages before exploring further. # API de Artifacts: guía de integración > Genera, versiona y comparte Artifacts desde tus sistemas: informes recurrentes, dashboards y comunicados publicados por la API, con las mismas reglas del panel. La API de Artifacts permite que tus sistemas produzcan y distribuyan entregables en Tess sin pasar por el chat. Un pipeline de BI puede generar el informe semanal para la dirección, un CRM puede publicar la propuesta para el equipo comercial y una rutina mensual puede actualizar el dashboard de indicadores, siempre en el mismo enlace y con historial de versiones. La API sigue las mismas reglas del panel: el dueño, los permisos por plan y rol y las restricciones de uso compartido definidas por el administrador. Nada de lo que hace la API evita la gobernanza del workspace. Para conocer la función, consulta [Artifacts](https://docs.tess.im/es/html-artifacts.md). ## Antes de empezar * **Clave de API:** envíala como token Bearer en el header `Authorization`. Consulta [Autenticación](https://docs.tess.im/es/api-quickstart.md). * **Workspace:** el header `x-workspace-id` es obligatorio en todas las llamadas. Sin él, la respuesta es `403`. * **Permisos:** las acciones dependen de que la función esté habilitada y del plan y del rol del usuario dueño de la clave. | Permiso | Qué habilita | | - | - | | Artifacts User | Crear, editar, restaurar, renombrar, compartir y eliminar tus propios Artifacts | | Eliminación de contenido del workspace | Necesario, junto con Artifacts User, para eliminar un Artifact o una versión | | Artifacts Manager | Leer cualquier Artifact del workspace (con registro en auditoría) y despublicar cualquiera de ellos | ## Conceptos * **Dueño:** quien crea el Artifact. Solo el dueño lo modifica, publica y comparte. Los demás reciben `404` (no saben que el Artifact existe) o `403 ARTIFACT_EDIT_FORBIDDEN` (pueden leerlo, pero no modificarlo). * **Versión más reciente (`head_version`):** cada edición o restauración crea una nueva versión. Las ediciones siempre parten de la más reciente. * **Versión compartida (`shared_version`):** la versión que ve quien tiene acceso. Cambia cuando publicas otra versión, en el primer uso compartido (que publica la versión más reciente), cuando se elimina la versión compartida (pasa a la anterior más reciente) y al despublicar (queda nula). Las ediciones nunca la cambian, así puedes revisar antes de liberar. * **Enlace (`viewer_url`):** la dirección del Artifact en Tess. Se mantiene entre versiones y exige iniciar sesión en Tess, incluso para el acceso público. ## Flujo de integración **1. Elige la plantilla (opcional)** [Listar Plantillas de Artifact](https://docs.tess.im/es/list-artifact-templates.md) devuelve las plantillas globales y las propias del workspace; cuando el slug es el mismo, prevalece la del workspace. Sin elección, la creación usa `default`, con la identidad visual de Tess. **2. Crea el Artifact** [Crear Artifact](https://docs.tess.im/es/create-artifact.md) recibe el título y el HTML del cuerpo, con CSS y JavaScript opcionales. La respuesta devuelve `universal_id`, la versión 1 y el `viewer_url`. El Artifact nace privado. ```bash theme={null} curl --request POST \ --url 'https://api.tess.im/artifacts' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --header 'x-workspace-id: YOUR_WORKSPACE_ID' \ --data '{"title": "Pipeline semanal", "lang": "es", "content": "

Pipeline semanal

Pipeline abierto: USD 1,2 M

"}' ``` **3. Comparte con el público correcto** [Compartir Artifact](https://docs.tess.im/es/share-artifact.md) concede acceso a personas, equipos, al workspace o a cualquier persona con sesión en Tess. El primer acceso concedido publica la versión actual. ```json theme={null} { "grant": [{ "type": "team", "team_id": 87 }, { "type": "user", "email": "cfo@empresa.com" }] } ``` **4. Actualiza sin cambiar el enlace** En el siguiente ciclo, usa [Editar Artifact](https://docs.tess.im/es/edit-artifact.md) con `base_version` para aplicar los cambios. La nueva versión no llega a quien tiene acceso (solo el dueño y los gestores con Artifacts Manager ven la versión más reciente) hasta que llames a [Publicar Versión del Artifact](https://docs.tess.im/es/publish-artifact.md). ```json theme={null} { "base_version": 1, "operations": [{ "op": "replace", "old": "USD 1,2 M", "new": "USD 1,4 M" }] } ``` **5. Controla el historial** [Listar Versiones del Artifact](https://docs.tess.im/es/list-artifact-versions.md) muestra la versión más reciente y la compartida. Para volver atrás, usa [Restaurar Versión del Artifact](https://docs.tess.im/es/restore-artifact-version.md) y publica la versión restaurada. > [!TIP] > > Para materiales recurrentes, guarda el `universal_id` y edita el mismo Artifact en cada ciclo. Así el enlace enviado a la dirección nunca cambia, y el historial muestra la evolución de los números. ## Uso compartido y gobernanza * Conceder acceso respeta las restricciones del usuario, definidas por el administrador en la página de miembros. Por defecto, organización, workspace y equipos están habilitados y el acceso público no. * Solo se pueden agregar personas que sean miembros activos del workspace o de la organización. * Una llamada de uso compartido es todo o nada: si un destino es rechazado, no se guarda nada y la respuesta lista `rejected_targets`. * [Despublicar Artifact](https://docs.tess.im/es/unpublish-artifact.md) elimina todos los accesos a la vez. Cuando un gestor despublica, el dueño no puede publicar de nuevo. * Los permisos se verifican en cada apertura: quien sale del workspace o pierde un nivel de uso compartido pierde el acceso al instante. * En el plan Enterprise, los cambios hechos por la API (crear, editar, publicar, compartir, eliminar) también aparecen en los [Eventos de Auditoría](https://docs.tess.im/es/audit-events.md), con `entity_type` igual a `artifact`. ## Errores Los errores específicos de Artifacts devuelven un código estable en `error_code` y una explicación en `message`. Los errores de validación, de workspace, de límite de solicitudes y de permiso de eliminación devuelven solo `message` (la validación también trae `errors`). Ejemplo: ```json theme={null} { "error_code": "ARTIFACT_STALE", "message": "Artifact is at version 4, edit was based on 3." } ``` | Status | Significado | | - | - | | `403` | Sin permiso para la acción (función desactivada, plan, rol, eliminación de contenido), workspace ausente o del que no eres miembro, publicación revocada por un gestor (`ARTIFACT_PUBLICATION_REVOKED`), o puedes leer el Artifact pero no eres el dueño | | `404` | El Artifact, la versión o la plantilla no existe, o no te pertenece; o el workspace indicado no existe | | `409` | `ARTIFACT_STALE`: la versión más reciente cambió desde `base_version`. Lee de nuevo y reintenta | | `422` | Datos inválidos, una edición que no se aplica o un destino de uso compartido rechazado | | `429` | Límite de solicitudes alcanzado | Cada página de endpoint lista sus códigos. Para los status generales de la API, consulta [Errores](https://docs.tess.im/es/errors.md). ## Límites | Elemento | Límite | | - | - | | Lecturas (`GET`) | 600 por minuto por usuario, sumadas al uso en el panel | | Escrituras | 120 por minuto por usuario, sumadas al uso en el panel | | Operaciones por edición | 40 | | Texto de una edición | 12.000 caracteres, sumando todos los campos de todas las operaciones (incluidos anclajes y selectores) | | Contenido del Artifact | 2.000.000 caracteres | | `styles` y `script` en la creación | 500.000 caracteres cada uno | | Destinos por llamada de uso compartido | 50 en `grant` y 50 en `revoke` | > [!WARNING] > > El contenido es estático: el script de la página no accede a la red. Para actualizar números, edita el Artifact con los datos nuevos y publica la versión. ## Endpoints > [card] [Listar Artifacts](https://docs.tess.im/es/list-artifacts.md) > > Tus Artifacts en el workspace, con paginación. > [card] [Crear Artifact](https://docs.tess.im/es/create-artifact.md) > > Versión 1 a partir de una plantilla. > [card] [Obtener Artifact](https://docs.tess.im/es/get-artifact.md) > > Versión más reciente con el HTML. > [card] [Editar Artifact](https://docs.tess.im/es/edit-artifact.md) > > Operaciones de edición que crean una nueva versión. > [card] [Publicar versión](https://docs.tess.im/es/publish-artifact.md) > > Define la versión que ve el público. > [card] [Compartir Artifact](https://docs.tess.im/es/share-artifact.md) > > Concede y revoca accesos. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.