API i webhooki

Gdzie to znaleźć

Jeśli dokumenty w Twoim biurze powstają gdzieś poza DocuTract, ten system może komunikować się z nami bezpośrednio. Otwórz menu z Twoim adresem w prawym górnym rogu i wybierz Integracje: tam wystawia się token, którym Twój system się z nami łączy, i tam dodajesz adres, na który informujemy o gotowych dokumentach.

Ekran zaczyna się od gotowych połączeń z CRM (Integracje z CRM); opisane tutaj tokeny i webhooki są niżej, w sekcji API i webhooki.

Token

Naciśnij Utwórz token, nadaj mu nazwę, którą później rozpoznasz (żeby wiedzieć, który system go używa), i zaznacz, co wolno mu robić: odczytywać szablony, tworzyć dokumenty, pracować ze sprawami.

Sam token jest pokazywany raz, zaraz po utworzeniu: przechowujemy tylko jego skrót (hash), więc ponowne pokazanie go jest niemożliwe nawet dla nas. Skopiuj go od razu do ustawień swojego systemu.

Lista pokazuje pierwsze znaki każdego tokenu, jego uprawnienia i to, kiedy był ostatnio używany. Unieważnij natychmiast wyłącza token; zapis o nim pozostaje, więc widać, że istniał i kiedy przestał działać.

Co potrafi API

Twój system może:

• otworzyć sprawę i przesłać do niej skany;
• utworzyć dokument z szablonu z już wypełnionymi wartościami;
• zapytać, na jakim etapie jest dokument;
• pobrać wszystkie wartości wraz ze skanem, z którego każda została odczytana;
• otrzymać krótkotrwały link do gotowego pliku.

Pełny opis każdego adresu i pola jest generowany z samego kodu i publikowany otwarcie: opis API.

Webhooki

Zamiast pytać nas, czy dokument jest gotowy, podaj nam adres, a my do Ciebie napiszemy. Dodaj go w sekcji Webhooki i zaznacz zdarzenia: dokument gotowy, błąd dokumentu, sprawa gotowa, wykryto rozbieżność, klient przesłał plik.

Każde żądanie jest podpisane nagłówkiem X-DocuTract-Signature, a sekret do weryfikacji podpisu jest pokazywany raz, tak jak token. Twój system musi sprawdzić podpis i odpowiedzieć kodem 2xx. Jeśli odpowie czymkolwiek innym lub nie odpowie wcale, próbujemy ponownie: po minucie, po pięciu, po pół godzinie, po dwóch godzinach i po dziesięciu, a potem przestajemy.

Gdy coś nie dotarło

Przycisk Dostarczenia pokazuje dziennik: jakie zdarzenie wysłaliśmy, kiedy, ile razy, jaki kod odpowiedzi wrócił i początek treści odpowiedzi. To odpowiedź na „nasz system nic nie dostał”: czarno na białym widać, że o 14:12 cztery razy odpowiedział kodem 500.

Wyślij test wysyła na adres ping od razu, bez czekania na prawdziwe zdarzenie, dzięki czemu odbiornik można skonfigurować, zanim przejdzie przez niego jakakolwiek praca. Ponów przy nieudanym dostarczeniu natychmiast wykonuje jeszcze jedną próbę.

Zapier, Make i n8n

Platformy no-code (usługi, w których integrację składa się bez programowania) same subskrybują nasze zdarzenia przez część API dla REST hooks, więc nikt nie musi kopiować ich adresów do DocuTract. Daj platformie token z uprawnieniami webhooks:read i webhooks:write oraz tymi, których potrzebują jej akcje (na przykład templates:read i documents:write).

• POST /api/v1/hooks z {"event": "document.ready", "target_url": "https://…"} subskrybuje adres na jedno zdarzenie. Odpowiedź zawiera id subskrypcji i, jednorazowo, jej secret do podpisu.
• GET /api/v1/hooks pokazuje subskrypcje utworzone w ten sposób; DELETE /api/v1/hooks/{id} usuwa jedną z nich.
• GET /api/v1/hooks/events wymienia zdarzenia: document.ready, document.failed, case.ready, finding.raised, intake.uploaded.
• GET /api/v1/hooks/samples/{event} zwraca przykładową treść, którą platforma pokazuje w swoim „wyzwalaczu testowym”, zanim wydarzy się prawdziwe zdarzenie.

Subskrypcja to zwykły adres webhooka: tak samo podpisywany, ponawiany i zapisywany w dzienniku, i widoczny na liście Webhooki. Przestaje działać, gdy token, który ją utworzył, zostanie unieważniony lub wygaśnie, albo gdy platforma odpowie na dostarczenie kodem 410 Gone.

Tak wygląda document.ready:

{
  "document_id": "00000000-0000-4000-8000-000000000001",
  "reference": "DOC-26-0001",
  "template_id": "00000000-0000-4000-8000-000000000002",
  "template_version": 1,
  "event": "document.ready",
  "occurred_at": "2026-01-15T10:30:00+00:00"
}

a tak case.ready:

{
  "case_id": "00000000-0000-4000-8000-000000000003",
  "title": "Sample case",
  "documents": [
    { "id": "00000000-0000-4000-8000-000000000001", "reference": "DOC-26-0001" }
  ],
  "event": "case.ready",
  "occurred_at": "2026-01-15T10:30:00+00:00"
}

Pola szablonu

GET /api/v1/templates/{id}/fields (uprawnienie templates:read) pokazuje, czego potrzebuje szablon: key każdego pola (według niego podaje się values w POST /api/v1/documents), jego label, skąd jest wypełniane, oraz fillable, równe false dla pola, które DocuTract wypełnia sam, na przykład daty. Formularz w Zapier lub Make powstaje z tej listy, więc zawsze odpowiada szablonowi w jego obecnej postaci.

Wyszukiwanie

Kilka wywołań istnieje po to, by system lub platforma no-code znalazły to, czego potrzebują, bez zgadywania:

• GET /api/v1/me (bez uprawnienia) zwraca obszar roboczy, do którego należy token, jego plan oraz nazwę i uprawnienia samego tokenu. To najprostszy sposób, by sprawdzić, że token działa.
• GET /api/v1/documents (uprawnienie documents:read) pokazuje dokumenty, najnowsze najpierw. Zawęzisz listę parametrami reference (dokładny numer DOC-…), status lub template_id; limit to maksymalnie 100, domyślnie 25.
• GET /api/v1/cases (uprawnienie cases:read) pokazuje najnowsze sprawy, opcjonalnie tylko z jednym status, z tym samym limit. Każda sprawa ma teraz też pole created_at.
• GET /api/v1/case-types (uprawnienie cases:read) wymienia typy spraw, z których można otworzyć sprawę.
• GET /api/v1/templates?name=… zostawia tylko szablony, których nazwa zawiera ten tekst, bez względu na wielkość liter.

Stronicowania celowo nie ma: te listy służą do znajdowania najnowszych pozycji, a nie do eksportu całego obszaru roboczego.

Który plan

API i webhooki są częścią planu Team. W każdym innym planie już utworzone tokeny i adresy pozostają widoczne i można je unieważnić, ale nowe nie są wystawiane, a wywołania z tokenem nie są już obsługiwane. Porównaj plany na stronie cennika.