Integración Filesystem

Próxima versión — Zylon 1.58Esta documentación se publica antes del lanzamiento para que puedas preparar tus integraciones de API. La imagen de la versión todavía no está disponible. Para instalaciones con 1.57, consulta la documentación de 1.57.

En 1.58, la validación de filesystem requiere credenciales anidadas incluso en la URL antigua. Consulta Migración de API 1.57 → 1.58 antes de actualizar tu integración.

La integración de Filesystem conecta un directorio compartido con el espacio de trabajo. Habilita el conector primero en la guía del operador: Configuración de Filesystem.

Requisitos previos

Un token de Workspace API y el slug de la organización.
Un proyecto de destino.
Las credenciales de Filesystem configuradas para la instancia.

Crear la integración

Crea la integración como un artefacto de tipo Integration. Las credenciales se envían en private_props y no se devuelven en las respuestas públicas.

Parametros del endpoint

Tipo	Nombre	Obligatorio	Notas
Body	`project_id`	No	Proyecto propietario de la integración. Omítelo para una integración de organización; esa operación requiere `AppAdmin` o superior.
Body	`type`	Si	Debe ser `Integration`.
Body	`source`	Si	Debe ser `FileSystem`.
Body	`name`	Si	Nombre visible de la integración.
Body	`props`	Si	Usa `{}`.
Body	`props.metadata`	No	Metadatos opcionales del proveedor.
Body	`private_props.username`	Si	Usuario de Filesystem.
Body	`private_props.password`	Si	Contraseña de Filesystem.

curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "Integration",
    "source": "FileSystem",
    "name": "Filesystem compartido",
    "props": {},
    "private_props": {
      "username": "{file_system_username}",
      "password": "{file_system_password}"
    }
  }'

Ejemplo de respuesta

{
  "id": "{integrationArtifactID}",
  "child_count": 0,
  "project_id": "{projectID}",
  "name": "Filesystem compartido",
  "type": "Integration",
  "source": "FileSystem",
  "state": "Published",
  "ingest_status": "NotApplicable",
  "props": {},
  "keep_file_after_ingestion": true,
  "created_at": "2026-02-08T14:10:00Z",
  "updated_at": "2026-02-08T14:10:00Z"
}

Actualizar las credenciales

Usa la operación general de actualización de artefactos. Envía solo los campos que quieras sustituir.

Parametros del endpoint

Tipo	Nombre	Obligatorio	Notas
Path	`integrationArtifactID`	Si	ID del artefacto de integración.
Body	`private_props.username`	Si	Nuevo usuario de Filesystem.
Body	`private_props.password`	Si	Nueva contraseña de Filesystem.

curl -X PUT "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "private_props": {
      "username": "{file_system_username}",
      "password": "{file_system_password}"
    }
  }'

La respuesta es el ArtifactDTO actualizado y nunca incluye private_props.

Obtener la integración

Usa el endpoint público del artefacto. No hay que recuperar las credenciales para consultar o iniciar una ingesta.

curl "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"

Ejemplo de respuesta

{
  "id": "{integrationArtifactID}",
  "child_count": 0,
  "project_id": "{projectID}",
  "name": "Filesystem compartido",
  "type": "Integration",
  "source": "FileSystem",
  "state": "Published",
  "ingest_status": "NotApplicable",
  "props": {},
  "keep_file_after_ingestion": true,
  "created_by": {
    "id": "{accountID}",
    "state": "Active",
    "email": "sasha@example.com",
    "name": "Sasha Patel",
    "provider": "Credentials",
    "roles": ["Workspace"],
    "created_at": "2026-02-08T14:12:45Z",
    "updated_at": "2026-02-08T14:12:45Z"
  },
  "created_at": "2026-02-08T14:10:00Z",
  "updated_at": "2026-02-08T15:02:00Z",
  "scopes": [
    {
      "scope_type": "project",
      "scope_id": "{projectID}",
      "enabled": true,
      "ws_auto_select": false
    }
  ]
}

Validar credenciales

La validación acepta la organización, un proyecto opcional y las credenciales en el cuerpo. Si omites project_id, necesitas el rol AppAdmin o superior; si lo envías, necesitas como mínimo el rol Admin del proyecto.

Parametros del endpoint

Tipo	Nombre	Obligatorio	Notas
Body	`organization_id`	Si	ID de la organización seleccionada mediante `x-org`.
Body	`project_id`	No	Proyecto donde se usarán las credenciales.
Body	`credentials.username`	Si	Usuario de Filesystem.
Body	`credentials.password`	Si	Contraseña de Filesystem.

curl -X POST "https://{BASE_URL}/api/v1/app/artifact/integration/filesystem/validate" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "{organizationID}",
    "project_id": "{projectID}",
    "credentials": {
      "username": "{file_system_username}",
      "password": "{file_system_password}"
    }
  }'

Ejemplo de respuesta

true

Listar archivos

Parametros del endpoint

Tipo	Nombre	Obligatorio	Notas
Path	`integrationArtifactID`	Si	ID del artefacto de integración Filesystem.

curl "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}/files" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"

Ejemplo de respuesta

[
  {
    "id": "/support/weekly-brief.pdf",
    "parentId": "/support",
    "name": "weekly-brief.pdf",
    "path": "/support/weekly-brief.pdf",
    "url": "file:///support/weekly-brief.pdf",
    "parent": "support",
    "isFile": true,
    "isDirectory": false,
    "isHidden": false,
    "lastModified": 1770488530000
  }
]

Iniciar la ingesta

Indica el proyecto de destino y las rutas que quieres importar. La respuesta es un stream de Server-Sent Events (SSE).

Parametros del endpoint

Tipo	Nombre	Obligatorio	Notas
Path	`integrationArtifactID`	Si	ID del artefacto de integración Filesystem.
Body	`project_id`	Si	Proyecto de destino.
Body	`item_paths`	Si	Rutas de archivos o directorios que se importarán.

curl -N -X POST "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}/ingest" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "project_id": "{projectID}",
    "item_paths": [
      "/support/weekly-brief.pdf",
      "/support/runbooks"
    ]
  }'

Ejemplo de stream

event: SyncEvent
data: {"type":"sync_started","current_artifact_count":0,"integration_item_count":2}

event: SyncEvent
data: {"type":"sync_progress","artifact_id":"{artifactID}","op":"Added","progress":0.5}

event: SyncEvent
data: {"type":"sync_completed"}

Errores y casos límite

400: faltan campos obligatorios o project_id no es válido.
403: conector no habilitado o permisos insuficientes.
404: organización, proyecto o artefacto de integración no encontrado.

Primeros pasos

Construye con Zylon

Coding Agents

Integración Filesystem

Requisitos previos

Crear la integración

Actualizar las credenciales

Obtener la integración

Validar credenciales

Listar archivos

Iniciar la ingesta

Errores y casos límite

​Requisitos previos

​Crear la integración

​Actualizar las credenciales

​Obtener la integración

​Validar credenciales

​Listar archivos

​Iniciar la ingesta

​Errores y casos límite

Requisitos previos

Crear la integración

Actualizar las credenciales

Obtener la integración

Validar credenciales

Listar archivos

Iniciar la ingesta

Errores y casos límite