Convenciones de las solicitudes: encabezados de contexto, errores y localización

Todos los endpoints /api/v1/* con ámbito de organización comparten el mismo contrato de solicitud: un token bearer, dos encabezados de contexto que seleccionan la organización y el equipo en los que actúas, cuerpos JSON (las cargas de archivos usan multipart o tus), un único formato de error y paginación mediante cursor en los endpoints de listas. Esta página define el contrato; las páginas de cada dominio lo presuponen.

Encabezados de contexto

Casi todo en la API de DUST pertenece a una organización y, dentro de ella, a un equipo. Seleccionas la organización y el equipo en los que actúa una solicitud mediante dos encabezados:

Encabezado	Obligatorio	Valor
Dust-Ctx-Org-Id	Sí, en endpoints con ámbito de organización	UUID de la organización.
Dust-Ctx-Team-Id	No	UUID del equipo. Si se omite, se usa de forma predeterminada el equipo raíz de la organización.

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 es la denominación heredada

Dust-Ctx-Grp-Id es el nombre heredado de Dust-Ctx-Team-Id y todavía se acepta en todos los lugares donde se acepta el nuevo encabezado (si se envían ambos, prevalece Dust-Ctx-Team-Id). Algunos códigos de error (GROUP_ID_REQUIRED) y nombres de campos también son anteriores al cambio de nombre de grupo a equipo; interpreta siempre Grp/group en el protocolo de comunicación como «equipo».

Detalles importantes en la práctica:

• Los valores de los encabezados deben ser UUID; los valores con formato incorrecto se rechazan con 400 INVALID_REQUEST antes de que se ejecute el endpoint.
• Las variantes con el prefijo X- (X-Dust-Ctx-Org-Id, X-Dust-Ctx-Team-Id y el par heredado) se aceptan como alias.
• Los endpoints que requieren contexto y no lo reciben devuelven los códigos de error ORG_ID_REQUIRED o TEAM_ID_REQUIRED.
• Algunos endpoints tienen ámbito de usuario y no necesitan contexto; GET /api/v1/me es el ejemplo más habitual.

El contexto es un límite de autorización

La autorización se evalúa para tu usuario actuando en el equipo indicado por los encabezados. La misma llamada con un Dust-Ctx-Team-Id distinto puede devolver resultados diferentes: puedes listar, leer y escribir aquello que ese equipo puede ver, es decir, sus propios registros y todo lo que se haya compartido con él. Enviar el contexto de un equipo al que no perteneces no amplía tus privilegios; las solicitudes se comprueban con respecto a tus pertenencias reales. Las operaciones de archivos, carpetas, relaciones, enlaces de Fichas, importaciones de ensamblajes, formularios de certificados, Fabric, divisiones, listados de equipos conectados, páginas públicas, diseños de páginas públicas, actividad y directorios de usuarios requieren pertenencia vigente al Equipo seleccionado y verifican que este pertenezca a la organización seleccionada, tanto para personas como para cuentas de servicio. El historial de una Ficha también exige permiso para verla; seleccionar el ID de una Ficha no concede acceso. La creación de Fichas (incluida la creación en bloque) y plantillas también requiere pertenencia vigente al Equipo seleccionado. Las listas de pertenencias para administradores de la organización permanecen dentro de la Organización seleccionada. Consulta Equipos y uso compartido.

Localización

El encabezado opcional Dust-Ctx-Locale selecciona el idioma del texto orientado al usuario que genera el servidor, sobre todo las cadenas message de los errores:

Dust-Ctx-Locale: zh-CN

Las configuraciones regionales admitidas son de, es, fr, it, ja, pt, en (predeterminada) y zh-CN. Cuando el encabezado no está presente, el servidor recurre al encabezado estándar Accept-Language y, después, al inglés. Los códigos de error son identificadores estables y nunca se localizan: controla el flujo según code y muestra message.

Errores

Las solicitudes fallidas devuelven un cuerpo JSON con un formato único y coherente:

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

Campo	Tipo	Significado
code	string	Código de error estable y legible por máquinas. Controla el flujo según este campo.
message	string	Descripción legible por personas, localizada según Dust-Ctx-Locale.
status	number	Refleja el código de estado HTTP.
detail	object (opcional)	Contexto adicional sobre este error, como detalles específicos de validación.

Códigos que encontrarás desde el principio:

Código	Estado habitual	Cuándo
INVALID_REQUEST	400	Cuerpo, consulta o encabezado con formato incorrecto (los detalles de validación se incluyen en detail).
UNAUTHORIZED	401	Falta el token bearer, ha caducado o no es válido.
FORBIDDEN	403	La autenticación es válida, pero el contexto de este equipo no puede realizar la acción.
NOT_FOUND / NO_DATA_FOUND	404	No hay ningún registro de ese tipo visible en este contexto.
ORG_ID_REQUIRED / TEAM_ID_REQUIRED	400	Falta el encabezado de contexto en un endpoint con ámbito definido.
THREAD_DATA_CONFLICT	409	Conflicto de concurrencia optimista: tu vista de la ficha estaba desactualizada.

Todas las respuestas también incluyen un encabezado x-request-id. Regístralo e inclúyelo cuando contactes con el servicio de asistencia: permite localizar con precisión tu solicitud en las trazas del servidor.

Errores y resultados de escaneo es la referencia completa: incluye todos los códigos que probablemente encontrarás con sus estados, las tablas canónicas de resultados de identificación y verificación, recomendaciones para reintentos y cómo conservar un comprobante de escaneo cuando falla una operación.

Un resultado negativo sigue siendo una respuesta

Los endpoints de escaneo comunican los resultados mediante códigos de error. Una identificación que no encuentra nada devuelve 404 IDENTIFIER_NOT_FOUND: esa es la respuesta, no un fallo de transporte. Una búsqueda incompleta devuelve 503 SCAN_SEARCH_INCOMPLETE, que es otra situación distinta. Controla el flujo según code; consulta la tabla de resultados de identificación.

Paginación

Los endpoints de listas (fichas, carpetas, archivos, eventos, plantillas, etc.) usan paginación mediante cursor:

• Solicitud: parámetros de consulta pageSize (longitud de la página) y cursor (cadena opaca procedente de una página anterior). pageSize debe ser un entero de 1 a 1.000; algunos endpoints imponen un máximo menor. Omítelo para usar el valor predeterminado del endpoint.
• Los endpoints que usan pageIndex aceptan enteros de 0 a 1.000.000. Los valores de paginación negativos o fraccionarios se rechazan.
• Respuesta: el array de elementos, además de las cadenas de cursor opcionales next y prev. Si falta next, significa que estás en la ú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..."
}

Los cursores son opacos: consérvalos y reutilízalos, pero nunca los analices. Los endpoints de listas que admiten ordenación aceptan order (asc/desc) y un orderCol específico del endpoint (para las fichas: createdAt, updatedAt, name).

Niveles de autorización

Cada operación requiere uno de tres niveles de privilegios, y el prefijo de la ruta permite saber cuál antes de leer siquiera un esquema:

Prefijo	Quién puede llamarlo	Notas
/api/v1/org/*	Administradores de la organización: usuarios con el rol admin (o owner) en la Organización indicada por Dust-Ctx-Org-Id	Creación de equipos, actualizaciones de equipos, pertenencias
/api/v1/connections/*	Administradores del equipo: administradores del Equipo que actúa, indicado por Dust-Ctx-Team-Id	Ciclo de vida y modificaciones de las conexiones
cualquier otro	Miembros del contexto de la solicitud, salvo que la operación indique lo contrario	Superficie de funciones estándar

Cada operación también incluye una extensión x-required-role en la especificación OpenAPI (member, publisher, team-admin u org-admin); considérala la política autorizada para cada operación. Una operación sin esta anotación requiere member. publisher es una concesión asociada a la pertenencia a un Equipo, no un nivel independiente: se requiere para hacer que los datos de un Equipo sean legibles públicamente, y los administradores del Equipo siempre la tienen. Llamar a una operación que esté por encima de tu nivel devuelve 403 FORBIDDEN, independientemente de la carga útil.

Cuerpos, ID y marcas de tiempo

• Las solicitudes usan Content-Type: application/json, salvo que un endpoint acepte explícitamente datos de formulario multipart (escaneos de identificadores en /api/v1/tags/* y cargas de archivos).
• Los ID son cadenas UUID conformes con RFC 4122 (threadId, eventId, ID de organizaciones y equipos, etc.). Trátalos como valores opacos.
• Las marcas de tiempo (createdAt, updatedAt, archivedAt, etc.) son cadenas de marca de tiempo UTC.
• Las escrituras se registran como eventos: modificar una ficha añade un evento a su historial en lugar de sobrescribirla silenciosamente; las lecturas como GET /api/v1/threads/{thread_id} devuelven { thread, events }.

Consulta también

• Inicio rápido de la API — estas convenciones en un flujo funcional.
• Errores y resultados de escaneo — todos los códigos, las tablas de resultados de identificación y verificación y las recomendaciones para reintentos.
• Autenticación y claves de API — de dónde procede el token bearer.
• Modelo central — qué significan las fichas, los equipos y los identificadores.
• Referencia completa de la API — parámetros y esquemas de cada endpoint, generados a partir de la especificación en uso.