La creazione della licenza e la creazione dell’URL originale sono separate, così i retry sono sicuri e gli URL freschi non vengono mai addebitati di nuovo.
1. Crea la licenza
POST /api/v2/licenses
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Idempotency-Key: 2bd25ec7-12da-45fc-9daa-67593b510932
{"media_id":123}Usa una chiave univoca di 8 fino a 160 caratteri ASCII stampabili per il tentativo di selezione logica e conservala quando riprovi. Una nuova licenza restituisce 201; un replay idempotente restituisce 200 con lo stesso ID della licenza.
Cathopic verifica prima l’originale. In una singola transazione blocca l’abbonamento individuale o del team, controlla l’accesso ai contenuti e le eventuali quote condivise esistenti, consuma al massimo un download e registra l’entitlement, la cronologia e la licenza.
2. Richiedi l’URL originale
POST /api/v2/licenses/LICENSE_UUID/download-url
Authorization: Bearer ACCESS_TOKENL’URL scade dopo cinque minuti. Richiedi un nuovo URL per un nuovo download; non crearne un’altra. Cathopic ricava il percorso di archiviazione e non accetta mai un percorso arbitrario.
Errori importanti
subscription_required: nessun accesso a pagamento attivo.media_type_not_in_plan: tipo non incluso.download_balance_exhausted: non restano download con piano limitato.file_unavailable: originale mancante; nessun addebito.idempotency_key_conflict: la chiave è stata usata per un altro ID media.
Conserva il X-Request-Id per l’assistenza, ma non registrare mai token, segreti o URL firmati. Dopo risposte 429 o transienti 5xx, fai un backoff con jitter.
