Przejdź do treści

DueReason API v1

Dokumentacja API

Dzięki API DueReason Twój zespół, pipeline'y i agenci AI mogą poprosić człowieka o zgodę, zanim zaczną działać, a uzasadnienia zostają w rejestrze. Pobierz listę akcji, o które Twoja organizacja przyjmuje wnioski, poproś o zatwierdzenie z danymi (payload) i uzasadnieniem, poczekaj na grant, zweryfikuj go, a potem wykonaj działanie i zgłoś wynik. Każdy krok to zdarzenie w rejestrze, a całość zamyka podpisane, niezależnie weryfikowalne potwierdzenie (receipt).

Adres bazowy
https://www.duereason.com/api/v1
Dokument OpenAPI 3.1
/api/v1/openapi.json

Maszynowo czytelny opis wszystkich endpointów i webhooków, do generowania klientów i walidacji żądań.

Żądania i odpowiedzi są w formacie JSON (UTF-8). Znaczniki czasu są w formacie ISO 8601 w UTC. Treść żądania może mieć najwyżej 256 KB.

Zacznij z DueReason

Załóż bezpłatne konto, wypróbuj na żywo albo porozmawiaj z nami o swoim procesie.

Otrzymuj nowości o produkcie

Przebieg integracji

  1. Pobierz listę akcji, o które Twoja organizacja przyjmuje wnioski o zatwierdzenie (GET /actions), każda ze schematem danych (payload), który musi spełniać wniosek.
  2. Poproś o zatwierdzenie: POST /approvals z akcją, dokładnymi danymi (payload) i uzasadnieniem. O tym, kto musi zatwierdzić, decydują przepływy (workflows) organizacji; wniosek niepasujący do żadnego jest odrzucany od razu z kodem no_workflow.
  3. Poczekaj na webhook approval.approved albo approval.rejected, albo odpytuj GET /approvals/{id}?wait=N. Nigdy nie działaj, zanim wniosek zostanie zatwierdzony.
  4. Zweryfikuj grant zwrócony przez POST /grants/verify, zanim na nim polegasz, albo sprawdź jego podpis samodzielnie, kluczami organizacji (JWKS).
  5. Wykonaj zatwierdzone działanie, a potem zgłoś, co się stało, przez POST /approvals/{id}/executions. Grant jest jednorazowy.
  6. Pobierz podpisane potwierdzenie decyzji przez GET /approvals/{id}/receipt: samodzielny zapis, który Ty, zatwierdzający albo audytor możecie zweryfikować bez konta DueReason.

Uwierzytelnianie

Każde żądanie zawiera klucz API jako token typu bearer. Właściciele i administratorzy tworzą klucze w konsoli w sekcji Ustawienia, Klucze API, opcjonalnie z terminem ważności; pełny klucz jest pokazywany tylko raz, DueReason przechowuje wyłącznie jego skrót SHA-256.

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Brakujący, błędnie sformatowany, przeterminowany lub unieważniony klucz daje odpowiedź 401. Ważny klucz bez zakresu wymaganego przez endpoint daje 403 z kodem insufficient_scope. Klucze nigdy nie są przyjmowane w parametrach adresu.

Zakresy

ZakresPozwala
approval:requestProszenie o zatwierdzenie, wycofywanie własnych oczekujących wniosków i zgłaszanie wyniku po użyciu grantu.
approval:readOdczyt wniosków, odpowiedzi i zgód; weryfikacja zgód.
action:readOdczyt akcji, o których zatwierdzenie można prosić, i schematów ich danych.
action:manageTworzenie, aktualizacja i usuwanie akcji oraz przepływów pracy (konfiguracja jako kod). Nie jest przyznawany domyślnie; nigdy nie łączy się z approval:request na tym samym kluczu, bo taki klucz mógłby sam zatwierdzać własne wnioski. Zapisy są rejestrowane w dzienniku zdarzeń z kluczem jako wykonawcą, a włączenie autoApprove wysyła e-mail do właścicieli organizacji.
mandate:readOdczyt mandatów i ich wykorzystania.
mandate:revokeOdwołanie mandatu wystawionego przez Twoją organizację.
webhook:manageTworzenie i listowanie endpointów webhook oraz odczyt ich klucza podpisującego jednorazowo, przy tworzeniu.
Moduł platform-work (domyślnie wyłączony)
ZakresPozwala
decision:readOdczyt decyzji, ich zdarzeń w rejestrze i czoła łańcucha.
decision:requestTworzenie i wycofywanie decyzji, przekazywanie wniosków o weryfikację.
decision:enactPotwierdzanie, że decyzja została wykonana.
statement:issueWydawanie uzasadnień i otrzymywanie linków do portalu pracownika.
worker:readOdczyt danych pracowników.
worker:writeTworzenie i aktualizacja danych pracowników.
system:readOdczyt rejestru zautomatyzowanych systemów.
notice:readOdczyt zgłoszeń DSA (dodatek DSA).
notice:writePrzekazywanie zgłoszeń DSA otrzymanych w Twoim interfejsie (dodatek DSA).

Żaden zakres nie pozwala odpowiedzieć na wniosek o zatwierdzenie: może to zrobić wyłącznie osoba wskazana w przepływie (workflow), w konsoli albo z poziomu powiadomienia.

Idempotentność

Każde żądanie POST wymaga nagłówka Idempotency-Key: dowolnego ciągu o długości od 1 do 200 znaków, generowanego raz dla każdej operacji logicznej, na przykład UUID. Ponowienie z tym samym kluczem nigdy nie powtarza skutku.

  • Ten sam klucz i to samo żądanie (metoda, ścieżka i treść): otrzymujesz pierwotny status i treść, bajt w bajt, z nagłówkiem Idempotent-Replayed: true.
  • Ten sam klucz z innym żądaniem: 422 z kodem idempotency_key_reused.
  • Ten sam klucz, gdy pierwsze żądanie jest jeszcze przetwarzane: 409 z kodem idempotency_key_in_use. Ponów po krótkiej przerwie.

Zapamiętywane są tylko odpowiedzi zakończone sukcesem. Żądanie, które się nie powiodło, niczego nie zmieniło, więc ponowienie z tym samym kluczem wykona je jeszcze raz, na przykład gdy weryfikator zatwierdzi już decyzję.

Klucze są pamiętane przez 24 godziny. PUT jest idempotentny z definicji i nie przyjmuje tego nagłówka.

Limity zapytań

Każdy klucz API może wykonać do 600 żądań na minutę, liczonych w stałym jednominutowym oknie i egzekwowanych per klucz, a nie per organizacja czy adres IP. Klucz współdzielony przez wielu pracowników lub agentów korzysta z tego samego budżetu, a każda odpowiedź, zarówno udana, jak i nie, zawiera poniższe trzy nagłówki.

NagłówekZnaczenie
RateLimit-LimitLimit dla bieżącego okna: 600.
RateLimit-RemainingLiczba żądań pozostałych w bieżącym oknie.
RateLimit-ResetLiczba sekund do zresetowania okna.

Przekroczenie limitu kończy się odpowiedzią 429 z kodem problemu rate_limited i nagłówkiem Retry-After podającym liczbę sekund do odczekania.

Przykładowa odpowiedź 429
{
  "type": "https://www.duereason.com/docs/api#error-rate_limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "This API key made more than 600 requests in a minute. Retry after 12 s.",
  "code": "rate_limited",
  "details": {
    "limit": 600,
    "retryAfterSeconds": 12
  }
}

RateLimit-Limit: 600 RateLimit-Remaining: 0 RateLimit-Reset: 12 Retry-After: 12

Odczekaj liczbę sekund podaną w Retry-After zamiast stałego opóźnienia. @duereason/sdk robi to automatycznie przy ponawianiu żądań po 429; musisz obsłużyć to samodzielnie tylko wtedy, gdy wywołujesz REST API bezpośrednio.

CORS

Każda operacja /api/v1 zezwala na żądania cross-origin z dowolnego źródła przeglądarki — ta sama zasada obowiązuje już dla /api/v1/openapi.json. Klucz API to token bearer wysyłany jawnie w nagłówku Authorization, nigdy niejawne poświadczenie takie jak ciasteczko, więc nie ma tu ryzyka typu CSRF; dzięki temu integracja uruchomiona w przeglądarce (wewnętrzny panel administracyjny, niestandardowy komponent Retool/Glide) dostaje prawdziwe błędy problem+json DueReason zamiast nieczytelnego błędu sieciowego.

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, Idempotency-Key
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS

Każda odpowiedź zawiera poniższe nagłówki. Żądanie wymagające preflightu (z nagłówkiem niestandardowym, np. Authorization albo Idempotency-Key) dostaje odpowiedź 204 z tymi samymi nagłówkami z żądania OPTIONS, które nigdy nie dociera do uwierzytelniania.

Błędy

Błędy są dokumentami problemu zgodnymi z RFC 9457, o typie application/problem+json. Rozgałęziaj logikę na podstawie pola code, które jest stabilne; detail to czytelne wyjaśnienie, które można bezpiecznie zapisywać w logach. Błędy walidacji wymieniają każdy problem w details.issues wraz z miejscem (path, query albo body) i ścieżką pola.

{
  "type": "https://www.duereason.com/docs/api#error-invalid",
  "title": "Invalid request",
  "status": 422,
  "detail": "The request body is invalid.",
  "code": "invalid",
  "details": {
    "issues": [
      {
        "in": "body",
        "path": "facts",
        "message": "Invalid input: expected string, received undefined"
      }
    ]
  }
}
KodStatusZnaczenie
malformed_json400Treść żądania nie jest poprawnym JSON-em.
idempotency_key_required400Żądanie POST bez nagłówka Idempotency-Key albo z nagłówkiem dłuższym niż 200 znaków.
unauthorized401Klucz API jest brakujący, błędnie sformatowany, wygasł lub został unieważniony.
payment_required402Subskrypcja organizacji wygasła, więc nowe wnioski i decyzje są odrzucane; details.billingUrl wskazuje, gdzie właściciel lub administrator wybiera plan. Odczyty, anulowanie, zgłaszanie wykonania i weryfikacja grantów działają nadal.
insufficient_scope403Klucz nie ma zakresu wymaganego przez endpoint; wskazuje go details.requiredScope.
forbidden403Ta czynność w ogóle nie jest dostępna dla klucza API.
not_found404W Twojej organizacji nie ma takiego zasobu. Identyfikatory innej organizacji również dają 404.
conflict409Stan decyzji na to nie pozwala, na przykład wykonanie decyzji wciąż oczekującej (pending_human), albo externalRef jest już zajęty.
not_pending409Stan wniosku na to nie pozwala: anulowanie wniosku już rozstrzygniętego albo zgłoszenie wykonania wniosku, który nie został zatwierdzony.
not_decided409Wniosek nie został jeszcze rozstrzygnięty; potwierdzenie powstaje, gdy zostanie zaakceptowany, odrzucony, wygaśnie lub zostanie anulowany.
already_responded409Ta osoba już odpowiedziała na wniosek (tylko w konsoli).
already_executed409Wykonanie z tym grantem zostało już zgłoszone; grant jest jednorazowy.
idempotency_key_in_use409Żądanie z tym samym Idempotency-Key jest jeszcze przetwarzane.
precondition_failed412Najpierw musi się wydarzyć coś innego, na przykład aktywacja wskazanego systemu, albo osoba jest użytkownikiem biznesowym P2B, do którego weryfikacja z art. 11 nie ma zastosowania. Punkty końcowe zgłoszeń zwracają też 412, gdy dodatek DSA jest wyłączony.
payload_too_large413Treść żądania przekracza 256 KB.
unsupported_media_type415Treść żądania nie została wysłana jako application/json.
invalid422Żądanie nie przeszło walidacji; details.issues wymienia wszystkie problemy.
no_workflow422Do wniosku nie pasuje żaden aktywny przepływ akcji, więc nie można go zatwierdzić. Nic nie zostało utworzone.
invalid_payload422Dane (payload) nie spełniają schematu akcji; details.problems wymienia przyczyny.
idempotency_key_reused422Ten Idempotency-Key został już użyty dla innego żądania.
rate_limited429Ponad 600 żądań w ciągu minuty z tego klucza. Odczekaj liczbę sekund podaną w Retry-After. Każda odpowiedź zawiera nagłówki RateLimit-Limit, RateLimit-Remaining i RateLimit-Reset.
internal500Wystąpił błąd po naszej stronie. Ponowienie z tym samym Idempotency-Key jest bezpieczne.
grants_unavailable503Wniosek jest zatwierdzony, ale jego grantu nie da się teraz podpisać z powodu problemu z konfiguracją po naszej stronie. Spróbuj ponownie później.
scanner_unavailable503Plików wysłanych w multipart POST /approvals nie udało się sprawdzić pod kątem złośliwego oprogramowania (skaner nie odpowiedział na czas). Nic nie zostało zapisane; spróbuj ponownie za kilka minut.

Stronicowanie

Listy zwracają w polu data najnowsze elementy jako pierwsze, wraz z nextCursor. Przekaż go w parametrze cursor, aby pobrać następną stronę; na ostatniej stronie ma wartość null. Parametr limit przyjmuje wartości od 1 do 100, domyślnie 50.

Endpointy

Zatwierdzenia

DueReason: zanim agent lub system zrobi coś istotnego, prosi ludzi o zgodę. Tu śledzisz wniosek, a przed działaniem weryfikujesz podpisany grant.

GET/api/v1/actions

Lista akcji

Akcje, dla których organizacja przyjmuje wnioski o zatwierdzenie, każda ze schematem danych (payload), który wniosek musi spełnić, alfabetycznie po kluczu, po jednej stronie naraz. Domyślnie zwracane są tylko aktywne akcje; dodaj include=inactive, by zobaczyć też te, dla których nie da się już złożyć wniosku. Podążaj za nextCursor (przekaż je z powrotem jako cursor), aż będzie null.

Zakres
action:read
Sukces
200
Przykład
curl -X GET "https://www.duereason.com/api/v1/actions?include=inactive" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/actions/{key}

Pobierz akcję

Jedna akcja po jej kluczu, aktywna lub nie, ze schematem danych (payload) i czasem ważności grantu.

Zakres
action:read
Sukces
200
Błędy
not_found
Przykład
curl -X GET "https://www.duereason.com/api/v1/actions/payment" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/actions

Utwórz akcję

Zdefiniuj nowy rodzaj rzeczy, dla której organizacja przyjmuje wnioski o zatwierdzenie: jej klucz (niezmienny, to wysyła agent jako action), nazwę, schemat danych i czas ważności grantu. Wymaga action:manage — zakresu nieprzyznawanego domyślnie i nigdy nie łączonego z approval:request na tym samym kluczu, bo taki klucz mógłby sam zatwierdzać własne wnioski.

Zakres
action:manage
Sukces
201

Wymaga Idempotency-Key

Przykład
curl -X POST "https://www.duereason.com/api/v1/actions" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "payment",
  "name": "Payment",
  "description": "Pay a supplier invoice.",
  "payloadSchema": {
    "type": "object",
    "properties": {
      "amount": {
        "type": "number",
        "minimum": 0
      },
      "currency": {
        "type": "string",
        "format": "currency"
      },
      "payee": {
        "type": "string"
      }
    },
    "required": [
      "amount",
      "currency",
      "payee"
    ]
  }
}'
PATCH/api/v1/actions/{key}

Zaktualizuj akcję

Zmień nazwę, opis, schemat danych, grantTtlSeconds lub status aktywności akcji. Klucz jest niezmienny. Zawężenie schematu danych może sprawić, że wnioski wysyłane już przez inne integracje przestaną przechodzić walidację.

Zakres
action:manage
Sukces
200
Przykład
curl -X PATCH "https://www.duereason.com/api/v1/actions/payment" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "active": false
}'
GET/api/v1/workflows

Lista przepływów

Reguły zatwierdzania skonfigurowane w organizacji: kiedy dana reguła obowiązuje (jej warunki), kto musi zatwierdzić (jej etapy) i czy zatwierdza automatycznie zamiast pytać człowieka. Od najnowszych, po jednej stronie naraz; podążaj za nextCursor (przekaż je z powrotem jako cursor), aż będzie null. Wartość warunku zachowuje swój pierwotny typ JSON (wartość logiczna pozostaje true/false, nigdy ciągiem znaków "true"), więc widać różnicę między porównaniem logicznym a tekstowym. Filtruj po akcji, by zobaczyć tylko przepływy, które jej dotyczą.

Zakres
action:read
Sukces
200
Przykład
curl -X GET "https://www.duereason.com/api/v1/workflows?action=payment" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/workflows/{id}

Pobierz przepływ

Jeden przepływ z jego warunkami, etapami i bieżącą wersją.

Zakres
action:read
Sukces
200
Błędy
not_found
Przykład
curl -X GET "https://www.duereason.com/api/v1/workflows/wfl_0192a703e5f76a8b9c0d1e2f3a4b5c6d" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/workflows

Utwórz przepływ

Dodaj regułę zatwierdzania dla akcji: jej warunki, etapy i to, czy zatwierdza automatycznie. Wymaga action:manage. Wartość warunku musi odpowiadać typowi zadeklarowanemu dla danej właściwości (właściwość logiczna wymaga true/false, nigdy ciągu „yes”). Utworzenie przepływu z autoApprove ustawionym na true wysyła e-mail do właścicieli organizacji i publikuje wiadomość na każdym kanale Slack/Teams subskrybującym security.auto_approve_enabled, więc taka samozatwierdzająca się konfiguracja nigdy nie przejdzie bez śladu.

Zakres
action:manage
Sukces
201

Wymaga Idempotency-Key

Przykład
curl -X POST "https://www.duereason.com/api/v1/workflows" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "actionKey": "payment",
  "name": "Payments over 1000",
  "priority": 10,
  "definition": {
    "conditions": [
      {
        "field": "payload.amount",
        "op": "gte",
        "value": 1000
      }
    ],
    "autoApprove": false,
    "steps": [
      {
        "name": "Finance",
        "groups": [
          "grp_finance"
        ],
        "users": [],
        "required": 1,
        "evidence": "none"
      }
    ]
  }
}'
PATCH/api/v1/workflows/{id}

Zaktualizuj przepływ

Zmień nazwę, opis, priorytet, status aktywności przepływu albo zastąp całą jego definicję (warunki, autoApprove i etapy razem, tak jak w edytorze konsoli — nie da się zmienić pojedynczego warunku osobno). Wymaga action:manage. Włączenie autoApprove powiadamia właścicieli organizacji tak samo jak jego utworzenie.

Zakres
action:manage
Sukces
200
Przykład
curl -X PATCH "https://www.duereason.com/api/v1/workflows/wfl_0192a703e5f76a8b9c0d1e2f3a4b5c6d" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "active": false
}'
DELETE/api/v1/workflows/{id}

Usuń przepływ

Usuń regułę zatwierdzania. Wnioski już złożone zachowują migawkę przepływu, który je obsłużył. Wymaga action:manage.

Zakres
action:manage
Sukces
200
Błędy
not_found
Przykład
curl -X DELETE "https://www.duereason.com/api/v1/workflows/wfl_0192a703e5f76a8b9c0d1e2f3a4b5c6d" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/approvals

Poproś o zatwierdzenie

Prosi o zatwierdzenie jednej akcji z dokładnie określonymi danymi i uzasadnieniem. O tym, kto musi zatwierdzić, decydują przepływy (workflows) organizacji. Gdy żaden nie pasuje, wniosek jest odrzucany z kodem no_workflow (w razie wątpliwości odmowa), a dane niezgodne ze schematem akcji z kodem invalid_payload. Zatwierdzający dostają e-mail, gdy otwiera się ich etap. Nie wykonuj akcji, dopóki wniosek nie zostanie zatwierdzony i nie masz jego grantu.

Zakres
approval:request
Sukces
201

Wymaga Idempotency-Key

Przykład
curl -X POST "https://www.duereason.com/api/v1/approvals" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "payment",
  "title": "Pay invoice INV-2026-118",
  "reason": "Due to the reason of: the supplier'\''s invoice is due on 10 October and matches PO-77.",
  "payload": {
    "amount": 1200,
    "currency": "EUR",
    "payee": "ACME sp. z o.o.",
    "invoice": "INV-2026-118"
  },
  "agent": {
    "name": "ap-agent",
    "model": "claude",
    "runId": "run_8812"
  },
  "context": [
    {
      "label": "Invoice",
      "url": "https://erp.example.com/invoices/INV-2026-118"
    }
  ],
  "expiresInSeconds": 86400
}'

Zamiast tego wyślij multipart/form-data: ten sam JSON żądania jako część tekstowa, plus jeden lub więcej plików. Taka sama walidacja, limity rozmiaru i skan antywirusowy jak w konsoli.

Przykład z załącznikami
curl -X POST "https://www.duereason.com/api/v1/approvals" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F 'request=<request.json;type=application/json' \
  -F files=@sbom.json
GET/api/v1/approvals

Lista wniosków o zatwierdzenie

Od najnowszych, z filtrem po statusie i akcji. Zatwierdzony wniosek zawiera grant.

Zakres
approval:read
Sukces
200
Przykład
curl -X GET "https://www.duereason.com/api/v1/approvals?status=pending&action=payment&q=invoice%20118&limit=20" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/approvals/{id}

Pobierz wniosek o zatwierdzenie

Pojedynczy wniosek z etapami, odpowiedziami, dowodami i, po zatwierdzeniu, grantem. Z parametrem wait=N (najwyżej 20) wywołanie czeka, aż wniosek się zmieni albo minie N sekund. Wynik najlepiej poznawać z webhooków (approval.approved, approval.rejected i pozostałych) albo z pętli oczekiwania w SDK i serwerze MCP, które korzystają z tego wywołania; wait to tylko udogodnienie.

Zakres
approval:read
Sukces
200
Przykład
curl -X GET "https://www.duereason.com/api/v1/approvals/apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c?wait=20" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/approvals/{id}/cancel

Anuluj wniosek o zatwierdzenie

Wycofuje oczekujący wniosek. Przez API może go anulować tylko klucz, który go utworzył; wniosek już rozstrzygnięty zwraca not_pending.

Zakres
approval:request
Sukces
200

Wymaga Idempotency-Key

Przykład
curl -X POST "https://www.duereason.com/api/v1/approvals/apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c/cancel" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
GET/api/v1/approvals/{id}/precedents

Pobierz precedensy wniosku o zatwierdzenie

Najbardziej podobne rozstrzygnięte wnioski tej samej czynności z ostatniego roku, od najwyżej ocenionych, każdy z wynikiem, osobą decydującą, jej pisemnym uzasadnieniem (obciętym do 300 znaków) i nazwami załączonych dowodów. Dodatkowo podsumowanie wszystkich rozstrzygniętych wniosków w tym okresie: liczby według wyniku i uzasadnienie ostatniego odrzucenia. Deterministyczne i lokalne: bez wywołania AI, tylko podobieństwo na podstawie opisu danych czynności oraz tytułu i uzasadnienia.

Zakres
approval:read
Sukces
200
Błędy
not_found
Przykład
curl -X GET "https://www.duereason.com/api/v1/approvals/apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c/precedents?limit=5" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/approvals/{id}/comments

Pobierz komentarze wniosku o zatwierdzenie

Wątek dyskusji pod wnioskiem, od najstarszych w ramach strony: pytanie doprecyzowujące, dodatkowy kontekst lub odpowiedź, każdy z autorem i czasem dodania. Stronicowanie typu keyset, od najnowszej strony; przekaż nextCursor z powrotem jako cursor, by pobrać stronę starszych komentarzy.

Zakres
approval:read
Sukces
200
Błędy
not_found
Przykład
curl -X GET "https://www.duereason.com/api/v1/approvals/apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c/comments?limit=20" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/approvals/{id}/comments

Dodaj komentarz do wniosku o zatwierdzenie

Dodaje wpis do wątku dyskusji pod wnioskiem, przypisany do wywołującego klucza API (nie do konkretnej osoby). Wymaga zakresu approval:request, tego samego, który służy do tworzenia i anulowania wniosków. Dodanie komentarza nigdy nie zmienia statusu wniosku. Limitowane osobno od budżetu komentarzy konsoli. Nigdy nie jest analizowane pod kątem wzmianek w formacie @[Imię](memberId), nawet jeśli treść przypadkiem zawiera taki wzorzec — tylko token wstawiony przez kompozytor konsoli oznacza prawdziwą wzmiankę.

Zakres
approval:request
Sukces
201

Wymaga Idempotency-Key

Przykład
curl -X POST "https://www.duereason.com/api/v1/approvals/apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c/comments" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "Confirmed against PO-77; the vendor matches our records."
}'
POST/api/v1/precedents/check

Sprawdź precedensy przed złożeniem wniosku

To samo wyszukiwanie podobnych, rozstrzygniętych wniosków co GET /approvals/{id}/precedents, o krok wcześniej: na podstawie czynności i danych, które zamierzasz wysłać, a nie identyfikatora istniejącego wniosku — dzięki temu agent wywołujący API bezpośrednio widzi, jak przebiegały podobne wnioski, zanim zdecyduje, o co poprosić. Opcjonalnie przyjmuje dotychczas przygotowany tytuł i uzasadnienie, by wyostrzyć sygnał podobieństwa tekstu. Wyłącznie informacyjne: nigdy nie blokuje ani nie zmienia późniejszego POST /approvals.

Zakres
approval:read
Sukces
200
Błędy
not_found

Wymaga Idempotency-Key

Przykład
curl -X POST "https://www.duereason.com/api/v1/precedents/check" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "actionKey": "payment",
  "payload": {
    "amount": 1200,
    "currency": "EUR",
    "payee": "Hosting Ltd"
  }
}'
POST/api/v1/approvals/{id}/executions

Zgłoś wykonanie

Informuje DueReason, że grant został użyty, i z jakim skutkiem. Grant musi należeć do tego wniosku i nie może być przeterminowany. Grant jest jednorazowy: drugie zgłoszenie zwraca already_executed.

Zakres
approval:request
Sukces
200

Wymaga Idempotency-Key

Przykład
curl -X POST "https://www.duereason.com/api/v1/approvals/apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c/executions" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "grant": "eyJhbGciOiJFZERTQSIsImtpZCI6Imdza18uLi4iLCJ0eXAiOiJkdWVyZWFzb24tZ3JhbnQrand0In0.eyJzdWIiOiJhcHJfLi4uIn0.c2lnbmF0dXJl",
  "outcome": "succeeded",
  "detail": "Bank transfer TX-55120"
}'

Zamiast tego wyślij multipart/form-data: ten sam JSON żądania jako część tekstowa, plus jeden lub więcej plików. Taka sama walidacja, limity rozmiaru i skan antywirusowy jak w konsoli.

Przykład z załącznikami
curl -X POST "https://www.duereason.com/api/v1/approvals/apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c/executions" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F 'request=<request.json;type=application/json' \
  -F files=@sbom.json
POST/api/v1/grants/verify

Zweryfikuj grant

Sprawdza podpis grantu, organizację i termin ważności oraz to, czy wydano go dokładnie dla tych danych. Dla wykonawców bez biblioteki JWS; pozostali weryfikują grant u siebie, kluczami organizacji spod adresu /.well-known/duereason/SLUG-ORGANIZACJI/jwks.json. Nieważny grant to nadal odpowiedź 200, z valid równym false i przyczyną.

Zakres
approval:read
Sukces
200

Wymaga Idempotency-Key

Przykład
curl -X POST "https://www.duereason.com/api/v1/grants/verify" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "grant": "eyJhbGciOiJFZERTQSIsImtpZCI6Imdza18uLi4iLCJ0eXAiOiJkdWVyZWFzb24tZ3JhbnQrand0In0.eyJzdWIiOiJhcHJfLi4uIn0.c2lnbmF0dXJl",
  "payload": {
    "amount": 1200,
    "currency": "EUR",
    "payee": "ACME sp. z o.o.",
    "invoice": "INV-2026-118"
  }
}'
GET/api/v1/approvals/{id}/receipt

Pobierz potwierdzenie decyzji

Samodzielny, podpisany zapis tego rozstrzygniętego wniosku: dane i ich skrót, wnioskujący, odpowiedzi i skróty dowodów z każdego etapu, grant (jeśli wydano) oraz zdarzenia rejestru tego wniosku. 409 not_decided, dopóki wniosek jest w toku. Format i sposoby weryfikacji — offline, za pomocą verifyReceipt() z @duereason/sdk albo pod adresem https://duereason.com/verify, bez konta DueReason — opisuje docs/duereason/receipts.md.

Zakres
approval:read
Sukces
200
Przykład
curl -X GET "https://www.duereason.com/api/v1/approvals/apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c/receipt" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/receipts

Eksportuj potwierdzenia decyzji zbiorczo

Potwierdzenie każdego rozstrzygniętego wniosku, którego decidedAt mieści się w [from, to), od najstarszych, stronicowane kursorem jak pozostałe listy. Wnioski w toku nigdy nie są uwzględniane. Każde potwierdzenie jest identyczne z tym, co zwraca GET /approvals/{id}/receipt dla danego wniosku. Zakres nie może przekraczać 92 dni; dłuższy okres pobierz kilkoma wywołaniami. Przeznaczone dla organizacji, która chce własnego, okresowego śladu audytowego (np. wszystkie potwierdzenia z kwartału) bez pobierania każdego zatwierdzenia osobno.

Zakres
approval:read
Sukces
200
Błędy
forbidden
Przykład
curl -X GET "https://www.duereason.com/api/v1/receipts?from=2026-07-01T00:00:00Z&to=2026-10-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"

Mandaty

Stałe, ograniczone i odwołalne upoważnienie: deleguj z góry fragment decyzji zatwierdzającej, aby pasujące wnioski były zatwierdzane automatycznie, mierzone i rejestrowane. Domyślnie wyłączone; włącza je właściciel lub administrator organizacji w Ustawieniach. Mandaty wystawia wyłącznie osoba w konsoli (Ustawienia > Mandaty); API tylko je odczytuje, sprawdza i odwołuje.

GET/api/v1/mandates

Lista mandatów

Stałe upoważnienia wydane przez Twoją organizację, od najnowszych. Filtruj po actionId lub activeOnly (nieodwołane i w oknie ważności).

Zakres
mandate:read
Sukces
200
Przykład
curl -X GET "https://www.duereason.com/api/v1/mandates" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/mandates/{id}

Pobierz mandat

Jeden mandat z jego ograniczeniami, limitami i wykorzystaniem w bieżącym okresie.

Zakres
mandate:read
Sukces
200
Błędy
not_found
Przykład
curl -X GET "https://www.duereason.com/api/v1/mandates/mdt_0192a6f3d4e65f8a9b0c1d2e3f4a5b6c" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/mandates/{id}/revoke

Odwołaj mandat

Działa natychmiast: żaden kolejny wniosek nie będzie już objęty tym mandatem. Odwołać może wyłącznie właściciel/administrator organizacji lub wystawca mandatu.

Zakres
mandate:revoke
Sukces
200

Wymaga Idempotency-Key

Przykład
curl -X POST "https://www.duereason.com/api/v1/mandates/mdt_0192a6f3d4e65f8a9b0c1d2e3f4a5b6c/revoke" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "SaaS seat cancelled."
}'
POST/api/v1/mandates/check

Sprawdź pokrycie mandatem

Sprawdź z wyprzedzeniem, czy taki wniosek zostałby automatycznie zatwierdzony na mocy mandatu i ile budżetu zostało, bez tworzenia wniosku i bez zużywania czegokolwiek. Używa dokładnie tej samej logiki dopasowania co POST /approvals, więc wynik tutaj i przy faktycznym zgłoszeniu nigdy się nie rozminą. Działa bezpiecznie: wyłączone mandaty, nieznana akcja lub błąd wewnętrzny zawsze dają covered: false z powodem w odpowiedzi 200, nigdy fałszywie pozytywny wynik.

Zakres
mandate:read
Sukces
200

Wymaga Idempotency-Key

Przykład
curl -X POST "https://www.duereason.com/api/v1/mandates/check" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "actionKey": "payment",
  "payload": {
    "amount": 120,
    "currency": "EUR",
    "payee": "Hosting Ltd"
  },
  "agent": {
    "name": "ap-agent"
  }
}'

Webhooki

Rejestruj, aktualizuj, wyłączaj, usuwaj i rotuj sekret endpointów, do których DueReason dostarcza zdarzenia approval.* i decision.*; przeglądaj i wysyłaj ponownie dostawy albo wyślij zdarzenie testowe. Treść, nagłówki i weryfikacja podpisów — patrz sekcja Webhooki poniżej.

GET/api/v1/webhooks

Lista endpointów webhook

Endpointy webhook Twojej organizacji, od najnowszych. Nigdy nie zawiera klucza podpisującego; jest on pokazywany tylko raz, w odpowiedzi tworzącej endpoint (albo w konsoli, przy rotacji).

Zakres
webhook:manage
Sukces
200
Przykład
curl -X GET "https://www.duereason.com/api/v1/webhooks" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/webhooks/{id}

Pobierz endpoint webhook

Jeden endpoint webhook po id: jego url, subskrybowane zdarzenia, flagę active i stan rotacji klucza podpisującego. Nigdy nie zawiera samego klucza podpisującego; jest on pokazywany tylko raz, w odpowiedzi tworzącej endpoint (albo w konsoli, przy rotacji).

Zakres
webhook:manage
Sukces
200
Błędy
not_found
Przykład
curl -X GET "https://www.duereason.com/api/v1/webhooks/whk_0192a714f6a87b9c0d1e2f3a4b5c6d7e" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/webhooks

Utwórz endpoint webhook

Rejestruje endpoint HTTPS i zdarzenia, które otrzymuje. Klucz podpisujący (whsec_...) jest wyłącznie w tej odpowiedzi; zapisz go od razu, nie da się go odczytać ponownie.

Zakres
webhook:manage
Sukces
201

Wymaga Idempotency-Key

Przykład
curl -X POST "https://www.duereason.com/api/v1/webhooks" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/duereason",
  "events": [
    "approval.approved",
    "approval.rejected"
  ]
}'
PATCH/api/v1/webhooks/{id}

Zaktualizuj endpoint webhook

Przełącza active albo zastępuje całą listę subskrybowanych zdarzeń (events, jeśli podane, zastępuje ją w całości; pomiń pole, by zostawić je bez zmian). Wyłączony endpoint nie otrzymuje nowych dostaw; te już w kolejce czekają, aż go włączysz albo wyślesz je ponownie.

Zakres
webhook:manage
Sukces
200
Przykład
curl -X PATCH "https://www.duereason.com/api/v1/webhooks/whk_0192a714f6a87b9c0d1e2f3a4b5c6d7e" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "active": false
}'
DELETE/api/v1/webhooks/{id}

Usuń endpoint webhook

Usuwa endpoint i jego historię dostaw. Nie ma cofnięcia; by znów otrzymywać zdarzenia, zarejestruj nowy endpoint.

Zakres
webhook:manage
Sukces
200
Błędy
not_found
Przykład
curl -X DELETE "https://www.duereason.com/api/v1/webhooks/whk_0192a714f6a87b9c0d1e2f3a4b5c6d7e" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/webhooks/{id}/rotate-secret

Zrotuj sekret podpisujący endpointu webhook

Natychmiast wydaje nowy sekret podpisujący. Dostawy w kolejce sprzed tego wywołania były już podpisane starym sekretem; wszystko wysłane później używa od razu nowego. Sekret zastąpiony tą rotacją jest w tej odpowiedzi i przez 24h można go jeszcze raz odczytać w konsoli, podczas przełączania weryfikacji po stronie odbiorcy; potem znika bezpowrotnie.

Zakres
webhook:manage
Sukces
200
Błędy
not_found

Wymaga Idempotency-Key

Przykład
curl -X POST "https://www.duereason.com/api/v1/webhooks/whk_0192a714f6a87b9c0d1e2f3a4b5c6d7e/rotate-secret" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
GET/api/v1/webhooks/{id}/deliveries

Lista dostaw endpointu webhook

Próby dostarczenia dla jednego endpointu, od najnowszych, łącznie z oczekującymi i nieudanymi. Można filtrować po status lub eventType. limit domyślnie 50, maksymalnie 200.

Zakres
webhook:manage
Sukces
200
Błędy
not_found
Przykład
curl -X GET "https://www.duereason.com/api/v1/webhooks/whk_0192a714f6a87b9c0d1e2f3a4b5c6d7e/deliveries?limit=20" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/webhooks/{id}/test

Wyślij zdarzenie testowe

Kolejkuje syntetyczną dostawę testową przez ten sam mechanizm co prawdziwe zdarzenie (podpis, kontrole SSRF, ponowienia), żebyś mógł potwierdzić adres URL, sekret i weryfikację podpisu, zanim nadejdzie prawdziwe zdarzenie. 412 precondition_failed na wyłączonym endpoincie.

Zakres
webhook:manage
Sukces
200

Wymaga Idempotency-Key

Przykład
curl -X POST "https://www.duereason.com/api/v1/webhooks/whk_0192a714f6a87b9c0d1e2f3a4b5c6d7e/test" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
POST/api/v1/webhooks/deliveries/{deliveryId}/redeliver

Wyślij dostawę webhook ponownie

Kolejkuje dostawę ponownie ze świeżym budżetem ponowień, zachowując jej id i treść, dzięki czemu Twój odbiorca może usuwać duplikaty na podstawie nagłówka DueReason-Delivery. 412 precondition_failed, gdy endpoint jest wyłączony.

Zakres
webhook:manage
Sukces
200

Wymaga Idempotency-Key

Przykład
curl -X POST "https://www.duereason.com/api/v1/webhooks/deliveries/dlv_0192a7210817c8a9b0c1d2e3f4a5b6c7/redeliver" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
Moduł platform-work (domyślnie wyłączony)

Te endpointy zwracają 412 precondition_failed, dopóki właściciel organizacji nie włączy modułu platform-work w Ustawieniach.

Decyzje

Rejestrowanie decyzji i prowadzenie ich przez kontrolę człowieka: wykonanie, wycofanie, pisemne uzasadnienie i przekazywanie wniosków o weryfikację.

POST/api/v1/decisions

Utwórz decyzję

Zapisuje w rejestrze decyzję dotyczącą osoby. Ograniczenie, zawieszenie i rozwiązanie zaczynają w stanie pending_human i czekają na przeszkolonego weryfikatora (art. 10 ust. 5); każdy inny rodzaj jest rejestrowany od razu. Nieznany workerRef zostaje zarejestrowany automatycznie, jeśli podano workerCountry. Decyzje zautomatyzowane muszą wskazywać aktywny system przez systemKey.

Zakres
decision:request
Sukces
201

Wymaga Idempotency-Key

Przykład
curl -X POST "https://www.duereason.com/api/v1/decisions" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "workerRef": "courier-4821",
  "workerCountry": "PL",
  "systemKey": "fraud-score",
  "type": "suspend",
  "automatedDetection": true,
  "automatedDecision": false,
  "summary": "Account suspended for 7 days in all delivery zones.",
  "facts": "Five deliveries on 28 September were confirmed 3 km or more from the drop-off point, according to the GPS trace.",
  "contractualGround": "Terms of service, section 8.2 (accurate delivery confirmation).",
  "durationDays": 7,
  "externalRef": "case-2026-0931"
}'
GET/api/v1/decisions

Lista decyzji

Decyzje w Twojej organizacji, od najnowszych, z opcjonalnym filtrem stanu lub osoby.

Zakres
decision:read
Sukces
200
Przykład
curl -X GET "https://www.duereason.com/api/v1/decisions?status=pending_human&limit=20" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/decisions/{id}

Pobierz decyzję

Pojedyncza decyzja wraz z uzasadnieniem, jeśli zostało wydane, i otwartym wnioskiem o weryfikację, jeśli istnieje. Klucze z zakresem statement:issue otrzymują też link do portalu pracownika.

Zakres
decision:read
Sukces
200
Błędy
not_found
Przykład
curl -X GET "https://www.duereason.com/api/v1/decisions/dec_0192a6c4e1f37b9d8c2e4f6a8b0c1d2e" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/decisions/{id}/enact

Wykonaj decyzję

Potwierdza, że wykonano zatwierdzoną lub zarejestrowaną decyzję. Decyzja wciąż oczekująca (pending_human) daje 409: wykonuj ją dopiero po webhooku decision.approved.

Zakres
decision:enact
Sukces
200

Wymaga Idempotency-Key

Przykład
curl -X POST "https://www.duereason.com/api/v1/decisions/dec_0192a6c4e1f37b9d8c2e4f6a8b0c1d2e/enact" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
POST/api/v1/decisions/{id}/withdraw

Wycofaj decyzję

Wycofuje decyzję oczekującą (pending_human) lub zatwierdzoną, która nie została jeszcze wykonana. Powód trafia do rejestru.

Zakres
decision:request
Sukces
200

Wymaga Idempotency-Key

Przykład
curl -X POST "https://www.duereason.com/api/v1/decisions/dec_0192a6c4e1f37b9d8c2e4f6a8b0c1d2e/withdraw" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Raised twice by the fraud pipeline; case-2026-0930 stands."
}'
POST/api/v1/decisions/{id}/statement

Wydaj uzasadnienie

Utrwala pisemne uzasadnienie (art. 11 ust. 1; art. 17 DSA) decyzji, która obowiązuje, i zwraca podpisany link do portalu dla osoby. Jeśli pracownik ma adres e-mail, DueReason wysyła mu też link. Zwraca 422, gdy decyzji brakuje faktów, podstawy albo osoby kontaktowej.

Zakres
statement:issue
Sukces
201

Wymaga Idempotency-Key

Przykład
curl -X POST "https://www.duereason.com/api/v1/decisions/dec_0192a6c4e1f37b9d8c2e4f6a8b0c1d2e/statement" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "locale": "pl"
}'
POST/api/v1/decisions/{id}/review-requests

Przekaż wniosek o weryfikację

Zapisuje, że osoba poprosiła o weryfikację w Twoim interfejsie (art. 11 ust. 2). Dwutygodniowy termin zaczyna biec teraz; dla jednej decyzji może być otwarty tylko jeden wniosek.

Zakres
decision:request
Sukces
201

Wymaga Idempotency-Key

Przykład
curl -X POST "https://www.duereason.com/api/v1/decisions/dec_0192a6c4e1f37b9d8c2e4f6a8b0c1d2e/review-requests" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "comment": "The app froze and confirmed the wrong stop."
}'

Pracownicy

Pseudonimowe dane osób, których dotyczą decyzje.

PUT/api/v1/workers/{externalRef}

Utwórz lub zaktualizuj pracownika

Tworzy osobę pod Twoim pseudonimowym identyfikatorem albo aktualizuje przesłane pola. Powtórzenie tego samego żądania nie zmienia danych. Dla pracowników, których dane usunięto, zwraca 409.

Zakres
worker:write
Sukces
200
Błędy
conflict
Przykład
curl -X PUT "https://www.duereason.com/api/v1/workers/courier-4821" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "country": "PL",
  "status": "self_employed",
  "activity": "regular",
  "locale": "pl",
  "contactEmail": "courier-4821@example.com"
}'
GET/api/v1/workers/{externalRef}

Pobierz pracownika

Dane pracownika o podanym pseudonimowym identyfikatorze.

Zakres
worker:read
Sukces
200
Błędy
not_found
Przykład
curl -X GET "https://www.duereason.com/api/v1/workers/courier-4821" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"

Systemy

Rejestr zautomatyzowanych systemów monitorowania i podejmowania decyzji (art. 9).

GET/api/v1/systems

Lista systemów

Aktywne i robocze wpisy rejestru zautomatyzowanych systemów z ich bieżącą wersją. Decyzja może wskazywać wyłącznie aktywny system.

Zakres
system:read
Sukces
200
Przykład
curl -X GET "https://www.duereason.com/api/v1/systems" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"

Rejestr

Łańcuch skrótów, w którym zapisano wszystko, co działo się z każdą decyzją.

GET/api/v1/decisions/{id}/events

Lista zdarzeń decyzji w rejestrze

Wszystkie zdarzenia zapisane dla decyzji, w kolejności łańcucha, ze skrótami łączącymi każde z poprzednim.

Zakres
decision:read
Sukces
200
Błędy
not_found
Przykład
curl -X GET "https://www.duereason.com/api/v1/decisions/dec_0192a6c4e1f37b9d8c2e4f6a8b0c1d2e/events" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/ledger/head

Pobierz czoło łańcucha

Ostatnia pozycja i skrót łańcucha decyzji platform-work Twojej organizacji oraz wynik jego ostatniej pełnej weryfikacji. Zapisuj czoło w systemie, nad którym masz kontrolę: późniejsze czoło, które go nie przedłuża, oznacza, że łańcuch został przepisany.

Zakres
decision:read
Sukces
200
Przykład
curl -X GET "https://www.duereason.com/api/v1/ledger/head" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/ledger/approvals/head

Pobierz czoło łańcucha zatwierdzeń

Ostatnia pozycja i skrót łańcucha zatwierdzeń Twojej organizacji (każdy wniosek, odpowiedź, zatwierdzenie, wykonanie i anulowanie) oraz wynik jego ostatniej pełnej weryfikacji. Zapisuj czoło w systemie, nad którym masz kontrolę: późniejsze czoło, które go nie przedłuża, oznacza, że łańcuch został przepisany.

Zakres
approval:read
Sukces
200
Przykład
curl -X GET "https://www.duereason.com/api/v1/ledger/approvals/head" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"

Zgłoszenia

Dodatek DSA: zgłoszenia nielegalnych treści na podstawie art. 16 rozporządzenia (UE) 2022/2065. Gdy dodatek jest wyłączony, te punkty końcowe zwracają 412 z kodem precondition_failed.

POST/api/v1/notices

Przekaż zgłoszenie

Zapisuje zgłoszenie rzekomo nielegalnych treści, które osoba wysłała przez Twój interfejs (art. 16 ust. 1). Zgłoszenie musi zawierać to, czego wymaga art. 16 ust. 2: lokalizację treści, uzasadnione wyjaśnienie, imię i nazwisko oraz adres e-mail zgłaszającego (chyba że csamExemption ma wartość true dla materiałów przedstawiających niegodziwe traktowanie dzieci w celach seksualnych, z kategorią STATEMENT_CATEGORY_PROTECTION_OF_MINORS) oraz oświadczenie o dobrej wierze. Niekompletne zgłoszenie daje 422, a details.problems wymienia każdy brak. Jeśli podano adres e-mail, DueReason wysyła potwierdzenie otrzymania (art. 16 ust. 4) w języku zgłoszenia, a później decyzję ze środkami odwoławczymi (art. 16 ust. 5). Zgłoszenia rozstrzygają ludzie w konsoli.

Zakres
notice:write
Sukces
201

Wymaga Idempotency-Key

Przykład
curl -X POST "https://www.duereason.com/api/v1/notices" \
  -H "Authorization: Bearer $DUEREASON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "contentUrls": [
    "https://example-platform.eu/listings/88213"
  ],
  "contentDescription": "Listing titled '\''Original designer handbag, new'\''.",
  "explanation": "The handbag is a counterfeit of a registered EU trade mark: the logo and serial number do not match the manufacturer'\''s.",
  "category": "STATEMENT_CATEGORY_INTELLECTUAL_PROPERTY_INFRINGEMENTS",
  "notifierName": "Anna Kowalska",
  "notifierEmail": "anna.kowalska@example.com",
  "goodFaith": true,
  "locale": "pl"
}'
GET/api/v1/notices/{id}

Pobierz zgłoszenie

Pojedyncze zgłoszenie ze statusem, decyzją po jej podjęciu, powiązaną decyzją w rejestrze wobec osoby, której dotyczy (jej uzasadnienie jest uzasadnieniem z art. 17), oraz informacją, kiedy wysłano zgłaszającemu potwierdzenie i decyzję.

Zakres
notice:read
Sukces
200
Przykład
curl -X GET "https://www.duereason.com/api/v1/notices/ntc_0192a6d2b7c84e1f9a3b5c7d9e1f3a5b" \
  -H "Authorization: Bearer $DUEREASON_API_KEY"

Webhooki

Właściciele i administratorzy dodają endpointy w sekcji Ustawienia, Webhooki i wybierają zdarzenia, które chcą otrzymywać, albo * dla wszystkich. Każde zdarzenie jest wysyłane metodą POST jako JSON na Twój endpoint HTTPS. Sekret do podpisów (whsec_...) jest pokazywany raz, przy tworzeniu endpointu lub zmianie sekretu.

Endpoint subskrybujący jawną listę zdarzeń nigdy nie zaczyna automatycznie otrzymywać typu zdarzenia dodanego do produktu później; listę trzeba wtedy samodzielnie zaktualizować o nowy typ. Wybierz zamiast tego *, aby subskrybować wszystkie obecne i przyszłe typy zdarzeń bez ponownej aktualizacji endpointu.

Treść zawiera id (identyfikator zdarzenia w rejestrze), type, createdAt i data. Dla zdarzeń approval.* pole data zawsze zawiera requestId i seq; dla zdarzeń decision.* (moduł platform-work) data zawiera zamiast tego decisionId i seq; a także pola danego zdarzenia.

approval.approved
{
  "id": "ape_0192a701b2c3d4e5f6a7b8c9d0e1f2a3",
  "type": "approval.approved",
  "createdAt": "2026-10-02T09:41:12.204Z",
  "data": {
    "requestId": "apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c",
    "seq": 3,
    "grantId": "grt_0192a6f8a1b23c4d5e6f7a8b9c0d1e2f",
    "approvers": [
      {
        "id": "usr_0192a6d2b3c4d5e6f7a8b9c0d1e2f3a4",
        "name": "Rita Nowak"
      }
    ],
    "auto": false,
    "mandateId": null
  }
}
approval.mandate.threshold_reached (zdarzenie mandatu na poziomie organizacji: brak requestId/seq)
{
  "id": "dlv_0192a7b4c5d6e7f8a9b0c1d2e3f4a5b6",
  "type": "approval.mandate.threshold_reached",
  "createdAt": "2026-10-06T08:03:19.880Z",
  "data": {
    "mandateId": "mdt_0192a6c0b1c2d3e4f5a6b7c8d9e0f1a2",
    "actionKey": "refunds.issue",
    "thresholdPercent": 80,
    "crossed": [
      {
        "kind": "cumulative",
        "pct": 83.5
      }
    ]
  }
}
decision.review_reversed (moduł platform-work)
{
  "id": "evt_0192a7a1b2c3d4e5f6a7b8c9d0e1f2a4",
  "type": "decision.review_reversed",
  "createdAt": "2026-10-05T14:22:47.512Z",
  "data": {
    "decisionId": "dec_0192a76e1f2a3b4c5d6e7f8a9b0c1d2e",
    "seq": 6,
    "reviewId": "rev_0192a7901a2b3c4d5e6f7a8b9c0d1e2f",
    "resolution": "Lowered-ranking penalty did not account for the worker's active appeal window; reversed.",
    "onTime": true
  }
}

Nagłówki

NagłówekWartość
DueReason-EventRodzaj zdarzenia, np. decision.approved.
DueReason-DeliveryIdentyfikator dostarczenia. Ponowienia i ręczne ponowne wysyłki używają tego samego: na jego podstawie usuwaj duplikaty.
DueReason-SignatureDwie części oddzielone przecinkiem: t, czas uniksowy podpisu, oraz v1, szesnastkowy HMAC-SHA256 z t, kropki i surowej treści, z Twoim sekretem jako kluczem.
User-AgentDueReason-Webhooks/1

Zdarzenia

* subskrybuje endpoint na wszystkie obecne i przyszłe typy zdarzeń, zarówno approval.*, jak i decision.*; samo nigdy nie jest dostarczanym typem. Przycisk "Wyślij zdarzenie testowe" w konsoli wysyła zamiast tego syntetyczne zdarzenie test, w takim samym kształcie koperty jak zdarzenie, które naśladuje -- type nigdy nie jest test przy prawdziwej dostawie, a test nigdy nie da się subskrybować.

ZdarzenieOpisPola danych poza tymi z approval.approved
approval.requestedUtworzono wniosek o zatwierdzenie.action, title, reason, payloadHash, agent, context, requester, workflow, expiresAt, attachments
approval.step_openedOtworzył się etap, a jego zatwierdzający dostali powiadomienie.step, name, required, evidence
approval.respondedZatwierdzający odpowiedział; dane zawierają werdykt, komentarz i skróty plików z dowodami.responseId, step, verdict, comment, approver, evidence
approval.approvedWniosek zatwierdzono. Pobierz go, aby dostać grant, i działaj tylko z ważnym grantem.Taki sam kształt jak approval.approved powyżej (requestId, seq, grantId, approvers, auto, mandateId).
approval.rejectedZatwierdzający odrzucił wniosek. Nie wykonuj akcji.step, approver, comment
approval.expiredNikt nie rozstrzygnął wniosku przed upływem terminu. Nie wykonuj akcji.expiresAt
approval.cancelledWnioskujący anulował wniosek.by, reason, decisionWithdrawn
approval.executedWykonawca zgłosił użycie grantu. Dane zawierają przedstawiony grant — zapis tego, co upoważniło wykonanie.outcome, detail, grant, evidence
approval.mandate.usedWniosek został zatwierdzony automatycznie na podstawie stałego mandatu, bez bieżącej decyzji.consumes
approval.mandate.issuedWydano mandat, przyznając stałe uprawnienie do automatycznego zatwierdzania pasujących wniosków.actionKey, subject, issuerId, reason
approval.mandate.revokedMandat został odwołany i nie zatwierdza już automatycznie żadnego wniosku.actionKey, revokedBy, reason
approval.mandate.threshold_reachedMandat przekroczył ustawiony próg alertu o użyciu.actionKey, thresholdPercent, crossed
approval.step_reminder_sentNikt nie odpowiedział na otwarty etap; jego osoby akceptujące zostały powiadomione ponownie.step
approval.step_escalatedNikt nie odpowiedział jeszcze dłużej; powiadomiono też grupę eskalacyjną ścieżki.step, groupId
Moduł platform-work (domyślnie wyłączony)
ZdarzenieOpisPola danych poza tymi z approval.approved
decision.requestedUtworzono decyzję.decisionId, requestedAt, type, status, workerRef, systemKey, systemVersion, automatedDetection, automatedDecision, summary, facts, legalGround, contractualGround, durationDays, externalRef
decision.approvedPrzeszkolony weryfikator zatwierdził decyzję objętą kontrolą. Możesz ją teraz wykonać.decisionId, note, reviewer
decision.rejectedPrzeszkolony weryfikator odrzucił decyzję objętą kontrolą. Nie wykonuj jej.decisionId, note, reviewer
decision.enactedPotwierdzono, że decyzja została wykonana.decisionId
decision.withdrawnDecyzję wycofano, zanim zaczęła obowiązywać.decisionId, reason
decision.statement_issuedWydano uzasadnienie.decisionId, statementId, contactName, contactEmail, reviewAvailable
decision.review_requestedOsoba poprosiła o weryfikację; zaczął biec dwutygodniowy termin.decisionId, reviewId, channel, dueAt
decision.review_upheldWeryfikacja potwierdziła decyzję.decisionId, reviewId, resolution, onTime
decision.review_reversedWeryfikacja uchyliła decyzję. Cofnij środek i zapisz naprawienie.decisionId, reviewId, resolution, onTime
decision.remediedPo uchyleniu decyzję naprawiono lub przyznano rekompensatę.decisionId, reviewId, remedy, note

Weryfikacja podpisów

Zweryfikuj go funkcją verifyWebhookSignature z @duereason/sdk, zamiast samodzielnie liczyć HMAC-SHA256: przekaż sekret swojego endpointu, surową treść żądania i nagłówek, a funkcja sprawdzi podpis w stałym czasie i odrzuci znaczniki czasu starsze niż pięć minut, aby zapobiec powtórzeniom.

Node.js
import { verifyWebhookSignature } from "@duereason/sdk";
import express from "express";

const app = express();

// Keep the raw bytes: a re-serialized object would not match the signature.
app.post("/webhooks/duereason", express.raw({ type: "application/json" }), (req, res) => {
  const body = req.body.toString("utf8");
  const header = req.get("DueReason-Signature") ?? "";
  if (!verifyWebhookSignature(process.env.DUEREASON_WEBHOOK_SECRET, body, header)) {
    return res.status(400).end();
  }
  const event = JSON.parse(body);
  // Retries reuse DueReason-Delivery: skip ids you have already handled.
  if (event.type === "approval.approved") {
    // Now, and only now, run the business logic this request gated.
  }
  res.status(204).end();
});
Next.js (App Router)
// app/api/webhooks/duereason/route.ts
import { verifyWebhookSignature } from "@duereason/sdk";

export async function POST(request: Request) {
  const body = await request.text(); // raw bytes -- do not call request.json() first
  const header = request.headers.get("DueReason-Signature") ?? "";
  if (!verifyWebhookSignature(process.env.DUEREASON_WEBHOOK_SECRET!, body, header)) {
    return new Response(null, { status: 400 });
  }
  const event = JSON.parse(body);
  // Retries reuse DueReason-Delivery: skip ids you have already handled.
  if (event.type === "approval.approved") {
    // Now, and only now, run the business logic this request gated.
  }
  return new Response(null, { status: 204 });
}

Nie używasz Node? Przetestowany port funkcji verifyWebhookSignature na Pythona -- to samo parsowanie nagłówka, okno tolerancji i porównanie w stałym czasie, tylko biblioteka standardowa -- leży w drzewie źródłowym SDK jako duereason/sdk/examples/python/verify_webhook_signature.py, obok przykładu weryfikacji grantu w Pythonie.

Dostarczanie i ponowienia

Każda odpowiedź 2xx w ciągu 10 sekund oznacza dostarczenie. W pozostałych przypadkach wysyłka jest ponawiana, łącznie do 8 prób: pierwsza przerwa trwa 30 sekund i za każdym razem się podwaja, ale nie przekracza 6 godzin. Przekierowania nie są obsługiwane. Po ostatniej próbie dostarczenie jest oznaczane jako nieudane; możesz wysłać je ponownie z konsoli.

Odpowiedź inna niż 2xx jest ponawiana tak samo jak przekroczenie czasu lub błąd połączenia -- również odpowiedzi 4xx, inaczej niż u wielu innych dostawców webhooków, którzy przy 4xx przestają ponawiać. Jedyny błąd, który przerywa ponawianie od razu, bez przejścia przez cały harmonogram, to sytuacja, w której nie da się odszyfrować sekretu podpisującego endpointu; wszystko inne, także adres URL, który teraz nie przechodzi walidacji wychodzącej, nadal jest ponawiane według powyższego harmonogramu.

Obsłuż żądanie asynchronicznie i odpowiedz 2xx w ciągu 10-sekundowego limitu czasu: handler, który blokuje dłużej, wygląda tak samo jak martwy endpoint, wywołuje ponowienie i może ostatecznie dostarczyć to samo zdarzenie dwukrotnie, gdy wolna odpowiedź w końcu dotrze. DueReason-Delivery pozostaje takie samo przy każdym ponowieniu tej samej logicznej dostawy, więc deduplikuj na jego podstawie niezależnie od liczby prób.

Gdy 5 kolejnych dostaw do endpointu wyczerpie swoje próby ponowienia, właściciele i administratorzy organizacji dostają jeden e-mail w tej sprawie -- a nie jeden na próbę -- z odnośnikiem do Ustawienia > Webhooki; udana dostawa od razu resetuje licznik.

Przychodzące: zgłoszenia i pull requesty GitHub

Powyższe webhooki to DueReason informujące Twoje systemy o zatwierdzeniu. Istnieje też kierunek przeciwny: oznaczone etykietą zgłoszenie lub pull request na GitHubie może automatycznie otworzyć wniosek o zatwierdzenie w DueReason. Dodaj endpoint w Ustawienia > Integracje > Webhooki przychodzące, a następnie wklej adres URL webhooka i własny sekret w ustawieniach webhooka repozytorium na GitHubie (typ treści application/json). DueReason weryfikuje podpis HMAC-SHA256 GitHuba na surowej treści żądania, zanim podejmie jakiekolwiek działanie, a ponowione dostarczenie (ten sam identyfikator X-GitHub-Delivery) nigdy nie otwiera drugiego wniosku.

Skonfiguruj endpointy przychodzące w Ustawienia > Integracje > Webhooki przychodzące.

Self-hosting

Chcesz uruchomić DueReason samodzielnie? Jedna baza Postgres i jeden obraz Dockera (web, worker i migrator) dają działającą instancję w trzech poleceniach, bez etapu budowania.

bash
curl -fsSL https://duereason.com/self-host/quickstart.sh -o quickstart.sh
chmod +x quickstart.sh && ./quickstart.sh
docker compose pull && docker compose up -d

Wdrożenia self-hosted działają na licencji Elastic License 2.0: możesz uruchamiać, czytać i modyfikować kod, ale nie możesz oferować go innym jako usługę hostowaną lub zarządzaną ani obchodzić mechanizmu klucza licencyjnego.