updoc API v1 — dokumentacja dla dostawców
https://api.updoc.eu/v1 · JSON · UTF-8. Środowisko testowe: https://api-dev.updoc.eu/v1.
updoc prosi Twojego klienta o dokumenty jednorazowym linkiem. Twój system tworzy prośbę przez API,
wysyła klientowi link (SMS-em, swoimi kanałami), a potem odbiera pliki: webhook mówi, że są gotowe,
API je wydaje. Po potwierdzeniu odbioru (ack) usuwamy plik z updoc.
Uwierzytelnienie
Authorization: Bearer upd_live_…
Klucze upd_live_… i upd_test_… wystawia updoc (panel). Klucz widać raz, przy wystawieniu; u nas
zostaje tylko jego skrót. Możesz mieć kilka aktywnych kluczy naraz, żeby wymieniać je bez przerwy.
Każdy klucz widzi wyłącznie dane swojego dostawcy: zasób innego dostawcy wygląda jak nieistniejący (404).
Limity
60 zapytań na minutę na dostawcę (konfigurowalne). Po przekroczeniu 429 z nagłówkiem Retry-After
(sekundy).
Błędy
Zawsze ten sam kształt:
{"error": {"code": "invalid_expires_at", "message": "expires_at najwyżej 30 dni od teraz."}}
code jest stabilny (opieraj na nim logikę), message jest dla ludzi i może się zmieniać.
| HTTP | code |
Kiedy |
|---|---|---|
| 401 | unauthorized |
Brak klucza, zły klucz, klucz unieważniony albo dostawca wyłączony. |
| 404 | not_found |
Nie ma takiej prośby/pliku/firmy (albo należy do innego dostawcy). |
| 409 | idempotency_key_reused |
Ten Idempotency-Key był użyty ponad 24 h temu. |
| 409 | file_not_ready |
Plik nie ma statusu ready (pobranie, ack). |
| 422 | invalid_request |
Błąd walidacji pola (nazwa pola w message). |
| 422 | invalid_expires_at |
expires_at za blisko (< 10 min) albo za daleko (limit konta). |
| 422 | limits_exceeded |
limits większe niż limity konta. |
| 422 | company_required |
Brak company i brak firmy domyślnej. |
| 422 | company_unknown |
Nowy company.ref bez company.name. |
| 422 | not_supported |
verify_phone (jeszcze nieobsługiwane). |
| 422 | unsupported_locale |
Język inny niż pl. |
| 422 | invalid_logo |
Logo nie jest PNG/JPEG w base64 albo ma ponad 256 kB. |
| 429 | rate_limited |
Za dużo zapytań; patrz Retry-After. |
Prośby
POST /v1/requests
Nagłówek Idempotency-Key (zalecany): ponowione zapytanie z tym samym kluczem w ciągu 24 h zwraca tę
samą prośbę i ten sam link (200 zamiast 201), zamiast tworzyć drugą.
{
"external_ref": "kontakt-123/kampania-9",
"company": {"ref": "kancelaria-a", "name": "Kancelaria A", "name_genitive": "Kancelarii A",
"phone": "+48 22 000 00 00", "email": "[email protected]"},
"message": "Prosimy o zdjęcie umowy kredytowej i harmonogramu spłat.",
"expires_at": "2026-11-21T18:00:00Z",
"documents": [{"label": "Umowa kredytowa", "hint": "Wszystkie strony, także aneksy"}],
"limits": {"max_files": 20, "max_file_bytes": 26214400},
"single_use": false,
"locale": "pl"
}
| Pole | Domyślnie | Opis |
|---|---|---|
external_ref |
"" |
Twój identyfikator; updoc go nie interpretuje, wraca w webhookach. |
company |
firma domyślna | Firma pokazywana klientowi. Nowy ref wymaga name; istniejący aktualizuje podane pola. |
message |
"" |
Tekst dla klienta: zwykły tekst, maks. 500 znaków, bez HTML i linków. |
expires_at |
+3 dni | Maks. 30 dni (limit konta). |
documents |
[] |
Lista wymaganych dokumentów (maks. 20). Pusta = dowolne pliki. |
limits |
20 plików × 25 MB | W granicach limitów konta. |
single_use |
false |
true: link zamyka się po pierwszym „Wyślij”. |
verify_phone |
— | Zarezerwowane (kod SMS); dziś 422 not_supported. |
locale |
pl |
Język strony. |
Odpowiedź 201:
{"id": "req_8Fq2Lw…", "url": "https://updoc.pl/Ab3…", "expires_at": "2026-11-21T18:00:00Z"}
url przekaż klientowi (np. w SMS-ie). Nie zapisuj go w logach: to klucz do strony klienta.
GET /v1/requests/{id}
Stan prośby: status (open, closed, expired), opened_at (otwarcia strony przez klienta),
documents, submissions (partie: każde kliknięcie „Wyślij”) i files:
{"id": "fil_…", "status": "ready", "reject_reason": "", "document_id": null, "submission_id": "sub_…",
"size": 2481221, "content_type": "image/jpeg", "sha256": "9f2…", "active_content": false,
"created_at": "…", "ready_at": "…", "acked_at": null}
Statusy pliku: uploading, quarantined (czeka na skan), ready, rejected (reject_reason:
unsupported_type, too_large, malware, corrupt), acked, deleted.
active_content: true: PDF zawiera JavaScript, akcję /Launch//OpenAction albo osadzone pliki. Pliku
nie zmieniamy (może być dowodem); nie otwieraj go w podglądzie przeglądarki.
POST /v1/requests/{id}/close
Zamyka link przed terminem. Zwraca stan jak GET.
Pliki
GET /v1/files/{id}/content
302 na podpisany adres pobrania, ważny 60 s. Tylko pliki ready. Nazwy pliku od klienta nie
przechowujemy: nazwij go po swojej stronie.
POST /v1/files/{id}/ack
Potwierdzenie odbioru. Plik znika z updoc w ciągu kilku minut. Bez ack znika po 7 dniach od
ready_at (dzień wcześniej dostaniesz file.expiring). Powtórny ack jest bezpieczny.
Logo firmy
POST /v1/companies/{ref}/logo
{"data": "<PNG albo JPEG w base64, maks. 256 kB>"}
202 {"id": "lgu_…", "status": "queued"}. Logo przekodowujemy (PNG, maks. 800×400) w ciągu minuty.
Pojawia się na stronach próśb utworzonych później: prośba zapisuje dane firmy w chwili utworzenia.
Kolor akcentu ustawia updoc w panelu.
Webhooki
Adres webhooka (tylko https://, publiczny) ustawia updoc w panelu; dostajesz wtedy sekret
whsec_… do weryfikacji podpisu.
| Zdarzenie | Kiedy | data |
|---|---|---|
request.opened |
Klient pierwszy raz otworzył stronę (nie podgląd linku w komunikatorze). | request_id, external_ref, opened_at |
file.ready |
Plik przeszedł skan, jest do pobrania. | request_id, external_ref, file_id, submission_id, document_id, size, content_type, sha256, active_content |
file.rejected |
Plik odrzucony. | request_id, external_ref, file_id, submission_id, document_id, reason |
request.submitted |
Klient kliknął „Wyślij” i wszystkie pliki partii są sprawdzone (po file.* tej partii). |
request_id, external_ref, submission_id, files (file_id, status) |
request.expired |
Minął expires_at. |
request_id, external_ref, expires_at |
file.expiring |
Dzień przed skasowaniem pliku bez ack. |
request_id, file_id, deletes_at |
Treść:
{"id": "evt_…", "type": "file.ready", "created_at": "2026-11-18T17:00:00+00:00", "data": {…}}
Webhook nie zawiera treści pliku ani nazwy pliku od klienta. Plik pobierasz przez API swoim kluczem.
Nagłówki: Updoc-Event-Id (do deduplikacji: to samo zdarzenie może przyjść więcej niż raz),
Updoc-Signature: t=<unix>,v1=<hex>, gdzie v1 = HMAC-SHA256(sekret, t + "." + body). Odrzucaj
podpisy starsze niż 5 minut.
import hashlib, hmac, time
def verify(secret: str, body: bytes, header: str, tolerance: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
ts = int(parts["t"])
if abs(time.time() - ts) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])
Odpowiedz 2xx w ciągu 10 s. Inny kod albo błąd połączenia = ponawiamy z rosnącym odstępem (1 min …
12 h) przez co najmniej 24 h. Nie podążamy za przekierowaniami. Kolejność dostarczenia nie jest
gwarantowana: źródłem prawdy jest zawsze GET /v1/requests/{id}.