Desarrollo con agentes de IA

Si utiliza un agente de programación con IA (Claude Code, Cursor, Copilot o similar) para desarrollar con la plataforma DUST, esta página es su punto de entrada. Todo lo que aparece aquí es una URL pública estable que puede proporcionar a un agente.

Empiece aquí

Proporcione a su agente	Para
/skills/dice-api-integration/SKILL.md	Llamar a la API de DUST: autenticación, encabezados de contexto, Fichas, Identificadores, archivos, uso compartido y Envíos
/skills/dust-go-connect-integration/SKILL.md	Añadir el escaneo de DUST a una aplicación web que se ejecuta dentro de la aplicación móvil DUST Go
/llms.txt	Un mapa de todas las páginas para que el agente pueda elegir lo que necesita
/llms-full.txt	Toda la documentación en un único documento de texto sin formato
/openapi.json	El contrato exacto de solicitudes y respuestas

Los cuatro datos en los que se equivocan los agentes

Si no proporciona ningún otro contenido al contexto de su agente, proporciónele estos datos. Cada uno corresponde a una solicitud que la API rechaza, en lugar de tolerarla silenciosamente, por lo que cualquier error hace que la integración falle por completo.

1. El campo del ámbito de búsqueda de identificación es searchTeamIds, un array JSON de UUID de Equipos. No existe ningún campo de solicitud searchGroupIds. Las cargas útiles de identificación rechazan las propiedades no declaradas, por lo que usar el nombre incorrecto hace que toda la solicitud falle con 400 INVALID_REQUEST. El único nombre heredado group que se conserva es el encabezado Dust-Ctx-Grp-Id, un alias aceptado de Dust-Ctx-Team-Id.
2. tags es obligatorio en la verificación y es un array de objetos: [{"tagId": "…", "tagType": "DUST"}], no un array de cadenas de identificadores. En cuerpos multipart se codifica como JSON.
3. Una identificación sin coincidencias es una respuesta con un estado de error. 404 IDENTIFIER_NOT_FOUND significa que no hubo ninguna coincidencia; 503 SCAN_SEARCH_INCOMPLETE significa que la búsqueda no pudo completarse y debe volver a intentarse; 400 SCAN_LOW_KEYPOINTS significa que debe repetirse el escaneo. El código generado que trata todas las respuestas que no sean 2xx como excepciones informa de interrupciones del servicio que nunca ocurrieron. La tabla canónica se encuentra en Errores y resultados de escaneo.
4. Las credenciales permanecen en el servidor. Un token bearer de DUST concede todo el acceso de la Cuenta de Servicio y nada restringe dicho acceso para una sesión del navegador. La arquitectura admitida es navegador → backend del cliente → API de DUST. Nunca genere un componente que reciba un token de DUST como prop.

Ejemplos canónicos

Estas son las estructuras que debe copiar. Ambos bloques se ejecutan en un 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`.

En la guía de inicio rápido de la API encontrará una secuencia completa y ejecutable de principio a fin (intercambio de tokens, detección de la organización, detección del Equipo, creación y lectura posterior) sin dependencias de paquetes.

llms.txt

De acuerdo con la convención llms.txt, la raíz del sitio proporciona:

Archivo	Contenido
/llms.txt	Mapa del sitio: todas las páginas con una descripción de una línea, además de referencias a la especificación OpenAPI, la documentación de referencia interactiva y los paquetes npm
/llms-full.txt	El contenido completo de la documentación en un único documento de texto sin formato
/llms-small.txt	Una variante minimizada para ventanas de contexto más pequeñas

Dirija su agente a /llms.txt para que pueda elegir las páginas o proporciónele /llms-full.txt cuando necesite una visión completa. Los enlaces dentro de los archivos combinados son URL absolutas que remiten a la página y la sección de las que proceden, por lo que un agente puede citar la fuente que utilizó.

La especificación OpenAPI

La descripción oficial de la API es el documento OpenAPI 3:

• Versión en línea del servidor de la API: https://apid.dustid.io/api/openapi.json
• Copia generada durante la compilación de este sitio: /openapi.json
• Documentación de referencia interactiva (Scalar): https://apid.dustid.io/api/docs

La copia de este sitio representa la superficie pública: se han eliminado de ella las operaciones internas de DUST. Utilice el documento en línea cuando necesite tener la certeza de que está describiendo el servidor al que realmente llama.

Skills de integración

Un skill es un único archivo Markdown con el formato SKILL.md (frontmatter YAML con name y description, seguido de instrucciones) que enseña a un agente a realizar una integración completa de principio a fin: autenticación, encabezados, flujos principales y modos de fallo. Los skills son autocontenidos: un agente que solo disponga del archivo del skill puede completar la integración.

dice-api-integrationAutenticar (clave de API → bearer), establecer los encabezados de contexto y ejecutar los flujos principales de la API: crear Fichas, vincular Identificadores, cargar archivos, compartir y enviar.DescargarCopiar

dust-go-connect-integrationPermitir que una aplicación web escanee Identificadores DUST dentro de la aplicación móvil DUST Go mediante @dustid/dust-go-connect.DescargarCopiar

Instalar un skill

1. Descargue el archivo del skill desde la URL estable indicada anteriormente (p. ej., /skills/dice-api-integration/SKILL.md).

2. Para Claude Code, colóquelo en .claude/skills/dice-api-integration/SKILL.md dentro de su proyecto (el nombre del directorio coincide con el valor name del skill). Claude lo detecta automáticamente y lo carga cuando la tarea coincide.

3. Para otros agentes, incluya el archivo en el contexto o el prompt del sistema del agente; el archivo está escrito en Markdown sin formato y es autocontenido.

Qué significa y qué no significa «generado»

Cada archivo de skill contiene un bloque de procedencia que indica la versión de la documentación, la versión de la especificación OpenAPI, el número de rutas que contiene y un resumen criptográfico de la especificación pública exacta a partir de la cual se generó el archivo. Estos cuatro datos permiten saber qué etapa de la API describe su copia y si dos copias proceden de la misma especificación.

Sea preciso sobre lo que esto aporta:

Parte de un skill	Origen	Qué puede quedar obsoleto
El índice de endpoints de dice-api-integration	Generado a partir de la especificación OpenAPI pública durante la compilación	Nada: contiene las propias rutas, métodos y descripciones de la especificación
Líneas de versión y resumen criptográfico	Generadas durante la compilación	Nada
Todo lo demás: instrucciones de autenticación, nombres de parámetros, estructuras de cargas útiles, comportamiento del SDK y gestión de fallos	Escrito manualmente	Cualquier aspecto que cambie la API sin que se realice la correspondiente modificación en la documentación

Un sello de compilación no es el resultado de una prueba

Un indicador de versión reciente demuestra que el archivo se compiló, no que los ejemplos que contiene se ejecutaron contra una API desplegada. Considere el índice de endpoints generado como una ayuda para la detección —una prueba de que existe una ruta— y considere que cada ejemplo debe verificarse con la especificación OpenAPI o en un entorno de prueba desechable antes de publicarlo. Si un ejemplo y la especificación discrepan, prevalece la especificación; comuníquenoslo también para que podamos corregir el texto.

Comprobar el código generado

Una breve lista de revisión para una persona que examine lo que ha producido un agente:

• Todas las rutas y métodos aparecen en la especificación. No hay endpoints inventados.
• Las llamadas a /api/v1/* incluyen Authorization: Bearer; todas las que están limitadas al ámbito de una organización también incluyen Dust-Ctx-Org-Id.
• La identificación envía searchTeamIds, nunca searchGroupIds.
• La verificación envía tags como un array de objetos { tagId, tagType }.
• La gestión de errores bifurca según code, nunca según el texto de message, y distingue entre «sin coincidencias», «volver a intentarlo» y «repetir el escaneo».
• Ninguna clave de API ni token bearer aparece en ningún elemento enviado a un navegador o cliente móvil.
• Se registran los recibos de escaneo (scan.scanId o detail.scan.scanId en caso de fallo).
• Un 401 provoca una sola actualización y un nuevo intento, no un bucle.

Paquetes npm

• @dustid/dust-go-connect — el puente de escaneo de DUST Go para aplicaciones web (consulte Integración con DUST Go).
• @dustid/apid-client — el cliente de API tipado para TypeScript. No está disponible en el registro público de npm; consulte Cliente TypeScript para conocer su disponibilidad y los requisitos previos. Un agente no debe generar un comando para instalarlo.