Odnotowywanie pochodzenia z systemu ERP

Systemy biznesowe odnotowują zdarzenia, których DICE nigdy nie widzi: przyjęcie towaru w SAP, zatwierdzenie kontroli w systemie MES, sprzedaż zamkniętą na platformie handlowej. Transakcje deklarowane pozwalają integracji zapisywać te momenty w historii rekordu na bieżąco — każda z nich jest przypisanym, trwałym wpisem, który towarzyszy pochodzeniu przedmiotu i może pojawić się na jego stronie publicznej.

Ten przepis łączy system ERP (ten sam schemat pasuje do systemu WMS, MES lub dowolnego systemu ewidencji) z POST /api/v1/events/declare, z uwierzytelnianiem jako konto usługi i przypisaniem każdego wpisu do operatora, który wykonał działanie w twoim systemie.

Notatka

Zadeklarowany wpis jest przypisanym twierdzeniem twojej organizacji — nigdy faktem zweryfikowanym przez platformę. DICE zapisuje, kto i kiedy go zgłosił, wyświetla go z oznaczeniem deklaracji i nigdy nie przedstawia go jako czegoś, co platforma zaobserwowała. Jest też trwały: jest udostępniany kolejnym właścicielom wraz z resztą historii rekordu i nie można go usunąć, a jedynie wycofać — przy czym wycofanie jest drugim widocznym wpisem, a nie wymazaniem.

Przepływ w skrócie

1. Integracja wymienia poświadczenie konta usługi na krótkotrwały token Bearer (Uwierzytelnianie).
2. W twoim systemie coś się dzieje — wydanie towaru, kontrola, zamknięcie naprawy.
3. Integracja wywołuje POST /api/v1/events/declare z ID rekordu, tytułem wpisu oraz czasem i miejscem twierdzenia, przesyłając tożsamość operatora w nagłówku Dust-Ctx-Declared-Actor.
4. Wpis pojawia się w dzienniku transakcji rekordu w DICE, oznaczony jako Deklarowana i przypisany do konta usługi działającego w imieniu twojego operatora.

Wymagania wstępne

• Konto usługi z kluczem API lub klientem OAuth — zobacz Uwierzytelnianie. Konto usługi potrzebuje uprawnień do edycji rekordów, w których będzie zapisywać wpisy (przyznaj mu dostęp do zespołu będącego właścicielem).
• ID organizacji dla nagłówka Dust-Ctx-Org-Id oraz ID zespołu, jeśli konto usługi ma działać jako określony zespół — zobacz Konwencje żądań.
• ID rekordów przedmiotów, których dotyczy zdarzenie. Integracja zwykle ustala je, wyszukując według pola wspólnego z twoim systemem — numeru seryjnego, partii lub numeru zamówienia — za pomocą GET /api/v1/threads (zobacz przewodnik po API rekordów).

Deklarowanie transakcji

Jedno wywołanie zapisuje jeden wpis w jednym rekordzie:

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

Pola żądania — wszystkie poza threadId są opcjonalne, ale całkowicie pusta deklaracja zostanie odrzucona:

Pole	Typ	Uwagi
threadId	UUID	Rekord, do którego należy wpis. Wymaga uprawnień do edycji.
title	string ≤ 80	Krótki tytuł — wyświetlany jako tytuł wpisu w strumieniach i na stronach.
note	string ≤ 4000	Dowolny tekst opisujący, co się wydarzyło.
kind	string ≤ 64	Otwarta klasyfikacja: sale, inspection, repair, service, … Twoje własne słownictwo. Wartość domyślna to other.
edtf	string ≤ 64	Kiedy to się wydarzyło, z precyzją, jaką faktycznie znasz — zobacz niżej. Pomiń, aby zapisać bieżący moment.
location	object	Deklarowane miejsce: { "name": string, "latitude"?: number, "longitude"?: number }. Wyświetlana jest wartość name.
resIds	UUID[] ≤ 25	Dowody: ID plików już załączonych do rekordu, które dokumentują wpis — raport z kontroli, certyfikat. ID plików niezałączonych do tego rekordu są odrzucane.

Odpowiedź zwraca utworzone twierdzenie — kind, title, note oraz ustrukturyzowany obiekt when zawierający ciąg display twierdzenia, precyzję i granice.

Podawanie czasu z precyzją, którą znasz

edtf przyjmuje podzbiór formatu EDTF (ISO 8601-2), dzięki czemu twierdzenie ma dokładnie taką precyzję, jaką dysponuje twój system — rok, miesiąc, dzień, zakres lub przybliżenie:

Twierdzenie	edtf	Wyświetlane jako
Dokładny dzień	2026-07-14	14 lip 2026
Miesiąc	2026-07	Lipiec 2026
Rok	1968	1968
Zakres zamknięty	1968/1970	1968–1970
W przybliżeniu	1835~	ok. 1835
Przed datą	../1970-03	Przed marcem 1970
Po dacie	2019/..	Po 2019

Twierdzenie jest wszędzie wyświetlane z podaną precyzją — zakres 1968/1970 nigdy nie jest sprowadzany do zmyślonej dokładnej daty. Przesyłaj precyzję, którą faktycznie masz, a nie domysł opatrzony znacznikiem czasu północy.

Wskazówka

Dokumenty ERP zwykle zawierają datę księgowania, a nie znacznik czasu. Przesyłaj datę (2026-08-06), a nie zmyślony moment — zapis jest wtedy uczciwszy i lepiej się prezentuje w rekordzie i na jego stronie publicznej.

Przypisywanie operatora

Konto usługi uwierzytelnia twój system. Nagłówek Dust-Ctx-Declared-Actor wskazuje w każdym żądaniu osobę, która w nim działała:

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

id jest wymagane; system, displayName i role są opcjonalne; wartość JSON musi mieć mniej niż 1 KB (jeśli zawiera znaki spoza ASCII, zakoduj ją jako URI). Zadeklarowany wykonawca jest zapisywany dosłownie w każdym wpisie utworzonym przez żądanie i wyświetlany w historii jako przypisanie deklarowane — dostarczone przez twoją integrację, niezweryfikowane przez DICE i nigdy niewpływające na uprawnienia. Administrator organizacji może ustawić je jako obowiązkowe; wtedy zapisy bez niego są odrzucane z błędem 403 ATTRIBUTION_REQUIRED. Pełna semantyka: Przypisanie deklarowanego wykonawcy.

W przypadku deklarowanego pochodzenia warto traktować ten nagłówek jako wymagany we własnym kodzie: „Skontrolowano — wynik pozytywny” to znacznie mocniejsze twierdzenie z dołączonym „Jane Doe, Quality Inspector” niż z samym „SAP Connector”.

Deklarowanie dla całej partii

Gdy jedno zdarzenie biznesowe dotyczy wielu przedmiotów — przyjęcia 200 jednostek z numerami seryjnymi, kontroli na poziomie partii — zadeklaruj je jednorazowo dla wszystkich:

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 przyjmuje od 1 do 500 ID rekordów; zapis jest typu wszystko albo nic i wymaga uprawnień do edycji każdego rekordu w partii.
• To samo twierdzenie trafia do każdego rekordu — w partii nie ma wariantów dla poszczególnych rekordów. Dane różniące się między przedmiotami (numer seryjny, partia, wyniki pomiarów) należą do pól rekordu, a nie do twierdzenia.
• Odpowiedź zawiera wspólne ID operacji operationId. Zapisz go: służy do korygowania partii (zobacz niżej).

Wskazówka

Punkt końcowy partii działa też z jednym ID rekordu i w przeciwieństwie do punktu końcowego pojedynczego wpisu zwraca operationId. Jeśli integracja może kiedykolwiek wymagać programowego skorygowania wpisu, deklarowanie przez punkt końcowy partii i przechowywanie operationId razem z dokumentem źródłowym daje trwały uchwyt.

Uzupełnianie wielu wpisów naraz

/declare/batch zapisuje jedno twierdzenie w wielu rekordach. Gdy masz do opublikowania wiele różnych twierdzeń — historyczne uzupełnienie danych, migrację z systemu opartego na arkuszach kalkulacyjnych, zdarzenia z hali produkcyjnej z całego dnia — użyj zamiast tego /declare/rows. Każdy wiersz jest zapisywany w każdym rekordzie z threadIds, a całość ma jeden wspólny 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" }
    ]
  }'

• Do 100 wierszy i 500 rekordów, z limitem 2000 wpisów łącznie (threadIds.length × rows.length) na żądanie. Większe uzupełnienia podziel na części.
• Wszystko albo nic w obrębie całego żądania: jedna nierozpoznana data powoduje odrzucenie wszystkich wierszy, zamiast pozostawić częściowe uzupełnienie z wpisami, które można by wycofywać tylko pojedynczo.
• Wiersze nie zawierają anchor ani dowodów resIds — oba dotyczą pojedynczych twierdzeń. Do nich używaj /declare.
• /declare/batch to jednowierszowy przypadek tego punktu końcowego; używaj go nadal, gdy twierdzenie rzeczywiście jest jedno.

Jest to ten sam punkt końcowy, do którego wysyła dane import CSV w DICE. Jeśli twoi klienci uzupełniają dane ręcznie, a nie z systemu, skieruj ich do strony Odnotowywanie przeszłych zdarzeń, zamiast budować integrację.

Korygowanie błędu

Zadeklarowane wpisy są niezmienne — nie można ich edytować ani usuwać. Korekta polega na wycofaniu: drugim przypisanym wpisie stwierdzającym, że pierwszy był błędny. Pierwotny wpis pozostaje w historii oznaczony jako wycofany, a oba trafiają do kolejnych właścicieli wraz z rekordem — errata, nigdy wymazanie.

Aby wycofać wszystko, co zapisała jedna partia (na przykład gdy przyjęcie towaru zostało stornowane w systemie ERP), prześlij zapisany operationId:

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

Powoduje to wycofanie każdego nadal aktywnego wpisu zapisanego przez operację — wpisy już wycofane pojedynczo są pomijane — i wymaga uprawnień do edycji każdego rekordu, którego to dotyczy. Pojedynczy wpis wycofuje się natomiast według ID zdarzenia: POST /api/v1/events/{event_id}/retract z opcjonalnym reason. ID zdarzeń pochodzą z historii rekordu (GET /api/v1/events?threadId=…).

Po wycofaniu zapisz poprawiony wpis za pomocą nowej deklaracji — ta para, błędny wpis i korekta, jest uczciwą postacią zapisu.

Uwaga

Strona publiczna publikuje migawkę, więc nowy wpis lub wycofanie trafia na stronę dopiero po jej ponownej publikacji. Gdy projekt strony korzysta z zasady żywego paszportu, pomyślna deklaracja lub wycofanie automatycznie publikuje ją ponownie na podstawie wersji, którą już udostępnia. W przeciwnym razie strona nadal wyświetla poprzednią migawkę, jest oznaczana jako nieaktualna względem swojego rekordu i aktualizuje się przy następnej publikacji. W obu przypadkach wycofane twierdzenie jest wyświetlane jako przekreślone i oznaczone jako wycofane, zamiast znikać — opublikowane pochodzenie nigdy nie jest po cichu zmieniane.

Tryby niepowodzenia

Odpowiedź	Znaczenie
400 INVALID_DATA	Wartość edtf wykracza poza obsługiwany podzbiór lub nie jest rzeczywistą datą kalendarzową, deklaracja jest pusta albo ID dowodu nie jest załączone do tego rekordu.
400 INVALID_REQUEST	Nieprawidłowa treść — np. pole przekraczające limit długości.
403 ATTRIBUTION_REQUIRED	Zasady konta usługi wymagają zadeklarowanego wykonawcy, a żądanie go nie zawierało.
404 NOT_FOUND	ID rekordu, którego wywołujący nie widzi lub który nie istnieje. W punkcie końcowym partii jedno takie ID powoduje niepowodzenie całej partii.

Treści błędów są zgodne ze standardowym kontraktem — zobacz Konwencje żądań oraz Błędy i wyniki skanowania, gdzie opisano każdy kod wraz z kodem stanu i wskazówkami dotyczącymi ponawiania.

Następne kroki

• Uwierzytelnianie i klucze API — konta usług, wymiana tokenów, semantyka deklarowanego wykonawcy.
• Błędy i wyniki skanowania — pełny kontrakt dotyczący niepowodzeń, w tym zachowanie odświeżania po błędzie 401.
• Przewodnik po API rekordów — zamiana numerów seryjnych i numerów zamówień z twojego systemu na ID rekordów.
• Odnotowywanie przeszłych zdarzeń — ta sama funkcja z perspektywy operatorów w DICE.
• Strony publiczne — jak zadeklarowane wpisy pojawiają się w publicznym paszporcie przedmiotu.