Jobbörsen-Schnittstelle – Technik für Partner

Diese Seite beschreibt die beiden Endpunkte, über die eine Jobbörse offene Stellen abruft und Bewerbungen zurückschickt. Die Einrichtung (Partner verbinden, Schlüssel erzeugen, Stellen freigeben) erfolgt in Cosmos unter Vermittlung → Einstellungen → Jobbörsen-Anbindung. Die Funktion ist ein eigenes Modul (Jobbörsen-Anbindung) und muss für die Firma freigeschaltet sein.

Zugang

Jeder Partner bekommt einen eigenen Schlüssel. Er wird bei „Partner verbinden“ einmalig angezeigt und kann jederzeit erneuert oder widerrufen werden.
Der Schlüssel gilt für genau eine Anbindung und für beide Richtungen.
Er wird als Kopfzeile mitgeschickt: Authorization: Bearer <schlüssel>.
Die Adressen enthalten den Kurznamen der Anbindung (<kanal>). Er wird bei der Einrichtung angezeigt.

Stellen abrufen

GET https://<projekt>.supabase.co/functions/v1/job-feed/<kanal>

Die Antwort enthält alle Stellen, die gerade ausgeschrieben sind, mit einem Eintrag je Standort:

{
  "count": 1,
  "jobs": [
    {
      "id": "0b6f1c2e-0000-4000-8000-00000000a001",
      "title": "Fahrer (m/w/d)",
      "description": "<p>…</p><h3>…</h3><ul><li>…</li></ul>",
      "url": "https://…/bewerben/…?job=0b6f1c2e-…",
      "apply_url": "https://…/bewerben/…?job=0b6f1c2e-…#apply",
      "employment_type": "FULL_TIME",
      "city": "Musterstadt",
      "postal_code": "12345",
      "country_code": "DE",
      "questions": [
        {
          "id": "fuehrerschein_d",
          "type": "select",
          "question": "Hast du einen Führerschein Klasse D?",
          "required": true,
          "options": [ { "value": "yes", "label": "Ja" }, { "value": "no", "label": "Nein" } ]
        },
        { "id": "start", "type": "date", "question": "Ab wann kannst du anfangen?", "required": false, "format": "dd/MM/yyyy" }
      ]
    }
  ]
}

id ist je Standort fest und ändert sich nie. Kommt ein Standort hinzu, kommt ein Eintrag hinzu.
description ist HTML und enthält nur die Tags p, h3, ul, li und br. Der Text ist vollständig maskiert.
employment_type fehlt, wenn für die Beschäftigungsart keine Zuordnung eingestellt ist. Die Zuordnung wird in der Anbindung gepflegt.
questions steht nur bei Stellen mit Zusatzfragen, sonst fehlt das Feld. Ohne Fragen ist der Feed Byte für Byte derselbe wie vorher. Das genaue Format steht unten unter Zusatzfragen im Feed.
Die Antwort trägt ein ETag. Mit If-None-Match kommt 304, wenn sich nichts geändert hat.

Antwort	Bedeutung
`200`	vollständige Liste; `count: 0` heißt wirklich „keine Stelle ausgeschrieben“
`304`	unverändert seit dem übergebenen `ETag`
`401`	Schlüssel fehlt, ist unbekannt oder gehört nicht zu dieser Adresse
`403`	Schlüssel widerrufen oder abgelaufen, Anbindung abgeschaltet, Modul aus
`429`	zu viele Abrufe, `Retry-After` beachten
`503`	vorübergehende Störung – bisherigen Stand behalten, später erneut abrufen

Bei einer Störung kommt nie eine leere Liste, sondern immer 503.

Bewerbung senden

POST https://<projekt>.supabase.co/functions/v1/job-board-apply/<kanal>, eine Bewerbung je Aufruf, JSON:

{
  "job_id": "0b6f1c2e-0000-4000-8000-00000000a001",
  "job_title": "Fahrer (m/w/d)",
  "source": { "name": "…" },
  "candidate": { "first_name": "…", "last_name": "…", "email_address": "…", "phone_number": "…" },
  "attachments": [ { "name": "lebenslauf.pdf", "type": "CV", "content_type": "application/pdf", "data": "<base64>" } ],
  "screening_question_answers": [ { "question_id": "…", "answer": "yes" } ]
}

200 mit "status":"ok" heißt gespeichert: Bewerber, Bewerbung und Dateien.
200 mit "status":"not_processed" heißt: Die Sendung lässt sich nie verarbeiten und wird nicht wiederholt gebraucht. Die meisten Partner wiederholen alles außer 200 — deshalb ist das die Vorgabe.
Wiederholungen derselben Bewerbung (gleiche Person, gleiche Stelle, im eingestellten Zeitfenster) werden erkannt und ebenfalls mit 200 beantwortet. Es entsteht nichts doppelt.
Bewerbungen auf eine unbekannte oder nicht mehr ausgeschriebene Stelle werden angenommen und markiert.
Antworten auf Zusatzfragen kommen in screening_question_answers: [{ "question_id", "answer" }]. Was mit ihnen geschieht, steht unten unter Antworten auf Zusatzfragen. Eine Antwort führt nie zur Ablehnung der Bewerbung.
Anhänge werden am Inhalt erkannt (PDF, DOCX, JPEG, PNG, je nach Einstellung der Anbindung). Ein unzulässiger oder zu großer Anhang wird verworfen und vermerkt; die Bewerbung wird trotzdem angenommen.

Antwort	Bedeutung	Erneut senden?
`200` `{"status":"ok"}`	gespeichert (neu, Wiederholung, unbekannte Stelle, verworfener Anhang)	nein
`200` `{"status":"not_processed"}`	nie verarbeitbar: kein gültiges JSON, größer als 40 MB, oder Person nicht anlegbar (kein Name, bzw. weder E-Mail noch Telefon). Nichts gespeichert, im Eingangsprotokoll als verworfen vermerkt. Vorgabe je Anbindung.	nein
`400` / `413` / `422`	dieselben Fälle, wenn die Anbindung auf „Ablehnen“ steht	nein, Sendung korrigieren
`401` / `403`	Zugang oder Anbindung nicht in Ordnung	erst nach Korrektur
`429`	zu viele Aufrufe	ja, nach `Retry-After`
`503`	vorübergehende Störung – nichts gespeichert	ja

Nach einer gespeicherten Bewerbung benachrichtigt Cosmos das Team und verschickt, wenn eingestellt, eine Eingangsbestätigung per E-Mail. WhatsApp wird nie automatisch versendet.

Zusatzfragen im Feed

Der Partner hat für die Antworten ein Format vorgegeben, für die Fragen im Feed nicht. Das folgende Format ist aus den Antworttypen abgeleitet. Die Rückfrage beim Partner läuft noch.

Feld	Typ	Bedeutung
`id`	Text, `A–Z a–z 0–9 _ . -`, höchstens 64 Zeichen	Stabile Kennung. Sie kommt mit der Antwort als `question_id` zurück.
`type`	`text`, `textarea`, `select`, `multiselect`, `date`, `file`	Antwortart
`question`	Text, höchstens 500 Zeichen	Fragetext für Bewerber
`required`	`true`/`false`	Pflichtfrage. Das prüft der Partner, Cosmos lehnt deswegen nichts ab.
`options`	Liste `{ "value", "label" }`	nur bei `select`/`multiselect`, 1 bis 50 Einträge. Ja/Nein-Fragen nutzen die Werte `yes`/`no`, nie `true`/`false`.
`format`	`dd/MM/yyyy`, `MM/dd/yyyy` oder `yyyy-MM-dd`	nur bei `date`: das Format der Frage, sonst der Rückfall der Anbindung. Fehlt beides, fehlt das Feld.

Fragen hängen an der Stelle. Jeder Standort, also jede Anzeige, trägt dieselben Fragen in derselben Reihenfolge.
Eine id bedeutet immer dieselbe Frage. Text, Antwortart, Optionen und Format einer Frage lassen sich nicht ändern. Eine inhaltliche Änderung legt eine neue Frage mit neuer id an und archiviert die alte. Eine archivierte Frage fehlt im Feed, Antworten darauf werden aber weiter zugeordnet. Eine id wird je Stelle nie ein zweites Mal vergeben.
file-Fragen erscheinen nur, wenn die Anbindung sie ausdrücklich erlaubt. Die Vorgabe ist aus, denn der Lebenslauf kommt ohnehin mit.

Antworten auf Zusatzfragen

Antwortart	erwartete `answer`	angenommen wird auch
`select`	`value` als Text	Beschriftung statt `value`; `true`/`false` als `yes`/`no`
`multiselect`	Liste von `value`s	Text mit Kommas
`date`	Text im `format` der Frage	`yyyy-MM-dd` immer
`text`, `textarea`	Text	Zahl, `true`/`false`
`file`	`{ "name", "content_type", "data" }` (Base64)	—

Nichts wird abgelehnt. Jede Antwort wird mit ihrem Rohwert gespeichert und, wo nötig, markiert:
- unbekannte question_id, etwa von einer Frage, die es nicht mehr gibt;
- Antwort auf eine archivierte, ältere Fassung;
- Wert, der zu keiner Option passt;
- unlesbares Datum.
Datum: dd/MM und MM/dd sind bei Tagen bis 12 nicht unterscheidbar. Gelesen wird deshalb in dieser Reihenfolge:
1. im Format der Frage;
2. sonst im Rückfall-Format der Anbindung;
3. sonst nur, wenn der Wert eindeutig ist. Ein mehrdeutiges Datum wird roh gespeichert und als mehrdeutig markiert, nie geraten. Passt ein Datum nur in die andere Schreibweise (12/31/2030 bei dd/MM/yyyy), wird es so gelesen und als Abweichung markiert.
Datei: Sie wird wie ein Anhang geprüft, nach Dateityp am Inhalt, Größe und Anzahl laut Anbindung. Danach liegt sie bei den Dokumenten des Bewerbers; in der Antwort stehen nur Name und Typ, nie der Inhalt. Eine unzulässige Datei wird verworfen und markiert, die Bewerbung bleibt angenommen.
Die Antworten stehen in der Bewerberakte unter „Bewerbungen“. Je Kennung lassen sie sich einem Zusatzfeld zuordnen; die Zuordnung ist eine Tabelle in der Anbindung. Für eine unbekannte Kennung oder eine Datei entsteht kein neues Zusatzfeld.

Zugang​

Stellen abrufen​

Bewerbung senden​

Zusatzfragen im Feed​

Antworten auf Zusatzfragen​

Zugang

Stellen abrufen

Bewerbung senden

Zusatzfragen im Feed

Antworten auf Zusatzfragen