EZD RP nie pozwala wgrywać plików bezpośrednio z kluczem API — najpierw trzeba pobrać upload-token (krótkoterminowy, ważny minuty), a dopiero potem przesłać plik. To dwustopniowy mechanizm zwiększający bezpieczeństwo.
Mechanizm w 3 krokach
- POST /upload-token — z kluczem API. Otrzymujesz tymczasowy token (zwykle ważny 5-15 min).
- POST /files — z plikiem PDF i upload-tokenem w nagłówku. Otrzymujesz `id_pliku`.
- POST /rpw lub POST /sprawy — z `id_pliku` w metadanych dokumentu. Plik zostaje powiązany ze sprawą.
Dlaczego upload-token, a nie bezpośredni upload?
- Bezpieczeństwo — klucz API nie przechodzi w każdym uploadzie pliku
- Audyt — każdy upload jest logowany z konkretnym tokenem (i czasem)
- Limit nadużyć — upload-token wygasa, więc skradziony nie jest wieczny
- Skalowalność — file upload może iść na osobny endpoint / serwer
Typowe błędy
| Błąd | Przyczyna | Rozwiązanie |
|---|---|---|
| 401 Unauthorized przy POST /files | Brak upload-tokena lub niepoprawny | Sprawdź czy token wstawiony w nagłówek (Authorization / X-Upload-Token) |
| 403 Token expired | Token wygasł (zbyt długo czekałeś) | Pobierz nowy upload-token i ponów upload |
| 413 Payload too large | Plik przekracza limit | Sprawdź dokumentację — typowo limit 50 MB / 100 MB |
| Plik wgrany, ale nie powiązany ze sprawą | Pominięto krok 3 (POST /rpw z id_pliku) | Plik wgrany ale 'wisi' bez sprawy — wykonaj POST /rpw |
Wzorzec idempotencji
Przy retry uploadu nie pobieraj nowego tokena — używaj poprzedniego, jeśli jeszcze ważny. Inaczej możesz zduplikować plik.Reguły poprawnej integracji
- Upload-token pobierany tuż przed uploadem (nie zapisywany na długo)
- Obsługa wygasania tokena — automatyczny retry z nowym tokenem
- Walidacja rozmiaru pliku przed wysyłką
- Logowanie ID każdego uploadu po Twojej stronie (do reconciliation)
- Test scenariusza 'token wygasł w trakcie uploadu' (w Piaskownicy)
Konsultacja integracji upload'ów
Pomożemy poprawnie zaprojektować upload plików z systemu zewnętrznego do EZD RP.
Umów konsultację