diff --git a/docs/10-api.md b/docs/10-api.md index b62ea36..3543071 100644 --- a/docs/10-api.md +++ b/docs/10-api.md @@ -1,141 +1,144 @@ -# 10 API-Referenz - -Alles unter `/api`, Antworten sind JSON. Zugriff mit -`Authorization: Bearer `, sofern nicht anders vermerkt. Bei `401` -verwirft das Frontend das Token und zeigt den Anmeldeschirm; `403` bedeutet -fehlende Rolle. - -| Vermerk | Bedeutung | -| --- | --- | -| *offen* | ohne Anmeldung erreichbar | -| *admin* | nur Rolle `admin` | -| *Token* | fester Token statt JWT (Systemschnittstelle) | - -## Gesundheit - -| Endpunkt | | -| --- | --- | -| `GET /api/health` | *offen* – `{"ok":true,"db":"up"}` | - -## Anmeldung – `/api/auth` - -| Endpunkt | Zweck | -| --- | --- | -| `POST /login` | *offen* – `{ identifier, password }` → `{ token, user }`; SHA-256-Hashes des Altbestands werden dabei auf bcrypt umgeschrieben | -| `GET /me` | angemeldeter Benutzer | -| `PATCH /me` | Farbe, Foto, Design, hell/dunkel | -| `POST /change-password` | `{ currentPassword, newPassword }` | - -## Benutzer – `/api/users` - -| Endpunkt | Zweck | -| --- | --- | -| `GET /directory` | Liste für Erwähnungen, Zuständigkeiten, Historie – **jede Rolle**, nie mit Hashes | -| `GET /` | *admin* – vollständige Liste | -| `POST /`, `PATCH /:id`, `DELETE /:id` | *admin* – anlegen, ändern, löschen | - -Der letzte aktive Administrator lässt sich nicht degradieren, deaktivieren oder -löschen. - -## Unternehmen – `/api/companies` - -| Endpunkt | Zweck | -| --- | --- | -| `GET /` | Liste mit Filtern | -| `GET /options` | Namen und Gruppen für Auswahlfelder | -| `GET /:id` | Karte samt Kontakten, Werdegang, Gesprächen, Historie | -| `POST /`, `PATCH /:id`, `DELETE /:id` | anlegen, ändern, löschen | -| `POST /:id/interviews` | Gespräch festhalten | - -## Kontakte – `/api/contacts` - -| Endpunkt | Zweck | -| --- | --- | -| `GET /` | Liste mit Filtern | -| `GET /last-employers` | frühere Arbeitgeber je Kontakt (für „Ehemalige") | -| `GET /:id` | Karte samt Werdegang, Gesprächen, Verbindungen, Historie | -| `POST /`, `PATCH /:id`, `DELETE /:id` | anlegen, ändern, löschen | -| `POST /:id/interviews` | Gespräch festhalten | -| `GET /:id/cv` | hochgelegten Lebenslauf herunterladen (Bearer nötig) | -| `POST /linkedin-photo` | Profilfoto aus der öffentlichen Open-Graph-Vorschau | - -## Ausschreibungen – `/api/tenders` - -`GET /`, `GET /:id`, `POST /`, `PATCH /:id`, `DELETE /:id`. Über `PATCH` laufen -auch Phasenwechsel, der Schalter `online` und die Zuweisung von Kontakten. - -## Projekte – `/api/projects` - -`GET /`, `POST /`, `PATCH /:id`, `DELETE /:id`. - -## Leads – `/api/leads` - -| Endpunkt | Zweck | -| --- | --- | -| `GET /` | Pipeline; `archived` entscheidet über Kanban oder Archiv | -| `GET /reminders` | fällige Erinnerungen – vom `ReminderWatcher` beim Anmelden und stündlich | -| `GET /:id` | Karte samt ToDos und Historie | -| `POST /`, `PATCH /:id`, `DELETE /:id` | anlegen, ändern (auch Spalte und Reihenfolge), löschen | -| `POST /:id/acknowledge` | Erinnerung quittieren: erledigt oder in n Tagen erneut | -| `POST /:id/todos`, `PATCH /todos/:todoId`, `DELETE /todos/:todoId` | Checkliste | - -## CV-Import – `/api/cvs` - -| Endpunkt | Zweck | -| --- | --- | -| `GET /` | Eingang, Screening, Auswahl | -| `POST /` | hochladen (mehrere, je 15 MB) | -| `POST /:id/analyze` | auslesen lassen – der einzige Schritt, der die KI ruft | -| `POST /:id/accept` | Vorschlag bestätigen → Kontakt anlegen | -| `POST /:id/reject` | verwerfen | -| `GET /:id/file` | Datei herunterladen | -| `DELETE /:id` | Eintrag entfernen | - -## KI – `/api/ai` - -| Endpunkt | Zweck | -| --- | --- | -| `GET /status` | `{ configured, model }` – steuert, ob die Knöpfe erscheinen | -| `POST /text` | Schreibhilfe: `{ task, text, prompt }` | - -## Suche – `/api/search` - -| Endpunkt | Zweck | -| --- | --- | -| `GET /?q=` | normale Suche über alle Bereiche, `LIKE` | -| `GET /mentions?q=` | Vorschläge für `@` | -| `POST /ai` | erweiterte Suche: `{ question }` → `{ answer, refs, model, truncated }` | - -## Netzwerk, Verbindungen, Historie, Stammdaten, Dashboard - -| Endpunkt | Zweck | -| --- | --- | -| `GET /api/network` | Knoten und Kanten für die Netzwerkansicht | -| `GET/POST/PATCH/DELETE /api/connections` | „kennt"-Verbindungen zwischen Kontakten | -| `GET /api/history`, `POST /api/history`, `DELETE /api/history/:id` | Verlauf lesen, Notiz schreiben, Eintrag entfernen | -| `GET/POST/PATCH/DELETE /api/options` | Stammdaten (Schreiben *admin*) | -| `GET /api/dashboard` | Kennzahlen und letzte Tätigkeiten | - -## perinco – `/api/perinco` - -| Endpunkt | Zweck | -| --- | --- | -| `GET /status` | `{ configured, url }` – ohne Einrichtung bleibt das Häkchen unsichtbar | -| `GET /contacts` | Kontakte des perinco CRM, gelesen über einen gemeinsamen Zwischenspeicher; wirft nie, sondern liefert im Fehlerfall eine leere Liste | - -## Systemschnittstelle – `/api/integrations` - -| Endpunkt | Zweck | -| --- | --- | -| `GET /contacts` | *Token* – die ICON-Kontakte für das perinco CRM. Nur Lesen, `PERINCO_INBOUND_TOKEN`, Vergleich mit `timingSafeEqual` | - -## Öffentlich – `/api/public` - -| Endpunkt | Zweck | -| --- | --- | -| `GET /tenders` | *offen* – Ausschreibungen mit `online = 1` und `status <> 'Archiviert'`, neueste zuerst | -| `GET /tenders/:id` | *offen* – eine davon | - -Beide antworten mit `Access-Control-Allow-Origin: *` und -`Cache-Control: public, max-age=60` und liefern nur `id`, `title`, `status`, -`notes`, `created_at`, `updated_at`. +# 10 API-Referenz + +Alles unter `/api`, Antworten sind JSON. Zugriff mit +`Authorization: Bearer `, sofern nicht anders vermerkt. Bei `401` +verwirft das Frontend das Token und zeigt den Anmeldeschirm; `403` bedeutet +fehlende Rolle. + +| Vermerk | Bedeutung | +| --- | --- | +| *offen* | ohne Anmeldung erreichbar | +| *admin* | nur Rolle `admin` | +| *Token* | fester Token statt JWT (Systemschnittstelle) | + +## Gesundheit + +| Endpunkt | | +| --- | --- | +| `GET /api/health` | *offen* – `{"ok":true,"db":"up"}` | + +## Anmeldung – `/api/auth` + +| Endpunkt | Zweck | +| --- | --- | +| `POST /login` | *offen* – `{ identifier, password }` → `{ token, user }`; SHA-256-Hashes des Altbestands werden dabei auf bcrypt umgeschrieben | +| `GET /me` | angemeldeter Benutzer | +| `PATCH /me` | Farbe, Foto, Design, hell/dunkel | +| `POST /change-password` | `{ currentPassword, newPassword }` | + +## Benutzer – `/api/users` + +| Endpunkt | Zweck | +| --- | --- | +| `GET /directory` | Liste für Erwähnungen, Zuständigkeiten, Historie – **jede Rolle**, nie mit Hashes | +| `GET /` | *admin* – vollständige Liste | +| `POST /`, `PATCH /:id`, `DELETE /:id` | *admin* – anlegen, ändern, löschen | + +Der letzte aktive Administrator lässt sich nicht degradieren, deaktivieren oder +löschen. + +## Unternehmen – `/api/companies` + +| Endpunkt | Zweck | +| --- | --- | +| `GET /` | Liste mit Filtern | +| `GET /options` | Namen und Gruppen für Auswahlfelder | +| `GET /:id` | Karte samt Kontakten, Werdegang, Gesprächen, Historie | +| `POST /`, `PATCH /:id`, `DELETE /:id` | anlegen, ändern, löschen | +| `POST /:id/interviews` | Gespräch festhalten | + +## Kontakte – `/api/contacts` + +| Endpunkt | Zweck | +| --- | --- | +| `GET /` | Liste mit Filtern | +| `GET /last-employers` | frühere Arbeitgeber je Kontakt (für „Ehemalige") | +| `GET /:id` | Karte samt Werdegang, Gesprächen, Verbindungen, Historie | +| `POST /`, `PATCH /:id`, `DELETE /:id` | anlegen, ändern, löschen | +| `POST /:id/interviews` | Gespräch festhalten | +| `GET /:id/cv` | hochgelegten Lebenslauf herunterladen (Bearer nötig) | +| `POST /linkedin-photo` | Profilfoto aus der öffentlichen Open-Graph-Vorschau | + +## Ausschreibungen – `/api/tenders` + +`GET /`, `GET /:id`, `POST /`, `PATCH /:id`, `DELETE /:id`. Über `PATCH` laufen +auch Phasenwechsel, der Schalter `online` und die Zuweisung von Kontakten. + +## Projekte – `/api/projects` + +`GET /`, `POST /`, `PATCH /:id`, `DELETE /:id`. + +## Leads – `/api/leads` + +| Endpunkt | Zweck | +| --- | --- | +| `GET /` | Pipeline; `archived` entscheidet über Kanban oder Archiv | +| `GET /reminders` | fällige Erinnerungen – vom `ReminderWatcher` beim Anmelden und stündlich | +| `GET /:id` | Karte samt ToDos und Historie | +| `POST /`, `PATCH /:id`, `DELETE /:id` | anlegen, ändern (auch Spalte und Reihenfolge), löschen | +| `POST /:id/acknowledge` | Erinnerung quittieren: erledigt oder in n Tagen erneut | +| `POST /:id/todos`, `PATCH /todos/:todoId`, `DELETE /todos/:todoId` | Checkliste | + +## CV-Import – `/api/cvs` + +| Endpunkt | Zweck | +| --- | --- | +| `GET /` | Eingang, Screening, Auswahl | +| `POST /` | hochladen (mehrere, je 15 MB) | +| `POST /:id/analyze` | auslesen lassen – der einzige Schritt, der die KI ruft | +| `POST /:id/accept` | Vorschlag bestätigen → Kontakt anlegen | +| `POST /:id/reject` | verwerfen | +| `GET /:id/file` | Datei herunterladen | +| `DELETE /:id` | Eintrag entfernen | + +## KI – `/api/ai` + +| Endpunkt | Zweck | +| --- | --- | +| `GET /status` | `{ configured, model }` – steuert, ob die Knöpfe erscheinen | +| `POST /text` | Schreibhilfe: `{ task, text, prompt }` | +| `GET /config` | *admin* – Zustand der Einrichtung; der Schlüssel nur verkürzt | +| `PATCH /config` | *admin* – `{ key?, model? }`; `key: ''` entfernt ihn wieder | +| `POST /test` | *admin* – Miniaufruf gegen das Modell | + +## Suche – `/api/search` + +| Endpunkt | Zweck | +| --- | --- | +| `GET /?q=` | normale Suche über alle Bereiche, `LIKE` | +| `GET /mentions?q=` | Vorschläge für `@` | +| `POST /ai` | erweiterte Suche: `{ question }` → `{ answer, refs, model, truncated }` | + +## Netzwerk, Verbindungen, Historie, Stammdaten, Dashboard + +| Endpunkt | Zweck | +| --- | --- | +| `GET /api/network` | Knoten und Kanten für die Netzwerkansicht | +| `GET/POST/PATCH/DELETE /api/connections` | „kennt"-Verbindungen zwischen Kontakten | +| `GET /api/history`, `POST /api/history`, `DELETE /api/history/:id` | Verlauf lesen, Notiz schreiben, Eintrag entfernen | +| `GET/POST/PATCH/DELETE /api/options` | Stammdaten (Schreiben *admin*) | +| `GET /api/dashboard` | Kennzahlen und letzte Tätigkeiten | + +## perinco – `/api/perinco` + +| Endpunkt | Zweck | +| --- | --- | +| `GET /status` | `{ configured, url }` – ohne Einrichtung bleibt das Häkchen unsichtbar | +| `GET /contacts` | Kontakte des perinco CRM, gelesen über einen gemeinsamen Zwischenspeicher; wirft nie, sondern liefert im Fehlerfall eine leere Liste | + +## Systemschnittstelle – `/api/integrations` + +| Endpunkt | Zweck | +| --- | --- | +| `GET /contacts` | *Token* – die ICON-Kontakte für das perinco CRM. Nur Lesen, `PERINCO_INBOUND_TOKEN`, Vergleich mit `timingSafeEqual` | + +## Öffentlich – `/api/public` + +| Endpunkt | Zweck | +| --- | --- | +| `GET /tenders` | *offen* – Ausschreibungen mit `online = 1` und `status <> 'Archiviert'`, neueste zuerst | +| `GET /tenders/:id` | *offen* – eine davon | + +Beide antworten mit `Access-Control-Allow-Origin: *` und +`Cache-Control: public, max-age=60` und liefern nur `id`, `title`, `status`, +`notes`, `created_at`, `updated_at`.