Obieg dokumentów API

API obiegu dokumentów umożliwia przesyłanie plików PDF, uruchamianie procesów z maksymalnie 5 odbiorcami, sprawdzanie ich postępu i pobieranie kolejnych wersji dokumentu. Powiadomienia o zdarzeniach można odbierać przez webhooki.

Spis treści

• Dostęp i autoryzacja
• Endpointy
• Przesłanie PDF
• Tworzenie procesu
• Odbiorcy i zatwierdzanie
• Wiadomości i PIN
• Szczegóły i statusy procesu
• Lista procesów
• Pobieranie dokumentów
• Ważność i przechowywanie
• Błędy i ponawianie żądań

Dostęp i autoryzacja

Bazowy adres API:

https://api.sare.pl/ext/doc-flow

Konto musi mieć włączony moduł "Obieg dokumentów". Klucz integracji i sekret są dostępne w ustawieniach tego modułu w panelu SARE. Do każdego żądania należy dodać nagłówek:

Authorization: Bearer <integrationKey>:<secret>

Uwaga

Dane dostępowe należy przechowywać po stronie serwera. Nie umieszczaj ich w kodzie frontendowym, adresie URL ani logach. Wygenerowanie nowego sekretu unieważnia poprzedni.

Limity

Każdy z poniższych endpointów ma limit 30 żądań na 60 sekund, liczony dla adresu IP. Po przekroczeniu limitu API zwraca 429.

Endpointy

Ścieżki w tabeli są względne wobec bazowego adresu API.

Metoda	Ścieżka	Zastosowanie
POST	/uploads	Przesłanie PDF i uzyskanie uploadId
POST	/processes	Utworzenie procesu
GET	/processes/{id}	Szczegóły i postęp procesu
GET	/processes	Lista procesów z filtrowaniem
GET	/processes/{id}/documents/current/download	Pobranie aktualnego dokumentu
GET	/processes/{id}/documents/versions/{version}/download	Pobranie wybranej wersji dokumentu

Publiczne API nie udostępnia edycji, uruchamiania szkiców, wstrzymywania ani anulowania procesów. Te operacje wykonuje się w panelu. Adres webhooka i rodzaje zdarzeń również ustawia się w panelu, poza żądaniem tworzącym proces.

Przesłanie PDF

POST /uploads przyjmuje multipart/form-data z jednym polem plikowym file.

• obsługiwany jest wyłącznie PDF z rozszerzeniem .pdf i typem application/pdf, o rozmiarze do 20 MiB (20 971 520 bajtów)
• plik przechodzi walidację zawartości i kontrolę bezpieczeństwa; zaszyfrowane PDF-y oraz pliki z niedozwoloną aktywną zawartością lub osadzonymi załącznikami są odrzucane
• odpowiedź 201 zawiera uploadId, potrzebne do utworzenia procesu
• upload jest jednorazowy i ważny przez 24 godziny; dokładny termin znajduje się w validUntil

curl -X POST 'https://api.sare.pl/ext/doc-flow/uploads' \
  -H 'Authorization: Bearer <integrationKey>:<secret>' \
  -F 'file=@./document.pdf;type=application/pdf'

Przykładowa odpowiedź:

{
  "uploadId": "dfu_t1_exampleUpload",
  "fileName": "document.pdf",
  "mimeType": "application/pdf",
  "sizeBytes": 123456,
  "sha256": "bc0e83603ea8596cbd473e292981e3e7f93ba626f8f3eb858857bc767f13e6c5",
  "validUntil": "2030-07-28T10:00:00.000Z"
}

Identyfikatory i daty w przykładach są poglądowe. W kolejnych żądaniach używaj wartości otrzymanych z API. sha256 identyfikuje zawartość zapisanego pliku.

Tworzenie procesu

POST /processes przyjmuje JSON i zwraca 201 ze szczegółami utworzonego procesu. Przekazanie odbiorców uruchamia obieg i zleca wysyłkę zaproszeń do aktywnych kroków. Samo przyjęcie żądania nie potwierdza doręczenia wiadomości.

Zapisz poniższy przykład jako process.json, podmień document.uploadId, dane nadawcy i odbiorcy, a następnie wykonaj żądanie:

{
  "referenceId": "ref_example_2030_0001",
  "externalId": "case-2030-0001",
  "name": "Umowa - Jan Kowalski",
  "description": "Akceptacja dokumentu",
  "sourceSystem": "crm",
  "expiresAt": "2030-08-10T12:00:00.000Z",
  "mode": "sequential",
  "fileAccessMode": "pin",
  "approvalMode": "button_only",
  "pinDeliveryChannel": "email",
  "includeSignatureCard": true,
  "sealingEnabled": false,
  "sendFinalDocumentToAllRecipients": false,
  "showCompletedSigners": false,
  "sender": {
    "name": "Biuro obsługi",
    "email": "[email protected]"
  },
  "emailSubject": "Dokument do akceptacji",
  "emailPreheader": "Zapoznaj się z dokumentem i potwierdź jego odbiór.",
  "document": {
    "uploadId": "dfu_t1_exampleUpload"
  },
  "recipients": [
    {
      "key": "step_1",
      "name": "Jan Kowalski",
      "email": "[email protected]",
      "role": "signer",
      "orderIndex": 1,
      "fileAccessMode": "pin",
      "approvalMode": "button_only"
    }
  ],
  "metadata": {
    "caseType": "contract"
  }
}

curl -X POST 'https://api.sare.pl/ext/doc-flow/processes' \
  -H 'Authorization: Bearer <integrationKey>:<secret>' \
  -H 'Content-Type: application/json' \
  --data-binary @process.json

Pola procesu

Pole	Wymagane	Znaczenie i wartość domyślna
name	tak	Nazwa procesu, 1-255 znaków
document.uploadId	tak	Identyfikator niewykorzystanego uploadu PDF z tego samego konta
referenceId	nie	Unikalny w obrębie konta identyfikator referencyjny, 3-120 znaków. Pominięty lub pusty jest generowany automatycznie
externalId	nie	Unikalny w obrębie konta identyfikator z systemu zewnętrznego, 1-160 znaków
description	nie	Opis, do 1000 znaków
sourceSystem	nie	Nazwa systemu źródłowego, 1-120 znaków
expiresAt	nie	Przyszły termin zakończenia przyjmowania akceptacji w ISO 8601 ze strefą czasową. Domyślnie brak terminu
mode	nie	sequential (domyślnie) lub parallel
fileAccessMode	nie	pin (domyślnie) lub none
approvalMode	nie	Domyślnie button_only; pozostałe wartości opisano poniżej
recipients	nie	Do 5 odbiorców. Brak lub pusta tablica tworzy szkic created, który trzeba uruchomić w panelu
includeSignatureCard	nie	Dołączenie karty podpisów do dokumentu wynikowego. Domyślnie true
sealingEnabled	nie	Pieczętowanie EuroCert. Domyślnie włączone, jeśli jest dostępne dla konta; bez dostępnej usługi pozostaje wyłączone
eurocertSealId	nie	Identyfikator pieczęci dostępnej dla konta, 1-120 znaków. Pominięty korzysta z ustawień konta
sendFinalDocumentToAllRecipients	nie	Powiadomienie wszystkich odbiorców z dostępem do dokumentu końcowego. Domyślnie false
showCompletedSigners	nie	Pokazywanie odbiorcy osób, które zakończyły swoje kroki. Domyślnie false
metadata	nie	Obiekt z dodatkowymi danymi integracji. Odpowiedź zawiera także ustawienia procesu dodane przez system

Pola wiadomości i dostarczania PIN-u opisano w sekcji Wiadomości i PIN. W publicznym API dokument przekazuje się przez uploadId; nie przesyła się tutaj Base64 ani adresu URL pliku.

Odbiorcy i zatwierdzanie

W trybie sequential kolejne osoby otrzymują dostęp po zakończeniu poprzedniego kroku. W trybie parallel kroki są aktywowane równolegle.

Pole odbiorcy	Wymagane	Zasady
key	tak	Unikalny w procesie klucz kroku, 1-80 znaków
name	tak	Imię i nazwisko lub nazwa, 1-200 znaków
email	tak	Poprawny adres e-mail, do 320 znaków, również przy PIN-ie SMS
role	tak	Etykieta roli, 1-80 znaków, np. signer
orderIndex	dla sequential	Dodatnia liczba całkowita, unikalna w procesie
fileAccessMode	tak	none lub pin; należy podać także wtedy, gdy ustawiono je na poziomie procesu
approvalMode	tak	Jedna z wartości z tabeli poniżej
gsm	dla PIN-u SMS bez fallbacku	Numer z kodem kraju: 8-15 cyfr, opcjonalny +, bez spacji, np. +48500100200
pin	nie	Początkowy kod, 4-12 znaków. Gdy go nie podasz, kod generuje system; ponowne wysłanie PIN-u może go zastąpić

fileAccessMode steruje dostępem do dokumentu: none oznacza dostęp przez link, a pin wymaga kodu. approvalMode określa sposób zakończenia kroku:

approvalMode	Działanie odbiorcy
view_only	Wyświetlenie dokumentu automatycznie kończy krok
button_only	Potwierdzenie przyciskiem
pin	Potwierdzenie kodem PIN
signature	Złożenie podpisu odręcznego w panelu odbiorcy
pin_and_signature	Kod PIN i podpis odręczny

Podpis odręczny w signature i pin_and_signature oraz pieczęć EuroCert są odrębnymi funkcjami. Ustawienia na poziomie odbiorcy określają wymagania jego kroku.

Wiadomości i PIN

Pole procesu	Znaczenie
sender	Nadawca: wymagane email (do 320 znaków), opcjonalne name (do 200 znaków). Bez tego obiektu używany jest nadawca z ustawień modułu
sender.replyTo	Pole przyjmowane przez API, ale adres odpowiedzi jest obecnie ustawiany na sender.email
emailSubject	Temat zaproszenia, do 255 znaków, bez znaków nowej linii. Pusty lub pominięty używa nazwy procesu
emailPreheader	Preheader zaproszenia, do 100 znaków, bez znaków nowej linii
emailTemplateId	Dodatni całkowity identyfikator gotowego szablonu SARE na koncie. Brak lub null wybiera standardową wiadomość
pinDeliveryChannel	email (domyślnie) lub sms
pinSmsSender	Nazwa nadawcy SMS dostępnego na koncie, do 40 znaków; wymagana dla kanału sms
pinFallbackToEmail	Domyślnie false. Dla kanału sms pozwala wysłać PIN e-mailem, gdy odbiorca nie ma numeru GSM

Zaproszenia do procesu są wysyłane e-mailem niezależnie od wybranego kanału PIN. Fallback dotyczy braku numeru GSM, a nie dowolnego błędu wysyłki SMS. Przy kanale email pola fallbacku i nadawcy SMS nie są używane.

Własny szablon zaproszenia

Szablon wskazany przez emailTemplateId musi być gotowym szablonem SARE. W HTML wymagany jest link z dokładnym href="{{doc_flow_url}}", bez dodatkowych parametrów, oraz dosłowny znacznik {{doc_flow_ref_id}} w widocznej treści. Jeśli szablon zawiera wersję TXT, ona również musi zawierać {{doc_flow_url}} i {{doc_flow_ref_id}}. Gdy TXT jest pusty, system tworzy go z HTML.

Opcjonalne znaczniki to {{doc_flow_process_name}} (nazwa procesu), {{doc_flow_valid_until}} (ważność linku dostępu, a nie termin akceptacji) i {{doc_flow_document_password}} (hasło dokumentu, gdy jest używane). Znacznik hasła jest wymagany, jeśli konfiguracja dokumentu przewiduje przekazanie go w zaproszeniu. Inne znaczniki w formacie {{...}} powodują błąd walidacji.

Własny szablon dotyczy zaproszeń, w tym kolejnych kroków sekwencji. Wiadomości z PIN-em oraz dostępem do dokumentu końcowego używają standardowej treści. Załączniki zapisane w szablonie SARE nie są dołączane do zaproszenia. Szablon jest sprawdzany przed użyciem; jego identyfikator nie zastępuje pola sender ani nadawcy w ustawieniach modułu.

Szczegóły i statusy procesu

GET /processes/{id} zwraca szczegóły procesu, odbiorców i dokumentów. Pole {id} oznacza identyfikator procesu dfp_..., a nie referenceId, externalId ani documentId.

curl 'https://api.sare.pl/ext/doc-flow/processes/dfp_t1_exampleProcess' \
  -H 'Authorization: Bearer <integrationKey>:<secret>'

Przykładowy fragment odpowiedzi (pozostałe ustawienia procesu pominięto):

{
  "id": "dfp_t1_exampleProcess",
  "referenceId": "ref_example_2030_0001",
  "externalId": "case-2030-0001",
  "documentId": "dfd_t1_exampleDocument",
  "name": "Umowa - Jan Kowalski",
  "status": "in_progress",
  "recipients": [
    {
      "key": "step_1",
      "status": "email_sent",
      "orderIndex": 1,
      "name": "Jan Kowalski",
      "email": "[email protected]",
      "gsm": null,
      "role": "signer",
      "fileAccessMode": "pin",
      "approvalMode": "button_only",
      "activatedAt": "2030-07-27T10:05:00.000Z",
      "viewedAt": null,
      "confirmedAt": null
    }
  ],
  "documents": [
    {
      "id": 123,
      "uploadId": "dfu_t1_exampleUpload",
      "processId": "dfp_t1_exampleProcess",
      "documentId": "dfd_t1_exampleDocument",
      "kind": "source",
      "version": 1,
      "fileName": "document.pdf",
      "mimeType": "application/pdf",
      "sha256": "bc0e83603ea8596cbd473e292981e3e7f93ba626f8f3eb858857bc767f13e6c5",
      "sizeBytes": 123456,
      "status": "attached",
      "uploadedAt": "2030-07-27T10:00:00.000Z",
      "attachedAt": "2030-07-27T10:05:00.000Z",
      "validUntil": "2031-01-23T10:05:00.000Z",
      "deletedAt": null
    }
  ],
  "createdAt": "2030-07-27T10:05:00.000Z",
  "updatedAt": "2030-07-27T10:05:00.000Z",
  "completedAt": null,
  "expiresAt": "2030-08-10T12:00:00.000Z",
  "readUntil": null,
  "readOnly": false
}

Odpowiedź zawiera również ustawienia procesu, wiadomości, PIN-u, nadawcy, pieczęci oraz metadata. Nie zawiera PIN-ów, tokenów ani publicznych linków odbiorców. Nie udostępnia też ścieżek plików w magazynie.

Status procesu	Znaczenie
created	Szkic, przed uruchomieniem
in_progress	Obieg w toku
paused	Obieg wstrzymany
completed	Zakończono wszystkie wymagane kroki
cancelled	Anulowanie, odrzucenie lub upłynięcie terminu procesu
failed	Proces zakończony błędem

Statusy kroków w recipients[].status: pending, active, email_sent, viewed, confirmed, failed, skipped. email_sent oznacza zlecenie wysyłki zaproszenia, a nie potwierdzenie jego doręczenia.

Dokumenty mają rodzaj source (źródłowy PDF), artifact (wersja wynikowa) lub sealed (wersja opieczętowana) oraz status uploaded, attached, expired lub replaced. Sam status procesu completed nie gwarantuje dostępności wersji sealed; jej powstanie można śledzić przez zdarzenia pieczętowania.

Lista procesów

GET /processes udostępnia następujące parametry:

Parametr	Znaczenie
page, limit	Numer strony i liczba wyników; domyślnie 1 i 10
sort	Pole sortowania: id, name, status, createdAt, updatedAt, sourceSystem; domyślnie id
order	ASC (domyślnie) lub DESC
status	Jeden ze statusów procesu
referenceId, externalId, sourceSystem	Dopasowanie fragmentu identyfikatora lub nazwy systemu, bez rozróżniania wielkości liter
recipient	Wyszukiwanie odbiorcy po nazwie lub adresie e-mail
recipientEmail, recipientName	Wyszukiwanie po adresie e-mail albo nazwie odbiorcy
createdFrom, createdTo	Włączne granice daty utworzenia, w ISO 8601 ze strefą czasową
search	Wyszukiwanie po procesie, identyfikatorach oraz nazwie lub e-mailu odbiorcy

curl --get 'https://api.sare.pl/ext/doc-flow/processes' \
  -H 'Authorization: Bearer <integrationKey>:<secret>' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=20' \
  --data-urlencode 'sort=createdAt' \
  --data-urlencode 'order=DESC' \
  --data-urlencode 'referenceId=ref_example_2030_0001'

Odpowiedź ma postać { "pagination": { "totalCount": 1, "page": 1, "limit": 20 }, "processes": [...] }. Każdy element processes ma strukturę szczegółów procesu, ale jego documents jest pustą tablicą. Dokumenty pobiera się przez GET /processes/{id}. Filtr batchId nie jest obsługiwany przez publiczne API.

Pobieranie dokumentów

Aktualny dokument

GET /processes/{id}/documents/current/download bez kind wybiera najnowszy dostępny dokument typu sealed, a gdy go nie ma - artifact, następnie source. Parametrem kind=source, kind=artifact lub kind=sealed można wskazać konkretny rodzaj.

curl --fail-with-body -o document.pdf \
  -H 'Authorization: Bearer <integrationKey>:<secret>' \
  'https://api.sare.pl/ext/doc-flow/processes/dfp_t1_exampleProcess/documents/current/download'

Wybrana wersja

GET /processes/{id}/documents/versions/{version}/download przyjmuje dodatni numer wersji i opcjonalne kind. Bez kind szuka rodzaju artifact. Aby pobrać oryginalny PDF, wskaż kind=source i jego numer z documents.

curl --fail-with-body -o source-v1.pdf \
  -H 'Authorization: Bearer <integrationKey>:<secret>' \
  'https://api.sare.pl/ext/doc-flow/processes/dfp_t1_exampleProcess/documents/versions/1/download?kind=source'

Odpowiedź 200 jest binarna i zawiera Content-Type, Content-Disposition oraz Content-Length. Sprawdzaj kod HTTP przed przetworzeniem zapisanego pliku: przy błędzie odpowiedź jest JSON-em. Brak dokumentu wybranego rodzaju lub wersji zwraca 404.

Ważność i przechowywanie

Ważność uploadu, możliwość zatwierdzenia procesu i okres odczytu dokumentu są odrębnymi terminami:

Element	Zasady
Niewykorzystany upload	Ważny przez 24 godziny od przesłania; termin w validUntil
Termin akceptacji	Opcjonalne expiresAt. Po jego upłynięciu proces przechodzi do cancelled z powodem expired i pozostaje do odczytu
Link bez expiresAt	Początkowa ważność wynosi 7 dni od wygenerowania
Link z expiresAt	Początkowa ważność obejmuje termin procesu i kolejne 30 dni; akceptacja jest możliwa tylko przed expiresAt
Odczyt po zakończeniu	Przez 30 dni od zakończenia, anulowania lub odrzucenia; dokładny termin zwraca readUntil, a readOnly informuje o trybie odczytu
Dokument przypięty do procesu	Bazowo 180 dni. Retencja jest przedłużana, jeśli termin procesu i okres odczytu wymagają późniejszej daty; sprawdzaj documents[].validUntil

Zakończenie kroku nie oznacza natychmiastowego wyłączenia linku. Dotychczasowy link może nadal służyć do odczytu w okresie readUntil, także po wykorzystaniu go do zatwierdzenia. Dostęp nadal podlega wymaganiom PIN-u i ograniczeniom danego kroku.

API pozwala ustawić expiresAt. Nie udostępnia osobnych ustawień okresu 24 godzin dla uploadu, bazowych 180 dni retencji ani 30 dni odczytu. Dłuższe przechowywanie pliku nie przedłuża automatycznie publicznego dostępu odbiorcy.

Błędy i ponawianie żądań

Błąd biznesowy zawiera kod w polu message, na przykład:

{
  "statusCode": 400,
  "message": "DOC_FLOW_UPLOAD_EXPIRED",
  "error": "Bad Request"
}

Błędy walidacji mogą zawierać dodatkowe informacje o niepoprawnych polach. Nie należy zakładać formatu błędów RCS z polem code.

HTTP	Przykładowe przyczyny
400	Niepoprawne dane, za duży lub niedozwolony plik, wykorzystany lub wygasły upload, konflikt identyfikatorów, niedostępny szablon lub pieczęć
401	Brak lub błędne dane dostępowe
403	Wyłączony moduł lub brak uprawnień
404	Brak procesu, uploadu albo wersji dokumentu
429	Przekroczony limit żądań
5xx	Błąd serwera lub przejściowa niedostępność usługi, np. 503 podczas kontroli bezpieczeństwa pliku

Wybrane kody błędów:

Kod	Znaczenie
DOC_FLOW_UPLOAD_ID_REQUIRED	Brak document.uploadId
DOC_FLOW_UPLOAD_NOT_FOUND	Upload nie istnieje lub nie należy do konta
DOC_FLOW_UPLOAD_EXPIRED	Minęła ważność uploadu
DOC_FLOW_UPLOAD_ALREADY_ATTACHED	Upload został już przypięty do procesu
DOC_FLOW_RECIPIENT_LIMIT_EXCEEDED	Więcej niż 5 odbiorców
DOC_FLOW_MONTHLY_RECIPIENT_LIMIT_EXCEEDED	Przekroczony miesięczny limit uczestników na koncie
DOC_FLOW_RECIPIENT_KEY_NOT_UNIQUE	Powtórzony klucz odbiorcy
DOC_FLOW_ORDER_INDEX_REQUIRED	Brak kolejności w trybie sekwencyjnym
DOC_FLOW_ORDER_INDEX_NOT_UNIQUE	Powtórzona kolejność w trybie sekwencyjnym
DOC_FLOW_REFERENCE_ID_NOT_UNIQUE	Istnieje już proces o tym referenceId
DOC_FLOW_EXTERNAL_ID_NOT_UNIQUE	Istnieje już proces o tym externalId
DOC_FLOW_PIN_SMS_SENDER_REQUIRED	Brak nadawcy dla PIN-u SMS
DOC_FLOW_PIN_SMS_SENDER_INVALID	Wybrany nadawca SMS nie jest dostępny na koncie
DOC_FLOW_PIN_SMS_NOT_AVAILABLE	Kanał SMS nie jest dostępny na koncie
DOC_FLOW_RECIPIENT_GSM_REQUIRED	Odbiorca wymagający PIN-u nie ma GSM, a fallback jest wyłączony
DOC_FLOW_PROCESS_NOT_FOUND	Nie znaleziono procesu
DOC_FLOW_DOCUMENT_NOT_FOUND	Nie znaleziono dokumentu wybranego rodzaju
DOC_FLOW_DOCUMENT_VERSION_NOT_FOUND	Nie znaleziono wybranej wersji dokumentu
DOC_FLOW_EMAIL_TEMPLATE_NOT_FOUND	Wybrany gotowy szablon nie istnieje
DOC_FLOW_EMAIL_TEMPLATE_INVALID	Szablon nie spełnia wymagań obiegu dokumentów
DOC_FLOW_EMAIL_TEMPLATE_FETCH_FAILED	Nie udało się pobrać bieżącej treści szablonu
DOC_FLOW_EMAIL_TEMPLATE_SOURCE_NOT_AVAILABLE	Brak dostępu do źródła szablonu lub wymaganego dokumentu
FILE_UPLOAD_FAILED	Brak pliku lub niepoprawne przesłanie
FILE_SIZE_EXCEEDED	Przekroczony rozmiar pliku
FILE_TYPE_NOT_ALLOWED	Niedozwolony format lub zawartość PDF
FILE_INFECTED	Kontrola bezpieczeństwa wykryła zagrożenie

Przechowuj id, referenceId, externalId oraz identyfikatory zdarzeń webhooków. Ustaw timeouty i stosuj rosnące odstępy przy ponawianiu odczytów po 429 lub przejściowym 5xx. Dla 429 uwzględniaj nagłówek Retry-After. Odpowiedzi 5xx zawierają ogólny komunikat Internal Server Error i requestId, który warto przekazać przy zgłoszeniu problemu.

POST /processes nie obsługuje nagłówka Idempotency-Key. Po utracie odpowiedzi najpierw wyszukaj proces po własnym referenceId lub externalId. Ponowne żądanie z tym samym identyfikatorem nie zwraca poprzedniego wyniku, lecz błąd unikalności; ponowne użycie uploadId również może zakończyć się błędem.