Splittermond Charaktergenerator — REST-API

Externe, rein lesende Schnittstelle · Version 1

Diese API liefert die eigenen Charakterdaten aus dem Portal an andere Anwendungen (z. B. einen Foundry-VTT-Konverter oder andere Charakter-Verwaltungen). Aktuell erlaubt sie ausschließlich Lesezugriff.

Basis-URL

https://splittermond.helden.training/wp-json/splittermond/v1/

Antwortformat

Alle Antworten sind JSON:

// Erfolg
{ "ok": true, "data": { … } }

// Fehler (WP_Error-Format)
{ "code": "smcg_…", "message": "Klartext", "data": { "status": 401 } }

Jede Antwort wird mit Cache-Control: no-store ausgeliefert.

Authentifizierung

Jede Anfrage braucht ein persönliches API-Token im HTTP-Header:

X-Smcg-Token: smcg_<id>_<geheimnis>

Alternativ wird Authorization: Bearer smcg_<id>_<geheimnis> akzeptiert. Manche Firewalls entfernen den Authorization-Header – im Zweifel X-Smcg-Token verwenden.

Token erzeugen: im Portal unter „Meine Charaktere → API-Zugänge“. Der Token-Text wird nur einmal angezeigt und ist jederzeit widerrufbar (optional mit Ablaufdatum). Er gilt nur für die Charaktere des Nutzers, der ihn erzeugt hat, und nur lesend.

Wichtig: Ein Token ist ein Geheimnis wie ein Passwort. Es gehört nicht in Browser-JavaScript, sondern in serverseitige Programme, Desktop-Tools oder ein Foundry-Modul.

Endpunkte

Alle Endpunkte benötigen ein gültiges Token (siehe oben).

Selbsttest für Clients: Name des Token-Besitzers und Anzahl seiner Charaktere.

Beispiel-Anfrage

curl -H "X-Smcg-Token: smcg_12_abcd…" \
     https://splittermond.helden.training/wp-json/splittermond/v1/me

Beispiel-Antwort

{
  "ok": true,
  "data": { "name": "Tom", "charaktere_anzahl": 3 }
}

Schlanke Liste der eigenen Charaktere.

Beispiel-Antwort

{
  "ok": true,
  "data": {
    "schema_version": "1.0",
    "characters": [
      { "id": 12, "name": "Lug", "rasse": "Varge",
        "ausbildung": "Kämpfer", "heldengrad": 2 }
    ]
  }
}

Vollständiger Charakter in aufgelöster, einfacher Form – Namen und fertige Werte statt interner IDs/Slugs. Nur eigene Charaktere; sonst 403.

Pfad-Parameter: id – Charakter-ID (aus GET /characters).

Beispiel-Antwort

{
  "ok": true,
  "data": {
    "schema_version": "1.0",
    "id": 12,
    "name": "Lug",
    "rasse": "Varge",
    "kultur": "…",
    "abstammung": "…",
    "ausbildung": "Kämpfer",
    "mondzeichen": "Der Fels",
    "heldengrad": 2,
    "groessenklasse": 5,
    "attribute": {
      "Ausstrahlung": 3, "Beweglichkeit": 2, "Intuition": 1, "Konstitution": 4,
      "Mystik": 0, "Stärke": 3, "Verstand": 2, "Willenskraft": 2
    },
    "abgeleitete_werte": {
      "Geschwindigkeit": 8, "Initiative": 7, "Lebenspunkte": 40, "Fokus": 12,
      "Verteidigung": 24, "Geistiger Widerstand": 20,
      "Körperlicher Widerstand": 20, "Schadensreduktion": 1, "Splitterpunkte": 4
    },
    "fertigkeiten": { "Akrobatik": 5, "Athletik": 3, "Wahrnehmung": 4 },
    "staerken": [ "Robust (2×)", "Flink" ],
    "schwaechen": [ "…" ],
    "meisterschaften": [ "Klingentanz (Klingenwaffen)" ],
    "zauber": [ "Beflügelte Waffe" ],
    "ausruestung": {
      "waffen":     [ { "name": "Zweihänder", "angelegt": true,
                        "schaden": "2W10", "wgs": 10, "merkmale": "…" } ],
      "ruestungen": [ { "name": "Kettenhemd", "angelegt": true,
                        "schadensreduktion": 3, "verteidigung": 0,
                        "behinderung": 1, "tick_zuschlag": 1 } ],
      "schilde":    [ { "name": "…", "angelegt": false, "verteidigung": 2,
                        "behinderung": 0, "tick_zuschlag": 0 } ],
      "inventar":   [ { "name": "Fackel", "menge": 3 } ]
    },
    "zustaende": [ { "name": "Erschöpft", "stufe": 1 } ],
    "spielstand": {
      "lebenspunkte_aktuell": 40, "lebenspunkte_max": 40,
      "fokus_aktuell": 12, "fokus_max": 12,
      "splitter_aktuell": 4, "splitter_max": 4,
      "erfahrung_gesamt": 115, "erfahrung_verfuegbar": 15,
      "geld_telar": 30
    },
    "gottheit": "…",
    "beschreibung": "…",
    "hintergrund": "…"
  }
}

Hinweise zu Werten

• abgeleitete_werte.Lebenspunkte = Gesamt-LP (LP pro Gesundheitsstufe × 5).
• spielstand.…_aktuell = Maximum minus verbrauchter Kästchen (wie im Charakterbogen).
• abgeleitete_werte.Schadensreduktion = nur die natürliche SR; die SR getragener Rüstung steht je Rüstung unter ausruestung.ruestungen[].schadensreduktion.
• gottheit nur vorhanden, wenn gewählt (reines Flavor).

Fehler-Codes

Grenzen von v1

• Kein Schreibzugriff – reiner Informationsabruf.
• Kein systemspezifisches Format (z. B. Foundry-Actor): Die Umwandlung macht der jeweilige Konverter; diese API liefert eine neutrale, aufgelöste Darstellung.
• Keine fremden Charaktere, keine Spielleiter-Sicht (kann später dazukommen).

Versionierung

Das Feld schema_version kennzeichnet das Ausgabeformat. Nicht abwärtskompatible Änderungen erhöhen es; ergänzende Felder können ohne Erhöhung dazukommen.