Guia da API de Equipas, partilha e ligações

Tudo na plataforma DUST pertence a Equipas e é acedido através delas. Este guia aborda as quatro camadas que controlam quem vê o quê:

1. Contexto — a Organização e a Equipa em nome das quais um pedido atua.
2. Partilha — conceder a outra Equipa acesso como visualizador ou editor a Registos e Pastas.
3. Ligações — o acordo permanente entre duas Equipas (normalmente de Organizações diferentes) que permite a partilha e os Envios.
4. Envios e divisões — transferir ou derivar registos através desses limites.

Esquemas completos: Referência da API.

Contexto do pedido

A identidade reside no AuthD; a API da plataforma define o âmbito de cada chamada através de cabeçalhos:

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

Dust-Ctx-Org-Id é obrigatório para chamadas ao nível da organização. Dust-Ctx-Team-Id seleciona a Equipa interveniente e, por predefinição, utiliza a Equipa raiz da Organização (Dust-Ctx-Grp-Id é a grafia antiga aceite). Consulte Autenticação e Convenções.

• GET /api/v1/me — utilizador atual, sessão, Organização ativa e Organizações disponíveis
• GET /api/v1/me/feature-flags — sinalizadores de funcionalidades para o autor da chamada

Equipas

As Equipas particionam uma Organização; os Registos, as Pastas e as partilhas pertencem todos a uma Equipa. A atualização dos metadados de uma Equipa preserva a respetiva Organização e o ID da Equipa; as propriedades de atualização não declaradas são rejeitadas.

Operação	Método e caminho
Listar as Equipas que pode ver	GET /api/v1/teams
Listar Equipas parceiras ligadas	GET /api/v1/teams/connected
Criar Equipas (administrador da organização)	POST /api/v1/org/teams
Listar todas as Equipas da Organização (administrador da organização)	GET /api/v1/org/teams
Atualizar/eliminar uma Equipa (administrador da organização)	PATCH / DELETE /api/v1/org/teams/{team_id}
Adicionar ou atualizar associações de membros (administrador da organização)	POST /api/v1/org/teams/members
Listar/remover associações de membros (administrador da organização)	GET / DELETE /api/v1/org/teams/members

GET /api/v1/teams suporta q, role, rootId e includeLinked (para incluir Equipas parceiras ligadas em seletores). GET /api/v1/teams/connected lista as Equipas parceiras acessíveis através de Ligações ativas — o público válido para partilhas e Envios.

Partilha

Uma partilha concede a uma Equipa acesso a um objeto — um Registo ou um conjunto (Pasta/Categoria) — como viewer ou editor. As concessões são armazenadas como tuplos de relações e o acesso também pode ser obtido indiretamente (uma Pasta partilhada transmite acesso ao respetivo conteúdo), pelo que existem dois modelos de leitura: a lista de concessões em bruto e o resumo do acesso efetivo.

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" },
  ],
});

Operação	Método e caminho
Criar partilhas	POST /api/v1/sharing
Listar partilhas	GET /api/v1/sharing?direction=in|out
Atualizar a relação de uma partilha	PATCH /api/v1/sharing/{tuple_id}
Remover partilhas	DELETE /api/v1/sharing (corpo: { "ids": […] })
Acesso efetivo a um objeto	GET /api/v1/sharing/access-summary?objectId=…&objectType=thread|bundle
Tudo o que foi partilhado com um parceiro	GET /api/v1/sharing/partner-inventory?teamId=…

direction=out lista o que a sua Equipa partilhou; direction=in, o que foi partilhado com ela. O resumo de acesso combina concessões diretas, herança de Pastas e relações entre Equipas para determinar as permissões efetivas de um objeto; o inventário do parceiro apresenta a vista por Ligação — útil antes de colocar uma Ligação em pausa ou de a alterar.

Funcionalidades práticas do lado dos Registos: GET /api/v1/threads/{thread_id}/shared (com quem este Registo é partilhado) e POST /api/v1/threads/permissions (o que o autor da chamada pode fazer) — consulte o guia de Registos.

Ligações

Uma Ligação (nome na API: team link) liga duas Equipas e controla toda a atividade entre Equipas. Inclui uma direção permitida para o fluxo de dados — send, receive ou send_receive, expressa do ponto de vista da Equipa requerente — e é estabelecida através de uma confirmação em três passos: o requerente cria a ligação, o parceiro aceita-a e o requerente confirma-a. As ligações são identificadas pelo respetivo code de convite.

Operação	Método e caminho
Criar (convidar)	POST /api/v1/connections — corpo { "allow": "send" | "receive" | "send_receive", "email"? }
Listar Ligações	GET /api/v1/connections
Obter/eliminar uma	GET / DELETE /api/v1/connections/{code}
Aceitar (parceiro)	PATCH /api/v1/connections/accept
Rejeitar (parceiro)	PATCH /api/v1/connections/reject
Confirmar (requerente)	PATCH /api/v1/connections/confirm
Cancelar	PATCH /api/v1/connections/cancel
Colocar em pausa/retomar	PATCH /api/v1/connections/pause / resume

Colocar uma Ligação em pausa suspende a atividade de partilha e de Envios que dela depende, sem eliminar a relação.

Alterações de direção

A alteração da direção de uma Ligação ativa exige também um processo de confirmação, para que nenhuma das partes possa alargar unilateralmente o fluxo de dados — qualquer uma das Equipas apresenta uma proposta, a outra Equipa aceita-a e a proponente confirma-a; a direção anterior permanece em vigor até à confirmação:

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

As partilhas cujo fluxo deixe de ser permitido pela nova direção ficam inativas, em vez de serem eliminadas.

Envios

Um Envio (espaço de nomes da API: /api/v1/transfers, nomenclatura antiga) transfere a propriedade de Registos para uma Equipa ligada: preparar um manifesto em rascunho, enviá-lo e aguardar a resposta do destinatário. Os endpoints, pela ordem do ciclo de vida:

Fase	Método e caminho
Criar rascunho	POST /api/v1/transfers
Adicionar/atualizar/remover itens do manifesto	POST /api/v1/transfers/{transfer_id}/items, PATCH / DELETE …/items/{item_id}
Definir o Registo principal	PUT /api/v1/transfers/{transfer_id}/primary-thread
Enviar	POST /api/v1/transfers/{transfer_id}/send
Pré-visualizar (destinatário, após o envio)	GET /api/v1/transfers/{transfer_id}/preview
Responder: aceitar/rejeitar/pedir alterações	POST /api/v1/transfers/{transfer_id}/respond
Trocar mensagens	POST /api/v1/transfers/{transfer_id}/messages
Cancelar (rascunho, enviado ou com alterações solicitadas)	POST /api/v1/transfers/{transfer_id}/cancel
Repetir um Envio falhado	POST /api/v1/transfers/{transfer_id}/retry
Abandonar um Envio falhado	POST /api/v1/transfers/{transfer_id}/abandon
Reiniciar a partir do manifesto de um Envio interrompido	POST /api/v1/transfers/{transfer_id}/start-from-prior-manifest
Listar (vistas de caixa de correio)	GET /api/v1/transfers?box=inbox|outbox|sent
Obter um Envio com o respetivo manifesto	GET /api/v1/transfers/{transfer_id}

A resposta recebe { "value": "accept" | "reject" | "request_changes" } (é necessário indicar um reason para pedidos de alteração). A listagem suporta os filtros box, view, status e direction=inbound|outbound.

Nota

Esta tabela é deliberadamente apenas um mapa. O conteúdo de um manifesto, o funcionamento da divulgação e o significado de cada estado são abordados em Envios; o modelo de proveniência subjacente à visibilidade dos dados entre Equipas é o Fabric.

Divisões

Uma divisão deriva um novo Registo a partir de outro existente na sua própria Equipa — um subconjunto selecionado de campos, ficheiros e identificadores — normalmente para preparar exatamente aquilo que pretende partilhar ou enviar, mantendo o restante privado:

• POST /api/v1/slices — dividir um Registo (escolher a Pasta de destino através de bundleId, selecionar fields, …)
• POST /api/v1/slices/batch — derivar vários Registos numa única operação
• GET /api/v1/slices/{slice_id} — uma divisão com as respetivas ligações do Fabric

Páginas relacionadas

• Modelo principal — como as Equipas, partilhas e Ligações se integram no domínio
• Envios — semântica do ciclo de vida dos Envios
• Fabric — proveniência e divulgação entre organizações
• Referência da API — esquemas completos para todos os endpoints acima