La création de la licence et la création de l’URL d’origine sont séparées, de sorte que les nouvelles tentatives sont sûres et que les URL fraîches ne sont jamais facturées à nouveau.
1. Créer la licence
POST /api/v2/licenses
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Idempotency-Key: 2bd25ec7-12da-45fc-9daa-67593b510932
{"media_id":123}Utilisez une clé unique de 8 à 160 caractères ASCII imprimables pour la tentative de sélection logique, et conservez-la lors des nouvelles tentatives. Une nouvelle licence renvoie 201 ; une relecture idempotente renvoie 200 avec le même ID de licence.
Cathopic vérifie d’abord l’original. En une seule transaction, il verrouille l’abonnement individuel ou d’équipe, vérifie l’accès au média et les droits partagés existants, consomme au plus un téléchargement, et enregistre le droit, l’historique et la licence.
2. Demander l’URL d’origine
POST /api/v2/licenses/LICENSE_UUID/download-url
Authorization: Bearer ACCESS_TOKENL’URL expire au bout de cinq minutes. Demandez une nouvelle URL pour un re-téléchargement ; ne créez pas une autre licence. Cathopic déduit le chemin de stockage et n’accepte jamais un chemin arbitraire.
Erreurs importantes
subscription_required: aucun accès payant actif.media_type_not_in_plan: type non inclus.download_balance_exhausted: il ne reste plus de téléchargements avec formule limitée.file_unavailable: original introuvable ; aucun frais.idempotency_key_conflict: la clé a été utilisée pour un autre ID de média.
Conservez le X-Request-Id pour le support, mais ne consignez jamais de jetons, de secrets ou d’URL signées. Faites une pause avec un jitter après les réponses 429 ou les erreurs transitoires 5xx.
