Modelo central

La API de la plataforma DUST modela los flujos de trabajo de objetos físicos mediante un pequeño conjunto de recursos que pueden combinarse. Una Ficha es el registro digital de un artículo físico; todo lo demás —identificadores, archivos, carpetas, ensamblajes, recursos compartidos y envíos— se adjunta a las Fichas, las organiza o las mueve. Esta página es el mapa: una sección breve por concepto, con los principales endpoints y un enlace a la guía detallada.

Correspondencia de nombres

Algunos espacios de nombres de la API son anteriores al vocabulario actual del producto. La aplicación web DICE y esta documentación usan los nombres de la izquierda; las rutas de la API conservan los nombres de la derecha.

Nombre en DICE / la documentación	Espacio de nombres de la API	Notas
Fichas	/api/v1/threads	—
Identificadores	/api/v1/tags	Denominación heredada tags en las rutas
Archivos	/api/v1/files	Se denominan recursos en algunos esquemas
Carpetas y categorías	/api/v1/bundles	Bundle es el nombre de implementación
Ensamblajes	/api/v1/assemblies	Los ensamblajes son Fichas de tipo assembly
Equipos	/api/v1/teams	Se seleccionan en cada solicitud mediante la cabecera Dust-Ctx-Team-Id (también se sigue aceptando la cabecera heredada Dust-Ctx-Grp-Id)
Conexiones	/api/v1/connections	Los esquemas de intercambio conservan la denominación heredada team link
Recursos compartidos	/api/v1/sharing	—
Envíos	/api/v1/transfers	Denominación heredada transfers en las rutas
Divisiones	/api/v1/slices	—
Fabric	/api/v1/fabric	Grafo de procedencia entre organizaciones
Certificados	/api/v1/certificates, /api/v1/certificate-forms	—
Páginas públicas	/api/v1/public-pages, /api/v1/public-page-designs	La publicación requiere el permiso publisher del Equipo
Eventos	/api/v1/events	—

Cada solicitud incluye un token de portador de AuthD; los endpoints cuyo ámbito es una organización —prácticamente todos— añaden la cabecera Dust-Ctx-Org-Id (y, opcionalmente, Dust-Ctx-Team-Id para seleccionar un Equipo). Consulta Autenticación y Convenciones. La referencia completa a nivel de parámetros se encuentra en la referencia de la API.

Fichas

Una Ficha es el registro de un activo físico, una pieza, un documento o un elemento de un flujo de trabajo: un nombre y una descripción, datos de campos tipados, archivos adjuntos, identificadores vinculados y un historial de eventos. Las Fichas tienen un kind: unidades ordinarias o assembly (consulta más abajo).

• POST /api/v1/threads — crear una o varias
• GET /api/v1/threads — buscar y enumerar (paginación mediante cursor)
• GET /api/v1/threads/{thread_id} — obtener una, con los datos de sus campos
• POST /api/v1/threads/{thread_id}/data — insertar, actualizar o eliminar valores de campos
• PATCH /api/v1/threads/archive / PATCH /api/v1/threads/restore — ciclo de vida del archivado

Más información: Guía de la API de Fichas.

Campos y Plantillas

Los valores de los campos están tipados (text, number, date, select, referencias a recursos e incluso campos cuyo valor es una ficha) y se anidan por tipo. Las Plantillas definen los campos previstos para un tipo repetible de Ficha.

• POST /api/v1/templates / GET /api/v1/templates — crear y enumerar plantillas
• GET /api/v1/templates/{templateId} / PATCH /api/v1/templates/{templateId} — leer y actualizar

Identificadores

Un identificador vincula una marca física —un identificador DUST, un código QR, un código de barras, un símbolo Data Matrix o un chip NFC— a una Ficha, de modo que un escaneo sobre el terreno se resuelva en el registro digital. El espacio de nombres de la API es /api/v1/tags (denominación heredada).

• POST /api/v1/tags/extract — analizar una captura DUST para obtener una huella canónica sin vincularla
• POST /api/v1/tags/bind — adjuntar un identificador a una Ficha
• POST /api/v1/tags/identify — encontrar la Ficha que coincide con un escaneo
• POST /api/v1/tags/verify — confirmar que un escaneo coincide con los identificadores de una Ficha específica
• POST /api/v1/tags/unbind — desvincular un identificador

Más información: Guía de la API de Identificadores.

Archivos

Los archivos (denominados recursos en algunos esquemas) se almacenan en almacenamiento de objetos y se adjuntan a las Fichas directamente o mediante campos de tipo recurso. Las cargas grandes usan el protocolo reanudable tus; las pequeñas usan una única solicitud POST multipart.

• POST /api/v1/files — carga multipart sencilla
• POST /api/v1/files/finalize — convertir las cargas tus completadas en registros de recursos
• GET /api/v1/files/{resource_id}/download — descargar
• POST /api/v1/files/urls — URL firmadas de corta duración
• GET /api/v1/files/search — buscar en los archivos

Más información: Guía de la API de Archivos.

Equipos y Organizaciones

La identidad reside en AuthD; la API de la plataforma circunscribe cada solicitud cuyo ámbito es una organización a una Organización y un Equipo mediante cabeceras de contexto. Los Equipos son propietarios de las Fichas, y los recursos compartidos, las conexiones y los envíos se gestionan entre Equipos.

• GET /api/v1/me — usuario actual y organizaciones disponibles
• GET /api/v1/teams — Equipos visibles para quien realiza la llamada
• POST /api/v1/org/teams / PATCH /api/v1/org/teams/{team_id} — administración de Equipos (administradores de la organización)
• POST /api/v1/org/teams/members — administrar pertenencias (administradores de la organización)

Más información: Equipos, recursos compartidos y conexiones.

Carpetas y categorías

Las Carpetas y las Categorías organizan las Fichas. Ambas son bundles en la API —kind: "folder" para la contención exclusiva y kind: "category" para el etiquetado no exclusivo— y los bundles se anidan para formar árboles.

• POST /api/v1/bundles — crear (con kind y un elemento principal childOfId opcional)
• GET /api/v1/bundles / GET /api/v1/bundles/children — enumerar o recorrer el árbol de forma diferida
• POST /api/v1/bundles/{bundle_id}/add / PATCH /api/v1/bundles/{bundle_id}/move — colocar Fichas
• PATCH /api/v1/bundles/parent — cambiar el elemento principal de un bundle

Ensamblajes y Piezas

Un ensamblaje es una Ficha de tipo assembly cuyas Piezas son otras Fichas: una estructura de lista de materiales. Las Piezas pueden protegerse contra su separación y las listas de piezas se agregan transitivamente.

• GET /api/v1/assemblies — enumerar las Fichas de ensamblaje
• POST /api/v1/assemblies/{assembly_id}/parts / DELETE /api/v1/assemblies/{assembly_id}/parts — adjuntar y separar Piezas
• GET /api/v1/assemblies/{assembly_id}/rolled-up-parts — lista transitiva de piezas
• PATCH /api/v1/assemblies/{assembly_id}/kind — convertir una Ficha entre unit y assembly
• POST /api/v1/imports/plan / POST /api/v1/imports/commit — simular y confirmar un paquete completo de importación de un ensamblaje

Enlaces y relaciones entre Fichas

Las Fichas pueden hacer referencia unas a otras mediante enlaces tipados. Las definiciones de relaciones dan nombre a los tipos de relación; los enlaces entre fichas son sus instancias.

• POST /api/v1/relations / GET /api/v1/relations — definir y enumerar tipos de relaciones
• POST /api/v1/links / GET /api/v1/links — crear y enumerar enlaces entre Fichas
• GET /api/v1/threads/{thread_id}/links — enlaces desde la perspectiva de una Ficha
• DELETE /api/v1/links/{link_id} — eliminar el enlace

Recursos compartidos

Compartir concede a otro Equipo acceso de tipo viewer o editor a una Ficha o un bundle. Los permisos se almacenan como tuplas de relaciones; el resumen de acceso muestra el resultado efectivo, incluido el acceso heredado.

• POST /api/v1/sharing — compartir Fichas o bundles con Equipos
• GET /api/v1/sharing — enumerar permisos (direction=in|out)
• GET /api/v1/sharing/access-summary — acceso efectivo a un objeto
• GET /api/v1/sharing/partner-inventory — todo lo compartido con un Equipo asociado

Más información: Equipos, recursos compartidos y conexiones.

Conexiones

Una Conexión (en la API: team link) es el acuerdo permanente entre dos Equipos —a menudo pertenecientes a Organizaciones distintas— que permite compartir y realizar envíos, con una dirección permitida para el flujo de datos. Cuenta con un proceso de invitación, aceptación y confirmación, así como con un ciclo de vida de pausa y reanudación.

• POST /api/v1/connections — crear (invitar)
• PATCH /api/v1/connections/accept / confirm / reject / cancel — proceso de acuerdo
• PATCH /api/v1/connections/pause / resume — suspender y restaurar
• POST /api/v1/connections/amend/propose — proponer un cambio de dirección

Envíos

Un Envío (en la API: transfer) transfiere la propiedad de las Fichas de un Equipo a otro: se crea un borrador de manifiesto, se envía y el destinatario lo acepta, lo rechaza o solicita cambios.

• POST /api/v1/transfers — crear un borrador
• POST /api/v1/transfers/{transfer_id}/items — añadir artículos al manifiesto
• POST /api/v1/transfers/{transfer_id}/send — enviar al Equipo destinatario
• POST /api/v1/transfers/{transfer_id}/respond — aceptar / rechazar / solicitar cambios
• GET /api/v1/transfers — vistas de entrada, salida y enviados

Semántica y ciclo de vida: Envíos; resumen de endpoints en Equipos, recursos compartidos y conexiones.

Divisiones

Una División deriva una Ficha nueva de otra existente dentro del mismo Equipo —copiando o enlazando campos, archivos e identificadores seleccionados—, por lo general para preparar un subconjunto que pueda compartirse.

• POST /api/v1/slices — dividir una Ficha
• POST /api/v1/slices/batch — derivar varias Fichas a la vez
• GET /api/v1/slices/{slice_id} — una División con sus enlaces de Fabric

Fabric

Fabric es la capa de procedencia entre organizaciones: cuando las Fichas se mueven o se divulgan más allá de los límites de un Equipo, Fabric registra el grafo de Fichas enlazadas y controla exactamente qué datos puede ver cada parte posterior (divulgación), revisión por revisión.

• GET /api/v1/fabric/threads/{thread_id}/graph — el grafo de procedencia visible desde una Ficha
• GET /api/v1/fabric/links/{link_id}/context — los datos divulgados actualmente en un enlace
• POST /api/v1/fabric/threads/{thread_id}/disclosure/revise / redact — cambiar lo que se divulga
• POST /api/v1/fabric/threads/{thread_id}/disclosure/push — enviar una divulgación a las partes posteriores
• GET /api/v1/fabric/notifications — notificaciones de divulgación para propietarios posteriores

Conceptos: Fabric.

Certificados

Los Certificados presentan los datos de una Ficha en forma de documentos emitidos y verificables. Los Formularios de Certificados son los diseños; la generación vincula un formulario a una Ficha mediante el nombre del campo.

Un formulario puede contener varias zonas QR de Vlink. La generación de Certificados acepta una configuración de Vlink por Identificador de zona y devuelve todas las asociaciones emitidas entre zonas y Vlink.

• POST /api/v1/certificate-forms / GET /api/v1/certificate-forms — administrar formularios
• POST /api/v1/certificates/preflight — comprobar que un formulario se resuelve con una Ficha
• POST /api/v1/certificates/generate — emitir un Certificado
• GET /api/v1/certificates — enumerar los Certificados de una Ficha
• POST /api/v1/certificates/void — anular uno

Conceptos: Certificados.

Páginas públicas

Una Página pública es la vista web sin autenticación de una Ficha: el pasaporte digital del producto al que llega un consumidor al escanear un Identificador. Lo que muestra se determina por completo mediante un Diseño de página pública reutilizable y propiedad del Equipo, por lo que la publicación no recibe contenido específico de cada Ficha: al publicar, el diseño se resuelve con la Ficha. La URL de una página se reserva y se vincula antes de publicar nada, por lo que las etiquetas pueden imprimirse primero.

Al publicar un diseño, se fija una Versión del diseño inmutable; cada página queda asociada a una Versión del diseño y a una Instantánea de datos (los valores resueltos para esa Ficha). Una Publicación en bloque vuelve a publicar todas las páginas de un ámbito —Carpeta, Categoría, Plantilla o una selección explícita— mediante una Versión del diseño, como una ejecución en segundo plano con su propio seguimiento del progreso y de los errores.

Reservar la URL de una página y vincularla a una Ficha son operaciones del nivel de miembro: reservar una dirección no publica nada, por lo que las etiquetas pueden imprimirse antes de que alguien decida publicar. Todo lo que hace públicos los datos —publicar una página, activarla o archivarla, crear un diseño, publicar una Versión del diseño, desplegar y realizar Publicaciones en bloque— requiere el permiso publisher del Equipo (ser administrador del Equipo lo implica), al igual que las comprobaciones previas y de vista previa. El valor x-required-role de cada operación en la referencia de la API es la fuente autorizada.

• POST /api/v1/public-pages / POST /api/v1/public-pages/{publicPageId}/bind — reservar la URL permanente de una página y, después, vincularla a una Ficha
• GET / PUT /api/v1/public-pages/thread/{threadId} — leer u obtener o crear la página de una Ficha
• GET /api/v1/public-pages/thread/{threadId}/activity — vistas anónimas y escaneos de verificación en la página publicada
• POST /api/v1/public-pages/{publicPageId}/publish — publicar una instantánea mediante la versión más reciente del diseño
• PATCH /api/v1/public-pages/{publicPageId} — activar o archivar una página sin cambiar su URL
• GET /api/v1/public-pages/{publicPageId}/publications — historial de publicaciones
• POST /api/v1/public-pages/preflight / preflight/batch — comprobar que un diseño se resuelve con una o varias Fichas
• POST /api/v1/public-page-designs / GET / PATCH /api/v1/public-page-designs/{designId} — crear un borrador de diseño
• POST /api/v1/public-page-designs/{designId}/versions — publicar una Versión del diseño (GET las enumera)
• POST /api/v1/public-pages/designs/{designId}/roll-out — poner en línea la versión más reciente de un diseño en todas sus páginas
• POST /api/v1/public-pages/waves — iniciar una Publicación en bloque (GET obtiene el registro de su ejecución, sus elementos y la lista)
• POST /api/v1/public-pages/waves/{waveId}/retry-failed / cancel — reintentar las operaciones fallidas o detener el trabajo restante

El despliegue solo avanza: una Versión del diseño nunca se restaura y, al cancelar una publicación en bloque, las páginas ya publicadas permanecen en la versión que recibieron.

Conceptos: Páginas públicas.

Eventos

Cada cambio relevante —ediciones de campos, vinculaciones, recursos compartidos y envíos— se registra como un evento y forma el registro de auditoría que DICE muestra como Registro de transacciones.

• GET /api/v1/events — enumerar eventos, que pueden filtrarse por Ficha, Equipo, acción y hora, con agrupación opcional de la actividad (groupBy)
  • lineage=upstream (con threadId) devuelve además los eventos de todas las Fichas anteriores del linaje de Fabric de la Ficha —la historia completa de una Ficha recibida—, limitados a lo que divulgó cada fuente. Las filas anteriores incluyen un objeto lineage (Ficha de origen, Equipo de origen, conexión y salto) y pueden estar marcadas como redacted; un cambio posterior en la divulgación de una fuente aparece como una fila de solo lectura fabric.disclosure.revised. Si se omite, la respuesta contiene únicamente los eventos propios de la Ficha.
  • resourceId, tagId o fieldId (uno a la vez, con threadId) limitan el historial a un archivo, identificador o campo; un certificado se identifica por su archivo. Con lineage=upstream se sigue el linaje propio del recurso.
  • Una Ficha recibida en un envío o creada mediante una división abre su historial con transfer.received / slice.derived, atribuido a la persona que aceptó el envío o realizó la división; no tiene created.thread ni bind propios.
• GET /api/v1/summary — métricas principales de recuento
• GET /api/v1/notifications — notificaciones de quien realiza la llamada

Próximos pasos

Inicio rápido

Realiza tu primera llamada autenticada en el inicio rápido.

Cliente de TypeScript

Usa el cliente tipado @dustid/apid-client en lugar de HTTP sin procesar.

Convenciones

Cabeceras, paginación y errores en las convenciones de la API.

Referencia completa

Todas las rutas, los parámetros y los esquemas en la referencia de la API.

Comprobantes PDF

Descarga un PDF bajo demanda con GET /api/v1/receipts/{kind}/{id}, donde kind es file, thread o shipment, e id es el UUID correspondiente. Usa tu autenticación habitual y las cabeceras de contexto de la organización y el equipo activos. La respuesta es application/pdf, con un nombre de archivo adjunto y una política de caché private y no-store. Accept-Language selecciona el idioma del comprobante.

Los comprobantes de archivos incluyen metadatos, la suma de comprobación SHA-256 guardada cuando está disponible, información de la ficha asociada y entradas del registro de transacciones permitidas. Los comprobantes de fichas incluyen campos, identificadores, archivos y sumas de comprobación, relaciones, información del ensamblaje y del linaje, y registros permitidos. Los comprobantes de envíos comienzan con la información del envío, su estado actual y su manifiesto, y después incluyen detalles y registros de las fichas visibles. Los envíos pendientes utilizan instantáneas ofrecidas; los demás estados utilizan los registros a los que quien realiza la llamada puede acceder actualmente.

Para un archivo visible a través de una divulgación, proporciona linkId; para un archivo ofrecido en un envío pendiente, proporciona transferId. Estos parámetros de consulta UUID opcionales no se pueden combinar y solo se aplican a los comprobantes de archivos. Mantienen las mismas restricciones de acceso y divulgación que la vista previa correspondiente.

Los comprobantes incluyen una marca de tiempo de generación y un enlace QR de vuelta a DICE. Son instantáneas sin firmar de los registros visibles para quien realiza la llamada, no firmas digitales. La generación es de solo lectura: no se guarda ningún comprobante adjunto ni evento en el registro de transacciones. Las exportaciones que superen los 10.000 eventos visibles en un registro fallan en lugar de truncarse silenciosamente. Los enlaces de un comprobante siguen requiriendo acceso a DICE.