🔌 REST-API v1

Roblox kennt keine Discord-IDs – die Zuordnung läuft über ein Verknüpfungssystem wie Bloxlink, mit dem sich Spieler einmalig verknüpfen (in den meisten Roblox-Discord-Communities ohnehin Standard). Das Server-Script löst die Discord-ID über die Bloxlink-API auf und stempelt beim Betreten und Verlassen des Spiels:

-- Server script (ServerScriptService)
local HttpService = game:GetService("HttpService")
local Players = game:GetService("Players")

local API_BASE = "https://shiftwatch.de/api/v1"
local API_KEY = "sk_..."           -- e.g. from a private server module
local BLOXLINK_KEY = "..."         -- Bloxlink server key (Developer API)
local DISCORD_GUILD_ID = "987654321098765432"

-- Resolve the Discord ID of a linked player via the Bloxlink API
local discordIdCache = {}
local function getDiscordId(player)
    if discordIdCache[player.UserId] ~= nil then
        return discordIdCache[player.UserId]
    end
    local ok, res = pcall(function()
        return HttpService:RequestAsync({
            Url = "https://api.blox.link/v4/public/guilds/" .. DISCORD_GUILD_ID
                .. "/roblox-to-discord/" .. player.UserId,
            Method = "GET",
            Headers = { Authorization = BLOXLINK_KEY }
        })
    end)
    local discordId
    if ok and res.Success then
        local data = HttpService:JSONDecode(res.Body)
        discordId = data.discordIDs and data.discordIDs[1] or nil
    end
    discordIdCache[player.UserId] = discordId
    return discordId
end

local function apiPost(path, payload)
    pcall(function()
        HttpService:RequestAsync({
            Url = API_BASE .. path,
            Method = "POST",
            Headers = {
                ["Content-Type"] = "application/json",
                ["Authorization"] = "Bearer " .. API_KEY
            },
            Body = HttpService:JSONEncode(payload)
        })
    end)
end

-- Clock in on join, clock out on leave
Players.PlayerAdded:Connect(function(player)
    local discordId = getDiscordId(player)
    if discordId then
        apiPost("/clock-in", { user_id = discordId })
    end
end)

Players.PlayerRemoving:Connect(function(player)
    local discordId = discordIdCache[player.UserId]
    if discordId then
        apiPost("/clock-out", { user_id = discordId })
    end
end)

-- Heartbeat loop: every 5 minutes for all linked online players
task.spawn(function()
    while true do
        task.wait(300)
        local ids = {}
        for _, player in ipairs(Players:GetPlayers()) do
            local discordId = discordIdCache[player.UserId]
            if discordId then
                table.insert(ids, discordId)
            end
        end
        if #ids > 0 then
            apiPost("/heartbeat", { user_ids = ids })
        end
    end
end)

Auf Minecraft-Servern (Paper/Spigot) liefert DiscordSRV die Verknüpfung zwischen Minecraft-Account und Discord-ID – Spieler verknüpfen sich einmalig per /discord link. Ein kleines Plugin stempelt dann beim Join und Quit:

// Paper/Spigot plugin, DiscordSRV as the account link source
public final class StempeluhrHook implements Listener {

    private static final String API_BASE = "https://shiftwatch.de/api/v1";
    private final String apiKey;   // load from config.yml
    private final HttpClient http = HttpClient.newHttpClient();

    public StempeluhrHook(String apiKey) {
        this.apiKey = apiKey;
    }

    private void apiPost(String path, String json) {
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(API_BASE + path))
                .header("Authorization", "Bearer " + apiKey)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();
        http.sendAsync(request, HttpResponse.BodyHandlers.ofString());
    }

    private String getDiscordId(Player player) {
        return DiscordSRV.getPlugin().getAccountLinkManager()
                .getDiscordId(player.getUniqueId());
    }

    @EventHandler
    public void onJoin(PlayerJoinEvent event) {
        String discordId = getDiscordId(event.getPlayer());
        if (discordId != null) {
            apiPost("/clock-in", "{\"user_id\": \"" + discordId + "\"}");
        }
    }

    @EventHandler
    public void onQuit(PlayerQuitEvent event) {
        String discordId = getDiscordId(event.getPlayer());
        if (discordId != null) {
            apiPost("/clock-out", "{\"user_id\": \"" + discordId + "\"}");
        }
    }

    // Heartbeat every 5 minutes for all linked online players
    public void startHeartbeat(JavaPlugin plugin) {
        Bukkit.getScheduler().runTaskTimerAsynchronously(plugin, () -> {
            List<String> ids = new ArrayList<>();
            for (Player player : Bukkit.getOnlinePlayers()) {
                String discordId = getDiscordId(player);
                if (discordId != null) {
                    ids.add(discordId);
                }
            }
            if (!ids.isEmpty()) {
                String json = "{\"user_ids\": [\""
                        + String.join("\", \"", ids) + "\"]}";
                apiPost("/heartbeat", json);
            }
        }, 20L * 60, 20L * 300);
    }
}

Die API lässt sich auch aus einem eigenen Discord-Bot nutzen – zum Beispiel für Voice-Dienstzeit: Wer den „Im Dienst"-Voice-Channel betritt, wird eingestempelt, wer ihn verlässt, wird ausgestempelt. Die Discord-IDs hat der Bot direkt zur Hand:

const { Client, GatewayIntentBits } = require('discord.js');

const API_BASE = 'https://shiftwatch.de/api/v1';
const API_KEY = process.env.STEMPELUHR_API_KEY;
const DUTY_CHANNEL_ID = '123456789012345678'; // "on duty" voice channel

async function apiPost(path, payload) {
    const res = await fetch(API_BASE + path, {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer ' + API_KEY,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(payload)
    });
    return res.json();
}

const client = new Client({
    intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildVoiceStates]
});

// Joining the duty channel clocks in, leaving clocks out
client.on('voiceStateUpdate', async (oldState, newState) => {
    const joined = newState.channelId === DUTY_CHANNEL_ID
        && oldState.channelId !== DUTY_CHANNEL_ID;
    const left = oldState.channelId === DUTY_CHANNEL_ID
        && newState.channelId !== DUTY_CHANNEL_ID;

    if (joined) await apiPost('/clock-in', { user_id: newState.id });
    if (left) await apiPost('/clock-out', { user_id: newState.id });
});

// Heartbeat every 5 minutes for everyone in the duty channel
setInterval(async () => {
    const channel = await client.channels.fetch(DUTY_CHANNEL_ID);
    const ids = [...channel.members.keys()];
    if (ids.length > 0) {
        await apiPost('/heartbeat', { user_ids: ids });
    }
}, 5 * 60 * 1000);

client.login(process.env.DISCORD_TOKEN);

Für Scripts, Cron-Jobs, eigene Tools oder ein Kiosk-Terminal reicht ein minimaler Python-Client:

import os
import requests

API_BASE = "https://shiftwatch.de/api/v1"

session = requests.Session()
session.headers.update({
    "Authorization": "Bearer " + os.environ["STEMPELUHR_API_KEY"]
})

def clock_in(user_id):
    return session.post(API_BASE + "/clock-in",
                        json={"user_id": user_id}).json()

def clock_out(user_id):
    return session.post(API_BASE + "/clock-out",
                        json={"user_id": user_id}).json()

def heartbeat(user_ids):
    return session.post(API_BASE + "/heartbeat",
                        json={"user_ids": user_ids}).json()

def status(user_id):
    return session.get(API_BASE + "/status/" + user_id).json()

# Example: clock a user in and show the running session
print(clock_in("123456789012345678"))
print(status("123456789012345678"))