Desenvolver com agentes de IA

Se utilizar um agente de programação com IA (Claude Code, Cursor, Copilot ou semelhante) para desenvolver com a plataforma DUST, esta página é o respetivo ponto de entrada. Tudo o que se encontra aqui é um URL público estável que pode fornecer a um agente.

Começar aqui

Fornecer ao agente	Para
/skills/dice-api-integration/SKILL.md	Chamar a API DUST: autenticação, cabeçalhos de contexto, Registos, Identificadores, ficheiros, partilha, Envios
/skills/dust-go-connect-integration/SKILL.md	Adicionar a digitalização DUST a uma aplicação Web executada dentro da aplicação móvel DUST Go
/llms.txt	Um mapa de todas as páginas, para o agente poder escolher aquilo de que necessita
/llms-full.txt	Toda a documentação num único documento de texto simples
/openapi.json	O contrato exato de pedidos e respostas

Os quatro factos que os agentes interpretam incorretamente

Se não adicionar mais nada ao contexto do agente, adicione estes factos. Cada um corresponde a um pedido que a API rejeita, em vez de o tolerar silenciosamente, pelo que qualquer erro faz a integração falhar por completo.

1. O campo do âmbito de pesquisa de identificação é searchTeamIds, uma matriz JSON de UUIDs de Equipas. Não existe qualquer campo de pedido searchGroupIds. Os conteúdos de identificação rejeitam propriedades não declaradas, pelo que a grafia incorreta faz com que todo o pedido falhe com 400 INVALID_REQUEST. O único nome group legado que permanece é o cabeçalho Dust-Ctx-Grp-Id, um alias aceite para Dust-Ctx-Team-Id.
2. tags é obrigatório na verificação e é uma matriz de objetos: [{"tagId": "…", "tagType": "DUST"}], não uma matriz de cadeias de IDs. Em corpos multipart, é codificado como JSON.
3. Uma identificação sem êxito é uma resposta com um estado de erro. 404 IDENTIFIER_NOT_FOUND significa que nada correspondeu; 503 SCAN_SEARCH_INCOMPLETE significa que não foi possível concluir a pesquisa e que esta deve ser repetida; 400 SCAN_LOW_KEYPOINTS significa que é necessário voltar a digitalizar. O código gerado que trata todos os estados não 2xx como exceções comunica interrupções de serviço que nunca ocorreram. A tabela canónica encontra-se em Erros e resultados da digitalização.
4. As credenciais permanecem no servidor. Um token bearer DUST possui todo o acesso da Conta de serviço e nada restringe esse acesso numa sessão do navegador. A arquitetura suportada é navegador → backend do cliente → API DUST. Nunca gere um componente que receba um token DUST como prop.

Exemplos canónicos

Estas são as estruturas a copiar. Ambos os blocos são executados num servidor.

// Identify: which Thread does this capture belong to?
const form = new FormData();
form.set("tagType", "DUST");
form.set("data", captureBlob);                              // binary, not base64
form.set("searchTeamIds", JSON.stringify(allowedTeamIds));  // NOT searchGroupIds

const response = await fetch(`${apidUrl}/api/v1/tags/identify`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Dust-Ctx-Org-Id": organizationId,
    // "Dust-Ctx-Team-Id": teamId,  // optional; omit for the org's root Team
  },
  body: form,
});
const body = await response.json();

if (response.ok) {
  // body.type is "identified" | "matches" | "label"
} else if (body.code === "IDENTIFIER_NOT_FOUND") {
  // An answer: nothing matched. Not a failure.
} else if (body.code === "SCAN_SEARCH_INCOMPLETE") {
  // Retry — the item may well be enrolled.
}

// Verify: is this capture the item it claims to be?
const form = new FormData();
form.set("threadId", threadId);
form.set("tagType", "DUST");
form.set("data", captureBlob);
form.set("tags", JSON.stringify([{ tagId, tagType: "DUST" }])); // required, objects

const response = await fetch(`${apidUrl}/api/v1/tags/verify`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Dust-Ctx-Org-Id": organizationId },
  body: form,
});
const body = await response.json();

// One candidate: a mismatch is an error status.
// Two or more: a mismatch is HTTP 200 with { success: false } — read `success`.

Está disponível no guia de iniciação rápida da API uma sequência completa, executável e integral (troca de tokens, descoberta da organização, descoberta de Equipas, criação e nova leitura), sem dependências de pacotes.

llms.txt

De acordo com a convenção llms.txt, a raiz do site disponibiliza:

Ficheiro	Conteúdo
/llms.txt	Mapa do site: todas as páginas com uma descrição de uma linha, além de referências à especificação OpenAPI, à referência interativa e aos pacotes npm
/llms-full.txt	O conteúdo completo da documentação num único documento de texto simples
/llms-small.txt	Uma variante minimizada para janelas de contexto mais pequenas

Direcione o agente para /llms.txt para que este escolha as páginas ou forneça-lhe /llms-full.txt quando necessitar da visão completa. As ligações dentro dos ficheiros combinados são URLs absolutos que remetem para a página e secção de origem, permitindo que um agente cite a fonte utilizada.

A especificação OpenAPI

A interface oficial da API é o documento OpenAPI 3:

• Em direto a partir do servidor da API: https://apid.dustid.io/api/openapi.json
• Uma cópia criada durante a compilação neste site: /openapi.json
• Referência interativa (Scalar): https://apid.dustid.io/api/docs

A cópia neste site corresponde à interface pública: as operações internas da DUST são removidas. Utilize o documento em direto quando precisar de ter a certeza de que está a descrever o servidor que está efetivamente a chamar.

Skills de integração

Uma skill é um único ficheiro Markdown no formato SKILL.md (frontmatter YAML com name e description, seguido de instruções) que ensina a um agente uma integração integral — autenticação, cabeçalhos, fluxos principais e modos de falha. As skills são autónomas: um agente que disponha apenas do ficheiro da skill pode concluir a integração.

dice-api-integrationAutenticar (chave de API → bearer), definir cabeçalhos de contexto e executar os principais fluxos da API: criar Registos, vincular Identificadores, carregar ficheiros, partilhar e enviar.TransferirCopiar

dust-go-connect-integrationPermitir que uma aplicação Web digitalize Identificadores DUST dentro da aplicação móvel DUST Go através de @dustid/dust-go-connect.TransferirCopiar

Instalar uma skill

1. Transfira o ficheiro da skill a partir do URL estável acima (por exemplo, /skills/dice-api-integration/SKILL.md).

2. Para o Claude Code, coloque-o em .claude/skills/dice-api-integration/SKILL.md no seu projeto (o nome do diretório corresponde ao name da skill). O Claude deteta-o automaticamente e carrega-o quando a tarefa corresponde.

3. Para outros agentes, inclua o ficheiro no contexto ou no prompt de sistema do agente — o ficheiro é Markdown simples e autónomo.

O que «gerado» significa e não significa

Cada ficheiro de skill contém um bloco de proveniência que indica a versão da documentação, a versão da especificação OpenAPI, o número de caminhos nela existentes e um resumo criptográfico da especificação pública exata com base na qual o ficheiro foi criado. Estes quatro factos permitem determinar que versão histórica da API é descrita pela sua cópia e se duas cópias provêm da mesma especificação.

Importa compreender com precisão o que isto proporciona:

Parte de uma skill	Origem	O que pode ficar desatualizado
O índice de endpoints em dice-api-integration	Gerado a partir da especificação OpenAPI pública durante a compilação	Nada — contém os caminhos, métodos e resumos da própria especificação
Linhas de versão e resumo criptográfico	Geradas durante a compilação	Nada
Tudo o resto: instruções de autenticação, nomes de parâmetros, estruturas dos conteúdos, comportamento do SDK e tratamento de falhas	Escrito manualmente	Tudo o que a API altere sem uma edição correspondente da documentação

Uma marca de compilação não é o resultado de um teste

Uma faixa de versão recente demonstra que o ficheiro foi compilado, não que os respetivos exemplos foram executados numa API implementada. Trate o índice de endpoints gerado como um auxiliar de descoberta — prova de que existe um caminho — e trate cada exemplo como algo a verificar em relação à especificação OpenAPI ou num ambiente de teste descartável antes da disponibilização. Se um exemplo e a especificação estiverem em desacordo, prevalece a especificação; informe-nos também, para que o texto seja corrigido.

Verificar código gerado

Uma breve lista de revisão para uma pessoa que esteja a analisar o que um agente produziu:

• Todos os caminhos e métodos constam da especificação. Não existem endpoints inventados.
• As chamadas /api/v1/* incluem Authorization: Bearer; todas as que estejam no âmbito de uma organização incluem também Dust-Ctx-Org-Id.
• A identificação envia searchTeamIds, nunca searchGroupIds.
• A verificação envia tags como uma matriz de objetos { tagId, tagType }.
• O tratamento de erros ramifica-se com base em code, nunca no texto de message, e distingue «sem correspondência», «tentar novamente» e «voltar a digitalizar».
• Nenhuma chave de API nem token bearer aparece em qualquer elemento enviado para um navegador ou cliente móvel.
• Os recibos de digitalização (scan.scanId ou detail.scan.scanId em caso de falha) são registados.
• Um 401 desencadeia uma atualização e uma nova tentativa, não um ciclo.

Pacotes npm

• @dustid/dust-go-connect — a ponte de digitalização DUST Go para aplicações Web (consulte Integrar com o DUST Go).
• @dustid/apid-client — o cliente TypeScript tipado da API. Não está disponível no registo npm público; consulte Cliente TypeScript para conhecer a disponibilidade e os pré-requisitos. Um agente não deve emitir um comando de instalação para este pacote.