Het aanmaken van de licentie en het aanmaken van de oorspronkelijke URL zijn gescheiden, zodat herpogingen veilig zijn en verse URL’s nooit opnieuw kosten veroorzaken.
1. Maak de licentie aan
POST /api/v2/licenses
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Idempotency-Key: 2bd25ec7-12da-45fc-9daa-67593b510932
{"media_id":123}Gebruik een unieke sleutel van 8 tot 160 afdrukbare ASCII-tekens voor de logische selectie-poging en behoud die bij het opnieuw proberen. Een nieuwe licentie geeft 201; een idempotente replay geeft 200 met hetzelfde licentienummer.
Cathopic verifieert eerst de oorspronkelijke bron. In één transactie vergrendelt het de individuele- of teamabonnement, controleert het mediatoegang en bestaande gedeelde rechten, verbruikt het maximaal één download en registreert het het recht, de geschiedenis en de licentie.
2. Vraag de oorspronkelijke URL aan
POST /api/v2/licenses/LICENSE_UUID/download-url
Authorization: Bearer ACCESS_TOKENDe URL verloopt na vijf minuten. Vraag een nieuwe URL aan voor een herdownload; maak geen nieuwe licentie. Cathopic leidt het opslagpad af en accepteert nooit een willekeurig pad.
Belangrijke fouten
subscription_required: geen actieve betaalde toegang.media_type_not_in_plan: type niet inbegrepen.download_balance_exhausted: er blijven geen downloads met beperkt plan over.file_unavailable: oorspronkelijke bron ontbreekt; geen kosten.idempotency_key_conflict: sleutel gebruikt voor een ander media-ID.
Bewaar de X-Request-Id voor ondersteuning, maar log nooit tokens, geheimen of ondertekende URL’s. Bouw terug met jitter na een 429 of een tijdelijke 5xx-reactie.
