Guía de la API de equipos, uso compartido y conexiones

Todo el contenido de la plataforma DUST pertenece a Equipos y se accede a él mediante ellos. Esta guía abarca las cuatro capas que controlan quién puede ver cada cosa:

1. Contexto — en nombre de qué Organización y Equipo actúa una solicitud.
2. Uso compartido — concesión a otro Equipo de acceso como lector o editor a Fichas y Carpetas.
3. Conexiones — el acuerdo vigente entre dos Equipos (normalmente de distintas Organizaciones) que permite el uso compartido y los Envíos.
4. Envíos y divisiones — transferencia o derivación de registros a través de esos límites.

Esquemas completos: Referencia de la API.

Contexto de las solicitudes

La identidad reside en AuthD; la API de la plataforma delimita cada llamada mediante encabezados:

Authorization: Bearer <authd-token>
Dust-Ctx-Org-Id: <organization-uuid>
Dust-Ctx-Team-Id: <team-uuid>

Dust-Ctx-Org-Id es obligatorio para las llamadas circunscritas a una organización. Dust-Ctx-Team-Id selecciona el Equipo que actúa y, de forma predeterminada, corresponde al Equipo raíz de la Organización (Dust-Ctx-Grp-Id es la grafía heredada aceptada). Consulta Autenticación y Convenciones.

• GET /api/v1/me — usuario actual, sesión, Organización activa y Organizaciones disponibles
• GET /api/v1/me/feature-flags — indicadores de funciones para quien realiza la llamada

Equipos

Los Equipos dividen una Organización; las Fichas, las Carpetas y los recursos compartidos pertenecen todos a un Equipo. Al actualizar los metadatos de un Equipo se conservan su Organización y su ID de Equipo; las propiedades de actualización no declaradas se rechazan.

Operación	Método y ruta
Enumerar los Equipos que puedes ver	GET /api/v1/teams
Enumerar los Equipos de socios conectados	GET /api/v1/teams/connected
Crear Equipos (administrador de la organización)	POST /api/v1/org/teams
Enumerar todos los Equipos de la Organización (administrador de la organización)	GET /api/v1/org/teams
Actualizar o eliminar un Equipo (administrador de la organización)	PATCH / DELETE /api/v1/org/teams/{team_id}
Añadir o actualizar pertenencias (administrador de la organización)	POST /api/v1/org/teams/members
Enumerar o eliminar pertenencias (administrador de la organización)	GET / DELETE /api/v1/org/teams/members

GET /api/v1/teams admite q, role, rootId e includeLinked (para incluir los Equipos de socios conectados en los selectores). GET /api/v1/teams/connected enumera los Equipos de socios accesibles mediante Conexiones activas: el público válido para el uso compartido y los Envíos.

Uso compartido

Una concesión de acceso compartido permite a un Equipo acceder a un objeto —una Ficha o una carpeta (Carpeta/Categoría)— como viewer o editor. Las concesiones se almacenan como tuplas de relaciones, y el acceso también puede concederse indirectamente (una Carpeta compartida da acceso a su contenido), por lo que existen dos modelos de lectura: la lista de concesiones sin procesar y el resumen de acceso efectivo.

curl

curl -fsS "$APID_URL/api/v1/sharing" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Dust-Ctx-Team-Id: $DUST_TEAM_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "item": "thread", "id": "'"$THREAD_ID"'", "teamId": "'"$PARTNER_TEAM_ID"'", "relation": "viewer" }
    ]
  }'

TypeScript

await client.sharing.add({
  items: [
    { item: "thread", id: threadId, teamId: partnerTeamId, relation: "viewer" },
  ],
});

Operación	Método y ruta
Crear recursos compartidos	POST /api/v1/sharing
Enumerar recursos compartidos	GET /api/v1/sharing?direction=in|out
Actualizar la relación de un recurso compartido	PATCH /api/v1/sharing/{tuple_id}
Eliminar recursos compartidos	DELETE /api/v1/sharing (cuerpo: { "ids": […] })
Acceso efectivo a un objeto	GET /api/v1/sharing/access-summary?objectId=…&objectType=thread|bundle
Todo lo compartido con un socio	GET /api/v1/sharing/partner-inventory?teamId=…

direction=out enumera lo que ha compartido tu Equipo; direction=in, lo que se ha compartido con él. El resumen de acceso resuelve las concesiones directas, la herencia de las Carpetas y las relaciones entre Equipos para determinar los permisos efectivos sobre un objeto; el inventario del socio ofrece una vista por Conexión, útil antes de pausar o modificar una Conexión.

Funciones prácticas del lado de la Ficha: GET /api/v1/threads/{thread_id}/shared (con quién se comparte esta Ficha) y POST /api/v1/threads/permissions (qué puede hacer quien realiza la llamada); consulta la guía de Fichas.

Conexiones

Una Conexión (nombre en la API: team link) conecta dos Equipos y controla toda la actividad entre ellos. Incluye una dirección permitida para el flujo de datos —send, receive o send_receive, expresada desde la perspectiva del Equipo solicitante— y se establece mediante un acuerdo de tres pasos: el solicitante crea el enlace, el socio lo acepta y el solicitante lo confirma. Los enlaces se identifican mediante el code de su invitación.

Operación	Método y ruta
Crear (invitar)	POST /api/v1/connections — cuerpo { "allow": "send" | "receive" | "send_receive", "email"? }
Enumerar Conexiones	GET /api/v1/connections
Obtener o eliminar una	GET / DELETE /api/v1/connections/{code}
Aceptar (socio)	PATCH /api/v1/connections/accept
Rechazar (socio)	PATCH /api/v1/connections/reject
Confirmar (solicitante)	PATCH /api/v1/connections/confirm
Cancelar	PATCH /api/v1/connections/cancel
Pausar o reanudar	PATCH /api/v1/connections/pause / resume

Pausar una Conexión suspende la actividad de uso compartido y de Envíos que depende de ella sin eliminar la relación.

Modificaciones de dirección

Cambiar la dirección de una Conexión activa requiere a su vez un acuerdo, por lo que ninguna de las partes puede ampliar unilateralmente el flujo de datos: cualquiera de los Equipos presenta la propuesta, el otro Equipo la acepta y quien la propuso la confirma; la dirección anterior permanece vigente hasta la confirmación:

• POST /api/v1/connections/amend/propose — cuerpo { "code", "allow" }
• PATCH /api/v1/connections/amend/accept / confirm / cancel

Los recursos compartidos cuyo flujo deje de estar permitido por la nueva dirección pasan a estar inactivos en lugar de eliminarse.

Envíos

Un Envío (espacio de nombres de la API: /api/v1/transfers, denominación heredada) transfiere la propiedad de las Fichas a un Equipo conectado: se prepara un borrador de manifiesto, se envía y el destinatario responde. Estos son los endpoints, en el orden de su ciclo de vida:

Etapa	Método y ruta
Crear borrador	POST /api/v1/transfers
Añadir, actualizar o eliminar artículos del manifiesto	POST /api/v1/transfers/{transfer_id}/items, PATCH / DELETE …/items/{item_id}
Establecer la Ficha principal	PUT /api/v1/transfers/{transfer_id}/primary-thread
Enviar	POST /api/v1/transfers/{transfer_id}/send
Previsualizar (destinatario, después del envío)	GET /api/v1/transfers/{transfer_id}/preview
Responder: aceptar, rechazar o solicitar cambios	POST /api/v1/transfers/{transfer_id}/respond
Conversar	POST /api/v1/transfers/{transfer_id}/messages
Cancelar (en borrador, enviado o con cambios solicitados)	POST /api/v1/transfers/{transfer_id}/cancel
Reintentar un Envío fallido	POST /api/v1/transfers/{transfer_id}/retry
Abandonar un Envío fallido	POST /api/v1/transfers/{transfer_id}/abandon
Reiniciar a partir del manifiesto de un Envío detenido	POST /api/v1/transfers/{transfer_id}/start-from-prior-manifest
Enumerar (vistas de buzón)	GET /api/v1/transfers?box=inbox|outbox|sent
Obtener uno con su manifiesto	GET /api/v1/transfers/{transfer_id}

Para responder se usa { "value": "accept" | "reject" | "request_changes" } (se requiere un reason para las solicitudes de cambios). La enumeración admite los filtros box, view, status y direction=inbound|outbound.

Nota

Esta tabla es deliberadamente solo un mapa. El contenido de un manifiesto, el funcionamiento de la divulgación y el significado de cada estado se explican en Envíos; el modelo de procedencia que sustenta la visibilidad de los datos entre Equipos se explica en Fabric.

Divisiones

Una división deriva una Ficha nueva de otra existente dentro de tu propio Equipo —un subconjunto seleccionado de campos, archivos e identificadores—, normalmente para preparar exactamente lo que deseas compartir o enviar y mantener en privado el resto:

• POST /api/v1/slices — dividir una Ficha (elige la Carpeta de destino mediante bundleId, selecciona fields, …)
• POST /api/v1/slices/batch — derivar muchas Fichas en una sola operación
• GET /api/v1/slices/{slice_id} — una división con sus enlaces de Fabric

Páginas relacionadas

• Modelo principal — cómo encajan en el dominio los Equipos, los recursos compartidos y las Conexiones
• Envíos — semántica del ciclo de vida de los Envíos
• Fabric — procedencia y divulgación entre organizaciones
• Referencia de la API — esquemas completos de todos los endpoints anteriores