{ "openapi": "3.1.1", "info": { "title": "Juba Player — API de Revenda", "version": "1.1.0", "description": "Contrato público para integrações servidor a servidor de revendedores aprovados. Os endpoints internos de admin, app, portal e provedor não fazem parte deste contrato. Gestão de playlists remotas com autorização explícita do cliente ou vínculo pelo administrador global. Ativação e gestão são independentes." }, "servers": [ { "url": "https://jubaplayer.com/api/v1" } ], "security": [ { "ApiKey": [] } ], "paths": { "/partner/me": { "get": { "summary": "Consultar conta e saldo", "description": "Retorna nome e créditos disponíveis da conta autenticada. Não altera saldo.", "tags": [ "Revenda" ], "responses": { "200": { "description": "Sucesso.", "headers": { "x-request-id": { "description": "UUID gerado pelo servidor para suporte/auditoria.", "schema": { "type": "string", "format": "uuid" } }, "x-ratelimit-limit": { "description": "Limite da janela aplicável.", "schema": { "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requisições restantes nessa janela.", "schema": { "type": "integer" } }, "x-ratelimit-reset": { "description": "Segundos até o fim da janela; não é timestamp Unix.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "credits" ], "properties": { "name": { "type": "string" }, "credits": { "type": "integer", "minimum": 0 } } }, "example": { "name": "Revenda Exemplo", "credits": 30 } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "operationId": "getPartner" } }, "/partner/devices/{deviceId}": { "get": { "summary": "Consultar licença de aparelho vinculado", "description": "Somente aparelhos com pelo menos uma ativação deste revendedor (API ou painel). Aparelhos inexistentes e sem vínculo retornam o mesmo 404. A resposta não contém listas, senhas ou chave do aparelho.", "tags": [ "Revenda" ], "responses": { "200": { "description": "Sucesso.", "headers": { "x-request-id": { "description": "UUID gerado pelo servidor para suporte/auditoria.", "schema": { "type": "string", "format": "uuid" } }, "x-ratelimit-limit": { "description": "Limite da janela aplicável.", "schema": { "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requisições restantes nessa janela.", "schema": { "type": "integer" } }, "x-ratelimit-reset": { "description": "Segundos até o fim da janela; não é timestamp Unix.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceLicense" }, "example": { "deviceId": "aa:bb:cc:dd:ee:ff", "license": { "status": "active", "plan": "annual", "registeredAt": "2026-11-11T12:00:00.000Z", "expiresAt": "2027-11-11T12:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "operationId": "getPartnerDevice", "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/DeviceId" }, "example": "aa:bb:cc:dd:ee:ff" } ] } }, "/partner/activate": { "post": { "summary": "Ativar ou renovar um aparelho", "description": "Consome 1 crédito e acrescenta 365 dias na configuração atual. Se a licença ainda for válida, soma ao vencimento; se expirada, começa agora. O aparelho precisa existir (abrir o app e sincronizar antes). Use Idempotency-Key em toda ativação. A operação real debita saldo; não há modo de simulação neste endpoint.", "tags": [ "Revenda" ], "responses": { "200": { "description": "Sucesso.", "headers": { "x-request-id": { "description": "UUID gerado pelo servidor para suporte/auditoria.", "schema": { "type": "string", "format": "uuid" } }, "x-ratelimit-limit": { "description": "Limite da janela aplicável.", "schema": { "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requisições restantes nessa janela.", "schema": { "type": "integer" } }, "x-ratelimit-reset": { "description": "Segundos até o fim da janela; não é timestamp Unix.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/DeviceLicense" }, { "type": "object", "required": [ "creditsLeft" ], "properties": { "creditsLeft": { "type": "integer", "minimum": 0 } } } ] }, "example": { "deviceId": "aa:bb:cc:dd:ee:ff", "license": { "status": "active", "plan": "annual", "registeredAt": "2026-11-11T12:00:00.000Z", "expiresAt": "2027-11-11T12:00:00.000Z" }, "creditsLeft": 29 } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "operationId": "activatePartnerDevice", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Fortemente recomendado. 8–128 caracteres: letras ASCII, números, ponto, sublinhado, dois-pontos ou hífen. Use um UUID por pedido e persista antes de enviar. Mesmo revendedor + mesma chave + mesmo aparelho retorna a resposta original sem novo débito, inclusive após rotação da API key. Mesma chave com outro aparelho retorna 409. Registro de sucesso conservado enquanto a conta existir; respostas de falha não reservam a chave. Sem cabeçalho, cada POST é uma nova ativação (compatibilidade).", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "a4939de8-394c-4fa5-aa09-21f78433b6db" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "deviceId" ], "properties": { "deviceId": { "$ref": "#/components/schemas/DeviceId" } } }, "example": { "deviceId": "aa:bb:cc:dd:ee:ff" } } } } } }, "/partner/management-invitations": { "post": { "summary": "Solicitar autorização de gestão", "description": "Cria link de uso único válido por 30 minutos. Entregue approvalUrl ao cliente, que deve autenticar o próprio aparelho e aprovar explicitamente. Nunca solicite sua chave de seis dígitos. Reemitir expira o convite anterior da mesma conta/aparelho. Não concede acesso por si só. Limite de escrita: 20/min por conta.", "parameters": [], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "expiresAt", "approvalUrl" ], "properties": { "id": { "type": "string", "format": "uuid" }, "expiresAt": { "type": "string", "format": "date-time" }, "approvalUrl": { "type": "string", "format": "uri" } } }, "example": { "id": "d6f7d632-522c-445a-9664-2cf7adef2f62", "expiresAt": "2026-11-11T12:00:00.000Z", "approvalUrl": "https://jubaplayer.com/entrar#gestao=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "deviceId" ], "properties": { "deviceId": { "$ref": "#/components/schemas/DeviceId" } } }, "example": { "deviceId": "aa:bb:cc:dd:ee:ff" } } } } } }, "/partner/managed-devices": { "get": { "summary": "Listar aparelhos sob gestão", "description": "Somente vínculos atuais; gestão não implica histórico de ativação. Página de 50 itens, ordenada por vínculo mais recente.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Página, começando em 1.", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "total", "pageSize", "items" ], "properties": { "total": { "type": "integer" }, "pageSize": { "const": 50 }, "items": { "type": "array", "items": { "type": "object", "required": [ "deviceId", "managementId", "grantedAt", "grantedBy" ], "properties": { "deviceId": { "$ref": "#/components/schemas/DeviceId" }, "managementId": { "type": "string", "format": "uuid" }, "grantedAt": { "type": "string", "format": "date-time" }, "grantedBy": { "type": "string", "enum": [ "client", "admin" ] } } } } } }, "example": { "total": 1, "pageSize": 50, "items": [ { "deviceId": "aa:bb:cc:dd:ee:ff", "managementId": "d6f7d632-522c-445a-9664-2cf7adef2f62", "grantedAt": "2026-11-11T12:00:00.000Z", "grantedBy": "admin" } ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } } } }, "/partner/devices/{deviceId}/playlists": { "get": { "summary": "Listar metadados das próprias listas", "description": "Exige vínculo atual. Retorna somente listas criadas durante este vínculo, sem URLs ou credenciais. Listas do cliente, do admin e de outros vínculos não aparecem. Limite de leitura: 60/min por conta.", "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/DeviceId" }, "description": "ID do aparelho autorizado." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PlaylistMetadata" } }, "example": [ { "id": "d6f7d632-522c-445a-9664-2cf7adef2f62", "name": "Minha lista", "type": "m3u", "createdAt": "2026-11-11T12:00:00.000Z", "managementId": "d6f7d632-522c-445a-9664-2cf7adef2f62" } ] } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } } }, "post": { "summary": "Adicionar lista remota", "description": "Exige vínculo atual. Só listas criadas pela revenda durante este vínculo podem ser alteradas. Revogação/transferência preserva listas, mas corta acesso; nova autorização não recupera acesso a listas de vínculos antigos. Máximo de 20 listas remotas por aparelho (inclui todas as origens). Corpo completo M3U, Xtream ou código de provedor ativo. URLs e credenciais são somente de escrita. Limite de escrita: 20/min por conta, compartilhado com convites e painel. POST não implementa Idempotency-Key: após timeout consulte as listas antes de repetir, pois pode duplicar. Salve o id retornado.", "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/DeviceId" }, "description": "ID do aparelho autorizado." } ], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } } }, "example": { "id": "d6f7d632-522c-445a-9664-2cf7adef2f62" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistInput" }, "example": { "type": "m3u", "name": "Minha lista", "url": "https://example.com/lista.m3u" } } } } } }, "/partner/devices/{deviceId}/playlists/{id}": { "put": { "summary": "Substituir dados da própria lista", "description": "Exige vínculo atual. Só listas criadas pela revenda durante este vínculo podem ser alteradas. Revogação/transferência preserva listas, mas corta acesso; nova autorização não recupera acesso a listas de vínculos antigos. Máximo de 20 listas remotas por aparelho (inclui todas as origens). Corpo completo M3U, Xtream ou código de provedor ativo. URLs e credenciais são somente de escrita. Limite de escrita: 20/min por conta, compartilhado com convites e painel. Envie todos os campos; preserva o ID. Repetir PUT com o mesmo conteúdo mantém o estado.", "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/DeviceId" }, "description": "ID do aparelho autorizado." }, { "name": "id", "in": "path", "required": true, "description": "UUID da lista retornado na criação.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } } }, "example": { "id": "d6f7d632-522c-445a-9664-2cf7adef2f62" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistInput" }, "example": { "type": "m3u", "name": "Minha lista", "url": "https://example.com/lista.m3u" } } } } }, "delete": { "summary": "Remover a própria lista", "description": "Exige vínculo atual e lista criada nele. Sem corpo JSON. Retorna 204; repetir após sucesso retorna 404. Não remove listas locais da TV.", "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/DeviceId" }, "description": "ID do aparelho autorizado." }, { "name": "id", "in": "path", "required": true, "description": "UUID da lista retornado na criação.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Lista removida; sem corpo." }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Gere no painel do revendedor → Conta e integração. Nunca exponha em frontend, URL ou aplicativos distribuídos." } }, "schemas": { "DeviceId": { "type": "string", "pattern": "^([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}$", "example": "aa:bb:cc:dd:ee:ff" }, "License": { "type": "object", "required": [ "status", "plan", "registeredAt", "expiresAt" ], "properties": { "status": { "type": "string", "enum": [ "trial", "active", "expired" ] }, "plan": { "type": "string", "description": "Ex.: annual, trial, unverified, none. Aceite novos valores." }, "reason": { "type": "string" }, "registeredAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "DeviceLicense": { "type": "object", "required": [ "deviceId", "license" ], "properties": { "deviceId": { "$ref": "#/components/schemas/DeviceId" }, "license": { "$ref": "#/components/schemas/License" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "PlaylistInput": { "oneOf": [ { "type": "object", "required": [ "type", "name", "url" ], "properties": { "type": { "const": "m3u" }, "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "url": { "type": "string", "format": "uri", "maxLength": 2000 }, "epgUrl": { "type": "string", "maxLength": 2000, "description": "URL opcional; aceita string vazia." } } }, { "type": "object", "required": [ "type", "name", "server", "username", "password" ], "properties": { "type": { "const": "xtream" }, "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "server": { "type": "string", "format": "uri", "maxLength": 300 }, "username": { "type": "string", "minLength": 1, "maxLength": 120 }, "password": { "type": "string", "minLength": 1, "maxLength": 200 } } }, { "type": "object", "required": [ "type", "name", "code", "username", "password" ], "properties": { "type": { "const": "provider" }, "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "code": { "type": "string", "pattern": "^[A-Za-z0-9]{3,12}$" }, "username": { "type": "string", "minLength": 1, "maxLength": 120 }, "password": { "type": "string", "minLength": 1, "maxLength": 200 } } } ] }, "PlaylistMetadata": { "type": "object", "required": [ "id", "name", "type", "createdAt", "managementId" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "type": { "type": "string", "enum": [ "m3u", "xtream", "provider" ] }, "createdAt": { "type": "string", "format": "date-time" }, "managementId": { "type": "string", "format": "uuid" } } } }, "responses": { "Error400": { "description": "Formato inválido de ID, JSON ou Idempotency-Key. Corrija a entrada antes de repetir.", "headers": { "x-request-id": { "description": "UUID gerado pelo servidor para suporte/auditoria.", "schema": { "type": "string", "format": "uuid" } }, "x-ratelimit-limit": { "description": "Limite da janela aplicável.", "schema": { "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requisições restantes nessa janela.", "schema": { "type": "integer" } }, "x-ratelimit-reset": { "description": "Segundos até o fim da janela; não é timestamp Unix.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "validation" } } } }, "Error401": { "description": "Chave ausente, inválida, revogada ou conta suspensa/pendente. Confira a conta e a chave.", "headers": { "x-request-id": { "description": "UUID gerado pelo servidor para suporte/auditoria.", "schema": { "type": "string", "format": "uuid" } }, "x-ratelimit-limit": { "description": "Limite da janela aplicável.", "schema": { "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requisições restantes nessa janela.", "schema": { "type": "integer" } }, "x-ratelimit-reset": { "description": "Segundos até o fim da janela; não é timestamp Unix.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_api_key" } } } }, "Error402": { "description": "Saldo insuficiente. Compre créditos no painel antes de tentar novamente.", "headers": { "x-request-id": { "description": "UUID gerado pelo servidor para suporte/auditoria.", "schema": { "type": "string", "format": "uuid" } }, "x-ratelimit-limit": { "description": "Limite da janela aplicável.", "schema": { "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requisições restantes nessa janela.", "schema": { "type": "integer" } }, "x-ratelimit-reset": { "description": "Segundos até o fim da janela; não é timestamp Unix.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "no_credits" } } } }, "Error404": { "description": "Aparelho/lista não encontrado ou fora do escopo permitido. Consulta de licença exige ativação anterior pela própria conta.", "headers": { "x-request-id": { "description": "UUID gerado pelo servidor para suporte/auditoria.", "schema": { "type": "string", "format": "uuid" } }, "x-ratelimit-limit": { "description": "Limite da janela aplicável.", "schema": { "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requisições restantes nessa janela.", "schema": { "type": "integer" } }, "x-ratelimit-reset": { "description": "Segundos até o fim da janela; não é timestamp Unix.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "device_not_found" } } } }, "Error409": { "description": "A mesma Idempotency-Key já foi concluída para outro aparelho. Não reutilize uma chave para operações diferentes.", "headers": { "x-request-id": { "description": "UUID gerado pelo servidor para suporte/auditoria.", "schema": { "type": "string", "format": "uuid" } }, "x-ratelimit-limit": { "description": "Limite da janela aplicável.", "schema": { "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requisições restantes nessa janela.", "schema": { "type": "integer" } }, "x-ratelimit-reset": { "description": "Segundos até o fim da janela; não é timestamp Unix.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "idempotency_conflict" } } } }, "Error413": { "description": "JSON excede 4096 bytes em ativação ou 8192 bytes em gestão.", "headers": { "x-request-id": { "description": "UUID gerado pelo servidor para suporte/auditoria.", "schema": { "type": "string", "format": "uuid" } }, "x-ratelimit-limit": { "description": "Limite da janela aplicável.", "schema": { "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requisições restantes nessa janela.", "schema": { "type": "integer" } }, "x-ratelimit-reset": { "description": "Segundos até o fim da janela; não é timestamp Unix.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "FST_ERR_CTP_BODY_TOO_LARGE" } } } }, "Error415": { "description": "Envie Content-Type: application/json.", "headers": { "x-request-id": { "description": "UUID gerado pelo servidor para suporte/auditoria.", "schema": { "type": "string", "format": "uuid" } }, "x-ratelimit-limit": { "description": "Limite da janela aplicável.", "schema": { "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requisições restantes nessa janela.", "schema": { "type": "integer" } }, "x-ratelimit-reset": { "description": "Segundos até o fim da janela; não é timestamp Unix.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "FST_ERR_CTP_INVALID_MEDIA_TYPE" } } } }, "Error429": { "description": "Limite excedido. Aguarde os segundos do cabeçalho Retry-After antes de repetir.", "headers": { "x-request-id": { "description": "UUID gerado pelo servidor para suporte/auditoria.", "schema": { "type": "string", "format": "uuid" } }, "x-ratelimit-limit": { "description": "Limite da janela aplicável.", "schema": { "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requisições restantes nessa janela.", "schema": { "type": "integer" } }, "x-ratelimit-reset": { "description": "Segundos até o fim da janela; não é timestamp Unix.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited" } } } }, "Error500": { "description": "Erro interno. Em ativações, repita somente com a MESMA Idempotency-Key. Sem ela, confirme com suporte antes de repetir.", "headers": { "x-request-id": { "description": "UUID gerado pelo servidor para suporte/auditoria.", "schema": { "type": "string", "format": "uuid" } }, "x-ratelimit-limit": { "description": "Limite da janela aplicável.", "schema": { "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requisições restantes nessa janela.", "schema": { "type": "integer" } }, "x-ratelimit-reset": { "description": "Segundos até o fim da janela; não é timestamp Unix.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "internal" } } } }, "Error403": { "description": "Gestão não autorizada, revogada ou conta indisponível. Solicite novo consentimento ou intervenção administrativa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "management_required" } } } } } } }