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).
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.
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.
Poczekaj na webhook approval.approved albo approval.rejected, albo odpytuj GET /approvals/{id}?wait=N. Nigdy nie działaj, zanim wniosek zostanie zatwierdzony.
Zweryfikuj grant zwrócony przez POST /grants/verify, zanim na nim polegasz, albo sprawdź jego podpis samodzielnie, kluczami organizacji (JWKS).
Wykonaj zatwierdzone działanie, a potem zgłoś, co się stało, przez POST /approvals/{id}/executions. Grant jest jednorazowy.
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.
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
Zakres
Pozwala
approval:request
Proszenie o zatwierdzenie, wycofywanie własnych oczekujących wniosków i zgłaszanie wyniku po użyciu grantu.
approval:read
Odczyt wniosków, odpowiedzi i zgód; weryfikacja zgód.
action:read
Odczyt akcji, o których zatwierdzenie można prosić, i schematów ich danych.
action:manage
Tworzenie, 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:read
Odczyt mandatów i ich wykorzystania.
mandate:revoke
Odwołanie mandatu wystawionego przez Twoją organizację.
webhook:manage
Tworzenie i listowanie endpointów webhook oraz odczyt ich klucza podpisującego jednorazowo, przy tworzeniu.
Moduł platform-work (domyślnie wyłączony)
Zakres
Pozwala
decision:read
Odczyt decyzji, ich zdarzeń w rejestrze i czoła łańcucha.
decision:request
Tworzenie i wycofywanie decyzji, przekazywanie wniosków o weryfikację.
decision:enact
Potwierdzanie, że decyzja została wykonana.
statement:issue
Wydawanie uzasadnień i otrzymywanie linków do portalu pracownika.
worker:read
Odczyt danych pracowników.
worker:write
Tworzenie i aktualizacja danych pracowników.
system:read
Odczyt rejestru zautomatyzowanych systemów.
notice:read
Odczyt zgłoszeń DSA (dodatek DSA).
notice:write
Przekazywanie 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łówek
Znaczenie
RateLimit-Limit
Limit dla bieżącego okna: 600.
RateLimit-Remaining
Liczba żądań pozostałych w bieżącym oknie.
RateLimit-Reset
Liczba 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
}
}
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.
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"
}
]
}
}
Kod
Status
Znaczenie
malformed_json
400
Treść żądania nie jest poprawnym JSON-em.
idempotency_key_required
400
Żądanie POST bez nagłówka Idempotency-Key albo z nagłówkiem dłuższym niż 200 znaków.
unauthorized
401
Klucz API jest brakujący, błędnie sformatowany, wygasł lub został unieważniony.
payment_required
402
Subskrypcja 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_scope
403
Klucz nie ma zakresu wymaganego przez endpoint; wskazuje go details.requiredScope.
forbidden
403
Ta czynność w ogóle nie jest dostępna dla klucza API.
not_found
404
W Twojej organizacji nie ma takiego zasobu. Identyfikatory innej organizacji również dają 404.
conflict
409
Stan decyzji na to nie pozwala, na przykład wykonanie decyzji wciąż oczekującej (pending_human), albo externalRef jest już zajęty.
not_pending
409
Stan wniosku na to nie pozwala: anulowanie wniosku już rozstrzygniętego albo zgłoszenie wykonania wniosku, który nie został zatwierdzony.
not_decided
409
Wniosek nie został jeszcze rozstrzygnięty; potwierdzenie powstaje, gdy zostanie zaakceptowany, odrzucony, wygaśnie lub zostanie anulowany.
already_responded
409
Ta osoba już odpowiedziała na wniosek (tylko w konsoli).
already_executed
409
Wykonanie z tym grantem zostało już zgłoszone; grant jest jednorazowy.
idempotency_key_in_use
409
Żądanie z tym samym Idempotency-Key jest jeszcze przetwarzane.
precondition_failed
412
Najpierw 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_large
413
Treść żądania przekracza 256 KB.
unsupported_media_type
415
Treść żądania nie została wysłana jako application/json.
invalid
422
Żądanie nie przeszło walidacji; details.issues wymienia wszystkie problemy.
no_workflow
422
Do wniosku nie pasuje żaden aktywny przepływ akcji, więc nie można go zatwierdzić. Nic nie zostało utworzone.
invalid_payload
422
Dane (payload) nie spełniają schematu akcji; details.problems wymienia przyczyny.
idempotency_key_reused
422
Ten Idempotency-Key został już użyty dla innego żądania.
rate_limited
429
Ponad 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.
internal
500
Wystąpił błąd po naszej stronie. Ponowienie z tym samym Idempotency-Key jest bezpieczne.
grants_unavailable
503
Wniosek jest zatwierdzony, ale jego grantu nie da się teraz podpisać z powodu problemu z konfiguracją po naszej stronie. Spróbuj ponownie później.
scanner_unavailable
503
Plikó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.
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.
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ę.
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ą.
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.
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.
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.
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.
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.
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.
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.
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ę.
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.
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.
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.
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ą.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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ę.
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.
{
"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łówek
Wartość
DueReason-Event
Rodzaj zdarzenia, np. decision.approved.
DueReason-Delivery
Identyfikator dostarczenia. Ponowienia i ręczne ponowne wysyłki używają tego samego: na jego podstawie usuwaj duplikaty.
DueReason-Signature
Dwie 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-Agent
DueReason-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ć.
Osoba poprosiła o weryfikację; zaczął biec dwutygodniowy termin.
decisionId, reviewId, channel, dueAt
decision.review_upheld
Weryfikacja potwierdziła decyzję.
decisionId, reviewId, resolution, onTime
decision.review_reversed
Weryfikacja uchyliła decyzję. Cofnij środek i zapisz naprawienie.
decisionId, reviewId, resolution, onTime
decision.remedied
Po 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.
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.