API do Brix: Portal de Desenvolvedores

Bem-vindo ao portal oficial de API do Brix! Aqui você encontra a documentação detalhada para integrar seu bot parceiro ou aplicação externa aos nossos serviços. Nossa API HTTP permite realizar conversão de moedas, consultar dados de usuários e expandir as integrações com o ecossistema do Brix, kyu~!

Autenticação & Como Obter um Token

A autenticação em toda a API do Brix é realizada de forma padronizada através do cabeçalho HTTP Authorization com o token de validação único fornecido exclusivamente para o seu bot ou aplicação.

Header	Valor
Authorization	brix_SEU_TOKEN_AQUI

---

API de Conversão de Moedas ( /api/pix )

Esta API permite a conversão bidirecional de moedas entre seu bot parceiro e o ecossistema do Brix. Seus usuários podem converter sua moeda em Braixencoin, e o Brix também pode disparar solicitações para o seu bot converter Braixencoin de volta para a sua moeda.

Endpoint (/api/pix)

O Brix recebe as solicitações de conversão via HTTP POST no endpoint central:

Mecanismo de Testes (Sandbox)

O Brix possui um sistema de testes integrado para facilitar a implementação da conversão de moedas:

Corpo da Requisição (JSON)

O sistema usa termos em inglês universal, mantendo compatibilidade com diversos sistemas por apresentar um padrão único de identificação de campos.

Campo	Tipo	Requerido	Descrição
user_id	String / Int	Sim	ID do usuário no Discord que receberá a conversão.
amount	Inteiro	Sim	Quantidade de moedas a converter.
ref_id	String (24)	Sim	ID único de referência para a transação. Usado para evitar processamento duplicado caso a requisição seja reenviada. Padrão sugerido: 24 caracteres.
currency	String	Não	Nome da moeda de origem. Se omitido, usa o padrão cadastrado.
currency_icon	URL	Não	URL de imagem (PNG/JPG) usada como ícone da moeda na DM.

Exemplo cURL (Produção)

curl -X POST https://brixbot.xyz/api/pix \
     -H "Authorization: brix_seu_token_real" \
     -H "Content-Type: application/json" \
     -d '{
           "user_id": "123456789012345678",
           "amount": 654,
           "currency": "MinhaMoeda",
           "currency_icon": "https://meusite.com/moeda.png",
           "ref_id": "xN7pL9qY2mR5kH4vC8wB3jF1"
         }'

Taxas e Limites de Conversão

O sistema de conversão do Brix foi feito para ser simples, transparente e justo:

Respostas & Erros da API

Sucesso (200 OK)

{
  "~kyuuu": true,
  "modo_teste": false
}

• modo_teste: true indica que a requisição foi processada como teste (token inválido/ausente).

Erros Comuns

Código	Descrição
400 Bad Request	JSON inválido ou mal formatado.
400 Bad Request	Campos obrigatórios ausentes (user_id, amount, ref_id).
400 Bad Request	user_id deve ser numérico e maior que 0.
400 Bad Request	amount deve ser inteiro, maior que 0 e menor que 10.000.000.
400 Bad Request	currency inválida ou muito longa (máx. 50 caracteres).
400 Bad Request	currency_icon deve ser uma URL válida (http/https) e até 300 caracteres.
400 Bad Request	ref_id deve ser uma string válida (24 caracteres alfanuméricos, _ ou -).
400 Bad Request	Metadados excessivos (máx. 20 campos).
400 Bad Request	Metadados muito grandes (chave até 50 chars, valor até 500 chars).
429 Too Many Requests	Muitas requisições pelo mesmo IP (rate limit global).
429 Too Many Requests	Muitas requisições para o mesmo usuário (rate limit por user_id).
200 OK	Transação duplicada detectada (mesmo ref_id), ignorada com sucesso.
500 Internal Error	Erro inesperado no processamento interno do servidor.

Webhook de Retorno (Brix → Parceiro)

O Brix também pode disparar solicitações para o seu bot quando um usuário utiliza o comando /bc transferir. Nesse fluxo, Braixencoins são convertidos de volta para a moeda do seu sistema.

Para receber transferências do Brix, você deve fornecer um webhook URL durante o cadastro da parceria. O Brix enviará um POST para esse endereço usando o mesmo token de validação no cabeçalho Authorization.

Payload Enviado pelo Brix ao seu Webhook

Campo	Tipo	Descrição
user_id	String	ID do usuário no Discord que realizou a transferência.
amount	Inteiro	Quantidade de Braixencoins enviados.
bot_name	String	Sempre "Brix" — identifica a origem da transferência.
ref_id	String (24)	ID único da transação gerado pelo Brix. Utilize para evitar processamento duplicado.
currency_icon	URL	URL da imagem da BraixenCoin para ser exibida nas DMs do seu bot.

Exemplo de Recebimento JSON

{
  "user_id": "123456789012345678",
  "amount": 654,
  "bot_name": "Brix",
  "ref_id": "sT6vM2bN8pK1xH4jL9cQ5wR3",
  "currency_icon": "https://brixbot.xyz/cdn/icon_braixencoin.png"
}

---

API de Consulta de Usuário ( /api/user )

Disponibiliza a consulta de informações públicas de conta e saldos dos usuários do Brix (como Braixencoins, gravetos, pontuação de reputação, nível/XP e status de assinatura premium) para integração com aplicações externas.

Endpoint (/api/user)

Modo Sandbox em /api/user

Parâmetros de Requisição

Parâmetro	Tipo	Local	Descrição
user_id	Integer / String	Query String (GET) ou Body JSON (POST)	ID numérico do Discord do usuário a ser consultado. Obrigatório em produção.

Resposta JSON (/api/user)

Exemplo da resposta JSON retornada em tempo real diretamente pela rota /api/user do sistema:

{
  "status": "Carregando dados da API..."
}

Campo	Tipo	Descrição
id	Integer	ID numérico do usuário no Discord.
braixencoin	Integer	Saldo atual de Braixencoins do usuário.
graveto	Integer	Saldo atual de gravetos do usuário.
xpg	Integer	Pontuação de experiência / nível.
rep	Integer	Pontuação de reputação acumulada.
descricao	String	Texto "sobre mim" configurado no perfil do usuário.
premium.ativo	Boolean	Indica se o usuário possui assinatura Premium ativa.
premium.expiracao	String / null	Data de expiração da assinatura (DD/MM/YYYY) se aplicável.