Registra la provenienza dal tuo ERP

I sistemi aziendali rilevano eventi a cui DICE non assiste mai: un’entrata merci in SAP, l’approvazione di un’ispezione nel tuo MES, una vendita conclusa nella tua piattaforma commerciale. Le transazioni dichiarate consentono alla tua integrazione di registrare questi momenti nella cronologia di una scheda mentre si verificano: ciascuno diventa una voce attribuita e permanente che accompagna la provenienza dell’articolo e può apparire sulla sua pagina pubblica.

Questa procedura collega un ERP (la stessa struttura è adatta a un WMS, un MES o qualsiasi sistema autorevole) a POST /api/v1/events/declare, eseguendo l’autenticazione come account di servizio e attribuendo ogni voce all’operatore umano che ha agito nel tuo sistema.

Nota

Una voce dichiarata è un’affermazione attribuita della tua organizzazione, mai un fatto verificato dalla piattaforma. DICE registra chi l’ha dichiarata e quando, la mostra contrassegnata come dichiarata e non la presenta mai come qualcosa osservato dalla piattaforma. È inoltre permanente: viene condivisa con i proprietari successivi insieme al resto della cronologia della scheda e non può essere eliminata, ma solo ritirata; il ritiro costituisce una seconda voce visibile, non una cancellazione.

Panoramica del flusso

1. La tua integrazione scambia le credenziali del proprio account di servizio con un bearer token di breve durata (Autenticazione).
2. Nel tuo sistema accade qualcosa: un’uscita merci, un’ispezione, la chiusura di una riparazione.
3. La tua integrazione chiama POST /api/v1/events/declare specificando l’id della scheda, un titolo e il momento e il luogo dell’affermazione, e invia l’identità dell’operatore nell’header Dust-Ctx-Declared-Actor.
4. La voce appare nel registro delle transazioni della scheda in DICE, contrassegnata come Dichiarata e attribuita all’account di servizio che agisce per conto del tuo operatore.

Prerequisiti

• Un account di servizio con una chiave API o un client OAuth; consulta Autenticazione. L’account di servizio deve disporre dell’accesso in modifica alle schede su cui scriverà (concedigli l’accesso al team proprietario).
• L’id della tua organizzazione per l’header Dust-Ctx-Org-Id e, se l’account di servizio deve agire come un team specifico, l’id del team; consulta Convenzioni delle richieste.
• Gli id delle schede degli articoli coinvolti. In genere un’integrazione li risolve effettuando una ricerca in base al campo condiviso con il tuo sistema, ad esempio un numero di serie, un lotto o un numero d’ordine, tramite GET /api/v1/threads (consulta la guida all’API delle schede).

Dichiara una transazione

Una chiamata registra una voce in una scheda:

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();

Campi della richiesta: tutti tranne threadId sono facoltativi, ma una dichiarazione completamente vuota viene rifiutata:

Campo	Tipo	Note
threadId	UUID	La scheda a cui appartiene la voce. Richiede l’accesso in modifica.
title	string ≤ 80	Titolo breve: ciò che i feed e le pagine mostrano come titolo della voce.
note	string ≤ 4000	Descrizione in testo libero di ciò che è accaduto.
kind	string ≤ 64	Classificazione aperta: sale, inspection, repair, service, … secondo il tuo vocabolario. Il valore predefinito è other.
edtf	string ≤ 64	Quando è accaduto, con la precisione effettivamente nota; vedi sotto. Omettilo per registrare l’evento come avvenuto ora.
location	object	Il luogo dichiarato: { "name": string, "latitude"?: number, "longitude"?: number }. name è il valore visualizzato.
resIds	UUID[] ≤ 25	Evidenze: id di file già allegati alla scheda che documentano la voce, ad esempio un rapporto d’ispezione o un certificato. Gli id di file non allegati a quella scheda vengono rifiutati.

La risposta restituisce l’affermazione materializzata: kind, title, note e un oggetto strutturato when contenente la stringa display, la precisione e i limiti dell’affermazione.

Indica il momento con la precisione che conosci

edtf accetta un sottoinsieme di EDTF (ISO 8601-2), così l’affermazione conserva esattamente la precisione disponibile nel tuo sistema: un anno, un mese, un giorno, un intervallo o un’approssimazione.

Affermazione	edtf	Visualizzazione
Un giorno esatto	2026-07-14	14 lug 2026
Un mese	2026-07	Luglio 2026
Un anno	1968	1968
Un intervallo chiuso	1968/1970	1968–1970
Circa	1835~	Circa 1835
Prima di una data	../1970-03	Prima di marzo 1970
Dopo una data	2019/..	Dopo il 2019

L’affermazione viene mostrata ovunque con la precisione indicata: un intervallo 1968/1970 non viene mai ridotto a una data esatta inventata. Invia la precisione realmente disponibile, non una data e ora ipotetica impostata a mezzanotte.

Consiglio

I documenti ERP contengono solitamente una data di registrazione, non una data e ora. Invia la data (2026-08-06), non un istante inventato: il registro sarà più veritiero e risulterà più leggibile nella scheda e nella relativa pagina pubblica.

Attribuisci l’operatore umano

Un account di servizio autentica il tuo sistema. L’header Dust-Ctx-Declared-Actor identifica, per ogni richiesta, la persona che ha agito al suo interno:

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

id è obbligatorio; system, displayName e role sono facoltativi; il valore JSON deve rimanere inferiore a 1 KB (codificalo come URI se contiene caratteri non ASCII). L’attore dichiarato viene registrato testualmente in ogni voce scritta dalla richiesta e mostrato nella cronologia come attribuzione dichiarata: è fornito dalla tua integrazione, non verificato da DICE e non influisce mai sulle autorizzazioni. Un amministratore dell’organizzazione può renderlo obbligatorio; in tal caso, le scritture prive di questo valore vengono rifiutate con 403 ATTRIBUTION_REQUIRED. Per la semantica completa, consulta Attribuzione dell’attore dichiarato.

Per la provenienza dichiarata, vale la pena considerare questo header obbligatorio nel tuo codice: l’affermazione «Ispezionato — approvato» è molto più solida se accompagnata da «Jane Doe, Ispettrice della qualità» anziché dal solo «Connettore SAP».

Dichiara per un intero lotto

Quando un singolo evento aziendale riguarda molti articoli, ad esempio il ricevimento di 200 unità serializzate o un’ispezione a livello di lotto, dichiaralo una sola volta per tutti:

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 accetta gli id di 1–500 schede; la scrittura è tutto o niente e richiede l’accesso in modifica a ogni scheda del batch.
• La stessa affermazione viene registrata in ogni scheda: all’interno di un batch non sono ammesse variazioni tra schede. I dati che differiscono per articolo (numero di serie, lotto, risultati delle misurazioni) devono essere inseriti nei campi della scheda, non nell’affermazione.
• La risposta include un operationId condiviso. Conservalo: è il riferimento per correggere il batch (vedi sotto).

Consiglio

L’endpoint batch funziona anche con l’id di una singola scheda e, a differenza dell’endpoint per una singola voce, restituisce un operationId. Se la tua integrazione potrebbe dover correggere una voce in modo programmatico, dichiararla tramite l’endpoint batch e conservare l’operationId insieme al documento di origine ti offre un riferimento durevole.

Inserisci più voci storiche contemporaneamente

/declare/batch scrive una sola affermazione in più schede. Quando devi pubblicare molte affermazioni diverse, ad esempio per l’inserimento di dati storici, la migrazione da un sistema basato su fogli di calcolo o gli eventi di un’intera giornata in reparto, usa invece /declare/rows. Ogni riga viene scritta in tutte le schede indicate in threadIds e l’intera operazione condivide un unico 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" }
    ]
  }'

• Fino a 100 righe e 500 schede, con un limite di 2.000 voci totali (threadIds.length × rows.length) per richiesta. Suddividi gli inserimenti più grandi.
• Tutto o niente per l’intera richiesta: una sola data non riconosciuta causa il rifiuto di tutte le righe, anziché lasciare un inserimento storico parziale composto da voci che possono essere ritirate soltanto una alla volta.
• Le righe non includono anchor né le evidenze resIds: entrambe sono operazioni relative a una singola affermazione. Per queste usa /declare.
• /declare/batch è il caso con una sola riga di questo endpoint; continua a usarlo quando si tratta effettivamente di un’unica affermazione.

Questo è lo stesso endpoint usato dall’importazione CSV di DICE. Se i tuoi clienti inseriscono manualmente dati storici anziché importarli da un sistema, indirizzali a Registrazione di eventi passati invece di creare un’integrazione.

Correggi un errore

Le voci dichiarate sono immutabili: non possono essere modificate né eliminate. La correzione avviene tramite un ritiro, ossia una seconda voce attribuita che dichiara che la prima era errata. L’originale rimane nella cronologia contrassegnato come ritirato ed entrambe le voci accompagnano il registro nelle fasi successive: è una rettifica, mai una cancellazione.

Per ritirare tutte le voci scritte da un batch, ad esempio perché l’entrata merci è stata stornata nel tuo ERP, invia l’operationId conservato:

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)."
  }'

Questa operazione ritira tutte le voci ancora attuali scritte dall’operazione, ignorando quelle già ritirate singolarmente, e richiede l’accesso in modifica a tutte le schede coinvolte. Per ritirare una singola voce tramite il relativo id evento, usa invece POST /api/v1/events/{event_id}/retract con un reason facoltativo. Gli id evento provengono dalla cronologia della scheda (GET /api/v1/events?threadId=…).

Dopo il ritiro, registra una voce corretta con una nuova dichiarazione: questa coppia, composta dalla voce errata e dalla correzione, rappresenta il registro in modo veritiero.

Attenzione

Una pagina pubblica pubblica un’istantanea, quindi una nuova voce o un ritiro raggiunge la pagina soltanto quando questa viene ripubblicata. Quando il design della pagina usa i criteri del passaporto dinamico, una dichiarazione o un ritiro completati correttamente la ripubblicano automaticamente sulla base della versione già fornita. In caso contrario, la pagina continua a mostrare l’istantanea precedente, viene indicata come non allineata al proprio registro e si aggiorna alla pubblicazione successiva. In entrambi i casi, l’affermazione ritirata viene visualizzata barrata e contrassegnata come ritirata, anziché scomparire: la provenienza pubblicata non viene mai riscritta senza darne evidenza.

Modalità di errore

Risposta	Significato
400 INVALID_DATA	Il valore edtf non rientra nel sottoinsieme supportato o non rappresenta una data di calendario reale, la dichiarazione è vuota oppure l’id di un’evidenza non è allegato a quella scheda.
400 INVALID_REQUEST	Corpo non valido, ad esempio un campo che supera il limite di lunghezza.
403 ATTRIBUTION_REQUIRED	I criteri dell’account di servizio richiedono un attore dichiarato, ma la richiesta non ne include alcuno.
404 NOT_FOUND	Un id di scheda che il chiamante non può vedere o che non esiste. Nell’endpoint batch, anche un solo id di questo tipo causa il fallimento dell’intero batch.

I corpi degli errori seguono il contratto standard; consulta Convenzioni delle richieste e Errori ed esiti delle scansioni per tutti i codici, con i relativi stati e le indicazioni sui nuovi tentativi.

Passaggi successivi

• Autenticazione e chiavi API — account di servizio, scambio dei token e semantica dell’attore dichiarato.
• Errori ed esiti delle scansioni — il contratto completo degli errori, incluso il comportamento di aggiornamento per 401.
• Guida all’API delle schede — risoluzione dei numeri di serie e degli ordini del tuo sistema negli id delle schede.
• Registrazione di eventi passati — la stessa funzionalità così come viene visualizzata dagli operatori in DICE.
• Pagine pubbliche — come vengono visualizzate le voci dichiarate nel passaporto pubblico dell’articolo.