A criação da licença e a criação da URL original são separadas, para que as tentativas sejam seguras e URLs novas nunca sejam cobradas novamente.
1. Crie a licença
POST /api/v2/licenses
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Idempotency-Key: 2bd25ec7-12da-45fc-9daa-67593b510932
{"media_id":123}Use uma chave única de 8 a 160 caracteres ASCII imprimíveis para a tentativa lógica de seleção e mantenha-a ao tentar novamente. Uma nova licença retorna 201; uma repetição idempotente retorna 200 com o mesmo ID da licença.
A Cathopic primeiro verifica a original. Em uma única transação, ela bloqueia a assinatura individual ou da equipe, verifica o acesso à mídia e as concessões compartilhadas existentes, consome no máximo um download e registra a concessão, o histórico e a licença.
2. Solicite a URL original
POST /api/v2/licenses/LICENSE_UUID/download-url
Authorization: Bearer ACCESS_TOKENA URL expira após cinco minutos. Solicite uma nova URL para um novo download; não crie outra licença. A Cathopic deriva o caminho de armazenamento e nunca aceita um caminho arbitrário.
Erros importantes
subscription_required: sem acesso pago ativo.media_type_not_in_plan: tipo não incluído.download_balance_exhausted: não restam downloads no plano limitado.file_unavailable: original ausente; sem cobrança.idempotency_key_conflict: a chave foi usada para outro ID de mídia.
Mantenha o X-Request-Id para o suporte, mas nunca registre tokens, segredos ou URLs assinadas. Faça backoff com jitter após respostas 429 ou 5xx transitórias.
