Quelle: https://spooly.eu/docs/quickstart

# Schnellstart

Vom Schlüssel zum ersten Aufruf in fünf Minuten. Du brauchst ein Terminal mit curl, oder Python mit requests, oder Node.js ab Version 18. Die JavaScript-Beispiele speicherst du als `test.mjs` und startest sie mit `node test.mjs`.

## 1. Zugang prüfen

Die API gehört zu Spooly Pro, der Trial zählt mit. In der Beta schalte ich Konten einzeln frei.

> Beta: Schreib mir kurz, was du bauen willst. Ich melde mich, sobald dein Konto frei ist. Oder schreib an support@spooly.eu.

## 2. Schlüssel anlegen

1. Öffne Spooly im Browser: Einstellungen, Geräte & Schlüssel, „Schlüssel anlegen“. In den Apps geht das nicht. „Geräte & Schlüssel“ gibt es nur im neuen Design. Hast du noch das alte, schaltest du es unter Einstellungen, Darstellung & Sprache auf „Neues Design (Beta)“ um.
2. Gib ihm einen Namen und wähl die Art „Sonstiges“. Für Schritt 5 schaltest du „Darf auch ändern“ ein.
3. Kopier den Schlüssel. Spooly zeigt ihn nur dieses eine Mal. Verloren heißt neu anlegen.

Leg ihn als Umgebungsvariable ab. Alle Beispiele dieser Doku lesen ihn von dort, so landet er nicht im Code.

Terminal (macOS, Linux):

```
export SPOOLY_KEY="spk_dein_schluessel"
```

PowerShell (Windows):

```
$env:SPOOLY_KEY="spk_dein_schluessel"
```

## 3. Erster Aufruf

`GET /me` zeigt Kontoart, Aufrufe von heute und den Namen des Schlüssels.

Unter Windows schreibst du in der PowerShell `curl.exe` statt `curl` (`curl` ruft dort einen anderen Befehl auf), `$env:SPOOLY_KEY` statt `$SPOOLY_KEY` und die ganze Anfrage in eine Zeile, ohne `\` am Zeilenende. Für die Änderung in Schritt 5 nimmst du unter Windows besser Python oder JavaScript.

Kommt 401 `invalid_key`, stimmt der Schlüssel nicht. 403 `api_disabled` heißt, dein Konto ist noch nicht freigeschaltet. [Alle Fehlercodes](https://spooly.eu/docs/errors)

```bash
curl "https://spooly.eu/api/v1/me" \
  -H "Authorization: Bearer $SPOOLY_KEY"
```

Antwort (200):

```
{
  "account": "pro",
  "calls_today": 142,
  "daily_limit": 10000,
  "key_name": "Werkstatt",
  "key_kind": "other",
  "account_id": "3f9a1c7e5b2d8a40c6e1f7b2",
  "currency": "EUR"
}
```

## 4. Spulen lesen

Listen kommen seitenweise. `total` nennt die Gesamtzahl, mit `limit` und `offset` blätterst du weiter.

Für Änderungen brauchst du die `id` der Spule, nicht ihre Nummer.

```bash
curl "https://spooly.eu/api/v1/spools?limit=5" \
  -H "Authorization: Bearer $SPOOLY_KEY"
```

Antwort (200):

```
{
  "items": [
    {
      "id": "7f3c2a10-5e1b-4c8e-9a44-2d6b1f0c7e21",
      "number": 1,
      "title": "Jade White",
      "name": null,
      "manufacturer": "Bambu Lab",
      "material": "PLA Matte",
      "finish": "matt",
      "color_hex": "#E8E9DF",
      "color_name": "Jade White",
      "remaining_grams": 342,
      "spool_size_grams": 1000,
      "empty_spool_grams": 250,
      "fill_level": "low",
      "location": "Schrank 01 · Fach vorne · Platz 3",
      "location_id": "loc_3c9b7e1a5d60",
      "place": 3,
      "archived": false,
      "price": 19.99,
      "notes": null
    }
  ],
  "total": 23,
  "limit": 5,
  "offset": 0
}
```

## 5. Ein Gewicht setzen

Das braucht einen Schlüssel mit „Darf auch ändern“.

Schick einen eigenen `Idempotency-Key` mit. Bricht die Verbindung ab und dein Programm wiederholt, läuft die Änderung trotzdem nur einmal. Je Änderung ein neuer Key, zum Beispiel eine UUID.

Die Änderung steht danach in der Änderungsliste des Schlüssels, dort kannst du sie zurücknehmen.

```bash
curl -X POST "https://spooly.eu/api/v1/spools/7f3c2a10-5e1b-4c8e-9a44-2d6b1f0c7e21/weight" \
  -H "Authorization: Bearer $SPOOLY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4b8e1f0a-6c2d-4e97-9a35-c1d7f2e60b84" \
  -d '{"grams":300}'
```

Antwort (200):

```
{
  "change_id": 381,
  "spool": {
    "id": "7f3c2a10-5e1b-4c8e-9a44-2d6b1f0c7e21",
    "number": 1,
    "title": "Jade White",
    "name": null,
    "manufacturer": "Bambu Lab",
    "material": "PLA Matte",
    "finish": "matt",
    "color_hex": "#E8E9DF",
    "color_name": "Jade White",
    "remaining_grams": 300,
    "spool_size_grams": 1000,
    "empty_spool_grams": 250,
    "fill_level": "low",
    "location": "Schrank 01 · Fach vorne · Platz 3",
    "location_id": "loc_3c9b7e1a5d60",
    "place": 3,
    "archived": false,
    "price": 19.99,
    "notes": null
  },
  "slot": null,
  "old_grams": 342,
  "new_grams": 300,
  "replayed": false,
  "task": null,
  "printer": null,
  "stock_empty": null,
  "summary": "Spule #1 Jade White: 342 auf 300 g"
}
```

## Wie es weitergeht

- [API-Referenz](https://spooly.eu/docs/api): Alle 24 Endpunkte mit Parametern und Beispielen.
- [Fehlercodes](https://spooly.eu/docs/errors): Was jeder Code bedeutet und was dein Programm tun sollte.
- [Grenzen](https://spooly.eu/docs/limits): Aufrufe am Tag, gleichzeitige Anfragen und Änderungen.