ERP-Integration: Firmenablauf

Überblick

Dieser Leitfaden beschreibt, wie ein ERP-System eine Firma samt Betriebsstätten, Einsatzorten und Ansprechpartnern aus talent.Flow übernimmt und weiterpflegt. Er folgt demselben Muster wie der Bewerberablauf: Ereignis → Referenz → Abruf → Pflege.

Der wesentliche Unterschied zum Bewerberablauf: Firmen tragen eine externe Id. Damit lässt sich die Zuordnung zum ERP-Datensatz direkt im Datensatz führen, statt in einer eigenen Tabelle.

Der Ablauf im Bild

sequenceDiagram
    participant U as Anwender in talent.Flow
    participant TF as talent.Flow
    participant ERP as Ihr ERP-System
    U->>TF: Firma anlegen bzw. übertragen
    TF->>ERP: POST auf Ihre Webhook-URL
    ERP-->>TF: 200 OK
    ERP->>TF: GET /v3/customers/{entityId}
    TF-->>ERP: Firma inkl. offices[] und contacts[]
    Note over ERP: Übernahme mit importExternalId als Schlüssel
    ERP->>TF: PUT / POST / DELETE zur Pflege
    TF-->>ERP: 200 OK

Schritt 1: Webhook registrieren

curl -X POST https://api.talent360.io/v3/webhooks/subscribe \
  -H "Authorization: Bearer IHR_ACCESS_TOKEN" \
  -H "User-Agent: Mozilla/5.0 (Kundenname)" \
  -H "Content-Type: application/json" \
  -d '{"event": 1379, "url": "https://erp.example.com/hooks/talent360"}'

Ereignisse rund um die Firma

Ein ERP, das nur echte Kunden führt, abonniert 1379. Soll auch der Vertriebsvorlauf mitlaufen, kommt 1380 dazu. Die Ereignisse 1381 bis 1383 melden Nachträge an einer bereits übernommenen Firma — sie sind für den laufenden Abgleich relevant, nicht für die Erstübernahme.

Registrierungsregeln, Fehlerschwelle und Wiederherstellung sind identisch zum Bewerberablauf — insbesondere gilt auch hier: sofort mit 200 antworten, sonst wird die Registrierung nach 10 Fehlern pausiert.

Schritt 2: Die Firma abrufen

curl -X GET https://api.talent360.io/v3/customers/815 \
  -H "Authorization: Bearer IHR_ACCESS_TOKEN" \
  -H "User-Agent: Mozilla/5.0 (Kundenname)" \
  -H "Accept: application/json"

Struktur der Antwort:

CustomerReadDto
├─ id, name, description, notes, ranking
├─ corporationId, corporation          Unternehmensgruppe
├─ companyTypeId, companyType
├─ customerStatus, customerStatusChangedAtUtc
├─ importExternalId, importedAtUtc     ← Zuordnung zum Quellsystem
├─ createdAtUtc, modifiedAtUtc
├─ address, responsibility
├─ offices[]                           Betriebsstätten
│   ├─ id, companyType, description
│   ├─ email, telephone, telefax
│   ├─ costCenter, vatId               Kostenstelle, USt-IdNr.
│   ├─ importExternalId, importedAtUtc ← auch je Betriebsstätte
│   ├─ locations[]                     Einsatzorte, je mit importExternalId, importedAtUtc
│   └─ address, responsibility
└─ contacts[]                          Ansprechpartner, je mit importExternalId, assignedOfficeIds

Die Einzelabrufe brauchen Sie vor allem für gezielte Nachladungen nach den Ereignissen 1381–1383. Neu in V 3.4.0: Eine unbekannte oder gelöschte Id liefert an allen drei Einzelabrufen 404 mit Fehlerkörper; bisher kam 204 ohne Inhalt.

Schritt 3: Daten ändern

Alle Änderungsendpunkte sind Teil-Updates: Nur die übermittelten Felder werden geändert. Die Zuständigkeit (responsibility) und createdAtUtc werden dabei ebenfalls übernommen.

Schritt 4: Daten ergänzen

Ein Einsatzort hängt immer an einer Betriebsstätte — die Reihenfolge ist damit vorgegeben: erst Firma, dann Betriebsstätte, dann Einsatzort. Gehört die Firma zu einem Konzern, liefert der Konzernkatalog die zulässigen Werte für corporationId.

Schritt 5: Daten löschen

Neu in V 3.4.0: Für Betriebsstätten, Einsatzorte, Ansprechpartner und Anfragen gibt es Löschendpunkte. Damit lassen sich Löschungen aus dem ERP spiegeln und Testdaten entfernen.

Abgleich ohne Webhook

Falls Sie zusätzlich einen periodischen Abgleich brauchen — etwa zur Kontrolle oder nach einem längeren Ausfall:

Der bevorzugte Weg zur Wiederherstellung bleibt aber das Webhook-Protokoll, weil es exakt die Ereignisse liefert, die Ihr System verpasst hat — siehe Bewerberablauf.

Empfehlungen im Überblick

Checkliste vor dem Go-Live