Guía de la API de fichas

Una Ficha es el registro digital de un objeto físico: un activo, una pieza, un documento o un elemento de un flujo de trabajo. Contiene un nombre y una descripción, datos de campos tipados, archivos adjuntos, identificadores vinculados y un historial de eventos. Las fichas pertenecen a un Equipo, por lo que cada solicitud necesita un token de portador y la cabecera Dust-Ctx-Org-Id (además de Dust-Ctx-Team-Id para actuar como un Equipo específico); consulta Autenticación y Convenciones.

Esta guía abarca los principales flujos. Para consultar todos los parámetros y esquemas de respuesta, visita la referencia de la API.

Resumen de los endpoints

Operación	Método y ruta
Crear una o varias fichas	`POST /api/v1/threads`
Enumerar o buscar fichas	`GET /api/v1/threads`
Contar fichas	`GET /api/v1/threads/count`
Obtener una ficha	`GET /api/v1/threads/{thread_id}`
Actualizar metadatos y campos	`POST /api/v1/threads/{thread_id}`
Actualizar solo los campos	`POST /api/v1/threads/{thread_id}/data`
Enumerar datos de campos archivados	`GET /api/v1/threads/{thread_id}/data/archived`
Restaurar datos de campos archivados	`POST /api/v1/threads/{thread_id}/data/restore`
Archivar fichas	`PATCH /api/v1/threads/archive`
Restaurar fichas	`PATCH /api/v1/threads/restore`
Comprobar los permisos del solicitante	`POST /api/v1/threads/permissions`
Señal periódica de presencia	`POST /api/v1/threads/{thread_id}/presence`
Enumerar los archivos de una ficha	`GET /api/v1/threads/{thread_id}/files`
Establecer o cargar una miniatura	`PATCH` / `POST /api/v1/threads/{thread_id}/thumbnail`

Las actualizaciones de miniaturas aceptan un resourceId autorizado o un imageUri en línea de una imagen ráster en base64 cuyo tamaño descodificado no supere los 5 MiB. Las URL de imágenes remotas se rechazan. La carga de archivos sigue estando disponible mediante el endpoint de carga de miniaturas. Las miniaturas respaldadas por un recurso siguen los permisos de lectura actuales del recurso de origen: las respuestas devuelven null tanto para thumbnail como para thumbnailId cuando se deniega el acceso o el origen ya no está adjunto. Las miniaturas cargadas que no tienen un recurso de origen siguen la visibilidad de la ficha.

Crear una ficha

POST /api/v1/threads acepta tres estructuras de cuerpo, seleccionadas mediante type: single (una ficha), list (varias fichas normalizadas) y raw (registros planos de clave-valor). Las tres aceptan un bundleId opcional para crear las fichas dentro de una carpeta.

curl
TypeScript

curl -fsS "$APID_URL/api/v1/threads" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "single",
    "thread": { "name": "Tire SZ3J-11-ZJ17" },
    "data": [
      { "name": "Serial Number", "type": "text", "value": { "text": "SZ3J-11-ZJ17" } },
      { "name": "Max PSI", "type": "number", "value": { "number": 51 } }
    ]
  }'

const created = await client.threads.create({
  type: "single",
  thread: { name: "Tire SZ3J-11-ZJ17" },
  data: [
    { name: "Serial Number", type: "text", value: { text: "SZ3J-11-ZJ17" } },
    { name: "Max PSI", type: "number", value: { number: 51 } },
  ],
});

Los valores de los campos se anidan bajo value según su tipo: { "text": … }, { "number": … }, etc. La especificación define entradas para texto, texto largo, número, booleano, fecha, intervalo de fechas, fecha y hora, hora, duración, correo electrónico, teléfono, URL, JSON, selección, selección múltiple, etiquetas, referencias a recursos (archivos) y referencias a fichas.

Importación en bloque

Usa type: "list" cuando ya tengas objetos { thread, data } normalizados, o type: "raw" para proporcionar a la API registros planos; esta deriva los campos a partir de los pares de clave-valor de cada objeto y usa nameKey y descriptionKey (de forma predeterminada, name / description) para los metadatos propios de la ficha:

{
  "type": "raw",
  "nameKey": "serial",
  "raw": [
    { "serial": "SZ3J-11-ZJ17", "part": "P355/30R19", "maxPsi": 51 }
  ]
}

Para importar estructuras completas de ensamblajes de forma atómica, consulta POST /api/v1/imports/plan y POST /api/v1/imports/commit en la referencia.

Consultar fichas

GET /api/v1/threads/{thread_id} devuelve la ficha con los datos de sus campos (una consulta opcional maxEvents incluye los eventos recientes). GET /api/v1/threads devuelve una lista con paginación mediante cursor (cursor, pageSize, order, orderCol) y admite filtros como:

Filtro	Significado
`q`, `queryCol`	Búsqueda de texto, restringida opcionalmente a una columna
`bundleId`	Fichas de una carpeta o categoría
`templateId`	Fichas creadas a partir de una plantilla
`tagType`	Fichas que tienen vinculado un identificador de este tipo
`hasResources`	Fichas con archivos adjuntos
`includeArchived`, `archivedOnly`	Visibilidad del archivo
`createdBy`, `ownedByTeam`	Filtros de procedencia
`excludeTransferred`, `transferredOnly`	Fichas enviadas fuera
`withActiveShipment`	Anotar cada artículo con su envío activo, si lo hubiera

GET /api/v1/threads/count acepta los mismos filtros y devuelve únicamente el recuento, lo que resulta útil para paneles y resúmenes de paginación.

Actualizar una ficha

Dos endpoints, cada uno con una finalidad:

POST /api/v1/threads/{thread_id} — acepta { thread, update?, remove? }: metadatos de la ficha (nombre, descripción, plantilla, etc.) más cambios opcionales en los campos en una sola llamada.
POST /api/v1/threads/{thread_id}/data — solo campos: { threadId, update, remove?, expectedUpdatedAt? }. Los campos de update se insertan o actualizan (se buscan por nombre o ID); remove acepta ID de campos.

{
  "threadId": "9f6a…",
  "update": [
    { "name": "VIN", "type": "text", "value": { "text": "1HGCM82633A004352" } }
  ],
  "remove": []
}

Datos de campos archivados

Al eliminar un campo, este se archiva en lugar de destruirse. GET /api/v1/threads/{thread_id}/data/archived enumera los campos archivados y POST /api/v1/threads/{thread_id}/data/restore los restaura por ID ({ threadId, restore: ["field-id", …] }).

Archivar y restaurar fichas

El archivado se realiza en bloque y es reversible:

PATCH /api/v1/threads/archive — { threadIds: […], toggle? }. Con toggle: true, las fichas archivadas de la lista se restauran y las activas se archivan en una sola llamada.
PATCH /api/v1/threads/restore — restaura fichas archivadas.

Las fichas archivadas desaparecen de las listas predeterminadas; usa includeArchived o archivedOnly para verlas.

Permisos

Antes de mostrar controles de edición o intentar escribir en varias fichas, consulta qué puede hacer realmente el solicitante:

curl -fsS "$APID_URL/api/v1/threads/permissions" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{ "threadIds": ["9f6a…", "c2d1…"] }'

POST /api/v1/threads/permissions devuelve los permisos efectivos del solicitante para cada ficha en el contexto del Equipo actual. Consultas relacionadas: GET /api/v1/threads/{thread_id}/access (qué Equipos proporcionan acceso) y GET /api/v1/threads/{thread_id}/shared (con quién se comparte la ficha); ambas se explican en Equipos, uso compartido y conexiones.

Presencia

POST /api/v1/threads/{thread_id}/presence es una señal periódica: envíala periódicamente mientras un usuario consulta una ficha (opcionalmente con el name / la image mostrados y con leaving: true al salir), y la respuesta enumerará los usuarios que están consultando la ficha en ese momento. DICE la utiliza para el indicador «quién más está aquí».

Archivos y miniaturas

Los archivos se adjuntan a las fichas mediante la API de archivos; las consultas del lado de la ficha están aquí:

GET /api/v1/threads/{thread_id}/files — los archivos de la ficha, paginados mediante cursor (includeArchived es obligatorio).
GET /api/v1/threads/{thread_id}/files/{res_id} / POST …/files/{res_id} — consultar y actualizar un único archivo adjunto.
POST /api/v1/threads/{thread_id}/thumbnail — cargar una imagen (multipart, campo thumbnail) y establecerla como miniatura de la ficha en un solo paso.
PATCH /api/v1/threads/{thread_id}/thumbnail — establecer la miniatura a partir del ID de un recurso existente o de un URI de imagen.

Modelo básico — cómo se relacionan las fichas con todo lo demás
Guía de la API de identificadores — cómo vincular identificadores físicos a fichas
Guía de la API de archivos — cargas y descargas
Referencia de la API — esquemas completos de todos los endpoints anteriores

Informar de un problema en la documentación