Convenções dos pedidos: cabeçalhos de contexto, erros, localização

Todos os endpoints /api/v1/* no âmbito de uma organização partilham o mesmo contrato de pedido: um bearer token, dois cabeçalhos de contexto que selecionam a organização e a equipa em nome das quais atua, corpos JSON (em alternativa, os carregamentos de ficheiros utilizam multipart ou tus), um único formato de erro e paginação por cursor nos endpoints de listagem. Esta página define o contrato; as páginas de cada domínio pressupõem-no.

Cabeçalhos de contexto

Quase tudo na API DUST pertence a uma organização e, dentro desta, a uma equipa. Dois cabeçalhos permitem escolher a organização/equipa em cujo contexto um pedido atua:

Cabeçalho	Obrigatório	Valor
Dust-Ctx-Org-Id	Sim, nos endpoints no âmbito de uma organização	UUID da organização.
Dust-Ctx-Team-Id	Não	UUID da equipa. Quando omitido, é utilizada por predefinição a equipa raiz da organização.

curl -fsS "https://apid.dustid.io/api/v1/threads" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Dust-Ctx-Team-Id: $DUST_TEAM_ID"

Grp é a designação antiga

Dust-Ctx-Grp-Id é o nome antigo de Dust-Ctx-Team-Id e continua a ser aceite em todos os locais onde o novo cabeçalho é aceite (quando ambos são enviados, prevalece Dust-Ctx-Team-Id). Alguns códigos de erro (GROUP_ID_REQUIRED) e nomes de campos também são anteriores à alteração de nome de group→team — no protocolo de comunicação, interprete sempre Grp/group como «equipa».

Aspetos importantes na prática:

• Os valores dos cabeçalhos têm de ser UUIDs; um valor malformado é rejeitado com 400 INVALID_REQUEST antes de o endpoint ser executado.
• As variantes com o prefixo X- (X-Dust-Ctx-Org-Id, X-Dust-Ctx-Team-Id e o par antigo) são aceites como aliases.
• Os endpoints que exigem contexto, mas não o recebem, falham com os códigos de erro ORG_ID_REQUIRED ou TEAM_ID_REQUIRED.
• Alguns endpoints estão no âmbito do utilizador e não necessitam de contexto — GET /api/v1/me é o exemplo mais comum.

O contexto é um limite de autorização

A autorização é avaliada para o seu utilizador a atuar na equipa indicada pelos cabeçalhos. A mesma chamada com um Dust-Ctx-Team-Id diferente pode devolver resultados diferentes: aquilo que pode listar, ler e escrever corresponde ao que essa equipa pode ver — os respetivos registos e tudo o que tenha sido partilhado com ela. Enviar um contexto ao qual não pertence não aumenta os seus privilégios; os pedidos são validados relativamente às suas associações efetivas. As operações de Ficheiro, Pasta, relação, ligação de Registo, Importação de conjunto, Formulário de certificado, Fabric, Dividir, listagem de Equipas ligadas, Página pública, Design de página pública, atividade e diretório de utilizadores exigem uma associação atual à Equipa selecionada e verificam se esta pertence à organização selecionada, tanto para pessoas como para Contas de serviço. O histórico de Registos exige ainda permissão para ver o Registo em causa; selecionar um ID de Registo não concede acesso. A criação de Registos (incluindo a criação em massa) e de modelos também exige uma associação atual à Equipa selecionada. As listas de associações dos administradores da organização permanecem limitadas à Organização selecionada. Consulte Equipas e partilha.

Localização

O cabeçalho opcional Dust-Ctx-Locale seleciona o idioma do texto destinado ao utilizador e gerado pelo servidor — sobretudo as cadeias message dos erros:

Dust-Ctx-Locale: zh-CN

Os idiomas suportados são de, es, fr, it, ja, pt, en (predefinição) e zh-CN. Quando o cabeçalho não está presente, o servidor recorre ao cabeçalho padrão Accept-Language e, em seguida, ao inglês. Os códigos de erro são identificadores estáveis e nunca são localizados — tome decisões com base em code e apresente message.

Erros

Os pedidos que falham devolvem um corpo JSON com um formato único e consistente:

{
  "code": "UNAUTHORIZED",
  "message": "You are not authorized to perform this action",
  "status": 401,
  "detail": { }
}

Campo	Tipo	Significado
code	string	Código de erro estável e legível por máquina. Tome decisões com base neste campo.
message	string	Descrição legível por pessoas, localizada de acordo com Dust-Ctx-Locale.
status	number	Reflete o código de estado HTTP.
detail	object (opcional)	Contexto adicional deste erro, por exemplo, detalhes específicos da validação.

Códigos que encontrará desde cedo:

Código	Estado habitual	Quando ocorre
INVALID_REQUEST	400	Corpo, consulta ou cabeçalho malformado (detalhes da validação em detail).
UNAUTHORIZED	401	Bearer token em falta, expirado ou inválido.
FORBIDDEN	403	O utilizador está autenticado, mas o contexto desta equipa não permite realizar a operação.
NOT_FOUND / NO_DATA_FOUND	404	Não existe qualquer registo deste tipo visível neste contexto.
ORG_ID_REQUIRED / TEAM_ID_REQUIRED	400	Cabeçalho de contexto em falta num endpoint com âmbito definido.
THREAD_DATA_CONFLICT	409	Conflito de concorrência otimista: a sua representação do registo estava desatualizada.

Todas as respostas incluem também um cabeçalho x-request-id. Registe-o e inclua-o ao contactar o suporte — permite localizar com precisão o seu pedido nos rastreios do servidor.

Erros e resultados de digitalização é a referência completa: todos os códigos que provavelmente encontrará e os respetivos estados, as tabelas canónicas de resultados de identificação e verificação, orientações sobre novas tentativas e como conservar um recibo de digitalização quando uma operação falha.

Um resultado negativo continua a ser uma resposta

Os endpoints de digitalização comunicam resultados através de códigos de erro. Uma identificação que não encontra nada devolve 404 IDENTIFIER_NOT_FOUND — essa é a resposta, não uma falha de transporte. Uma pesquisa incompleta devolve 503 SCAN_SEARCH_INCOMPLETE, o que constitui uma situação diferente. Tome decisões com base em code; consulte a tabela de resultados canónicos de identificação.

Paginação

Os endpoints de listagem (registos, pastas, ficheiros, eventos, modelos, …) utilizam paginação por cursor:

• Pedido: parâmetros de consulta pageSize (comprimento da página) e cursor (cadeia opaca de uma página anterior). pageSize tem de ser um número inteiro entre 1 e 1 000; alguns endpoints impõem um máximo inferior. Omita-o para utilizar o valor predefinido do endpoint.
• Os endpoints que utilizam pageIndex aceitam números inteiros entre 0 e 1 000 000. Os valores de paginação negativos ou fracionários são rejeitados.
• Resposta: a matriz de itens, juntamente com cadeias de cursor opcionais next e prev. A ausência de next significa que se encontra na última página.

# First page
curl -fsS "https://apid.dustid.io/api/v1/threads?pageSize=50" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID"

# Follow the cursor
curl -fsS "https://apid.dustid.io/api/v1/threads?pageSize=50&cursor=$NEXT" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID"

{
  "threads": [ ... ],
  "next": "eyJjcmVhdGVkQXQiOi...",
  "prev": "eyJjcmVhdGVkQXQiOi..."
}

Os cursores são opacos — guarde-os e reutilize-os; nunca os analise. Os endpoints de listagem que suportam ordenação aceitam order (asc/desc) e um orderCol específico do endpoint (para registos: createdAt, updatedAt, name).

Níveis de autorização

Todas as operações exigem um de três níveis de privilégio, e o prefixo do caminho permite saber qual deles é necessário antes de ler qualquer esquema:

Prefixo	Quem pode chamar o endpoint	Notas
/api/v1/org/*	Administradores da organização — utilizadores com a função admin (ou owner) na Organização indicada por Dust-Ctx-Org-Id	Criação de equipas, atualizações de equipas, associações
/api/v1/connections/*	Administradores da equipa — administradores da Equipa em nome da qual se atua, indicada por Dust-Ctx-Team-Id	Ciclo de vida e alterações das ligações
todos os restantes	Membros do contexto do pedido, salvo indicação em contrário na operação	Superfície funcional padrão

Cada operação também inclui uma extensão x-required-role na especificação OpenAPI (member, publisher, team-admin ou org-admin) — considere-a a política autoritativa de cada operação; uma operação sem esta anotação exige member. publisher é uma permissão concedida numa associação a uma Equipa, e não um nível independente: é necessária para tornar os dados de uma Equipa publicamente legíveis, e os administradores da Equipa possuem-na sempre. Chamar uma operação acima do seu nível devolve 403 FORBIDDEN, independentemente do conteúdo.

Corpos, IDs e carimbos de data/hora

• Os pedidos utilizam Content-Type: application/json, salvo quando um endpoint aceita explicitamente dados de formulário multipart (digitalizações de identificadores em /api/v1/tags/*, carregamentos de ficheiros).
• Os IDs são cadeias UUID RFC 4122 (threadId, eventId, IDs de organização e de equipa, …). Trate-os como opacos.
• Os carimbos de data/hora (createdAt, updatedAt, archivedAt, …) são cadeias de carimbo de data/hora em UTC.
• As escritas são registadas como eventos: alterar um registo acrescenta uma entrada ao respetivo histórico de eventos em vez de o substituir silenciosamente — as leituras como GET /api/v1/threads/{thread_id} devolvem { thread, events }.

Consulte também

• Início rápido da API — estas convenções num fluxo funcional completo.
• Erros e resultados de digitalização — todos os códigos, as tabelas de resultados de identificação/verificação e orientações sobre novas tentativas.
• Autenticação e chaves de API — a origem do bearer token.
• Modelo principal — o significado de registos, equipas e identificadores.
• Referência completa da API — parâmetros e esquemas de cada endpoint, gerados a partir da especificação em utilização.