{ "openapi": "3.1.0", "info": { "title": "AgiPlay — API de revendedores", "version": "1.0.0", "description": "Integração servidor a servidor. HTTPS obrigatório e User-Agent contendo `AgiPlay`. Não use uma sessão do site, PIN de cliente ou segredo no navegador.\n\n## Assinatura das requisições\nEnvie X-AgiPlay-Key (public_id), X-AgiPlay-Ts (Unix seconds), X-AgiPlay-Nonce (32 hex minúsculos) e X-AgiPlay-Sig (64 hex minúsculos). A chave secreta é fornecida como 64 caracteres hex: decodifique para 32 bytes antes do HMAC-SHA256.\n\nCanonical: exatamente sete linhas separadas por LF, sem LF final:\n```\nMETHOD_EM_MAIÚSCULAS\n/path/sem/query\nquery_canônica\nunix_seconds\nnonce\nsha256_hex_dos_bytes_exatos_do_corpo\npublic_id\n```\nQuery: pares decodificados, inclusive duplicados; encode RFC 3986 com hex maiúsculo; ordene por chave codificada e depois valor codificado, byte a byte; una key=value com &. Espaço vira %20; um + literal vira %2B. Query ausente é linha vazia. No parsing bruto, separar por & e pelo primeiro =, aplicar percent-decoding sem converter + em espaço. Corpo GET/vazio: bytes vazios. JSON deve ser serializado uma vez: assine e envie os mesmos bytes UTF-8. O public_id faz parte da assinatura; não use a assinatura de seis linhas da API de dispositivo.\n\nJanela padrão de relógio ±300 segundos; nonces são retidos até timestamp assinado +600 s. Cada retry HTTP recebe novo nonce/timestamp/assinatura. Idempotência comercial é o campo JSON idempotency_key (UUID) nos endpoints que o exigem, não um header: persista o mesmo UUID e conteúdo para repetir a mesma operação. Nunca gere novo UUID comercial a cada retry. O header Retry-After informa segundos. Limites por revendedor: 120 leituras/min, 30 escritas/min, 10 sondagens/min; no máximo duas operações assíncronas ativas. Assinaturas inválidas têm limite por IP.\n\n## Respostas\nSiga o wrapper indicado em cada operação: balance é objeto direto; a maioria usa data. HTTP 202 indica aceitação/execução pendente, não conclusão. Erros seguem error.code/message/hint opcional. Não trate timeout como cancelamento; consulte/reenvie de forma idempotente. Novas compras Stripe permanecem desativadas; esta API não cria checkout nem concede crédito sem saldo.\n\n## Webhooks recebidos no seu servidor\nPOST JSON com X-AgiPlay-Event, X-AgiPlay-Event-Id, X-AgiPlay-Delivery e X-AgiPlay-Signature: `t=,v1=`. Assinatura = HMAC-SHA256 usando o segredo whsec_ COMPLETO como texto UTF-8 (não hex-decode), sobre `timestamp.eventId.rawBody`, com pontos literais. Verifique bytes brutos antes de parsear JSON e use comparação em tempo constante. Rejeite timestamps fora de ±300 s como política do receptor; confira id e type do JSON com os headers. Guarde eventId em uma inbox persistente com inserção atômica e retenção de pelo menos 7 dias, antes de responder 2xx; duplicatas já persistidas podem receber 2xx sem repetir efeitos. Processe a inbox em worker idempotente. X-AgiPlay-Delivery é informativo, não faz parte da assinatura. Não use created_at do evento como relógio da tentativa.\n\nTimeout de entrega 5 s; sem redirects. Falhas são repetidas após 60, 300, 1800, 7200, 21600 e 86400 s; após a tentativa final status dead. Cada tentativa recebe timestamp e assinatura atuais. Use 2xx apenas após persistência durável; 4xx/5xx também causam retry. Eventos de teste são webhook.test.\n\n## Exemplos locais gratuitos\n- [Node.js cliente](https://agiplay.app/developers/examples/node/client.mjs) · [receptor](https://agiplay.app/developers/examples/node/webhook.mjs)\n- [Python cliente](https://agiplay.app/developers/examples/python/client.py) · [receptor](https://agiplay.app/developers/examples/python/webhook.py)\n- [PHP cliente](https://agiplay.app/developers/examples/php/client.php.txt) · [receptor](https://agiplay.app/developers/examples/php/webhook.php.txt)\n- [Instalação e uso](https://agiplay.app/developers/examples/README.md)\n\nSomente exemplos fictícios. Não cole segredos nesta documentação. Chamadas reais estão desativadas no renderer público.", "contact": { "name": "AgiPlay", "email": "suporte@agiplay.app" } }, "servers": [ { "url": "https://api.agiplay.app", "description": "Produção; requer revenda ativa, chave e escopos autorizados." } ], "security": [ { "ResellerHmacKey": [] } ], "tags": [ { "name": "Autenticação", "description": "Verificação da assinatura HMAC das requisições." }, { "name": "Conta", "description": "Identidade, saldo, preços e extrato da revenda autenticada." }, { "name": "Clientes", "description": "Cadastro, vínculo e consulta dos clientes da revenda." }, { "name": "Acesso", "description": "Ativação e renovação do acesso usando créditos." }, { "name": "Operações", "description": "Consulta e cancelamento das operações assíncronas." }, { "name": "Listas", "description": "Gerenciamento de listas dos clientes pela revenda." }, { "name": "Webhooks", "description": "Cadastro de destinos e acompanhamento de notificações assinadas." } ], "paths": { "/v1/reseller/signature-check": { "post": { "operationId": "resellerPostSignatureCheck", "summary": "Conferir assinatura sem alterar dados", "description": "Permite conferir HMAC com corpo JSON arbitrário, sem registrar uma operação comercial. Consome nonce e orçamento de escrita.\n\nEscopo: qualquer chave válida. Limite: 30 escritas/min por revendedor.", "tags": [ "Autenticação" ], "x-required-scope": "", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "valid": { "type": "boolean" }, "key_id": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "clock_skew_seconds": { "type": "integer" }, "body_sha256": { "type": "string" } } } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "/v1/reseller/me": { "get": { "operationId": "resellerGetMe", "summary": "Consultar a revenda e a chave atual", "description": "Escopo: account:read. Limite: 120 leituras/min por revendedor.", "tags": [ "Conta" ], "x-required-scope": "account:read", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "clients": { "type": "integer" }, "source_access": { "type": "boolean" }, "key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "account:read", "clients:read", "clients:write", "billing:write", "playlists:read", "playlists:write", "playlists:source", "transfers:write", "operations:read", "webhooks:manage" ] } } } } } } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reseller/balance": { "get": { "operationId": "resellerGetBalance", "summary": "Consultar saldo e últimos lançamentos", "description": "Resposta sem wrapper data. Créditos são unidades inteiras, diferentes de centavos. Inclui até 20 lançamentos recentes.\n\nEscopo: account:read. Limite: 120 leituras/min por revendedor.", "tags": [ "Conta" ], "x-required-scope": "account:read", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reseller/pricing": { "get": { "operationId": "resellerGetPricing", "summary": "Consultar preços e pacotes atuais", "description": "Escopo: account:read. Limite: 120 leituras/min por revendedor.", "tags": [ "Conta" ], "x-required-scope": "account:read", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "quantity", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10000 }, "description": "Opcional: inclui quote com quantidade, centavos por crédito e total. Deve atender o mínimo e as faixas da configuração; core limita a 10000." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Pricing" } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reseller/ledger": { "get": { "operationId": "resellerGetLedger", "summary": "Consultar extrato paginado", "description": "Escopo: account:read. Limite: 120 leituras/min por revendedor.", "tags": [ "Conta" ], "x-required-scope": "account:read", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "delta": { "type": "integer" }, "reason": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "balance_after": { "type": [ "integer", "null" ] }, "debt_after": { "type": [ "integer", "null" ] }, "months": { "type": [ "integer", "null" ] }, "days": { "type": [ "integer", "null" ] }, "kind": { "type": "string" }, "origin": { "type": [ "string", "null" ] }, "client_id": { "type": [ "string", "null" ], "format": "uuid" } } } }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "data", "current_page", "last_page", "total" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reseller/clients": { "get": { "operationId": "resellerGetClients", "summary": "Listar clientes da revenda", "description": "Escopo: clients:read. Limite: 120 leituras/min por revendedor.", "tags": [ "Clientes" ], "x-required-scope": "clients:read", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 }, "description": "Pesquisa nome, e-mail ou UUID. Não retorna clientes de outra revenda." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Client" } }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "data", "current_page", "last_page", "total" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "resellerPostClients", "summary": "Convidar novo cliente", "description": "Novo e-mail cria cliente sem senha ou débito e envia convite por e-mail (invited). Conta já vinculada à revenda retorna owned. Conta existente fora da revenda retorna use_transfer_code sem criar solicitação de acesso. Para conta sem revenda, peça ao titular ID e código de seis caracteres do QR “Vincular revendedor” e use /clients/link, sem lista nova. Para conta de outra revenda, somente /clients/claim permite transferência com código de transferência de 15 minutos e nova lista autorizada; /clients/link nunca transfere. Nenhuma resposta autoriza acessar conta alheia.\n\nEscopo: clients:write. Limite: 30 escritas/min por revendedor.", "tags": [ "Clientes" ], "x-required-scope": "clients:write", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" } ], "responses": { "202": { "description": "Convite enviado, vínculo existente ou necessidade de código de transferência.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "invited", "use_transfer_code", "owned" ] }, "client": { "anyOf": [ { "$ref": "#/components/schemas/Client" }, { "type": "null" } ] } } } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "email": { "type": "string", "format": "email", "maxLength": 190 } }, "required": [ "name", "email" ] }, "example": { "name": "Cliente de exemplo", "email": "cliente@example.com" } } } } } }, "/v1/reseller/clients/{client}": { "get": { "operationId": "resellerGetClientsClient", "summary": "Consultar cliente vinculado", "description": "Escopo: clients:read. Limite: 120 leituras/min por revendedor. Consulta somente cliente atualmente vinculado à própria revenda; inexistente ou fora da revenda retorna 404 sem dados pessoais. Operação somente leitura: não cria biblioteca, inicia trial, renova ou altera validade. Leia data.validity_revision para preparar expected_revision de uma ativação; data.revision representa a propriedade.", "tags": [ "Clientes" ], "x-required-scope": "clients:read", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Client" } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reseller/clients/link": { "post": { "operationId": "resellerPostClientsLink", "summary": "Vincular cliente pelo QR do titular", "description": "Vínculo síncrono de conta sem revenda pelo ID UUID e código de 6 caracteres do QR “Vincular revendedor” exibido ao titular no AgiPlay. Código temporário válido por 600 segundos, uso único, rotação pelo titular e queima após cinco erros; não é o código de transferência de /clients/claim. Não exige e-mail, playlist, OTP ou cobrança e não altera listas, créditos, validade, trial nem cria biblioteca. Conta já própria retorna owned. Conta de outra revenda permanece intacta; somente um código válido atual permite revelar client_already_managed.\n\nEscopo: clients:write. HMAC, HTTPS, User-Agent AgiPlay, timestamp e nonce novos a cada tentativa. Limites: 30 escritas/min por revenda; cinco falhas por cliente/revenda em 600 s e 30 falhas/h por revenda, compartilhadas com o painel do site e entre chaves. Em 429 respeite Retry-After.\n\nPersista cliente, código e idempotency_key UUID antes da primeira tentativa. Em perda de resposta, repita os mesmos três valores com nova assinatura; sucesso persistido retorna 200 e data.replayed=true, inclusive após o código expirar/ser consumido ou a chave API ser rotacionada. A revenda e a chave usadas no retry devem estar ativas e ter o escopo exigido. Mudança de cliente, código ou tipo de operação com o mesmo UUID retorna 409 idempotency_conflict. Cada repetição consulta o Client atual e exige que a propriedade e sua revisão continuem iguais ao vínculo persistido; não trate o recibo antigo como acesso permanente.", "tags": [ "Clientes" ], "x-required-scope": "clients:write", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" } ], "responses": { "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "client_already_managed somente com código válido atual; idempotency_conflict quando UUID da operação é reutilizado com outro cliente, código ou tipo. client_not_owned/ownership_changed se um vínculo persistido perdeu a propriedade ou mudou de revisão.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Formato inválido, ou link_code_invalid para ID desconhecido, código errado/expirado/consumido e conta de revenda. Não revela dados de conta fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Vínculo concluído nesta requisição; data.status=linked e data.replayed=false.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ClientLinkResult" } }, "required": [ "data" ] } } } }, "200": { "description": "Cliente já pertence à revenda (owned), ou repetição persistida (replayed=true).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ClientLinkResult" } }, "required": [ "data" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "pattern": "^[A-Za-z0-9]{6}$", "minLength": 6, "maxLength": 6, "description": "Seis letras/dígitos do QR do titular, sem espaços ou hífen; comparação sem distinção entre maiúsculas e minúsculas." }, "idempotency_key": { "type": "string", "format": "uuid", "description": "UUID comercial persistido antes da tentativa, reutilizado com cliente e código idênticos em retry." } }, "required": [ "client_id", "code", "idempotency_key" ] }, "example": { "client_id": "45f6a56c-e677-4e0a-a19e-8f8347f7b8be", "code": "AB2CD3", "idempotency_key": "413a90fc-2a2f-4e31-9c24-b4de2f9a9178" } } } } } }, "/v1/reseller/clients/claim": { "post": { "operationId": "resellerPostClientsClaim", "summary": "Solicitar transferência autorizada", "description": "Exige ID e código do cliente e uma nova lista autorizada. A transferência é assíncrona; não considere a titularidade transferida no 202. Consulte a operação. Código tem até 5 tentativas; o fluxo valida a nova lista antes de concluir e conserva validade já concedida.\n\nEscopo: transfers:write. Limite: 30 escritas/min por revendedor; também 10 sondagens/min.", "tags": [ "Clientes" ], "x-required-scope": "transfers:write", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" } ], "responses": { "202": { "description": "Aceito; consulte operação/status até concluir.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationAccepted" } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "maxLength": 32, "writeOnly": true, "description": "Código temporário de 12 caracteres emitido na conta do cliente, normalmente XXXX-XXXX-XXXX; validade 15 minutos." }, "idempotency_key": { "type": "string", "format": "uuid" }, "playlist": { "$ref": "#/components/schemas/PlaylistInput" } }, "required": [ "client_id", "code", "idempotency_key", "playlist" ] } } } } } }, "/v1/reseller/clients/{client}/activate": { "post": { "operationId": "resellerPostClientsClientActivate", "summary": "Ativar período com débito de créditos", "description": "Pacotes: 1→30 dias/1 crédito; 3→90/3; 6→180/6; 12→365/12. Reutilize o mesmo idempotency_key UUID e conteúdo para repetir a mesma ativação; nonce e timestamp HTTP devem ser novos. Saldo insuficiente: 402 insufficient_credits. Dívida, cobrança direta ativa ou ciclo já cobrado podem impedir ativação.\n\nEscopo: billing:write. Limite: 30 escritas/min por revendedor. Leia validity_revision em GET /clients/{client} antes da decisão de compra e persista como expected_revision com UUID e pacote. expected_revision é obrigatório. Em 409 revision_conflict, releia o cliente e confirme explicitamente outra ativação; nunca refaça a compra automaticamente com revisão nova.", "tags": [ "Acesso" ], "x-required-scope": "billing:write", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Activation" } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "revision_conflict: validade mudou desde a leitura. Releia o cliente e exija decisão explícita antes de outra compra. Também pode indicar conflito de idempotência, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "months": { "type": "integer", "enum": [ 1, 3, 6, 12 ] }, "idempotency_key": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "integer", "minimum": 0, "description": "Client.validity_revision lida antes da decisão: timestamp Unix em segundos da validade atual, ou 0 sem validade. Não use Client.revision. Obrigatória; persista com a operação." } }, "required": [ "months", "idempotency_key", "expected_revision" ] } } } } } }, "/v1/reseller/clients/{client}/auto-renew": { "put": { "operationId": "resellerPutClientsClientAutoRenew", "summary": "Ativar ou desativar renovação automática", "description": "Não cobra imediatamente. Desativar encerra ciclos pendentes, sem remover o período já concedido. Quando habilitado, o job debita créditos conforme política e elegibilidade.\n\nEscopo: billing:write. Limite: 30 escritas/min por revendedor.", "tags": [ "Acesso" ], "x-required-scope": "billing:write", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BillingPolicy" } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "months": { "type": "integer", "enum": [ 1, 3, 6, 12 ], "description": "Obrigatório quando enabled=true." } }, "required": [ "enabled" ] }, "example": { "enabled": false } } } } } }, "/v1/reseller/clients/{client}/cancel": { "post": { "operationId": "resellerPostClientsClientCancel", "summary": "Cancelar renovação e ciclos pendentes", "description": "Desativa a renovação automática e fecha ciclos pendentes. Não exclui cliente, listas ou período já concedido.\n\nEscopo: billing:write. Limite: 30 escritas/min por revendedor.", "tags": [ "Acesso" ], "x-required-scope": "billing:write", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BillingPolicy" } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reseller/operations/{id}": { "get": { "operationId": "resellerGetOperationsId", "summary": "Consultar operação", "description": "Estados: queued, running, succeeded, failed, cancelled. Cancelamento não desfaz uma operação já concluída. Até duas operações ativas por revendedor; excesso retorna 429 operations_busy com Retry-After 15.\n\nEscopo: operations:read. Limite: 120 leituras/min por revendedor.", "tags": [ "Operações" ], "x-required-scope": "operations:read", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Operation" } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reseller/operations/{id}/cancel": { "post": { "operationId": "resellerPostOperationsIdCancel", "summary": "Cancelar operação em andamento", "description": "Estados: queued, running, succeeded, failed, cancelled. Cancelamento não desfaz uma operação já concluída. Até duas operações ativas por revendedor; excesso retorna 429 operations_busy com Retry-After 15.\n\nEscopo: operations:read. Limite: 30 escritas/min por revendedor.", "tags": [ "Operações" ], "x-required-scope": "operations:read", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Operation" } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reseller/playlists/test": { "post": { "operationId": "resellerPostPlaylistsTest", "summary": "Testar uma fonte autorizada", "description": "Teste assíncrono isolado; não adiciona automaticamente a lista ao cliente. URL e credenciais não são refletidas na resposta.\n\nEscopo: playlists:write. Limite: 30 escritas/min por revendedor; também 10 sondagens/min.", "tags": [ "Listas" ], "x-required-scope": "playlists:write", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" } ], "responses": { "202": { "description": "Aceito; consulte operação/status até concluir.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationAccepted" } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistWrite" } } } } } }, "/v1/reseller/clients/{client}/playlists": { "get": { "operationId": "resellerGetClientsClientPlaylists", "summary": "Listar listas gerenciadas do cliente", "description": "Escopo: playlists:read. Limite: 120 leituras/min por revendedor.", "tags": [ "Listas" ], "x-required-scope": "playlists:read", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Playlist" } } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "resellerPostClientsClientPlaylists", "summary": "Adicionar lista ao cliente", "description": "Escopo: playlists:write. Limite: 30 escritas/min por revendedor; também 10 sondagens/min.", "tags": [ "Listas" ], "x-required-scope": "playlists:write", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Aceito; consulte operação/status até concluir.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationAccepted" } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistWrite" } } } } } }, "/v1/reseller/clients/{client}/playlists/{id}": { "get": { "operationId": "resellerGetClientsClientPlaylistsId", "summary": "Consultar lista", "description": "Escopo: playlists:read. Limite: 120 leituras/min por revendedor.", "tags": [ "Listas" ], "x-required-scope": "playlists:read", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Playlist" } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "resellerPatchClientsClientPlaylistsId", "summary": "Atualizar lista", "description": "Atualização assíncrona. kind não pode ser alterado nesta operação; campos omitidos são preservados. Reutilize idempotency_key somente para repetir o mesmo conteúdo.\n\nEscopo: playlists:write. Limite: 30 escritas/min por revendedor; também 10 sondagens/min.", "tags": [ "Listas" ], "x-required-scope": "playlists:write", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Aceito; consulte operação/status até concluir.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationAccepted" } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistPatch" } } } } }, "delete": { "operationId": "resellerDeleteClientsClientPlaylistsId", "summary": "Excluir lista", "description": "Exclui somente uma lista da revenda no cliente autorizado. Não é um cancelamento da assinatura. Confirmar no seu próprio produto antes de chamar.\n\nEscopo: playlists:write. Limite: 30 escritas/min por revendedor.", "tags": [ "Listas" ], "x-required-scope": "playlists:write", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reseller/clients/{client}/playlists/{id}/status": { "get": { "operationId": "resellerGetClientsClientPlaylistsIdStatus", "summary": "Consultar sincronização e publicação", "description": "Escopo: playlists:read. Limite: 120 leituras/min por revendedor.", "tags": [ "Listas" ], "x-required-scope": "playlists:read", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PlaylistStatus" } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reseller/clients/{client}/playlists/{id}/source": { "get": { "operationId": "resellerGetClientsClientPlaylistsIdSource", "summary": "Ler fonte com permissão especial", "description": "Além do escopo playlists:source exige api_source_access habilitado pela administração. Leitura auditada, Cache-Control private, no-store. Somente no servidor; não registre nem envie essas credenciais ao navegador. Os demais recursos não expõem fontes.\n\nEscopo: playlists:source. Limite: 120 leituras/min por revendedor.", "tags": [ "Listas" ], "x-required-scope": "playlists:source", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "kind": { "type": "string" }, "url": { "type": "string" }, "host": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "epg_url": { "type": "string" } } } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reseller/clients/{client}/playlists/{id}/sync": { "post": { "operationId": "resellerPostClientsClientPlaylistsIdSync", "summary": "Solicitar sincronização", "description": "202 indica fila, não catálogo pronto. Respeite Retry-After e consulte /status.\n\nEscopo: playlists:write. Limite: 30 escritas/min por revendedor.", "tags": [ "Listas" ], "x-required-scope": "playlists:write", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Aceito; consulte operação/status até concluir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "queued": { "type": "boolean" }, "eta_sec": { "type": "integer" }, "status": { "type": "string" } } } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reseller/clients/{client}/playlists/{id}/resync": { "post": { "operationId": "resellerPostClientsClientPlaylistsIdResync", "summary": "Ressincronizar lista", "description": "Limpa contador de falhas e erro anterior antes de solicitar recarga. 202 indica fila, não catálogo pronto. Respeite Retry-After e consulte /status.\n\nEscopo: playlists:write. Limite: 30 escritas/min por revendedor.", "tags": [ "Listas" ], "x-required-scope": "playlists:write", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Aceito; consulte operação/status até concluir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "queued": { "type": "boolean" }, "eta_sec": { "type": "integer" }, "status": { "type": "string" } } } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reseller/webhooks": { "get": { "operationId": "resellerGetWebhooks", "summary": "Listar destinos e eventos disponíveis", "description": "Escopo: webhooks:manage. Limite: 120 leituras/min por revendedor.", "tags": [ "Webhooks" ], "x-required-scope": "webhooks:manage", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "events": { "type": "array", "items": { "type": "string", "enum": [ "client.activated", "client.renewed", "client.expired", "funds.changed", "funds.low", "transfer.completed", "transfer.lost", "playlist.synced", "playlist.sync_failed" ] } }, "max_endpoints": { "type": "integer" } }, "required": [ "data", "events", "max_endpoints" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "resellerPostWebhooks", "summary": "Cadastrar destino HTTPS", "description": "Até 5 destinos por revenda. Armazene secret no servidor: aparece apenas nesta criação ou em rotação explícita. Não inclui wildcard; selecione os eventos.\n\nEscopo: webhooks:manage. Limite: 30 escritas/min por revendedor.", "tags": [ "Webhooks" ], "x-required-scope": "webhooks:manage", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" } ], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookSecret" } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTPS público, sem usuário/senha/fragmento. DNS e endereço validados contra SSRF; sem redirecionamento." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "client.activated", "client.renewed", "client.expired", "funds.changed", "funds.low", "transfer.completed", "transfer.lost", "playlist.synced", "playlist.sync_failed" ] }, "minItems": 1 } }, "required": [ "url", "events" ] }, "example": { "url": "https://example.com/agiplay/events", "events": [ "client.activated", "playlist.synced" ] } } } } } }, "/v1/reseller/webhooks/{id}": { "patch": { "operationId": "resellerPatchWebhooksId", "summary": "Atualizar ou pausar destino", "description": "Escopo: webhooks:manage. Limite: 30 escritas/min por revendedor.", "tags": [ "Webhooks" ], "x-required-scope": "webhooks:manage", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTPS público, sem usuário/senha/fragmento. DNS e endereço validados contra SSRF; sem redirecionamento." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "client.activated", "client.renewed", "client.expired", "funds.changed", "funds.low", "transfer.completed", "transfer.lost", "playlist.synced", "playlist.sync_failed" ] }, "minItems": 1 }, "status": { "type": "string", "enum": [ "active", "disabled" ] } } } } } } }, "delete": { "operationId": "resellerDeleteWebhooksId", "summary": "Remover destino", "description": "Entregas pendentes desse destino são encerradas, sem excluir clientes.\n\nEscopo: webhooks:manage. Limite: 30 escritas/min por revendedor.", "tags": [ "Webhooks" ], "x-required-scope": "webhooks:manage", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reseller/webhooks/{id}/secret": { "post": { "operationId": "resellerPostWebhooksIdSecret", "summary": "Rotacionar segredo do destino", "description": "O novo segredo substitui o anterior imediatamente. Coordene a atualização do receptor; não há janela de sobreposição garantida.\n\nEscopo: webhooks:manage. Limite: 30 escritas/min por revendedor.", "tags": [ "Webhooks" ], "x-required-scope": "webhooks:manage", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookSecret" } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reseller/webhooks/{id}/test": { "post": { "operationId": "resellerPostWebhooksIdTest", "summary": "Enfileirar evento de teste", "description": "Evento webhook.test, com data.message = AgiPlay webhook test. Resposta 202 não comprova recebimento.\n\nEscopo: webhooks:manage. Limite: 30 escritas/min por revendedor.", "tags": [ "Webhooks" ], "x-required-scope": "webhooks:manage", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Aceito; consulte operação/status até concluir.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookDelivery" } }, "required": [ "data" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reseller/webhooks/{id}/deliveries": { "get": { "operationId": "resellerGetWebhooksIdDeliveries", "summary": "Consultar tentativas de entrega", "description": "50 entregas por página. Corpo/resposta remota não são expostos. Acompanhe status, tentativas e próximo horário.\n\nEscopo: webhooks:manage. Limite: 120 leituras/min por revendedor.", "tags": [ "Webhooks" ], "x-required-scope": "webhooks:manage", "parameters": [ { "$ref": "#/components/parameters/X-AgiPlay-Ts" }, { "$ref": "#/components/parameters/X-AgiPlay-Nonce" }, { "$ref": "#/components/parameters/X-AgiPlay-Sig" }, { "$ref": "#/components/parameters/User-Agent" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "data", "current_page", "last_page", "total" ] } } } }, "400": { "description": "Requisição malformada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Assinatura inválida, janela de tempo ou repetição de nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Saldo insuficiente para ativação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "HTTPS/User-Agent obrigatório, revendedor inativo, escopo insuficiente ou acesso à fonte desativado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou fora da revenda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de idempotência, revisão, propriedade ou faturamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validação ou regra de negócio inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite atingido; respeite Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até nova tentativa." } } }, "503": { "description": "Dependência temporariamente indisponível; não suponha sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "ResellerHmacKey": { "type": "apiKey", "in": "header", "name": "X-AgiPlay-Key", "description": "public_id agp_ seguido por 32 hex minúsculos. Não é suficiente sozinho: assine com os headers Ts/Nonce/Sig e o segredo privado." } }, "parameters": { "X-AgiPlay-Ts": { "name": "X-AgiPlay-Ts", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,11})$", "description": "Unix seconds decimal, sem zeros à esquerda. Janela padrão ±300 s; mantenha relógio sincronizado." } }, "X-AgiPlay-Nonce": { "name": "X-AgiPlay-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "16 bytes aleatórios em hexadecimal minúsculo. Novo nonce para cada tentativa HTTP." } }, "X-AgiPlay-Sig": { "name": "X-AgiPlay-Sig", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "HMAC-SHA256 canônico de 7 linhas; hexadecimal minúsculo." } }, "User-Agent": { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "description": "Obrigatório conter AgiPlay, por exemplo AgiPlay-Integration/1.0." } }, "page": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "per_page": { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "fields": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Subscription": { "type": "object", "description": "Resumo vigente de acesso da conta. Pode conter datas em Unix seconds, campos de licença, limites e jogos; não confundir com os timestamps ISO 8601 dos recursos da API.", "additionalProperties": true }, "Client": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "revision": { "type": "integer", "description": "Revisão de propriedade da conta; não é a revisão de validade usada em expected_revision." }, "subscription": { "$ref": "#/components/schemas/Subscription" }, "device_count": { "type": "integer" }, "playlist_count": { "type": "integer" }, "validity_revision": { "type": "integer", "minimum": 0, "description": "Timestamp Unix em segundos da expiração atual; 0 sem validade. Use como expected_revision." } }, "required": [ "id", "name", "email", "revision", "subscription", "validity_revision" ] }, "Balance": { "type": "object", "properties": { "reseller_id": { "type": "integer" }, "credits": { "type": "integer", "description": "Créditos inteiros; um crédito ativa 30 dias no pacote mensal." }, "debt_credits": { "type": "integer" }, "blocked": { "type": "boolean" }, "reseller_status": { "type": "string" }, "pending_cycles": { "type": "integer" }, "entries": { "type": "array", "items": { "type": "object", "description": "Lançamento de crédito; inclui id, delta, kind, balance_after, debt_after, reason, origin, months, days, reference, user_id e created_at.", "additionalProperties": true } } }, "required": [ "credits", "debt_credits", "blocked", "reseller_status" ] }, "Pricing": { "type": "object", "description": "Configuração de preços vigente: currency, plans, wholesale, packages e revision. Valores monetários em centavos BRL; percentuais em basis points. Consulte a resposta atual; não fixe preços no cliente.", "properties": { "currency": { "type": "string", "enum": [ "BRL" ] }, "plans": { "type": "object", "additionalProperties": true }, "wholesale": { "type": "object", "additionalProperties": true }, "packages": { "type": "object", "additionalProperties": { "type": "integer" } }, "revision": { "type": "string" }, "quote": { "type": "object", "properties": { "quantity": { "type": "integer" }, "monthly_price_cents": { "type": "integer" }, "base_bps": { "type": "integer" }, "discount_bps": { "type": "integer" }, "tier_min_quantity": { "type": "integer" }, "unit_cents": { "type": "integer" }, "total_cents": { "type": "integer" } }, "additionalProperties": true, "description": "Presente quando quantity é informado; inclui currency BRL e pricing_revision." } } }, "Activation": { "type": "object", "properties": { "reseller_id": { "type": "integer" }, "credits": { "type": "integer" }, "debt_credits": { "type": "integer" }, "blocked": { "type": "boolean" }, "reseller_status": { "type": "string" }, "status": { "type": "string", "enum": [ "activated" ] }, "replayed": { "type": "boolean" }, "subscription": { "$ref": "#/components/schemas/Subscription" }, "entitlement_uuid": { "type": [ "string", "null" ], "format": "uuid" }, "debited": { "type": "integer" }, "days": { "type": "integer" }, "validity_revision": { "type": "integer" }, "ledger_id": { "type": "integer" } }, "required": [ "status", "replayed", "debited", "days", "validity_revision", "credits" ] }, "BillingPolicy": { "type": "object", "properties": { "user_id": { "type": "integer" }, "reseller_id": { "type": "integer" }, "auto_renew": { "type": "boolean" }, "months": { "type": "integer", "enum": [ 1, 3, 6, 12 ] }, "status": { "type": "string" }, "disabled_reason": { "type": [ "string", "null" ] }, "pending": { "type": "boolean" } }, "required": [ "auto_renew", "months", "status", "pending" ] }, "Operation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "playlist.create", "playlist.update", "playlist.test", "transfer.claim", "client.link" ] }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] }, "error": { "type": [ "string", "null" ] }, "result": { "type": [ "object", "null" ], "additionalProperties": true }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "type", "status", "error", "result" ] }, "OperationAccepted": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Operation" }, "replayed": { "type": "boolean" } }, "required": [ "data", "replayed" ] }, "PlaylistInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "kind": { "type": "string", "enum": [ "m3u_url", "hls_url", "xtream" ] }, "url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "writeOnly": true, "description": "Obrigatório para m3u_url/hls_url. Somente HTTP(S) autorizado e aceito pela proteção SSRF." }, "host": { "type": [ "string", "null" ], "format": "uri", "maxLength": 512, "writeOnly": true, "description": "Obrigatório para xtream." }, "username": { "type": [ "string", "null" ], "maxLength": 120, "writeOnly": true }, "password": { "type": [ "string", "null" ], "maxLength": 120, "writeOnly": true }, "epg_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "writeOnly": true }, "pin": { "type": [ "string", "null" ], "pattern": "^[0-9]{4,8}$", "writeOnly": true }, "hidden": { "type": "boolean" }, "is_default": { "type": "boolean" }, "sort": { "type": "integer", "minimum": 0, "maximum": 32000 }, "stream_format_pref": { "type": [ "string", "null" ], "enum": [ "auto", "ts", "hls", null ] }, "user_agent": { "type": [ "string", "null" ], "maxLength": 200 }, "refresh_interval_min": { "type": "integer", "minimum": 60, "maximum": 10080 } }, "required": [ "name", "kind" ], "allOf": [ { "if": { "properties": { "kind": { "const": "m3u_url" } } }, "then": { "required": [ "url" ], "properties": { "url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "writeOnly": true, "description": "Obrigatório para m3u_url/hls_url. Somente HTTP(S) autorizado e aceito pela proteção SSRF." } } } }, { "if": { "properties": { "kind": { "const": "hls_url" } } }, "then": { "required": [ "url" ], "properties": { "url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "writeOnly": true, "description": "Obrigatório para m3u_url/hls_url. Somente HTTP(S) autorizado e aceito pela proteção SSRF." } } } }, { "if": { "properties": { "kind": { "const": "xtream" } } }, "then": { "required": [ "host", "username", "password" ], "properties": { "host": { "type": [ "string", "null" ], "format": "uri", "maxLength": 512, "writeOnly": true, "description": "Obrigatório para xtream." }, "username": { "type": [ "string", "null" ], "maxLength": 120, "writeOnly": true }, "password": { "type": [ "string", "null" ], "maxLength": 120, "writeOnly": true } } } } ] }, "PlaylistWrite": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "kind": { "type": "string", "enum": [ "m3u_url", "hls_url", "xtream" ] }, "url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "writeOnly": true, "description": "Obrigatório para m3u_url/hls_url. Somente HTTP(S) autorizado e aceito pela proteção SSRF." }, "host": { "type": [ "string", "null" ], "format": "uri", "maxLength": 512, "writeOnly": true, "description": "Obrigatório para xtream." }, "username": { "type": [ "string", "null" ], "maxLength": 120, "writeOnly": true }, "password": { "type": [ "string", "null" ], "maxLength": 120, "writeOnly": true }, "epg_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "writeOnly": true }, "pin": { "type": [ "string", "null" ], "pattern": "^[0-9]{4,8}$", "writeOnly": true }, "hidden": { "type": "boolean" }, "is_default": { "type": "boolean" }, "sort": { "type": "integer", "minimum": 0, "maximum": 32000 }, "stream_format_pref": { "type": [ "string", "null" ], "enum": [ "auto", "ts", "hls", null ] }, "user_agent": { "type": [ "string", "null" ], "maxLength": 200 }, "refresh_interval_min": { "type": "integer", "minimum": 60, "maximum": 10080 }, "idempotency_key": { "type": "string", "format": "uuid" } }, "required": [ "name", "kind", "idempotency_key" ], "allOf": [ { "if": { "properties": { "kind": { "const": "m3u_url" } } }, "then": { "required": [ "url" ], "properties": { "url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "writeOnly": true, "description": "Obrigatório para m3u_url/hls_url. Somente HTTP(S) autorizado e aceito pela proteção SSRF." } } } }, { "if": { "properties": { "kind": { "const": "hls_url" } } }, "then": { "required": [ "url" ], "properties": { "url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "writeOnly": true, "description": "Obrigatório para m3u_url/hls_url. Somente HTTP(S) autorizado e aceito pela proteção SSRF." } } } }, { "if": { "properties": { "kind": { "const": "xtream" } } }, "then": { "required": [ "host", "username", "password" ], "properties": { "host": { "type": [ "string", "null" ], "format": "uri", "maxLength": 512, "writeOnly": true, "description": "Obrigatório para xtream." }, "username": { "type": [ "string", "null" ], "maxLength": 120, "writeOnly": true }, "password": { "type": [ "string", "null" ], "maxLength": 120, "writeOnly": true } } } } ] }, "PlaylistPatch": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "writeOnly": true, "description": "Obrigatório para m3u_url/hls_url. Somente HTTP(S) autorizado e aceito pela proteção SSRF." }, "host": { "type": [ "string", "null" ], "format": "uri", "maxLength": 512, "writeOnly": true, "description": "Obrigatório para xtream." }, "username": { "type": [ "string", "null" ], "maxLength": 120, "writeOnly": true }, "password": { "type": [ "string", "null" ], "maxLength": 120, "writeOnly": true }, "epg_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "writeOnly": true }, "pin": { "type": [ "string", "null" ], "pattern": "^[0-9]{4,8}$", "writeOnly": true }, "hidden": { "type": "boolean" }, "is_default": { "type": "boolean" }, "sort": { "type": "integer", "minimum": 0, "maximum": 32000 }, "stream_format_pref": { "type": [ "string", "null" ], "enum": [ "auto", "ts", "hls", null ] }, "user_agent": { "type": [ "string", "null" ], "maxLength": 200 }, "refresh_interval_min": { "type": "integer", "minimum": 60, "maximum": 10080 }, "idempotency_key": { "type": "string", "format": "uuid" } }, "required": [ "idempotency_key" ] }, "Playlist": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "kind": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "syncing", "ready", "error", "disabled" ] }, "hidden": { "type": "boolean" }, "is_default": { "type": "boolean" }, "counts": { "type": [ "object", "null" ], "additionalProperties": { "type": "integer" } }, "provider_status": { "type": [ "string", "null" ] }, "provider_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "provider_max_connections": { "type": [ "integer", "null" ] }, "has_error": { "type": "boolean" }, "consecutive_failures": { "type": "integer" }, "last_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_refresh_at": { "type": [ "string", "null" ], "format": "date-time" }, "published": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "kind", "status", "published" ] }, "PlaylistStatus": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "published": { "type": "boolean" }, "has_error": { "type": "boolean" }, "provider_status": { "type": [ "string", "null" ] }, "last_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_refresh_at": { "type": [ "string", "null" ], "format": "date-time" }, "retry_after": { "type": "integer" } }, "required": [ "id", "status", "published", "retry_after" ] }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "host": { "type": "string", "description": "Somente host; URL completa não é devolvida." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "client.activated", "client.renewed", "client.expired", "funds.changed", "funds.low", "transfer.completed", "transfer.lost", "playlist.synced", "playlist.sync_failed" ] } }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "consecutive_failures": { "type": "integer" }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "host", "events", "status" ] }, "WebhookSecret": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "Mostrado somente ao criar ou rotacionar. String whsec_ literal usada como chave HMAC, não decodificar hexadecimal." } }, "required": [ "secret" ] } ] }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event_id": { "type": [ "string", "null" ], "format": "uuid" }, "event_type": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "delivered", "dead" ] }, "attempts": { "type": "integer" }, "last_status_code": { "type": [ "integer", "null" ] }, "last_outcome": { "type": [ "string", "null" ] }, "last_duration_ms": { "type": [ "integer", "null" ] }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "status", "attempts" ] }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "client.activated", "client.renewed", "client.expired", "funds.changed", "funds.low", "transfer.completed", "transfer.lost", "playlist.synced", "playlist.sync_failed", "webhook.test" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": true, "description": "Dados mínimos próprios do evento. Clientes e listas são identificados por UUID; não inclui fontes ou credenciais de listas." } }, "required": [ "id", "type", "created_at", "data" ] }, "ClientLinkResult": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "linked", "owned" ] }, "replayed": { "type": "boolean" }, "client": { "$ref": "#/components/schemas/Client" } }, "required": [ "status", "replayed", "client" ] } } }, "webhooks": { "resellerEvent": { "post": { "summary": "Receber evento AgiPlay", "description": "Receptor implementado por você; verificar assinatura/raw body e persistir antes de responder. Não é uma rota api.agiplay.app.", "security": [], "parameters": [ { "name": "X-AgiPlay-Event", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-AgiPlay-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-AgiPlay-Delivery", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-AgiPlay-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "204": { "description": "Persistido ou duplicata já persistida." }, "400": { "description": "Payload inválido." }, "401": { "description": "Assinatura ou timestamp inválido." }, "503": { "description": "Não persistido; AgiPlay tentará novamente." } }, "operationId": "resellerReceiveEvent" } } } }