Jak bezpiecznie licencjonować i pobierać zasób

Utworzenie licencji i utworzenie oryginalnego adresu URL są oddzielne, więc ponawianie jest bezpieczne, a świeże adresy URL nie obciążają ponownie.

1. Utwórz licencję

POST /api/v2/licenses
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Idempotency-Key: 2bd25ec7-12da-45fc-9daa-67593b510932

{"media_id":123}

Użyj unikalnego klucza od 8 do 160 znaków ASCII możliwych do wydrukowania dla logicznej próby wyboru i zachowaj go podczas ponawiania. Nowa licencja zwraca 201; idempotentne ponowne wywołanie zwraca 200 z tym samym identyfikatorem licencji.

Cathopic najpierw weryfikuje oryginał. W jednej transakcji blokuje subskrypcję indywidualną lub zespołową, sprawdza dostęp do multimediów i istniejące udziały współdzielone, zużywa co najwyżej jedno pobranie oraz rejestruje uprawnienie, historię i licencję.

2. Poproś o oryginalny adres URL

POST /api/v2/licenses/LICENSE_UUID/download-url
Authorization: Bearer ACCESS_TOKEN

Adres URL wygasa po pięciu minutach. Poproś o nowy adres URL do ponownego pobrania; nie twórz kolejnej licencji. Cathopic wyprowadza ścieżkę przechowywania i nigdy nie akceptuje dowolnej ścieżki.

Ważne błędy

• subscription_required: brak aktywnego płatnego dostępu.

• media_type_not_in_plan: typ nie jest uwzględniony.

• download_balance_exhausted: nie pozostały żadne pobrania w ramach planu z limitami.

• file_unavailable: oryginał nieobecny; bez opłaty.

• idempotency_key_conflict: klucz użyty dla innego identyfikatora media.

Zachowaj X-Request-Id do wsparcia, ale nigdy nie loguj tokenów, sekretów ani podpisanych adresów URL. Po odpowiedziach 429 lub przejściowych 5xx zastosuj wycofanie z losowym opóźnieniem (jitter).