# Öffentliche Schnittstelle

Für fremde Anwendungen, Skripte und Automaten. Wer den Planer selbst bedient,
braucht sie nicht.

Basisadresse: `<APP_URL>/api/v1`

## Ausweisen

Jede Anfrage trägt einen Token:

```bash
curl -H "Authorization: Bearer planer_ab12cd34_…" \
     https://planer.example.de/api/v1/selbst
```

Alternativ `X-Planer-Token: planer_…`, falls das Werkzeug keine
Authorization-Kopfzeile kann.

Tokens legst du in der Anwendung unter **API** an (nur Verwaltung). Der Wert
erscheint **einmal**; danach liegt in der Datenbank nur sein Fingerabdruck.
Wer ihn verliert, legt einen neuen an.

## Rechte

Drei Stück, und **keines schließt ein anderes ein**:

| Recht       | Was damit geht                         |
| ----------- | -------------------------------------- |
| `lesen`     | Aufgaben abfragen                      |
| `erfassen`  | Neue Aufgaben anlegen — mehr nicht     |
| `schreiben` | Bestehende Aufgaben ändern und abhaken |

Ein Dienst, der nur meldet „hier ist etwas Neues", bekommt `erfassen` und
sonst nichts. Das ist der häufigste Fall und der, bei dem ein mitgelesener
Token am wenigsten anrichtet.

## Fehler

| Status | Bedeutung                                                   |
| ------ | ----------------------------------------------------------- |
| 400    | Die Anfrage war fehlerhaft (Feldliste steht in der Antwort) |
| 401    | Kein gültiger Token                                         |
| 403    | Dieser Token darf das nicht                                 |
| 404    | Gibt es nicht                                               |

401 sieht immer gleich aus — ob ein Token unbekannt, abgelaufen oder
zurückgezogen ist, verrät die Schnittstelle nicht. Von außen soll sich nicht
abfragen lassen, welche Tokens es gibt.

## Endpunkte

### `GET /selbst`

Wer bin ich, was darf ich? Braucht **kein** Recht — sonst müsste man raten,
ob der Token falsch ist oder nur zu wenig darf.

```json
{ "name": "Wartungsplaner-Import", "rechte": ["erfassen"] }
```

### `GET /aufgaben` · Recht `lesen`

| Parameter | Standard | Bedeutung           |
| --------- | -------- | ------------------- |
| `grenze`  | 25       | Höchstens 100       |
| `versatz` | 0        | Zum Blättern        |
| `offen`   | —        | `true` oder `false` |

```json
{
  "aufgaben": [
    {
      "id": "clx…",
      "titel": "#4711 Drucker klemmt",
      "notiz": null,
      "status": "OFFEN",
      "prioritaet": 3,
      "aufwandMinuten": null,
      "faelligAm": null,
      "quelle": "API",
      "ref": "ticket-4711",
      "url": "https://…",
      "erstelltAm": "2026-03-17T08:20:00.000Z",
      "bereich": null,
      "projekt": null
    }
  ],
  "gesamt": 42,
  "grenze": 25,
  "versatz": 0
}
```

### `POST /aufgaben` · Recht `erfassen`

```bash
curl -X POST https://planer.example.de/api/v1/aufgaben \
  -H "Authorization: Bearer planer_…" \
  -H "Content-Type: application/json" \
  -d '{"titel":"Drucker klemmt","ref":"ticket-4711"}'
```

| Feld             | Pflicht | Bemerkung                           |
| ---------------- | ------- | ----------------------------------- |
| `titel`          | ja      | bis 200 Zeichen                     |
| `notiz`          | nein    | bis 4000 Zeichen                    |
| `ref`            | nein    | Kennung beim Aufrufer — siehe unten |
| `url`            | nein    | Verweis ins Ursprungssystem         |
| `faelligAm`      | nein    | `JJJJ-MM-TT`                        |
| `prioritaet`     | nein    | 1 (dringend) bis 5 (irgendwann)     |
| `aufwandMinuten` | nein    | 1 bis 1440                          |

Antwort: `201` mit der angelegten Aufgabe.

**`ref` macht den Aufruf wiederholbar.** Zweimal dieselbe Kennung ergibt
**eine** Aufgabe, nicht zwei — der zweite Aufruf frischt Titel, Notiz und
Verweis auf. Ohne `ref` entsteht jedes Mal eine neue Aufgabe; dann hast du es
so gewollt.

Benutze `ref`, wann immer es drüben eine stabile Kennung gibt. Das ist der
Unterschied zwischen einer Schnittstelle, die man nach einem Netzhänger
gefahrlos wiederholen kann, und einer, die dabei Karteileichen anlegt.

### `GET /aufgaben/<id>` · Recht `lesen`

### `PATCH /aufgaben/<id>` · Recht `schreiben`

```bash
curl -X PATCH https://planer.example.de/api/v1/aufgaben/clx… \
  -H "Authorization: Bearer planer_…" \
  -H "Content-Type: application/json" \
  -d '{"erledigt":true}'
```

Änderbar sind `titel`, `notiz`, `faelligAm`, `prioritaet`, `aufwandMinuten`
und `erledigt`. Mindestens ein Feld muss dabei sein.

## Was die Schnittstelle bewusst **nicht** kann

- **Bereich und Projekt setzen.** Was von außen kommt, landet in der Inbox.
  Die Einordnung ist Sache dessen, der plant, nicht dessen, der meldet —
  sonst räumt ein fremder Dienst die eigene Ordnung um.
- **Aufgaben löschen.** Abhaken ja, löschen nein. Ein Fehler im fremden
  Skript soll keine Planung vernichten.
- **Zeitblöcke, Bereiche, Projekte oder Kalender anfassen.**

Fehlt dir etwas davon, ist das eine Entscheidung und kein Versehen — sag
Bescheid, dann wird darüber geredet.

## Protokoll

Jede **schreibende** Nutzung landet im Protokoll, mit dem Token, über den sie
kam. Lesen nicht: Ein Dienst, der im Minutentakt abfragt, würde das Protokoll
unbrauchbar machen.

Auch ein abgewiesener Zugriff wird vermerkt. Ein Dienst, der immer wieder an
dieselbe Wand läuft, ist entweder falsch eingerichtet oder versucht etwas.