📡 Endpoints

Receba requisições HTTP de fora do Discord (Roblox, Minecraft, FiveM, sites, APIs) direto no seu Logic Script.

Um Endpoint é uma URL própria de um arquivo do Logic Script. Quando alguém faz uma requisição HTTP POST pra essa URL, o bloco on endpoint(event) do arquivo roda — igual qualquer outro evento — e pode responder de volta com event.reply(...).

1. Ative o Endpoint e crie o Secret

• Pelo Dashboard (Servidor → Logic Script → aba Endpoints) ou pelo comando /logic script.
• Só o(a) dono(a) do servidor pode criar ou regenerar o Secret — é a chave que autentica as requisições.
• O Secret só aparece uma única vez, no momento em que é criado ou regenerado. Guarde-o num lugar seguro — não é possível recuperá-lo depois, só gerar um novo (o que invalida o antigo na hora).

2. A URL do Endpoint

POST https://ayamihoshiori.website/endpoints/{guildId}/{logicScriptId}

{guildId} é o ID do seu servidor Discord. {logicScriptId} é o ID permanente do arquivo (algo como logic_01J8Y7P6A2C4X9), visível no Dashboard e no comando /logic script. Nenhum dos dois pode ser escolhido ou alterado por você — são gerados automaticamente e nunca mudam.

3. Autenticação

Toda requisição precisa enviar o Secret em um destes headers:

Authorization: Bearer SEU_SECRET

X-Ayami-Secret: SEU_SECRET

• Secret ausente ou incorreto → 401 Unauthorized.
• Endpoint desativado → 403 Forbidden.

4. O bloco on endpoint(event)

on endpoint(event)
  let jogador = event.body.player
  let nivel = event.body.level

  print("Jogador:", jogador, "Nivel:", nivel)

  event.status(200)
  event.header("Content-Type", "application/json")
  event.reply({ success: true, message: "Dados recebidos" })
end

O parâmetro event traz body (corpo da requisição, já interpretado como objeto quando é JSON), headers, query, method, ip, userAgent e timestamp. Se o script não chamar event.reply(...), a resposta padrão é { success: true } com status 200.

5. Limites por plano

• 🌙 Lua Crescente — até 3 Endpoints, 512 KB de memória, 30 requisições/min por Endpoint, 128 KB por requisição, histórico das últimas 20 requisições, logs de erro.
• ✨ Constellation — até 9 Endpoints, 4 MB de memória, 120 requisições/min, 1 MB por requisição, histórico das últimas 200 requisições, whitelist de IPs e estatísticas avançadas.

6. Boas práticas

• Sempre valide event.body antes de usar — aplicações externas podem mandar dados incompletos ou no formato errado.
• Use event.status(...) também nos casos de erro (ex.: 400, 422) — facilita o time que está integrando do outro lado.
• Nunca coloque o Secret em código-fonte público (repositórios, scripts client-side de jogo, etc.) — trate como senha.
• Se o volume de chamadas crescer, considere o plano Constellation para mais requisições por minuto e whitelist de IP.

7. Exemplos em outras linguagens/plataformas

Roblox (Luau):

local HttpService = game:GetService("HttpService")

local body = HttpService:JSONEncode({
    player = player.Name,
    level = playerLevel
})

local response = HttpService:RequestAsync({
    Url = "https://ayamihoshiori.website/endpoints/{guildId}/{logicScriptId}",
    Method = "POST",
    Headers = {
        ["Content-Type"] = "application/json",
        ["Authorization"] = "Bearer SEU_SECRET"
    },
    Body = body
})

Minecraft (plugin Java, usando HttpClient):

HttpClient client = HttpClient.newHttpClient();
String json = "{\"player\":\"" + playerName + "\",\"level\":" + level + "}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://ayamihoshiori.website/endpoints/{guildId}/{logicScriptId}"))
    .header("Content-Type", "application/json")
    .header("Authorization", "Bearer SEU_SECRET")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

client.send(request, HttpResponse.BodyHandlers.ofString());

Node.js:

await fetch("https://ayamihoshiori.website/endpoints/{guildId}/{logicScriptId}", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer SEU_SECRET"
  },
  body: JSON.stringify({ player: "Steve", level: 20 })
});

Python:

import requests

requests.post(
    "https://ayamihoshiori.website/endpoints/{guildId}/{logicScriptId}",
    headers={"Authorization": "Bearer SEU_SECRET"},
    json={"player": "Steve", "level": 20}
)

Qualquer outra API HTTP (curl, como referência):

curl -X POST "https://ayamihoshiori.website/endpoints/{guildId}/{logicScriptId}" \
  -H "Content-Type: application/json" \
  -H "X-Ayami-Secret: SEU_SECRET" \
  -d '{"player": "Steve", "level": 20}'

Páginas relacionadas