← updoc.eu

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}.