{"openapi":"3.0.0","info":{"title":"LivePix API","version":"2.0.0","description":"\n# Introdução\n\nA API LivePix foi construída utilizando tecnologias modernas, oferecendo segurança, escalabilidade e padronização REST.\n\n## Visão Geral\n\nEsta API permite integração completa com a plataforma LivePix, possibilitando:\n- Gerenciamento de conta e perfil\n- Recebimento e envio de pagamentos e mensagens\n- Gestão de assinaturas e planos\n- Controle de recompensas e moedas\n- Configuração de webhooks para notificações em tempo real\n- Controle remoto de alertas para streamers\n\n## Padronização de Respostas\n\n### Respostas de Sucesso\n- **200 OK**: Requisição bem-sucedida com dados retornados\n- **201 Created**: Recurso criado com sucesso\n- **204 No Content**: Requisição bem-sucedida sem conteúdo de retorno\n\n### Respostas de Erro\nTodas as respostas de erro seguem o formato padrão:\n```json\n{\n \"message\": \"Descrição do erro\"\n}\n```\n\n#### Códigos de Erro Comuns:\n- **400 Bad Request**: Requisição mal formada\n- **401 Unauthorized**: Autenticação ausente ou inválida\n- **403 Forbidden**: Permissões insuficientes\n- **404 Not Found**: Recurso não encontrado\n- **422 Unprocessable Entity**: Dados inválidos\n- **429 Too Many Requests**: Limite de taxa excedido\n- **500 Internal Server Error**: Erro inesperado do servidor\n\n## Rate Limiting\n\nPara garantir o uso justo e a estabilidade da API, cada endpoint possui um limite de requisições que reseta a cada minuto. \n\n### Headers de Rate Limit\nCada resposta inclui headers informativos sobre o status do rate limit:\n- **X-RateLimit-Limit**: Limite máximo de requisições\n- **X-RateLimit-Remaining**: Requisições restantes\n- **X-RateLimit-Reset**: Timestamp Unix do próximo reset\n\nSe você exceder o limite, receberá um erro **429 Too Many Requests** até o próximo reset.\n\n### Limites por Endpoint\n- Endpoints de leitura: 1000 req/min\n- Endpoints de escrita: 100-1000 req/min\n- Endpoints administrativos: 10-50 req/min\n\n# Autenticação OAuth2\n\nA API LivePix implementa o padrão OAuth 2.0 ([RFC 6749](https://tools.ietf.org/html/rfc6749)) para autenticação e autorização segura. Este guia irá ajudá-lo a implementar a autenticação passo a passo.\n\n## 📚 Recursos Úteis\n\n- **Especificação OAuth 2.0**: [RFC 6749](https://tools.ietf.org/html/rfc6749)\n- **OAuth 2.0 Simplified**: [oauth.com](https://oauth.com/)\n- **OAuth 2.0 Playground**: [developers.google.com/oauthplayground](https://developers.google.com/oauthplayground/)\n- **Guia Visual OAuth**: [oauth.net/2/](https://oauth.net/2/)\n\n## 🔑 Pré-requisitos\n\n1. **Criar uma Aplicação OAuth**\n - Acesse [dashboard.livepix.gg](https://dashboard.livepix.gg)\n - Navegue até Configurações → API\n - Clique em \"Nova Aplicação\"\n - Preencha os dados e anote o `client_id` e `client_secret`\n\n2. **Configurar URLs de Redirecionamento**\n - Adicione todas as URLs de callback que sua aplicação usará\n - Para desenvolvimento local, use: `http://localhost:3000/callback`\n - Para produção, use HTTPS: `https://seuapp.com/callback`\n\n## 🔐 Escopos Disponíveis\n\nOs escopos definem as permissões que sua aplicação terá. Solicite apenas os escopos necessários:\n\n| Escopo | Descrição | Uso Típico |\n|--------|-----------|------------|\n| `account:read` | Leitura de informações da conta | Exibir perfil do usuário |\n| `messages:read` | Leitura de mensagens recebidas | Listar histórico de mensagens |\n| `messages:write` | Envio de novas mensagens | Enviar mensagens para outros usuários |\n| `payments:read` | Leitura de pagamentos | Consultar transações |\n| `payments:write` | Criação de pagamentos | Processar novos pagamentos |\n| `subscriptions:read` | Leitura de assinaturas | Verificar status de assinaturas |\n| `subscriptions:write` | Gerenciamento de assinaturas | Criar/cancelar assinaturas |\n| `subscription-plans:read` | Leitura de planos | Listar planos disponíveis |\n| `subscription-plans:write` | Gerenciamento de planos | Criar/editar planos |\n| `rewards:read` | Leitura de recompensas | Consultar recompensas |\n| `wallet:read` | Leitura de carteira | Consultar saldo e transações |\n| `currencies:read` | Leitura de moedas | Consultar moedas aceitas |\n| `webhooks` | Gerenciamento de webhooks | Configurar notificações |\n| `controls` | Controle de alertas | Controlar alertas remotamente |\n\n## 🚀 Métodos de Autenticação\n\n### Método 1: Client Credentials (Para sua própria conta)\n\nUse este método quando sua aplicação precisa acessar apenas sua própria conta LivePix.\n\n#### Exemplo com cURL:\n```bash\ncurl -X POST https://oauth.livepix.gg/oauth2/token \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"grant_type=client_credentials\" \\\n -d \"client_id=SEU_CLIENT_ID\" \\\n -d \"client_secret=SEU_CLIENT_SECRET\" \\\n -d \"scope=account:read wallet:read\"\n```\n\n#### Exemplo com JavaScript (Node.js):\n```javascript\nconst axios = require('axios');\nconst qs = require('querystring');\n\nasync function getAccessToken() {\n try {\n const response = await axios.post(\n 'https://oauth.livepix.gg/oauth2/token',\n qs.stringify({\n grant_type: 'client_credentials',\n client_id: process.env.CLIENT_ID,\n client_secret: process.env.CLIENT_SECRET,\n scope: 'account:read wallet:read'\n }),\n {\n headers: {\n 'Content-Type': 'application/x-www-form-urlencoded'\n }\n }\n );\n \n return response.data.access_token;\n } catch (error) {\n console.error('Erro ao obter token:', error);\n }\n}\n```\n\n#### Exemplo com Python:\n```python\nimport requests\nimport os\n\ndef get_access_token():\n response = requests.post(\n 'https://oauth.livepix.gg/oauth2/token',\n data={\n 'grant_type': 'client_credentials',\n 'client_id': os.environ['CLIENT_ID'],\n 'client_secret': os.environ['CLIENT_SECRET'],\n 'scope': 'account:read wallet:read'\n }\n )\n \n if response.status_code == 200:\n return response.json()['access_token']\n else:\n raise Exception(f\"Erro: {response.text}\")\n```\n\n### Método 2: Authorization Code (Para contas de terceiros)\n\nUse este método quando sua aplicação precisa acessar contas de outros usuários LivePix.\n\n#### Passo 1: Redirecionar o usuário para autorização\n\n```javascript\n// Construir URL de autorização\nconst authUrl = new URL('https://oauth.livepix.gg/oauth2/auth');\nauthUrl.searchParams.append('client_id', 'SEU_CLIENT_ID');\nauthUrl.searchParams.append('redirect_uri', 'https://seuapp.com/callback');\nauthUrl.searchParams.append('response_type', 'code');\nauthUrl.searchParams.append('scope', 'account:read messages:read');\nauthUrl.searchParams.append('state', generateRandomState()); // Protege contra CSRF\n\n// Redirecionar o usuário\nwindow.location.href = authUrl.toString();\n```\n\n#### Passo 2: Receber o código de autorização\n\nApós a aprovação, o usuário será redirecionado para:\n```\nhttps://seuapp.com/callback?code=CODIGO_AUTORIZAÇÃO&state=SEU_STATE\n```\n\n#### Passo 3: Trocar o código por um token de acesso\n\n```javascript\n// No seu servidor backend\napp.get('/callback', async (req, res) => {\n const { code, state } = req.query;\n \n // Verificar o state para prevenir CSRF\n if (state !== sessionState) {\n return res.status(400).send('State inválido');\n }\n \n try {\n const response = await axios.post(\n 'https://oauth.livepix.gg/oauth2/token',\n qs.stringify({\n grant_type: 'authorization_code',\n client_id: process.env.CLIENT_ID,\n client_secret: process.env.CLIENT_SECRET,\n code: code,\n redirect_uri: 'https://seuapp.com/callback'\n }),\n {\n headers: {\n 'Content-Type': 'application/x-www-form-urlencoded'\n }\n }\n );\n \n const { access_token, expires_in } = response.data;\n \n // Armazenar o token de forma segura\n req.session.accessToken = access_token;\n req.session.expiresAt = Date.now() + (expires_in * 1000);\n \n res.redirect('/dashboard');\n } catch (error) {\n console.error('Erro ao trocar código:', error);\n res.status(500).send('Erro na autenticação');\n }\n});\n```\n\n## 🔄 Usando o Token de Acesso\n\nApós obter o token, inclua-o em todas as requisições à API:\n\n```javascript\n// Exemplo de requisição autenticada\nconst response = await axios.get('https://api.livepix.gg/v2/account', {\n headers: {\n 'Authorization': `Bearer ${accessToken}`\n }\n});\n```\n\n```python\n# Exemplo em Python\nheaders = {\n 'Authorization': f'Bearer {access_token}'\n}\nresponse = requests.get('https://api.livepix.gg/v2/account', headers=headers)\n```\n\n## ⚙️ Renovação de Tokens\n\nOs tokens expiram após o tempo especificado em `expires_in` (geralmente 3600 segundos). Implemente uma lógica de renovação:\n\n```javascript\nclass TokenManager {\n constructor(clientId, clientSecret) {\n this.clientId = clientId;\n this.clientSecret = clientSecret;\n this.token = null;\n this.expiresAt = null;\n }\n \n async getToken() {\n // Se o token ainda é válido, retorná-lo\n if (this.token && Date.now() < this.expiresAt - 60000) {\n return this.token;\n }\n \n // Caso contrário, obter um novo token\n const response = await this.requestNewToken();\n this.token = response.access_token;\n this.expiresAt = Date.now() + (response.expires_in * 1000);\n \n return this.token;\n }\n \n async requestNewToken() {\n // Implementar requisição de novo token\n // ...\n }\n}\n```\n\n## 🐛 Problemas Comuns e Soluções\n\n### Erro: \"Invalid client\"\n**Causa**: `client_id` ou `client_secret` incorretos\n**Solução**: Verifique suas credenciais nas configurações da aplicação\n\n### Erro: \"Invalid redirect URI\"\n**Causa**: A URL de callback não está cadastrada\n**Solução**: Adicione a URL exata nas configurações da aplicação\n\n### Erro: \"Invalid scope\"\n**Causa**: Escopo solicitado não existe ou está mal formatado\n**Solução**: Verifique a lista de escopos disponíveis e use espaços para separar múltiplos escopos\n\n### Erro: \"Unauthorized\"\n**Causa**: Token expirado ou inválido\n**Solução**: Obtenha um novo token ou verifique o formato do header Authorization\n\n### Rate Limiting\n**Sintoma**: Múltiplas requisições de token em curto período\n**Solução**: Implemente cache de tokens e reutilize até a expiração\n\n## 🔒 Boas Práticas de Segurança\n\n1. **Nunca exponha o `client_secret`** no código frontend\n2. **Use HTTPS** em produção para todas as URLs de callback\n3. **Implemente o parâmetro `state`** para prevenir ataques CSRF\n4. **Armazene tokens de forma segura** (não em localStorage para aplicações web)\n5. **Implemente renovação automática** de tokens antes da expiração\n6. **Solicite apenas os escopos necessários** para sua aplicação\n7. **Monitore o uso de tokens** e implemente logs de auditoria\n\n## ⚠️ Limite de Emissão de Tokens\n\n- Reutilize tokens até sua expiração (indicada em `expires_in`)\n- Não solicite novos tokens a cada requisição\n- Implemente cache de tokens em sua aplicação\n- Uso excessivo pode resultar em suspensão da conta\n\n# Webhooks\n\nVocê pode configurar uma URL para receber notificações de mensagens e assinaturas recebidas.\n\nAo receber uma mensagem ou assinatura, a URL configurada será chamada com as informações do evento no corpo da requisição. Se a primeira chamada falhar, a URL será chamada a cada 10 minutos até que a mesma retorne uma resposta de sucesso (HTTP 200) em até 24 horas.\n\nPor segurança, apenas algumas informações básicas são enviadas a URL configurada no webhook. Para obter todos os detalhes da mensagem ou assinatura, você deve realizar uma chamada a API.\n ","contact":{"name":"Suporte","url":"https://livepix.gg","email":"ajuda@livepix.gg"}},"servers":[{"url":"https://api.livepix.gg/","description":"Endpoint"}],"tags":[{"name":"Conta","description":"Endpoints para gerenciar informações do perfil e conta do usuário autenticado"},{"name":"Pagamentos","description":"Endpoints para listar pagamentos recebidos e criar novos pagamentos"},{"name":"Mensagens","description":"Endpoints para listar mensagens recebidas e enviar novas mensagens com valores"},{"name":"Assinaturas","description":"Endpoints para gerenciar assinaturas recebidas e planos de assinatura recorrente"},{"name":"Recompensas","description":"Endpoints para listar e gerenciar recompensas e benefícios do usuário"},{"name":"Moedas","description":"Endpoints para consultar configurações de moedas aceitas pelo usuário"},{"name":"Carteira","description":"Endpoints para consultar saldo, transações e recebíveis da carteira"},{"name":"Webhooks","description":"Endpoints para configurar URLs de notificação para eventos da plataforma"},{"name":"Controles de Alertas","description":"Endpoints para controlar remotamente a exibição de alertas em transmissões ao vivo"}],"paths":{"/v2/account":{"get":{"tags":["Conta"],"summary":"Obter detalhes da conta autenticada","description":"Recupera informações detalhadas sobre a conta atualmente autenticada.\n\nEste endpoint retorna as informações de perfil associadas ao token OAuth2\nusado na requisição. Os dados da conta incluem identificação do usuário,\ninformações de contato e preferências de exibição.\n\n**Escopo Obrigatório:** `account:read`\n\n**Limite de Taxa:** 1000 requisições por minuto\n\n**Casos de Uso:**\n- Exibir informações do perfil do usuário em sua aplicação\n- Verificar o status de autenticação da conta\n- Recuperar metadados do usuário para personalização\n","operationId":"getAccount","security":[{"OAuth2":["account:read"]}],"responses":{"200":{"description":"Informações da conta recuperadas com sucesso","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","email","username","displayName"],"properties":{"id":{"type":"string","description":"Identificador único da conta do usuário (MongoDB ObjectId)","example":"61021c7bdabe5e001225b65b","pattern":"^[0-9a-fA-F]{24}$"},"email":{"type":"string","format":"email","description":"Endereço de e-mail principal associado à conta","example":"harry.potter@hogwarts.com"},"username":{"type":"string","description":"Nome de usuário único da conta (usado em URLs e menções)","example":"harrypotter","minLength":3,"maxLength":30,"pattern":"^[a-zA-Z0-9_]+$"},"displayName":{"type":"string","description":"Nome de exibição público mostrado para outros usuários","example":"Harry Potter","minLength":1,"maxLength":50},"avatar":{"type":"string","format":"uri","description":"URL da imagem de avatar do perfil do usuário (pode ser nulo se não configurado)","example":"https://cdn.livepix.gg/profile/avatars/example.png","nullable":true}}}}},"examples":{"perfilCompleto":{"summary":"Usuário com perfil completo","value":{"data":{"id":"61021c7bdabe5e001225b65b","email":"harry.potter@hogwarts.com","username":"harrypotter","displayName":"Harry Potter","avatar":"https://cdn.livepix.gg/profile/avatars/example.png"}}},"perfilMinimo":{"summary":"Usuário com perfil mínimo","value":{"data":{"id":"61021c7bdabe5e001225b65b","email":"usuario@exemplo.com","username":"usuario123","displayName":"Usuário","avatar":null}}}}}}},"401":{"description":"Falha na autenticação ou token inválido","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","enum":["Missing authentication","Invalid authentication"]}}},"examples":{"tokenAusente":{"summary":"Token ausente","value":{"message":"Missing authentication"}},"tokenInvalido":{"summary":"Token inválido ou expirado","value":{"message":"Invalid authentication"}}}}}},"403":{"description":"Token válido mas sem permissões necessárias","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"429":{"description":"Limite de taxa excedido","headers":{"X-RateLimit-Limit":{"description":"Limite máximo de requisições para este endpoint","schema":{"type":"integer","example":1000}},"X-RateLimit-Remaining":{"description":"Número de requisições restantes na janela atual","schema":{"type":"integer","example":0}},"X-RateLimit-Reset":{"description":"Momento em que a janela de limite será resetada (timestamp Unix)","schema":{"type":"integer","example":1640995200}}},"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Too many requests. Please wait before trying again."}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}}},"/v2/controls":{"get":{"tags":["Controles de Alertas"],"summary":"Consultar estado dos controles","description":"Retorna o estado atual dos controles de alertas do usuário autenticado.\nInclui configurações como reprodução automática e outras preferências \nrelacionadas à exibição de alertas em tempo real.\n\n**Rate Limit:** 1000 requests por hora\n","security":[{"OAuth2":["controls"]}],"responses":{"200":{"description":"Estado dos controles retornado com sucesso","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["autoPlay"],"description":"Configurações atuais dos controles de alertas","properties":{"autoPlay":{"type":"boolean","description":"Determina se os alertas são exibidos automaticamente.\n- `true`: Alertas aparecem automaticamente quando recebidos\n- `false`: Alertas ficam em fila aguardando ação manual\n\nÚtil para streamers que querem controlar quando mostrar alertas.\n","example":true}}}}}}}},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'controls'.\n","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"This client is not authorized to perform this action"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Unexpected server error"}}}}}}}},"patch":{"tags":["Controles de Alertas"],"summary":"Atualizar controles de alertas","description":"Atualiza as configurações dos controles de alertas do usuário autenticado.\nPermite modificar comportamentos como reprodução automática de alertas.\n\n**Rate Limit:** 1000 requests por hora\n","security":[{"OAuth2":["controls"]}],"requestBody":{"required":true,"description":"Novas configurações dos controles","content":{"application/json":{"schema":{"type":"object","required":["autoPlay"],"properties":{"autoPlay":{"type":"boolean","description":"Define se os alertas devem ser exibidos automaticamente.\n- `true`: Alertas aparecem automaticamente quando recebidos\n- `false`: Alertas ficam em fila aguardando ação manual\n\nRecomendado `false` para streams ao vivo onde o timing é importante.\n","example":false}}}}}},"responses":{"204":{"description":"Controles atualizados com sucesso.\nNão há conteúdo de retorno.\n"},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'controls'.\n","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"This client is not authorized to perform this action"}}}}}},"422":{"description":"Dados fornecidos não passaram na validação.\nVerifique se o campo autoPlay é um valor booleano.\n","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The provided data is invalid"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Unexpected server error"}}}}}}}}},"/v2/controls/skip":{"post":{"tags":["Controles de Alertas"],"summary":"Pular alerta atual","description":"Pula o alerta que está sendo exibido atualmente ou o próximo na fila.\nÚtil para streamers que precisam pular alertas inadequados ou \nquando há muitos alertas acumulados.\n\nEsta ação remove o alerta da fila sem exibi-lo.\n\n**Rate Limit:** 1000 requests por hora\n","security":[{"OAuth2":["controls"]}],"responses":{"204":{"description":"Comando executado com sucesso.\nO alerta atual foi pulado.\nNão há conteúdo de retorno.\n"},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'controls'.\n","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"This client is not authorized to perform this action"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Unexpected server error"}}}}}}}}},"/v2/controls/replay":{"post":{"tags":["Controles de Alertas"],"summary":"Reexibir último alerta","description":"Reexibe o último alerta que foi mostrado.\nÚtil quando o streamer ou viewers perderam o alerta anterior,\nou quando há problemas técnicos durante a exibição.\n\nEsta ação não remove o alerta do histórico, apenas o exibe novamente.\n\n**Rate Limit:** 1000 requests por hora\n","security":[{"OAuth2":["controls"]}],"responses":{"204":{"description":"Comando executado com sucesso.\nO último alerta foi reexibido.\nNão há conteúdo de retorno.\n"},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'controls'.\n","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"This client is not authorized to perform this action"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Unexpected server error"}}}}}}}}},"/v2/currencies":{"get":{"tags":["Moedas"],"summary":"Listar moedas disponíveis","description":"Retorna a lista de todas as moedas disponíveis para recebimento de pagamentos\npelo usuário autenticado.\n\nInclui tanto moedas fiat (como BRL) quanto criptomoedas configuradas.\nPara criptomoedas, também retorna informações da rede e endereços.\n\n**Rate Limit:** 1000 requests por hora\n","security":[{"OAuth2":["currencies:read"]}],"responses":{"200":{"description":"Lista de moedas disponíveis retornada com sucesso","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","description":"Array de moedas disponíveis para recebimento.\nSempre inclui BRL como primeira moeda da lista.\n","items":{"type":"object","required":["symbol","minimumAmount","decimals"],"properties":{"symbol":{"type":"string","pattern":"^[A-Z]{3,10}$","description":"Símbolo/código da moeda.\nPara moedas fiat: códigos ISO 4217 (ex: BRL, USD)\nPara criptomoedas: símbolos padrão (ex: BTC, ETH, USDT)\n","example":"BRL"},"minimumAmount":{"type":"integer","minimum":1,"description":"Valor mínimo de pagamentos aceitos nesta moeda em centavos.\nPara BRL: 100 = R$ 1,00\nPara criptomoedas: valor convertido para centavos\n","example":100},"decimals":{"type":"integer","minimum":0,"maximum":18,"description":"Número de casas decimais para formatação da moeda.\nPara BRL: 2 (centavos)\nPara criptomoedas: varia (normalmente 8-18)\n","example":2},"crypto":{"type":"object","required":["network","address","userAddress"],"description":"Informações adicionais para criptomoedas.\nCampo presente apenas para moedas digitais.\n","properties":{"network":{"type":"string","description":"Rede blockchain da criptomoeda:\n- `bsc`: Binance Smart Chain\n- `ethereum`: Ethereum Mainnet\n- `polygon`: Polygon Network\n- `tron`: Tron Network\n","example":"bsc"},"address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Endereço do contrato do token na blockchain.\nPara tokens nativos da rede (BNB, ETH), pode ser endereço zero.\n","example":"0x00e1656e45f18ec6747f5a8496fd39b50b38396d"},"userAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Endereço da carteira do usuário para receber esta criptomoeda.\nPagamentos devem ser enviados para este endereço.\n","example":"0xa1b2c3d4e5f6789012345678901234567890abcd"}}}}},"example":[{"symbol":"BRL","minimumAmount":100,"decimals":2},{"symbol":"USDT","minimumAmount":100,"decimals":6,"crypto":{"network":"bsc","address":"0x55d398326f99059fF775485246999027B3197955","userAddress":"0xa1b2c3d4e5f6789012345678901234567890abcd"}},{"symbol":"BNB","minimumAmount":1000,"decimals":18,"crypto":{"network":"bsc","address":"0x0000000000000000000000000000000000000000","userAddress":"0xa1b2c3d4e5f6789012345678901234567890abcd"}}]}}}}}},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'currencies:read'.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}}},"/v2/messages":{"get":{"tags":["Mensagens"],"summary":"Listar mensagens recebidas","description":"Recupera uma lista de mensagens (transações com texto) recebidas pela conta autenticada.\n\nAs mensagens são transações financeiras que incluem um texto do remetente.\nEste endpoint permite filtrar mensagens por diferentes critérios e suporta paginação.\n\n**Escopo Obrigatório:** `messages:read`\n\n**Limite de Taxa:** 1000 requisições por minuto\n\n**Casos de Uso:**\n- Listar mensagens recebidas em lives ou streams\n- Filtrar mensagens por moeda ou comprovante\n- Implementar feed de mensagens com paginação\n","operationId":"listMessages","security":[{"OAuth2":["messages:read"]}],"parameters":[{"in":"query","name":"proof","schema":{"type":"string"},"required":false,"description":"Filtrar mensagens pelo comprovante. Pode ser qualquer string identificadora\n(código Pix, hash de transação, etc.)\n","example":"E0000000020210727170449258921630"},{"in":"query","name":"reference","schema":{"type":"string"},"required":false,"description":"Filtrar mensagens pela referência única","example":"61021c7bdabe5e001225b65b"},{"in":"query","name":"currency","schema":{"type":"string"},"required":false,"description":"Filtrar mensagens por moeda específica","example":"BRL"},{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1},"required":false,"description":"Número da página para paginação (começa em 1)"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"description":"Número máximo de itens por página (máximo 100)"}],"responses":{"200":{"description":"Lista de mensagens recuperada com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","description":"Lista de mensagens","items":{"type":"object","properties":{"id":{"type":"string","description":"Identificador único da mensagem","example":"61021c7bdabe5e001225b65b"},"proof":{"type":"string","description":"Comprovante da transação. Pode ser qualquer identificador\ncomo código Pix, hash de blockchain, etc.\n","example":"E0000000020210727170449258921630"},"reference":{"type":"string","description":"Referência interna da mensagem","example":"61021c7bdabe5e001225b65b"},"username":{"type":"string","description":"Nome de usuário do remetente da mensagem","example":"Harry"},"message":{"type":"string","description":"Texto da mensagem enviada","example":"Olá! Ótimo conteúdo!","maxLength":32},"amount":{"type":"integer","description":"Valor da mensagem em centavos","example":1000},"currency":{"type":"string","description":"Código da moeda","example":"BRL"},"flagged":{"type":"boolean","description":"Indica se a mensagem foi sinalizada como imprópria\npelo sistema de moderação automática\n","example":false},"createdAt":{"type":"string","format":"date-time","description":"Data e hora em que a mensagem foi recebida","example":"2021-01-01T00:00:00-03:00"}}}}}}}}},"401":{"description":"Autenticação inválida","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Invalid authentication"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}},"post":{"tags":["Mensagens"],"summary":"Enviar mensagem com pagamento","description":"Cria uma solicitação para enviar uma mensagem com pagamento anexado.\n\nEste endpoint gera uma URL de checkout onde o remetente pode completar o\npagamento e enviar a mensagem. Suporta divisão de pagamento (split) entre\nmúltiplos destinatários.\n\n**Escopo Obrigatório:** `messages:write`\n\n**Limite de Taxa:** 1000 requisições por minuto\n\n**Fluxo:**\n1. Crie a solicitação de mensagem com este endpoint\n2. Redirecione o usuário para a URL de checkout retornada\n3. O usuário completa o pagamento e envia a mensagem\n4. Após o envio, o usuário é redirecionado para sua `redirectUrl`\n5. A mensagem aparece no feed do destinatário\n","operationId":"createMessage","security":[{"OAuth2":["messages:write"]}],"requestBody":{"required":true,"description":"Dados para criar a mensagem com pagamento","content":{"application/json":{"schema":{"type":"object","required":["username","message","amount","currency","redirectUrl"],"properties":{"username":{"type":"string","minLength":1,"maxLength":32,"description":"Nome de usuário do destinatário da mensagem.\nDeve ser um usuário válido na plataforma.\n","example":"harrypotter"},"message":{"type":"string","minLength":1,"maxLength":32,"description":"Texto da mensagem a ser enviada.\nMáximo de 32 caracteres.\n","example":"Parabéns pelo stream!"},"amount":{"type":"integer","minimum":100,"description":"Valor da mensagem em centavos.\nValor mínimo: R$ 1,00 (100 centavos)\n","example":1000},"currency":{"type":"string","description":"Código da moeda para o pagamento","example":"BRL"},"redirectUrl":{"type":"string","format":"uri","description":"URL para onde o usuário será redirecionado após\ncompletar ou cancelar o pagamento\n","example":"https://example.com/callback"},"split":{"type":"array","description":"Configuração opcional para dividir o pagamento","items":{"type":"object","required":["userId","percentage","taxPayer"],"properties":{"userId":{"type":"string","description":"ID do usuário destinatário da divisão"},"percentage":{"type":"integer","minimum":1,"maximum":99,"description":"Percentual do pagamento"},"taxPayer":{"type":"boolean","description":"Se este destinatário paga as taxas"},"split":{"type":"array","description":"Sub-divisão opcional","items":{"type":"object","properties":{"userId":{"type":"string"},"percentage":{"type":"integer","minimum":1,"maximum":99},"expireAt":{"type":"string"}}}}}}}}}}}},"responses":{"201":{"description":"Solicitação de mensagem criada com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"reference":{"type":"string","description":"Referência única desta solicitação","example":"61021c7bdabe5e001225b65b"},"redirectUrl":{"type":"string","format":"uri","description":"URL do checkout para completar o pagamento e enviar a mensagem","example":"https://checkout.livepix.gg/61021c7bdabe5e001225b65b"}}}}}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"The request is invalid"}}}}}},"401":{"description":"Autenticação inválida","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Invalid authentication"}}}}}},"404":{"description":"Usuário destinatário não encontrado","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"User not found"}}}}}},"422":{"description":"Dados inválidos","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"The provided data is invalid"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}}},"/v2/messages/{messageId}":{"get":{"tags":["Mensagens"],"summary":"Consultar detalhes de uma mensagem","description":"Recupera informações detalhadas de uma mensagem específica.\n\n**Escopo Obrigatório:** `messages:read`\n\n**Limite de Taxa:** 1000 requisições por minuto\n","operationId":"getMessage","security":[{"OAuth2":["messages:read"]}],"parameters":[{"in":"path","name":"messageId","schema":{"type":"string"},"required":true,"description":"Identificador único da mensagem","example":"61021c7bdabe5e001225b65b"}],"responses":{"200":{"description":"Detalhes da mensagem recuperados com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Identificador único da mensagem","example":"61021c7bdabe5e001225b65b"},"proof":{"type":"string","description":"Comprovante do pagamento. Pode ser qualquer string\ncomo código Pix, hash de transação, etc.\n","example":"E0000000020210727170449258921630"},"reference":{"type":"string","description":"Referência interna da mensagem","example":"61021c7bdabe5e001225b65b"},"username":{"type":"string","description":"Nome de usuário do remetente","example":"Harry"},"message":{"type":"string","description":"Texto da mensagem","example":"Olá! Ótimo conteúdo!"},"amount":{"type":"integer","description":"Valor da mensagem em centavos","example":1000},"currency":{"type":"string","description":"Código da moeda","example":"BRL"},"flagged":{"type":"boolean","description":"Indica se a mensagem foi sinalizada como imprópria\n","example":false},"createdAt":{"type":"string","format":"date-time","description":"Data e hora de recebimento da mensagem","example":"2021-01-01T00:00:00-03:00"}}}}}}}},"401":{"description":"Não autorizado a acessar esta mensagem","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"404":{"description":"Mensagem não encontrada","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Message not found"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}}},"/v2/payments":{"get":{"tags":["Pagamentos"],"summary":"Listar pagamentos recebidos","description":"Recupera uma lista de pagamentos recebidos pela conta autenticada.\n\nEste endpoint permite filtrar pagamentos por diferentes critérios como comprovante,\nreferência ou moeda. Suporta paginação através dos parâmetros page e limit.\n\n**Escopo Obrigatório:** `payments:read`\n\n**Limite de Taxa:** 1000 requisições por minuto\n\n**Casos de Uso:**\n- Listar histórico de pagamentos recebidos\n- Filtrar pagamentos por moeda específica\n- Buscar pagamento por comprovante ou referência\n- Implementar listagem paginada de transações\n","operationId":"listPayments","security":[{"OAuth2":["payments:read"]}],"parameters":[{"in":"query","name":"proof","schema":{"type":"string"},"required":false,"description":"Filtrar pagamentos pelo comprovante. O comprovante pode ser qualquer string \nidentificadora do pagamento (ex: código Pix, ID de transação, hash de blockchain, etc.)\n","example":"E0000000020210727170449258921630"},{"in":"query","name":"reference","schema":{"type":"string"},"required":false,"description":"Filtrar pagamentos pela referência única","example":"61021c7bdabe5e001225b65b"},{"in":"query","name":"currency","schema":{"type":"string"},"required":false,"description":"Filtrar pagamentos por moeda específica","example":"BRL"},{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1},"required":false,"description":"Número da página para paginação (começa em 1)"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"description":"Número máximo de itens por página (máximo 100)"}],"responses":{"200":{"description":"Lista de pagamentos recuperada com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","description":"Lista de pagamentos","items":{"type":"object","properties":{"id":{"type":"string","description":"Identificador único do pagamento","example":"61021c7bdabe5e001225b65b"},"proof":{"type":"string","description":"Comprovante do pagamento. Pode ser qualquer identificador externo\ncomo código Pix, hash de transação blockchain, ID de processador, etc.\n","example":"E0000000020210727170449258921630"},"reference":{"type":"string","description":"Referência interna do pagamento","example":"61021c7bdabe5e001225b65b"},"amount":{"type":"integer","description":"Valor do pagamento em centavos (para evitar problemas com ponto flutuante)","example":1000},"currency":{"type":"string","description":"Código da moeda","example":"BRL"},"createdAt":{"type":"string","format":"date-time","description":"Data e hora em que o pagamento foi recebido","example":"2021-01-01T00:00:00-03:00"}}}}}}}}},"401":{"description":"Autenticação inválida","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Invalid authentication"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}},"post":{"tags":["Pagamentos"],"summary":"Criar solicitação de pagamento","description":"Cria uma nova solicitação de pagamento que pode ser paga pelo usuário.\n\nEste endpoint gera uma URL de checkout onde o usuário pode completar o pagamento.\nSuporta divisão de pagamento (split) entre múltiplos destinatários.\n\n**Escopo Obrigatório:** `payments:write`\n\n**Limite de Taxa:** 1000 requisições por minuto\n","operationId":"createPayment","security":[{"OAuth2":["payments:write"]}],"requestBody":{"required":true,"description":"Dados para criar a solicitação de pagamento","content":{"application/json":{"schema":{"type":"object","required":["amount","currency","redirectUrl"],"properties":{"amount":{"type":"integer","minimum":100,"description":"Valor do pagamento em centavos. Use inteiros para evitar problemas\ncom ponto flutuante. Ex: R$ 10,00 = 1000\n","example":1000},"currency":{"type":"string","description":"Código da moeda para o pagamento","example":"BRL"},"redirectUrl":{"type":"string","format":"uri","description":"URL para onde o usuário será redirecionado após completar ou\ncancelar o pagamento\n","example":"https://example.com/callback"},"split":{"type":"array","description":"Configuração opcional para dividir o pagamento entre múltiplos destinatários","items":{"type":"object","required":["userId","percentage","taxPayer"],"properties":{"userId":{"type":"string","description":"ID do usuário destinatário","example":"61021c7bdabe5e001225b65b"},"percentage":{"type":"integer","minimum":1,"maximum":99,"description":"Percentual do pagamento para este destinatário","example":70},"taxPayer":{"type":"boolean","description":"Se este destinatário paga as taxas","example":true},"split":{"type":"array","description":"Sub-divisão opcional do percentual deste destinatário","items":{"type":"object","required":["userId","percentage"],"properties":{"userId":{"type":"string","description":"ID do usuário para sub-divisão"},"percentage":{"type":"integer","minimum":1,"maximum":99,"description":"Percentual da sub-divisão"},"expireAt":{"type":"string","description":"Data de expiração da sub-divisão"}}}}}}}}}}}},"responses":{"201":{"description":"Solicitação de pagamento criada com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"reference":{"type":"string","description":"Referência única desta solicitação de pagamento","example":"61021c7bdabe5e001225b65b"},"redirectUrl":{"type":"string","format":"uri","description":"URL do checkout para completar o pagamento","example":"https://checkout.livepix.gg/61021c7bdabe5e001225b65b"}}}}}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"The request is invalid"}}}}}},"401":{"description":"Autenticação inválida","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Invalid authentication"}}}}}},"422":{"description":"Dados inválidos","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"The provided data is invalid"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}}},"/v2/payments/{paymentId}":{"get":{"tags":["Pagamentos"],"summary":"Consultar detalhes de um pagamento","description":"Recupera informações detalhadas de um pagamento específico.\n\n**Escopo Obrigatório:** `payments:read`\n\n**Limite de Taxa:** 1000 requisições por minuto\n","operationId":"getPayment","security":[{"OAuth2":["payments:read"]}],"parameters":[{"in":"path","name":"paymentId","schema":{"type":"string"},"required":true,"description":"Identificador único do pagamento","example":"61021c7bdabe5e001225b65b"}],"responses":{"200":{"description":"Detalhes do pagamento recuperados com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Identificador único do pagamento","example":"61021c7bdabe5e001225b65b"},"proof":{"type":"string","description":"Comprovante do pagamento. Pode ser qualquer string identificadora\ncomo código Pix, hash de transação, ID do processador, etc.\n","example":"E0000000020210727170449258921630"},"reference":{"type":"string","description":"Referência interna do pagamento","example":"61021c7bdabe5e001225b65b"},"amount":{"type":"integer","description":"Valor do pagamento em centavos","example":1000},"currency":{"type":"string","description":"Código da moeda","example":"BRL"},"createdAt":{"type":"string","format":"date-time","description":"Data e hora de criação do pagamento","example":"2021-01-01T00:00:00-03:00"}}}}}}}},"401":{"description":"Não autorizado a acessar este pagamento","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"404":{"description":"Pagamento não encontrado","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Payment not found"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}}},"/v2/rewards":{"get":{"tags":["Recompensas"],"summary":"Listar recompensas configuradas","description":"Retorna uma lista paginada de todas as recompensas configuradas \npelo usuário autenticado.\nInclui recompensas de todos os tipos (Discord, Twitch, etc.) \nindependentemente do status.\n\n**Rate Limit:** 1000 requests por hora\n","security":[{"OAuth2":["rewards:read"]}],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","minimum":1},"required":false,"default":1,"description":"Número da página para paginação (mínimo 1)","example":1},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"default":20,"description":"Número máximo de itens por página (entre 1 e 100)","example":20}],"responses":{"200":{"description":"Lista de recompensas retornada com sucesso","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","description":"Array de recompensas configuradas","items":{"type":"object","required":["id","type","title","description","triggers","config","amount","status","updatedAt","createdAt"],"properties":{"id":{"type":"string","format":"objectid","description":"Identificador único da recompensa","example":"61021c7bdabe5e001225b65b"},"type":{"type":"string","description":"Tipo da recompensa que determina como ela será concedida:\n- `discord-role`: Adiciona role no Discord\n- `twitch-vip`: Concede VIP no Twitch\n- `custom`: Recompensa personalizada\n","example":"discord-role"},"title":{"type":"string","minLength":1,"description":"Título público da recompensa exibido aos usuários.\nDeve ser claro e atrativo.\n","example":"Grupo dos Apoiadores VIP"},"description":{"type":"string","minLength":1,"description":"Descrição detalhada da recompensa.\nExplica o que o usuário receberá ao atingir os critérios.\n","example":"Tenha acesso exclusivo ao grupo dos apoiadores VIP no Discord!"},"triggers":{"type":"array","description":"Lista de gatilhos que determinam quando a recompensa será concedida.\nPode incluir eventos como pagamentos, assinaturas, etc.\n","items":{"type":"string"},"example":["payment","subscription"]},"config":{"type":"object","description":"Configurações específicas da recompensa baseadas no tipo.\nPara discord-role: {roleId: \"123456\", serverId: \"789012\"}\nPara twitch-vip: {channelId: \"twitchchannel\"}\n","additionalProperties":true,"example":{"roleId":"123456789012345678","serverId":"987654321098765432"}},"amount":{"type":"integer","minimum":0,"description":"Valor mínimo em centavos necessário para conceder a recompensa.\nPara BRL: 1000 = R$ 10,00\nSe 0, será concedida independentemente do valor.\n","example":1000},"status":{"type":"string","description":"Status atual da recompensa:\n- `Enabled`: Recompensa ativa e funcional\n- `Disabled`: Recompensa desativada temporariamente\n- `Error`: Recompensa com erro de configuração\n","example":"Enabled"},"updatedAt":{"type":"string","format":"date-time","description":"Data e hora da última modificação da recompensa","example":"2023-12-01T15:30:00-03:00"},"createdAt":{"type":"string","format":"date-time","description":"Data e hora de criação da recompensa","example":"2023-01-01T10:00:00-03:00"}}}}}}}}},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'rewards:read'.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}}},"/v2/rewards/{rewardId}/grants":{"get":{"tags":["Recompensas"],"summary":"Listar concessões de uma recompensa","description":"Retorna uma lista paginada de todas as concessões (grants) \nde uma recompensa específica.\nMostra quais usuários receberam a recompensa e quando.\n\n**Rate Limit:** 1000 requests por hora\n","security":[{"OAuth2":["rewards:read"]}],"parameters":[{"in":"path","name":"rewardId","schema":{"type":"string","format":"objectid"},"required":true,"description":"Identificador único da recompensa.\nDeve ser uma recompensa válida pertencente ao usuário autenticado.\n","example":"61021c7bdabe5e001225b65b"},{"in":"query","name":"page","schema":{"type":"integer","minimum":1},"required":false,"default":1,"description":"Número da página para paginação (mínimo 1)","example":1},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"default":20,"description":"Número máximo de itens por página (entre 1 e 100)","example":20}],"responses":{"200":{"description":"Lista de concessões da recompensa retornada com sucesso","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","description":"Array de concessões da recompensa ordenadas por data\n(mais recentes primeiro)\n","items":{"type":"object","required":["id","user","data","status","updatedAt","createdAt"],"properties":{"id":{"type":"string","format":"objectid","description":"Identificador único da concessão","example":"61021c7bdabe5e001225b65b"},"user":{"type":"object","required":["id","username"],"description":"Informações do usuário que recebeu a recompensa","properties":{"id":{"type":"string","format":"objectid","description":"ID único do usuário","example":"61021c7bdabe5e001225b65b"},"username":{"type":"string","minLength":1,"maxLength":72,"description":"Nome de usuário do beneficiário","example":"harrypotter"}}},"data":{"type":"object","description":"Dados específicos da concessão.\nPode incluir informações sobre como a recompensa foi aplicada,\nIDs de recursos externos, etc.\n","additionalProperties":true,"example":{"roleGranted":true,"externalId":"discord_123456789"}},"status":{"type":"string","description":"Status da concessão:\n- `Active`: Concessão ativa e funcional\n- `Revoked`: Concessão revogada ou removida\n- `Pending`: Concessão pendente de processamento\n- `Failed`: Falha ao processar a concessão\n","example":"Active"},"updatedAt":{"type":"string","format":"date-time","description":"Data e hora da última atualização da concessão","example":"2023-12-01T15:30:00-03:00"},"createdAt":{"type":"string","format":"date-time","description":"Data e hora em que a recompensa foi concedida","example":"2023-01-15T14:20:00-03:00"}}}}}}}}},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'rewards:read'.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"404":{"description":"Recompensa não encontrada ou não pertence ao usuário autenticado.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Reward not found"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}}},"/v2/subscriptions/plans":{"get":{"tags":["Planos de Assinatura"],"summary":"Listar planos de assinatura","description":"Retorna uma lista paginada de todos os planos de assinatura ativos \npertencentes à conta autenticada.\nApenas planos com status 'active' são retornados.\n\n**Rate Limit:** 50 requests por hora\n","security":[{"OAuth2":["subscription-plans:read"]}],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","minimum":1},"required":false,"default":1,"description":"Número da página para paginação (mínimo 1)","example":1},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"default":20,"description":"Número máximo de itens por página (entre 1 e 100)","example":20}],"responses":{"200":{"description":"Lista de planos retornada com sucesso","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","description":"Array de planos de assinatura ativos","items":{"type":"object","required":["id","slug","name","description","amount","currency","createdAt"],"properties":{"id":{"type":"string","format":"objectid","description":"Identificador único do plano","example":"61021c7bdabe5e001225b65b"},"slug":{"type":"string","minLength":1,"description":"Identificador amigável único do plano.\nUsado para URLs e referências públicas.\n","example":"basic"},"name":{"type":"string","minLength":1,"description":"Nome público do plano exibido aos usuários","example":"Plano Básico"},"description":{"type":"string","minLength":1,"description":"Descrição detalhada do plano e seus benefícios","example":"Plano básico com funcionalidades essenciais"},"amount":{"type":"number","minimum":0,"description":"Valor base do plano em formato decimal.\nEste valor é usado como base para cálculo das assinaturas.\n","example":10},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"Código da moeda do plano (padrão BRL)","example":"BRL"},"createdAt":{"type":"string","format":"date-time","description":"Data e hora de criação do plano","example":"2023-01-01T10:00:00-03:00"}}}}}}}}},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'subscription-plans:read'.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}},"post":{"tags":["Planos de Assinatura"],"summary":"Criar novo plano de assinatura","description":"Cria um novo plano de assinatura para a conta autenticada.\nO plano será criado com status 'active' e estará imediatamente \ndisponível para criar assinaturas.\n\n**Rate Limit:** 10 requests por hora\n","security":[{"OAuth2":["subscription-plans:write"]}],"requestBody":{"required":true,"description":"Dados necessários para criar o plano","content":{"application/json":{"schema":{"type":"object","required":["slug","name","description","amount"],"properties":{"slug":{"type":"string","minLength":1,"pattern":"^[a-z0-9-_]+$","description":"Identificador único amigável para o plano.\nDeve conter apenas letras minúsculas, números, hífens e underscores.\nSerá usado em URLs e referências públicas.\n","example":"basic"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Nome público do plano que será exibido aos usuários.\nDeve ser claro e descritivo.\n","example":"Plano Básico"},"description":{"type":"string","minLength":1,"maxLength":1000,"description":"Descrição detalhada do plano e seus benefícios.\nSerá exibida aos usuários durante a escolha do plano.\n","example":"Plano básico com funcionalidades essenciais para começar"},"amount":{"type":"number","minimum":0,"multipleOf":0.01,"description":"Valor base do plano em formato decimal.\nPara BRL: 10.00 representa R$ 10,00.\nEste valor será usado como base para cálculos de assinaturas.\n","example":10},"currency":{"type":"string","enum":["BRL"],"default":"BRL","description":"Código da moeda do plano.\nAtualmente apenas BRL (Real Brasileiro) é suportado.\n","example":"BRL"}}}}}},"responses":{"201":{"description":"Plano criado com sucesso","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id"],"description":"Dados do plano criado","properties":{"id":{"type":"string","format":"objectid","description":"Identificador único do plano criado.\nUse este ID para operações futuras com o plano.\n","example":"61021c7bdabe5e001225b65b"}}}}}}}},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'subscription-plans:write'.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"422":{"description":"Dados fornecidos não passaram na validação.\nVerifique se o slug não está duplicado e todos os campos obrigatórios estão preenchidos.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"The provided data is invalid"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}}},"/v2/subscriptions/plans/{planId}":{"get":{"tags":["Planos de Assinatura"],"summary":"Obter detalhes de um plano","description":"Retorna informações detalhadas de um plano de assinatura específico.\nApenas planos pertencentes ao usuário autenticado podem ser consultados.\n\n**Rate Limit:** 50 requests por hora\n","security":[{"OAuth2":["subscription-plans:read"]}],"parameters":[{"in":"path","name":"planId","schema":{"type":"string","format":"objectid"},"required":true,"description":"Identificador único do plano.\nDeve ser um plano válido pertencente ao usuário autenticado.\n","example":"61021c7bdabe5e001225b65b"}],"responses":{"200":{"description":"Detalhes do plano retornados com sucesso","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","slug","name","description","amount","currency","createdAt"],"description":"Detalhes completos do plano","properties":{"id":{"type":"string","format":"objectid","description":"Identificador único do plano","example":"61021c7bdabe5e001225b65b"},"slug":{"type":"string","minLength":1,"description":"Identificador amigável único do plano.\nUsado para URLs e referências públicas.\n","example":"basic"},"name":{"type":"string","minLength":1,"description":"Nome público do plano exibido aos usuários","example":"Plano Básico"},"description":{"type":"string","minLength":1,"description":"Descrição detalhada do plano e seus benefícios","example":"Plano básico com funcionalidades essenciais"},"amount":{"type":"number","minimum":0,"description":"Valor base do plano em formato decimal.\nEste valor é usado como base para cálculo das assinaturas.\n","example":10},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"Código da moeda do plano (padrão BRL)","example":"BRL"},"createdAt":{"type":"string","format":"date-time","description":"Data e hora de criação do plano","example":"2023-01-01T10:00:00-03:00"}}}}}}}},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'subscription-plans:read'.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"404":{"description":"Plano não encontrado ou não pertence ao usuário autenticado.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Plan not found"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}},"patch":{"tags":["Planos de Assinatura"],"summary":"Atualizar plano de assinatura","description":"Atualiza as informações de um plano de assinatura existente.\nApenas planos pertencentes ao usuário autenticado podem ser atualizados.\nA moeda não pode ser alterada após a criação do plano.\n\n**Rate Limit:** 50 requests por hora\n","security":[{"OAuth2":["subscription-plans:write"]}],"parameters":[{"in":"path","name":"planId","schema":{"type":"string","format":"objectid"},"required":true,"description":"Identificador único do plano a ser atualizado.\nDeve ser um plano válido pertencente ao usuário autenticado.\n","example":"61021c7bdabe5e001225b65b"}],"requestBody":{"required":true,"description":"Dados para atualização do plano","content":{"application/json":{"schema":{"type":"object","required":["slug","name","description","amount"],"properties":{"slug":{"type":"string","minLength":1,"pattern":"^[a-z0-9-_]+$","description":"Identificador único amigável para o plano.\nDeve conter apenas letras minúsculas, números, hífens e underscores.\nSerá usado em URLs e referências públicas.\n","example":"basic"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Nome público do plano que será exibido aos usuários.\nDeve ser claro e descritivo.\n","example":"Plano Básico Atualizado"},"description":{"type":"string","minLength":1,"maxLength":1000,"description":"Descrição detalhada do plano e seus benefícios.\nSerá exibida aos usuários durante a escolha do plano.\n","example":"Plano básico com funcionalidades essenciais e novos recursos"},"amount":{"type":"number","minimum":0,"multipleOf":0.01,"description":"Novo valor base do plano em formato decimal.\nPara BRL: 15.00 representa R$ 15,00.\nAfetará apenas novas assinaturas criadas após a alteração.\n","example":15}}}}}},"responses":{"204":{"description":"Plano atualizado com sucesso.\nNão há conteúdo de retorno.\n"},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'subscription-plans:write'.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"404":{"description":"Plano não encontrado ou não pertence ao usuário autenticado.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Plan not found"}}}}}},"422":{"description":"Dados fornecidos não passaram na validação.\nVerifique se o slug não está duplicado e todos os campos obrigatórios estão preenchidos.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"The provided data is invalid"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}},"delete":{"tags":["Planos de Assinatura"],"summary":"Desativar plano de assinatura","description":"Desativa um plano de assinatura alterando seu status para 'disabled'.\nPlanos desativados não podem ser usados para criar novas assinaturas,\nmas assinaturas existentes continuam funcionando normalmente.\nEsta operação não remove o plano permanentemente.\n\n**Rate Limit:** 50 requests por hora\n","security":[{"OAuth2":["subscription-plans:write"]}],"parameters":[{"in":"path","name":"planId","schema":{"type":"string","format":"objectid"},"required":true,"description":"Identificador único do plano a ser desativado.\nDeve ser um plano válido pertencente ao usuário autenticado.\n","example":"61021c7bdabe5e001225b65b"}],"responses":{"204":{"description":"Plano desativado com sucesso.\nNão há conteúdo de retorno.\n"},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'subscription-plans:write'.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"404":{"description":"Plano não encontrado ou não pertence ao usuário autenticado.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Plan not found"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}}},"/v2/subscriptions":{"get":{"tags":["Assinaturas"],"summary":"Listar assinaturas recebidas","description":"Retorna uma lista paginada de todas as assinaturas recebidas pela conta autenticada.\nEste endpoint permite filtrar assinaturas por status e moeda.\n\n**Rate Limit:** 1000 requests por hora\n","security":[{"OAuth2":["subscriptions:read"]}],"parameters":[{"in":"query","name":"status","schema":{"type":"string","enum":["active","pending","cancelled"]},"required":false,"description":"Filtrar assinaturas pelo status atual:\n- `active`: Assinaturas ativas com pagamentos em dia\n- `pending`: Assinaturas pendentes de confirmação de pagamento\n- `cancelled`: Assinaturas canceladas pelo usuário ou sistema\n","example":"active"},{"in":"query","name":"currency","schema":{"type":"string","pattern":"^[A-Z]{3}$"},"required":false,"description":"Filtrar assinaturas pela moeda do pagamento.\nDeve ser fornecido como código de 3 letras (ex: BRL, USD).\n","example":"BRL"},{"in":"query","name":"page","schema":{"type":"integer","minimum":1},"required":false,"default":1,"description":"Número da página para paginação (mínimo 1)","example":1},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"default":20,"description":"Número máximo de itens por página (entre 1 e 100)","example":20}],"responses":{"200":{"description":"Lista de assinaturas retornada com sucesso","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","description":"Array de assinaturas recebidas","items":{"type":"object","required":["id","subscriber","months","currency","amount","recurrence","status","renewAt","updatedAt","createdAt"],"properties":{"id":{"type":"string","format":"objectid","description":"Identificador único da assinatura","example":"61021c7bdabe5e001225b65b"},"subscriber":{"type":"string","minLength":1,"maxLength":72,"description":"Nome de usuário do assinante","example":"harrypotter"},"months":{"type":"integer","minimum":0,"description":"Número total de renovações/meses pagos da assinatura.\nAumenta a cada pagamento bem-sucedido.\n","example":3},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"Código da moeda da assinatura (padrão BRL)","example":"BRL"},"amount":{"type":"integer","minimum":1,"description":"Valor da assinatura em centavos.\nPara BRL: 1000 = R$ 10,00\n","example":1000},"recurrence":{"type":"string","enum":["monthly","quarterly","semiannual","yearly"],"description":"Frequência de cobrança da assinatura:\n- `monthly`: Mensal (a cada 30 dias)\n- `quarterly`: Trimestral (a cada 3 meses)\n- `semiannual`: Semestral (a cada 6 meses)\n- `yearly`: Anual (a cada 12 meses)\n","example":"monthly"},"status":{"type":"string","enum":["active","pending","cancelled"],"description":"Status atual da assinatura:\n- `active`: Ativa e em dia com pagamentos\n- `pending`: Pendente de confirmação de pagamento\n- `cancelled`: Cancelada permanentemente\n","example":"active"},"renewAt":{"type":"string","format":"date-time","description":"Data e hora da próxima renovação/cobrança da assinatura.\nFormato ISO 8601 com timezone.\n","example":"2024-01-01T00:00:00-03:00"},"updatedAt":{"type":"string","format":"date-time","description":"Data e hora da última modificação da assinatura","example":"2023-12-01T15:30:00-03:00"},"createdAt":{"type":"string","format":"date-time","description":"Data e hora de criação da assinatura","example":"2023-01-01T10:00:00-03:00"}}}}}}}}},"400":{"description":"Requisição inválida. Parâmetros fornecidos estão em formato incorreto.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"The request is invalid"}}}}}},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'subscriptions:read'.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"422":{"description":"Dados fornecidos não passaram na validação.\nVerifique os parâmetros de consulta.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"The provided data is invalid"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}},"post":{"tags":["Assinaturas"],"summary":"Criar nova assinatura","description":"Cria uma nova assinatura para um plano específico.\nEste endpoint inicia o processo de pagamento e retorna uma URL para checkout.\nO assinante receberá alertas de renovação no e-mail fornecido.\n\n**Rate Limit:** 1000 requests por hora\n","security":[{"OAuth2":["subscriptions:write"]}],"requestBody":{"required":true,"description":"Dados necessários para criar a assinatura","content":{"application/json":{"schema":{"type":"object","required":["planId","recurrence","subscriber","redirectUrl"],"properties":{"planId":{"type":"string","format":"objectid","description":"Identificador único do plano de assinatura.\nDeve ser um plano ativo e válido do usuário.\n","example":"61021c7bdabe5e001225b65b"},"recurrence":{"type":"string","enum":["monthly","quarterly","semiannual","yearly"],"description":"Frequência de cobrança da assinatura:\n- `monthly`: Cobrança mensal\n- `quarterly`: Cobrança a cada 3 meses\n- `semiannual`: Cobrança a cada 6 meses\n- `yearly`: Cobrança anual\n","example":"monthly"},"subscriber":{"type":"object","required":["username","email"],"description":"Informações do assinante","properties":{"username":{"type":"string","minLength":1,"maxLength":72,"description":"Nome de usuário do assinante.\nSerá exibido nos alertas e notificações.\n","example":"harrypotter"},"email":{"type":"string","format":"email","maxLength":255,"description":"E-mail válido do assinante.\nUsado para enviar alertas de renovação e notificações.\n","example":"harry.potter@hogwarts.com"}}},"redirectUrl":{"type":"string","format":"uri","maxLength":2048,"description":"URL completa para redirecionar o usuário após completar o pagamento.\nDeve ser uma URL válida e acessível (HTTPS recomendado).\n","example":"https://example.com/callback"},"split":{"type":"array","description":"Configuração opcional de divisão de receita.\nPermite dividir automaticamente os pagamentos entre múltiplos usuários.\n","maxItems":10,"items":{"type":"object","required":["userId","percentage","taxPayer"],"properties":{"userId":{"type":"string","format":"objectid","description":"ID do usuário que receberá parte da receita"},"percentage":{"type":"integer","minimum":1,"maximum":99,"description":"Porcentagem da receita para este usuário (1-99).\nTotal de todas as porcentagens deve somar 100%.\n"},"taxPayer":{"type":"boolean","description":"Se true, este usuário será responsável pelo pagamento de taxas.\n"},"split":{"type":"array","description":"Sub-divisões adicionais (máximo 2 níveis)","maxItems":5,"items":{"type":"object","required":["userId","percentage"],"properties":{"userId":{"type":"string","format":"objectid"},"percentage":{"type":"integer","minimum":1,"maximum":99},"expireAt":{"type":"string","format":"date-time","description":"Data de expiração desta sub-divisão"}}}}}}}}}}}},"responses":{"201":{"description":"Assinatura criada com sucesso","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["reference","redirectUrl"],"description":"Dados da assinatura criada","properties":{"reference":{"type":"string","format":"objectid","description":"Referência única da assinatura criada.\nUse este ID para rastrear e consultar a assinatura.\n","example":"61021c7bdabe5e001225b65b"},"redirectUrl":{"type":"string","format":"uri","description":"URL do checkout para o usuário completar o pagamento.\nRedirecione o assinante para esta URL para finalizar a assinatura.\n","example":"https://checkout.livepix.gg/61021c7bdabe5e001225b65b"}}}}}}}},"400":{"description":"Requisição inválida. Parâmetros fornecidos estão em formato incorreto.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"The request is invalid"}}}}}},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'subscriptions:write'.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"422":{"description":"Dados fornecidos não passaram na validação.\nVerifique os parâmetros do corpo da requisição.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"The provided data is invalid"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}}},"/v2/subscriptions/{subscriptionId}":{"get":{"tags":["Assinaturas"],"summary":"Obter detalhes de uma assinatura","description":"Retorna informações detalhadas de uma assinatura específica.\nApenas assinaturas pertencentes ao usuário autenticado podem ser consultadas.\n\n**Rate Limit:** 1000 requests por hora\n","security":[{"OAuth2":["subscriptions:read"]}],"parameters":[{"in":"path","name":"subscriptionId","schema":{"type":"string","format":"objectid"},"required":true,"description":"Identificador único da assinatura.\nDeve ser uma assinatura válida pertencente ao usuário autenticado.\n","example":"61021c7bdabe5e001225b65b"}],"responses":{"200":{"description":"Detalhes da assinatura retornados com sucesso","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","subscriber","months","currency","amount","recurrence","status","renewAt","updatedAt","createdAt"],"description":"Detalhes completos da assinatura","properties":{"id":{"type":"string","format":"objectid","description":"Identificador único da assinatura","example":"61021c7bdabe5e001225b65b"},"subscriber":{"type":"string","minLength":1,"maxLength":72,"description":"Nome de usuário do assinante","example":"harrypotter"},"months":{"type":"integer","minimum":0,"description":"Número total de renovações/meses pagos da assinatura.\nAumenta a cada pagamento bem-sucedido.\n","example":3},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"Código da moeda da assinatura (padrão BRL)","example":"BRL"},"amount":{"type":"integer","minimum":1,"description":"Valor da assinatura em centavos.\nPara BRL: 1000 = R$ 10,00\n","example":1000},"recurrence":{"type":"string","enum":["monthly","quarterly","semiannual","yearly"],"description":"Frequência de cobrança da assinatura:\n- `monthly`: Mensal (a cada 30 dias)\n- `quarterly`: Trimestral (a cada 3 meses)\n- `semiannual`: Semestral (a cada 6 meses)\n- `yearly`: Anual (a cada 12 meses)\n","example":"monthly"},"status":{"type":"string","enum":["active","pending","cancelled"],"description":"Status atual da assinatura:\n- `active`: Ativa e em dia com pagamentos\n- `pending`: Pendente de confirmação de pagamento\n- `cancelled`: Cancelada permanentemente\n","example":"active"},"renewAt":{"type":"string","format":"date-time","description":"Data e hora da próxima renovação/cobrança da assinatura.\nFormato ISO 8601 com timezone.\n","example":"2024-01-01T00:00:00-03:00"},"updatedAt":{"type":"string","format":"date-time","description":"Data e hora da última modificação da assinatura","example":"2023-12-01T15:30:00-03:00"},"createdAt":{"type":"string","format":"date-time","description":"Data e hora de criação da assinatura","example":"2023-01-01T10:00:00-03:00"}}}}}}}},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'subscriptions:read'.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"404":{"description":"Assinatura não encontrada ou não pertence ao usuário autenticado.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Subscription not found"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}},"delete":{"tags":["Assinaturas"],"summary":"Cancelar assinatura","description":"Cancela permanentemente uma assinatura ativa.\nUma vez cancelada, a assinatura não pode ser reativada e não haverão mais cobranças.\nO assinante pode opcionalmente fornecer um motivo para o cancelamento.\n\n**Rate Limit:** 1000 requests por hora\n","security":[{"OAuth2":["subscriptions:write"]}],"parameters":[{"in":"path","name":"subscriptionId","schema":{"type":"string","format":"objectid"},"required":true,"description":"Identificador único da assinatura a ser cancelada.\nDeve ser uma assinatura válida pertencente ao usuário autenticado.\n","example":"61021c7bdabe5e001225b65b"}],"requestBody":{"required":false,"description":"Dados opcionais para o cancelamento","content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500,"description":"Motivo opcional para o cancelamento da assinatura.\nEste campo é usado para fins de análise e melhoria do serviço.\n","example":"Não preciso mais do serviço"}}}}}},"responses":{"204":{"description":"Assinatura cancelada com sucesso.\nNão há conteúdo de retorno.\n"},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'subscriptions:write'.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"404":{"description":"Assinatura não encontrada ou não pertence ao usuário autenticado.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Subscription not found"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}}},"/v2/subscriptions/{subscriptionId}/transactions":{"get":{"tags":["Assinaturas"],"summary":"Listar transações de uma assinatura","description":"Retorna uma lista paginada de todas as transações (pagamentos) \nrecebidas para uma assinatura específica.\nPermite filtrar por comprovante PIX para busca específica.\n\n**Rate Limit:** Sem limite específico\n","security":[{"OAuth2":["subscriptions:read"]}],"parameters":[{"in":"path","name":"subscriptionId","schema":{"type":"string","format":"objectid"},"required":true,"description":"Identificador único da assinatura.\nDeve ser uma assinatura válida pertencente ao usuário autenticado.\n","example":"61021c7bdabe5e001225b65b"},{"in":"query","name":"proof","schema":{"type":"string","pattern":"^E[0-9]{30}$"},"required":false,"description":"Filtrar transações pelo ID do comprovante PIX.\nFormato: E seguido de 30 dígitos numéricos.\n","example":"E0000000020210727170449258921630"},{"in":"query","name":"page","schema":{"type":"integer","minimum":1},"required":false,"default":1,"description":"Número da página para paginação (mínimo 1)","example":1},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"default":20,"description":"Número máximo de itens por página (entre 1 e 100)","example":20}],"responses":{"200":{"description":"Lista de transações da assinatura retornada com sucesso","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","description":"Array de transações de pagamento da assinatura","items":{"type":"object","required":["id","proof","amount","createdAt"],"properties":{"id":{"type":"string","format":"objectid","description":"Identificador único da transação","example":"61021c7bdabe5e001225b65b"},"proof":{"type":"string","pattern":"^E[0-9]{30}$","description":"Identificador único do comprovante PIX.\nUsado para rastreamento e validação do pagamento.\n","example":"E0000000020210727170449258921630"},"amount":{"type":"integer","minimum":1,"description":"Valor da transação em centavos.\nPara BRL: 1000 = R$ 10,00\n","example":1000},"createdAt":{"type":"string","format":"date-time","description":"Data e hora em que a transação foi processada e confirmada.\nFormato ISO 8601 com timezone.\n","example":"2023-07-27T17:04:49-03:00"}}}}}}}}},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'subscriptions:read'.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"404":{"description":"Assinatura não encontrada ou não pertence ao usuário autenticado.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Subscription not found"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}}},"/v2/wallet":{"get":{"tags":["Carteira"],"summary":"Consultar saldos da carteira","description":"Retorna os saldos de todas as moedas disponíveis na carteira do usuário autenticado.\nInclui saldo disponível, saldo em trânsito e saldo pendente para cada moeda.\nSe não há conta criada para o usuário, retorna erro 404.\n\n**Rate Limit:** 100 requests por hora\n","security":[{"OAuth2":["wallet:read"]}],"responses":{"200":{"description":"Saldos da carteira retornados com sucesso","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","description":"Array de contas/carteiras por moeda","items":{"type":"object","required":["currency","balance","balanceHeld","balancePending"],"properties":{"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"Código da moeda da carteira.\nCada moeda possui uma carteira separada.\n","example":"BRL"},"balance":{"type":"integer","minimum":0,"description":"Saldo disponível da carteira em centavos.\nEste valor está disponível para saque imediato.\nPara BRL: 1000 = R$ 10,00\n","example":2500},"balanceHeld":{"type":"integer","minimum":0,"description":"Saldo em trânsito em centavos.\nRepresenta valores sacados que estão pendentes de confirmação.\nNão está disponível para novo saque até ser confirmado ou cancelado.\n","example":0},"balancePending":{"type":"integer","minimum":0,"description":"Saldo pendente de liberação em centavos.\nRepresenta pagamentos recebidos que ainda não foram liberados\ndevido ao prazo de compensação (normalmente 1 dia útil).\n","example":500}}}}}}}}},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'wallet:read'.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"404":{"description":"Conta de carteira não encontrada para o usuário.\nIsso pode ocorrer se o usuário ainda não recebeu pagamentos.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Account not found"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}}},"/v2/wallet/{currency}/transactions":{"get":{"tags":["Carteira"],"summary":"Listar transações da carteira","description":"Retorna uma lista paginada de todas as transações (entradas e saídas)\nde uma carteira específica por moeda.\nInclui histórico completo de movimentações financeiras.\n\n**Rate Limit:** 1000 requests por hora\n","security":[{"OAuth2":["wallet:read"]}],"parameters":[{"in":"path","name":"currency","schema":{"type":"string","pattern":"^[A-Z]{3}$"},"required":true,"description":"Código da moeda das transações a serem consultadas.\nDeve ser uma moeda suportada pela plataforma.\n","example":"BRL"},{"in":"query","name":"page","schema":{"type":"integer","minimum":1},"required":false,"default":1,"description":"Número da página para paginação (mínimo 1)","example":1},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"default":20,"description":"Número máximo de itens por página (entre 1 e 100)","example":20}],"responses":{"200":{"description":"Lista de transações da carteira retornada com sucesso","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","description":"Array de transações da carteira ordenadas por data\n(mais recentes primeiro)\n","items":{"type":"object","required":["proof","amount","balance","timestamp"],"properties":{"proof":{"type":"string","pattern":"^E[0-9]{30}$","description":"Identificador único do comprovante da transação.\nPara transações PIX, segue o padrão E + 30 dígitos.\nUsado para rastreamento e conciliação.\n","example":"E0000000020210727170449258921630"},"amount":{"type":"integer","description":"Valor da transação em centavos.\nValores positivos representam entradas (créditos).\nValores negativos representam saídas (débitos).\nPara BRL: 1000 = R$ 10,00, -500 = -R$ 5,00\n","example":1000},"balance":{"type":"integer","minimum":0,"description":"Saldo da carteira após esta transação em centavos.\nRepresenta o saldo acumulado até o momento desta transação.\n","example":3500},"timestamp":{"type":"integer","minimum":0,"description":"Timestamp Unix da transação (em segundos).\nRepresenta o momento exato em que a transação foi processada.\n","example":1627409049}}}}}}}}},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'wallet:read'.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}}},"/v2/wallet/{currency}/receivables":{"get":{"tags":["Carteira"],"summary":"Listar recebíveis pendentes","description":"Retorna uma lista paginada de transações que foram recebidas \nmas ainda estão pendentes de liberação na carteira.\nEstas transações ainda não estão disponíveis para saque devido \nao prazo de compensação (normalmente 1 dia útil).\n\n**Rate Limit:** 1000 requests por hora\n","security":[{"OAuth2":["wallet:read"]}],"parameters":[{"in":"path","name":"currency","schema":{"type":"string","pattern":"^[A-Z]{3}$"},"required":true,"description":"Código da moeda dos recebíveis a serem consultados.\nDeve ser uma moeda suportada pela plataforma.\n","example":"BRL"},{"in":"query","name":"page","schema":{"type":"integer","minimum":1},"required":false,"default":1,"description":"Número da página para paginação (mínimo 1)","example":1},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"default":20,"description":"Número máximo de itens por página (entre 1 e 100)","example":20}],"responses":{"200":{"description":"Lista de recebíveis pendentes retornada com sucesso","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","description":"Array de recebíveis pendentes ordenados por data de liberação\n(próximas liberações primeiro)\n","items":{"type":"object","required":["proof","amount","releaseAt","timestamp"],"properties":{"proof":{"type":"string","pattern":"^E[0-9]{30}$","description":"Identificador único do comprovante da transação.\nPara transações PIX, segue o padrão E + 30 dígitos.\nUsado para rastreamento e conciliação.\n","example":"E0000000020210727170449258921630"},"amount":{"type":"integer","minimum":1,"description":"Valor do recebível em centavos.\nSempre positivo pois representa valores a serem liberados.\nPara BRL: 1000 = R$ 10,00\n","example":1500},"releaseAt":{"type":"integer","minimum":0,"description":"Timestamp Unix de quando o valor será liberado (em segundos).\nApós este momento, o valor estará disponível no saldo da carteira.\nNormalmente é 1 dia útil após o recebimento.\n","example":1627495449},"timestamp":{"type":"integer","minimum":0,"description":"Timestamp Unix de quando a transação foi originalmente recebida (em segundos).\nRepresenta o momento do pagamento original.\n","example":1627409049}}}}}}}}},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'wallet:read'.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}}},"/v2/webhooks":{"get":{"tags":["Webhooks"],"summary":"Listar webhooks configurados","description":"Retorna uma lista paginada de todos os webhooks configurados \npelo cliente autenticado.\nCada cliente pode ter até 3 webhooks configurados simultaneamente.\n\n**Rate Limit:** 50 requests por hora\n","security":[{"OAuth2":["webhooks"]}],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","minimum":1},"required":false,"default":1,"description":"Número da página para paginação (mínimo 1)","example":1},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"default":20,"description":"Número máximo de itens por página (entre 1 e 100)","example":20}],"responses":{"200":{"description":"Lista de webhooks retornada com sucesso","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","description":"Array de webhooks configurados para o cliente","maxItems":3,"items":{"type":"object","required":["id","url","createdAt"],"properties":{"id":{"type":"string","format":"objectid","description":"Identificador único do webhook","example":"61021c7bdabe5e001225b65b"},"url":{"type":"string","format":"uri","maxLength":2048,"description":"URL completa do webhook onde os eventos serão enviados.\nDeve ser acessível publicamente e aceitar requisições POST.\n","example":"https://example.com/webhook/livepix"},"createdAt":{"type":"string","format":"date-time","description":"Data e hora de criação do webhook","example":"2023-01-01T10:00:00-03:00"}}}}}}}}},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'webhooks'.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}},"post":{"tags":["Webhooks"],"summary":"Criar novo webhook","description":"Cria um novo webhook para receber eventos da plataforma.\nCada cliente pode ter até 3 webhooks configurados simultaneamente.\nO webhook receberá eventos como pagamentos, mensagens e assinaturas.\n\n**Rate Limit:** 10 requests por hora\n","security":[{"OAuth2":["webhooks"]}],"requestBody":{"required":true,"description":"Dados necessários para criar o webhook","content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","maxLength":2048,"description":"URL completa onde os eventos serão enviados via POST.\nDeve ser:\n- Acessível publicamente\n- Aceitar requisições POST\n- Retornar status HTTP 200 para confirmar recebimento\n- HTTPS recomendado para segurança\n","example":"https://example.com/webhook/livepix"}}}}}},"responses":{"201":{"description":"Webhook criado com sucesso","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id"],"description":"Dados do webhook criado","properties":{"id":{"type":"string","format":"objectid","description":"Identificador único do webhook criado.\nUse este ID para operações futuras com o webhook.\n","example":"61021c7bdabe5e001225b65b"}}}}}}}},"400":{"description":"Limite de webhooks excedido.\nCada cliente pode ter no máximo 3 webhooks configurados.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"You are not allowed to create more webhooks for this user"}}}}}},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'webhooks'.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"422":{"description":"Dados fornecidos não passaram na validação.\nVerifique se a URL é válida e acessível.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"The provided data is invalid"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}}},"/v2/webhooks/{webhookId}":{"delete":{"tags":["Webhooks"],"summary":"Excluir webhook","description":"Remove permanentemente um webhook configurado.\nApós a exclusão, o webhook não receberá mais eventos.\nEsta operação não pode ser desfeita.\n\n**Rate Limit:** 50 requests por hora\n","security":[{"OAuth2":["webhooks"]}],"parameters":[{"in":"path","name":"webhookId","schema":{"type":"string","format":"objectid"},"required":true,"description":"Identificador único do webhook a ser excluído.\nDeve ser um webhook válido pertencente ao cliente autenticado.\n","example":"61021c7bdabe5e001225b65b"}],"responses":{"204":{"description":"Webhook excluído com sucesso.\nNão há conteúdo de retorno.\n"},"401":{"description":"Token de autenticação inválido, expirado ou sem permissão necessária.\nVerifique se o token possui o escopo 'webhooks' e se o webhook\npertence ao cliente autenticado.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}}}}},"404":{"description":"Webhook não encontrado ou não pertence ao cliente autenticado.\n","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Webhook not found"}}}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}}}}}}}}},"components":{"responses":{"Unauthorized":{"description":"Falha na autenticação ou token inválido/expirado","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","enum":["Missing authentication","Invalid authentication"]}}},"examples":{"missingToken":{"summary":"Token ausente","value":{"message":"Missing authentication"}},"invalidToken":{"summary":"Token inválido ou expirado","value":{"message":"Invalid authentication"}}}}}},"Forbidden":{"description":"Token válido mas sem permissões necessárias","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"This client is not authorized to perform this action"}}},"examples":{"insufficientScope":{"summary":"Permissões insuficientes","value":{"message":"This client is not authorized to perform this action"}}}}}},"NotFound":{"description":"Recurso não encontrado","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro"}}},"examples":{"resourceNotFound":{"summary":"Recurso não encontrado","value":{"message":"Resource not found"}}}}}},"UnprocessableEntity":{"description":"Dados fornecidos são inválidos ou mal formatados","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"The provided data is invalid"}}},"examples":{"invalidData":{"summary":"Dados inválidos","value":{"message":"The provided data is invalid"}}}}}},"BadRequest":{"description":"Requisição inválida ou mal formada","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro"}}},"examples":{"invalidRequest":{"summary":"Requisição inválida","value":{"message":"The request is invalid"}}}}}},"TooManyRequests":{"description":"Limite de taxa excedido","headers":{"X-RateLimit-Limit":{"description":"Limite máximo de requisições para este endpoint","schema":{"type":"integer","example":1000}},"X-RateLimit-Remaining":{"description":"Número de requisições restantes na janela atual","schema":{"type":"integer","example":0}},"X-RateLimit-Reset":{"description":"Momento em que a janela de limite será resetada (timestamp Unix)","schema":{"type":"integer","example":1640995200}}},"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Too many requests. Please wait before trying again."}}},"examples":{"rateLimitExceeded":{"summary":"Limite de taxa excedido","value":{"message":"Too many requests. Please wait before trying again."}}}}}},"InternalServerError":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Mensagem descritiva do erro","example":"Unexpected server error"}}},"examples":{"serverError":{"summary":"Erro inesperado do servidor","value":{"message":"Unexpected server error"}}}}}}},"securitySchemes":{"OAuth2":{"description":"Sistema de autenticação OAuth 2.0 da LivePix.\n\n**Como obter acesso:**\n1. Registre sua aplicação no painel de desenvolvedores\n2. Configure as URLs de callback adequadas\n3. Solicite autorização do usuário com os escopos necessários\n4. Troque o código de autorização por um token de acesso\n\n**Tipos de autenticação disponíveis:**\n- **Authorization Code**: Para aplicações web com backend seguro\n- **Client Credentials**: Para aplicações servidor-para-servidor\n\nUtilize os escopos abaixo para acessar as informações específicas do usuário.\n","type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://oauth.livepix.gg/oauth2/auth","tokenUrl":"https://oauth.livepix.gg/oauth2/token","scopes":{"offline":"Permite renovar o token de acesso automaticamente.\nNecessário para aplicações que precisam de acesso contínuo\nsem intervenção do usuário.\n","account:read":"Permite acesso de leitura aos dados básicos da conta do usuário.\nInclui informações como nome de usuário, ID único e dados públicos do perfil.\n","currencies:read":"Permite consultar as moedas disponíveis para pagamentos do usuário.\nInclui tanto moedas fiat (BRL) quanto criptomoedas configuradas,\ncom informações de endereços e redes blockchain.\n","rewards:read":"Permite consultar as recompensas configuradas pelo usuário.\nInclui acesso à lista de recompensas e suas concessões (grants)\npara usuários que realizaram pagamentos.\n","rewards:write":"Permite criar, atualizar e gerenciar recompensas do usuário.\nInclui configuração de gatilhos automáticos e integração\ncom plataformas externas como Discord e Twitch.\n","messages:read":"Permite acesso de leitura às mensagens recebidas pelo usuário.\nInclui mensagens de pagamento, feedback de viewers e\ncomunicações diretas através da plataforma.\n","messages:write":"Permite enviar mensagens em nome do usuário.\nUsado para integrar bots e sistemas automatizados\nque precisam interagir com a comunidade.\n","payments:read":"Permite consultar o histórico de pagamentos recebidos.\nInclui informações detalhadas sobre valores, datas,\nremetentes e status de cada transação.\n","payments:write":"Permite criar solicitações de pagamento e PIX Copia e Cola.\nUsado para integrar sistemas de cobrança e\nsolicitar pagamentos de forma programática.\n","subscriptions:read":"Permite consultar as assinaturas recebidas pelo usuário.\nInclui histórico de pagamentos, status de renovação\ne informações dos assinantes ativos.\n","subscriptions:write":"Permite criar novas assinaturas e gerenciar assinantes.\nInclui cancelamento de assinaturas e modificação\nde planos existentes conforme necessário.\n","subscription-plans:read":"Permite consultar os planos de assinatura criados pelo usuário.\nInclui informações sobre preços, benefícios\ne configurações de cada plano disponível.\n","subscription-plans:write":"Permite criar e gerenciar planos de assinatura.\nInclui criação de novos planos, atualização de preços\ne desativação de planos não utilizados.\n","wallet:read":"Permite consultar o saldo e histórico da carteira do usuário.\nInclui saldo disponível, valores pendentes de liberação\ne histórico completo de transações financeiras.\n","webhooks":"Permite configurar e gerenciar webhooks para receber eventos.\nInclui criação, listagem e exclusão de URLs de callback\npara receber notificações em tempo real sobre pagamentos,\nmensagens e outros eventos importantes.\n","controls":"Permite acessar e modificar os controles de alertas em tempo real.\nInclui configuração de reprodução automática, pular alertas\ne reexibir o último alerta para streamers e criadores de conteúdo.\n"}},"clientCredentials":{"tokenUrl":"https://oauth.livepix.gg/oauth2/token","scopes":{"offline":"Permite renovar o token de acesso automaticamente.\nNecessário para aplicações que precisam de acesso contínuo\nsem intervenção do usuário.\n","account:read":"Permite acesso de leitura aos dados básicos da conta do usuário.\nInclui informações como nome de usuário, ID único e dados públicos do perfil.\n","currencies:read":"Permite consultar as moedas disponíveis para pagamentos do usuário.\nInclui tanto moedas fiat (BRL) quanto criptomoedas configuradas,\ncom informações de endereços e redes blockchain.\n","rewards:read":"Permite consultar as recompensas configuradas pelo usuário.\nInclui acesso à lista de recompensas e suas concessões (grants)\npara usuários que realizaram pagamentos.\n","rewards:write":"Permite criar, atualizar e gerenciar recompensas do usuário.\nInclui configuração de gatilhos automáticos e integração\ncom plataformas externas como Discord e Twitch.\n","messages:read":"Permite acesso de leitura às mensagens recebidas pelo usuário.\nInclui mensagens de pagamento, feedback de viewers e\ncomunicações diretas através da plataforma.\n","messages:write":"Permite enviar mensagens em nome do usuário.\nUsado para integrar bots e sistemas automatizados\nque precisam interagir com a comunidade.\n","payments:read":"Permite consultar o histórico de pagamentos recebidos.\nInclui informações detalhadas sobre valores, datas,\nremetentes e status de cada transação.\n","payments:write":"Permite criar solicitações de pagamento e PIX Copia e Cola.\nUsado para integrar sistemas de cobrança e\nsolicitar pagamentos de forma programática.\n","subscriptions:read":"Permite consultar as assinaturas recebidas pelo usuário.\nInclui histórico de pagamentos, status de renovação\ne informações dos assinantes ativos.\n","subscriptions:write":"Permite criar novas assinaturas e gerenciar assinantes.\nInclui cancelamento de assinaturas e modificação\nde planos existentes conforme necessário.\n","subscription-plans:read":"Permite consultar os planos de assinatura criados pelo usuário.\nInclui informações sobre preços, benefícios\ne configurações de cada plano disponível.\n","subscription-plans:write":"Permite criar e gerenciar planos de assinatura.\nInclui criação de novos planos, atualização de preços\ne desativação de planos não utilizados.\n","wallet:read":"Permite consultar o saldo e histórico da carteira do usuário.\nInclui saldo disponível, valores pendentes de liberação\ne histórico completo de transações financeiras.\n","webhooks":"Permite configurar e gerenciar webhooks para receber eventos.\nInclui criação, listagem e exclusão de URLs de callback\npara receber notificações em tempo real sobre pagamentos,\nmensagens e outros eventos importantes.\n","controls":"Permite acessar e modificar os controles de alertas em tempo real.\nInclui configuração de reprodução automática, pular alertas\ne reexibir o último alerta para streamers e criadores de conteúdo.\n"}}}}}},"x-webhooks":{"payment":{"post":{"summary":"Pagamento recebido","description":"Evento enviado quando o usuário recebe um novo pagamento.\n\n**Como processar:**\n1. Verifique o `userId` para identificar o destinatário\n2. Use o `resource.id` para consultar detalhes via API se necessário\n3. Processe de acordo com o tipo de pagamento\n4. **IMPORTANTE:** Sempre retorne HTTP 200 para confirmar o recebimento\n\n**Segurança:**\n- Valide o `clientId` para garantir que é para sua aplicação\n- Implemente idempotência usando `resource.id` como chave única\n","tags":["Pagamentos"],"requestBody":{"required":true,"description":"Dados do evento de pagamento","content":{"application/json":{"schema":{"type":"object","required":["userId","clientId","event","resource"],"properties":{"userId":{"type":"string","format":"objectid","description":"ID único do usuário que recebeu o pagamento.\nUse este campo para identificar o destinatário do evento.\n","example":"61021c7bdabe5e001225b65b"},"clientId":{"type":"string","format":"objectid","description":"ID da aplicação cliente que deve processar este evento.\nVerifique se corresponde ao ID da sua aplicação.\n","example":"61021c7bdabe5e001225b65c"},"event":{"type":"string","enum":["new"],"description":"Tipo do evento que ocorreu:\n- `new`: Novo pagamento confirmado\n","example":"new"},"resource":{"type":"object","required":["id","reference","type"],"description":"Informações sobre o recurso que gerou o evento","properties":{"id":{"type":"string","format":"objectid","description":"ID único do pagamento.\nUse este ID para consultar detalhes via API /v2/payments/{id}\nou como chave para implementar idempotência.\n","example":"61021c7bdabe5e001225b65d"},"reference":{"type":"string","format":"objectid","description":"Referência única do pagamento gerada pela plataforma.\nPode ser usada para rastreamento e conciliação.\n","example":"61021c7bdabe5e001225b65e"},"type":{"type":"string","enum":["payment"],"description":"Tipo do recurso que gerou o evento.\nSempre será \"payment\" para eventos de pagamento.\n","example":"payment"}}}}}}}},"responses":{"200":{"description":"Webhook processado com sucesso.\n\n**IMPORTANTE:** Sempre retorne status 200 para confirmar que recebeu\ne processou o evento com sucesso. Se não retornar 200, o sistema\ntentará reenviar o webhook múltiplas vezes.\n","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Event processed successfully"}}}}}},"4xx":{"description":"Erro no processamento do webhook.\nO sistema tentará reenviar o evento algumas vezes antes de descartar.\n"},"5xx":{"description":"Erro interno no seu sistema.\nO sistema tentará reenviar o evento algumas vezes antes de descartar.\n"}}}},"message":{"post":{"summary":"Mensagem recebida","description":"Evento enviado quando o usuário recebe uma nova mensagem.\n\n**Como processar:**\n1. Verifique o `userId` para identificar o destinatário\n2. Use o `resource.id` para consultar detalhes via API se necessário\n3. Processe a mensagem de acordo com suas regras de negócio\n4. **IMPORTANTE:** Sempre retorne HTTP 200 para confirmar o recebimento\n\n**Casos de uso:**\n- Integração com bots de chat\n- Analytics de engajamento\n- Notificações personalizadas\n","tags":["Mensagens"],"requestBody":{"required":true,"description":"Dados do evento de mensagem","content":{"application/json":{"schema":{"type":"object","required":["userId","clientId","event","resource"],"properties":{"userId":{"type":"string","format":"objectid","description":"ID único do usuário que recebeu a mensagem.\nUse este campo para identificar o destinatário do evento.\n","example":"61021c7bdabe5e001225b65b"},"clientId":{"type":"string","format":"objectid","description":"ID da aplicação cliente que deve processar este evento.\nVerifique se corresponde ao ID da sua aplicação.\n","example":"61021c7bdabe5e001225b65c"},"event":{"type":"string","enum":["new"],"description":"Tipo do evento que ocorreu:\n- `new`: Nova mensagem recebida\n","example":"new"},"resource":{"type":"object","required":["id","reference","type"],"description":"Informações sobre o recurso que gerou o evento","properties":{"id":{"type":"string","format":"objectid","description":"ID único da mensagem.\nUse este ID para consultar detalhes via API /v2/messages/{id}\nou como chave para implementar idempotência.\n","example":"61021c7bdabe5e001225b65d"},"reference":{"type":"string","format":"objectid","description":"Referência única da mensagem gerada pela plataforma.\nPode ser usada para rastreamento e threading.\n","example":"61021c7bdabe5e001225b65e"},"type":{"type":"string","enum":["message"],"description":"Tipo do recurso que gerou o evento.\nSempre será \"message\" para eventos de mensagem.\n","example":"message"}}}}}}}},"responses":{"200":{"description":"Webhook processado com sucesso.\nRetorne status 200 para confirmar o processamento.\n","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Message event processed successfully"}}}}}}}}},"subscription":{"post":{"summary":"Assinatura iniciada","description":"Evento enviado quando uma nova assinatura é criada e confirmada.\n\n**Quando é disparado:**\n- Nova assinatura criada e primeiro pagamento confirmado\n- Renovação de assinatura processada com sucesso\n\n**Como processar:**\n1. Identifique o usuário via `userId`\n2. Consulte detalhes da assinatura via API se necessário\n\n**Casos de uso:**\n- Ativação automática de benefícios\n- Integração com Discord/Twitch para roles\n- Analytics de assinantes\n- Campanhas de engajamento\n","tags":["Assinaturas"],"requestBody":{"required":true,"description":"Dados do evento de assinatura","content":{"application/json":{"schema":{"type":"object","required":["userId","clientId","event","resource"],"properties":{"userId":{"type":"string","format":"objectid","description":"ID único do usuário que recebeu a assinatura.\nUse este campo para identificar o criador de conteúdo.\n","example":"61021c7bdabe5e001225b65b"},"clientId":{"type":"string","format":"objectid","description":"ID da aplicação cliente que deve processar este evento.\nVerifique se corresponde ao ID da sua aplicação.\n","example":"61021c7bdabe5e001225b65c"},"event":{"type":"string","enum":["new"],"description":"Tipo do evento que ocorreu:\n- `new`: Nova assinatura confirmada ou renovação processada\n","example":"new"},"resource":{"type":"object","required":["id","reference","type"],"description":"Informações sobre o recurso que gerou o evento","properties":{"id":{"type":"string","format":"objectid","description":"ID único da assinatura.\nUse este ID para consultar detalhes via API /v2/subscriptions/{id}\n","example":"61021c7bdabe5e001225b65d"},"reference":{"type":"string","format":"objectid","description":"Referência única da assinatura.\nPermanece a mesma durante renovações.\n","example":"61021c7bdabe5e001225b65e"},"type":{"type":"string","enum":["subscription"],"description":"Tipo do recurso que gerou o evento.\nSempre será \"subscription\" para eventos de assinatura.\n","example":"subscription"}}}}}}}},"responses":{"200":{"description":"Webhook processado com sucesso.\nRetorne status 200 para confirmar o processamento.\n","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Subscription event processed successfully"}}}}}}}},"delete":{"summary":"Assinatura cancelada","description":"Evento enviado quando uma assinatura é cancelada.\n\n**Como processar:**\n1. Identifique a assinatura cancelada\n2. Remova benefícios ativos do assinante\n3. Atualize estatísticas e analytics\n","tags":["Assinaturas"],"requestBody":{"required":true,"description":"Dados do evento de cancelamento","content":{"application/json":{"schema":{"type":"object","required":["userId","clientId","event","resource"],"properties":{"userId":{"type":"string","format":"objectid","description":"ID único do usuário cuja assinatura foi cancelada.\nUse este campo para identificar o criador de conteúdo afetado.\n","example":"61021c7bdabe5e001225b65b"},"clientId":{"type":"string","format":"objectid","description":"ID da aplicação cliente que deve processar este evento.\nVerifique se corresponde ao ID da sua aplicação.\n","example":"61021c7bdabe5e001225b65c"},"event":{"type":"string","enum":["cancelled"],"description":"Tipo do evento que ocorreu:\n- `cancelled`: Assinatura foi cancelada permanentemente\n","example":"cancelled"},"resource":{"type":"object","required":["id","reference","type"],"description":"Informações sobre o recurso que gerou o evento","properties":{"id":{"type":"string","format":"objectid","description":"ID único da assinatura cancelada.\nA assinatura ainda pode ser consultada via API para histórico.\n","example":"61021c7bdabe5e001225b65d"},"reference":{"type":"string","format":"objectid","description":"Referência única da assinatura cancelada.\nUse para identificar a assinatura em seus sistemas.\n","example":"61021c7bdabe5e001225b65e"},"type":{"type":"string","enum":["subscription"],"description":"Tipo do recurso que gerou o evento.\nSempre será \"subscription\" para eventos de assinatura.\n","example":"subscription"}}}}}}}},"responses":{"200":{"description":"Webhook processado com sucesso.\nRetorne status 200 para confirmar que processou o cancelamento.\n","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Subscription cancellation processed successfully"}}}}}}}}}}}