Registrar la procedencia desde su ERP

Los sistemas empresariales ven eventos de los que DICE nunca es testigo: una recepción de mercancías en SAP, la aprobación de una inspección en su MES, una venta cerrada en su plataforma de comercio. Las Transacciones declaradas permiten que su integración registre esos momentos en el historial de una Ficha a medida que ocurren; cada uno es una entrada permanente y atribuida que acompaña a la procedencia del artículo y puede aparecer en su Página pública.

Esta guía conecta un ERP (el mismo esquema sirve para un WMS, un MES o cualquier sistema de registro) con POST /api/v1/events/declare, mediante la autenticación como una Cuenta de servicio y la atribución de cada entrada al operador humano que actuó en su sistema.

Nota

Una entrada declarada es la afirmación atribuida de su organización, nunca un hecho verificado por la plataforma. DICE registra quién la afirmó y cuándo, la muestra marcada como declarada y nunca la presenta como algo observado por la plataforma. También es permanente: se comparte con los propietarios posteriores junto con el resto del historial de la Ficha y no se puede eliminar, solo retractar; además, una retractación es una segunda entrada visible, no un borrado.

Resumen del flujo

1. Su integración intercambia las credenciales de su Cuenta de servicio por un token de portador de corta duración (Autenticación).
2. Algo sucede en su sistema: una salida de mercancías, una inspección, el cierre de una reparación.
3. Su integración llama a POST /api/v1/events/declare con el id de la Ficha, un título y la fecha, hora y ubicación de la afirmación, y envía la identidad del operador en la cabecera Dust-Ctx-Declared-Actor.
4. La entrada aparece en el Registro de transacciones de la Ficha en DICE, marcada como Declarada y atribuida a la Cuenta de servicio que actuó en nombre de su operador.

Requisitos previos

• Una Cuenta de servicio con una clave de API o un cliente OAuth; consulte Autenticación. La Cuenta de servicio necesita acceso de edición a las Fichas en las que escribirá (concédale acceso al Equipo propietario).
• El id de su organización para la cabecera Dust-Ctx-Org-Id y el id del Equipo si la Cuenta de servicio debe actuar como un Equipo específico; consulte Convenciones de las solicitudes.
• Los ids de las Fichas de los artículos implicados. Normalmente, una integración los resuelve mediante una búsqueda por el campo que comparte con su sistema —un número de serie, lote o pedido— a través de GET /api/v1/threads (consulte la guía de la API de Fichas).

Declarar una transacción

Una llamada registra una entrada en una Ficha:

curl

curl -fsS "https://apid.dustid.io/api/v1/events/declare" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H 'Dust-Ctx-Declared-Actor: {"id": "JDOE", "system": "SAP", "displayName": "Jane Doe"}' \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "0b9e7c9a-2f9d-4d8a-9a51-1c2e57ab8d10",
    "title": "Incoming inspection passed",
    "note": "Visual and dimensional inspection against PO 4500012345.",
    "kind": "inspection",
    "edtf": "2026-08-06",
    "location": { "name": "Plant 1710, Springfield" }
  }'

TypeScript

const response = await fetch("https://apid.dustid.io/api/v1/events/declare", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Dust-Ctx-Org-Id": orgId,
    "Dust-Ctx-Declared-Actor": JSON.stringify({
      id: "JDOE",
      system: "SAP",
      displayName: "Jane Doe",
    }),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    threadId: "0b9e7c9a-2f9d-4d8a-9a51-1c2e57ab8d10",
    title: "Incoming inspection passed",
    note: "Visual and dimensional inspection against PO 4500012345.",
    kind: "inspection",
    edtf: "2026-08-06",
    location: { name: "Plant 1710, Springfield" },
  }),
});
if (!response.ok) throw new Error(`declare failed: ${response.status}`);
const claim = await response.json();

Campos de la solicitud: todos son opcionales excepto threadId, pero se rechaza una declaración completamente vacía:

Campo	Tipo	Notas
threadId	UUID	La Ficha a la que pertenece la entrada. Requiere acceso de edición.
title	string ≤ 80	Título breve: lo que los canales y las páginas muestran como título de la entrada.
note	string ≤ 4000	Detalle en texto libre de lo ocurrido.
kind	string ≤ 64	Clasificación abierta: sale, inspection, repair, service, … según su vocabulario. El valor predeterminado es other.
edtf	string ≤ 64	Cuándo ocurrió, con la precisión que realmente conoce; consulte más adelante. Omítalo para registrarlo con la fecha y hora actuales.
location	object	El lugar declarado: { "name": string, "latitude"?: number, "longitude"?: number }. name es lo que se representa.
resIds	UUID[] ≤ 25	Evidencias: ids de archivos ya adjuntos a la Ficha que documentan la entrada, como un informe de inspección o un certificado. Se rechazan los ids de archivos que no estén adjuntos a esa Ficha.

La respuesta devuelve la afirmación materializada: kind, title, note y un objeto estructurado when que contiene la cadena display, la precisión y los límites de la afirmación.

Indicar el tiempo con la precisión que conoce

edtf admite un subconjunto de EDTF (ISO 8601-2), de modo que la afirmación conserva exactamente la precisión que tiene su sistema: un año, un mes, un día, un intervalo o una aproximación:

Afirmación	edtf	Se representa como
Un día exacto	2026-07-14	14 de julio de 2026
Un mes	2026-07	Julio de 2026
Un año	1968	1968
Un intervalo cerrado	1968/1970	1968–1970
Aproximadamente	1835~	Aproximadamente 1835
Antes de una fecha	../1970-03	Antes de marzo de 1970
Después de una fecha	2019/..	Después de 2019

La afirmación se muestra en todas partes con la precisión que indicó: un intervalo 1968/1970 nunca se reduce a una fecha exacta inventada. Envíe la precisión que realmente tiene, no una suposición con una marca de tiempo a medianoche.

Consejo

Los documentos de un ERP suelen contener una fecha de contabilización, no una marca de tiempo. Publique la fecha (2026-08-06), no un instante inventado: el registro será más fiel y se leerá mejor en la Ficha y en su Página pública.

Atribuir la acción al operador humano

Una Cuenta de servicio autentica su sistema. La cabecera Dust-Ctx-Declared-Actor identifica a la persona que actuó en él, en cada solicitud:

Dust-Ctx-Declared-Actor: {"id": "JDOE", "system": "SAP", "displayName": "Jane Doe", "role": "Quality Inspector"}

id es obligatorio; system, displayName y role son opcionales; el valor JSON debe ocupar menos de 1 KB (codifíquelo como URI si contiene caracteres que no sean ASCII). El actor declarado se registra literalmente en cada entrada que escribe la solicitud y se muestra en el historial como una atribución declarada: la proporciona su integración, DICE no la verifica y nunca afecta a los permisos. Un administrador de la organización puede hacerla obligatoria, en cuyo caso las escrituras que no la incluyan se rechazan con 403 ATTRIBUTION_REQUIRED. Semántica completa: Atribución del actor declarado.

Para la procedencia declarada, conviene tratar esta cabecera como obligatoria en su propio código: «Inspeccionado — aprobado» es una afirmación mucho más sólida si lleva adjunto «Jane Doe, inspectora de calidad» que si solo indica «Conector de SAP».

Declarar en un lote completo

Cuando un evento empresarial afecta a muchos artículos —la recepción de mercancías de 200 unidades serializadas o una inspección de lote—, declárelo una vez en todos ellos:

curl -fsS "https://apid.dustid.io/api/v1/events/declare/batch" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H 'Dust-Ctx-Declared-Actor: {"id": "JDOE", "system": "SAP"}' \
  -H "Content-Type: application/json" \
  -d '{
    "threadIds": ["0b9e7c9a-…", "4f1d22c0-…", "9a8b11de-…"],
    "title": "Incoming inspection passed",
    "kind": "inspection",
    "edtf": "2026-08-06",
    "location": { "name": "Plant 1710, Springfield" }
  }'

• threadIds acepta entre 1 y 500 ids de Fichas; la escritura es atómica y requiere acceso de edición a todas las Fichas del lote.
• La misma afirmación se registra en todas las Fichas: no puede haber variaciones por Ficha dentro de un lote. Los datos que difieren según el artículo (número de serie, lote o resultados de mediciones) deben guardarse en campos de la Ficha, no en la afirmación.
• La respuesta incluye un operationId compartido. Guárdelo: es el identificador del lote para realizar correcciones (véase más adelante).

Consejo

El endpoint de lotes también funciona con un único id de Ficha y, a diferencia del endpoint de entrada única, devuelve un operationId. Si alguna vez su integración pudiera necesitar corregir una entrada mediante programación, declararla a través del endpoint de lotes y almacenar el operationId junto con el documento de origen le proporcionará un identificador duradero.

Incorporar muchas entradas históricas a la vez

/declare/batch escribe una afirmación en muchas Fichas. Cuando tenga que publicar muchas afirmaciones diferentes —una incorporación de datos históricos, una migración desde un sistema basado en hojas de cálculo o los eventos de una jornada en la planta—, use /declare/rows. Cada fila se escribe en todas las Fichas de threadIds y todo comparte un único operationId:

curl -fsS "https://apid.dustid.io/api/v1/events/declare/rows" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H 'Dust-Ctx-Declared-Actor: {"id": "JDOE", "system": "SAP"}' \
  -H "Content-Type: application/json" \
  -d '{
    "threadIds": ["0b9e7c9a-…"],
    "rows": [
      { "title": "Inspected", "kind": "inspection", "edtf": "2024-03-01", "location": { "name": "Geneva" } },
      { "title": "Sealed for shipment", "kind": "shipment", "edtf": "2024-03-04" },
      { "title": "Customs cleared", "edtf": "2024-03-11" }
    ]
  }'

• Hasta 100 filas y 500 Fichas, con un límite de 2.000 entradas totales (threadIds.length × rows.length) por solicitud. Divida las incorporaciones de datos más grandes.
• La solicitud completa es atómica: una fecha no reconocida provoca el rechazo de todas las filas, en vez de dejar una incorporación parcial con entradas que solo podrían retractarse una a una.
• Las filas no admiten anchor ni evidencias mediante resIds: ambos son elementos de una sola afirmación. Use /declare para ellos.
• /declare/batch es el caso de una sola fila de este endpoint; continúe usándolo cuando la afirmación sea realmente una sola.

Este es el mismo endpoint al que publica la importación de CSV de DICE. Si sus clientes incorporan datos históricos manualmente en lugar de hacerlo desde un sistema, diríjalos a Registrar eventos pasados en vez de crear una integración.

Corregir un error

Las entradas declaradas son inmutables: no se pueden editar ni eliminar. La corrección es una retractación: una segunda entrada atribuida que indica que la primera era incorrecta. La original permanece en el historial marcada como retractada, y ambas acompañan al registro en los pasos posteriores: una fe de erratas, nunca un borrado.

Para retractar todo lo que escribió un lote (por ejemplo, si se anuló la recepción de mercancías en su ERP), publique el operationId almacenado:

curl -fsS "https://apid.dustid.io/api/v1/events/retract/by-operation" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "operationId": "7c3f0f9e-5b7a-4a4f-8f7d-2f1d0e6a9b21",
    "reason": "Goods receipt reversed (movement type 102)."
  }'

Esto retracta todas las entradas aún vigentes que escribió la operación —se omiten las que ya se retractaron individualmente— y requiere acceso de edición a todas las Fichas implicadas. Para retractar una sola entrada, se utiliza en su lugar su id de evento: POST /api/v1/events/{event_id}/retract, con un reason opcional. Los ids de los eventos se obtienen del historial de la Ficha (GET /api/v1/events?threadId=…).

Después de retractarla, registre una entrada corregida mediante una nueva declaración: ese par, la entrada errónea más la corrección, representa fielmente el registro.

Precaución

Una Página pública publica una instantánea, por lo que una entrada nueva o una retractación solo llega a la página cuando esta se vuelve a publicar. Cuando el diseño de la página utiliza la política de pasaporte actualizado, una declaración o retractación realizada correctamente vuelve a publicarla automáticamente con la versión que ya ofrece. De lo contrario, la página sigue mostrando la instantánea anterior, aparece indicada como desactualizada respecto a su registro y se actualiza en la siguiente publicación. En ambos casos, la afirmación retirada aparece tachada y marcada como retirada, en vez de desaparecer: la procedencia publicada nunca se reescribe silenciosamente.

Modos de fallo

Respuesta	Significado
400 INVALID_DATA	El valor edtf queda fuera del subconjunto admitido o no es una fecha real del calendario, la declaración está vacía o un id de evidencia no está adjunto a esa Ficha.
400 INVALID_REQUEST	Cuerpo con formato incorrecto; por ejemplo, un campo supera su límite de longitud.
403 ATTRIBUTION_REQUIRED	La política de la Cuenta de servicio exige un actor declarado y la solicitud no incluyó ninguno.
404 NOT_FOUND	Un id de Ficha que el solicitante no puede ver o que no existe. En el endpoint de lotes, un solo id de este tipo hace que falle todo el lote.

Los cuerpos de error siguen el contrato estándar; consulte Convenciones de las solicitudes y Errores y resultados de escaneo para conocer todos los códigos, sus estados y las recomendaciones para volver a intentarlo.

Siguientes pasos

• Autenticación y claves de API — Cuentas de servicio, intercambio de tokens y semántica del actor declarado.
• Errores y resultados de escaneo — el contrato completo de fallos, incluido el comportamiento de renovación tras un 401.
• Guía de la API de Fichas — resolución de los números de serie y pedidos de su sistema en ids de Fichas.
• Registrar eventos pasados — la misma función tal como la ven sus operadores en DICE.
• Páginas públicas — cómo aparecen las entradas declaradas en el pasaporte público del artículo.