La creación de licencia y la URL original son operaciones separadas para que los reintentos sean seguros y las URLs nuevas no vuelvan a cobrar.
1. Crear la licencia
POST /api/v2/licenses
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Idempotency-Key: 2bd25ec7-12da-45fc-9daa-67593b510932
{"media_id":123}Usa una clave única de 8 a 160 caracteres ASCII imprimibles para el intento lógico y consérvala al reintentar. Una licencia nueva devuelve 201; una repetición devuelve 200 con el mismo ID.
Cathopic primero verifica el original. En una transacción bloquea la suscripción individual o de equipo, comprueba el acceso y los derechos compartidos, consume como máximo una descarga y registra derecho, historial y licencia.
2. Solicitar la URL original
POST /api/v2/licenses/LICENSE_UUID/download-url
Authorization: Bearer ACCESS_TOKENLa URL caduca a los cinco minutos. Solicita otra URL para volver a descargar; no crees otra licencia. Cathopic deriva la ruta y nunca acepta una ruta arbitraria.
Errores importantes
subscription_required: no hay acceso de pago activo.media_type_not_in_plan: tipo no incluido.download_balance_exhausted: no quedan descargas.file_unavailable: falta el original; no se cobra.idempotency_key_conflict: clave usada para otro media ID.
Conserva X-Request-Id para soporte, pero nunca registres tokens, secretos ni URLs firmadas. Aplica espera con jitter tras 429 o errores 5xx transitorios.
