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.

Kurzfassung: Webhook auf das Firmen-Ereignis registrieren, danach GET /v3/customers/{id} aufrufen — dieser eine Aufruf liefert die Firma mit Betriebsstätten, deren Einsatzorten und den Ansprechpartnern vollständig verschachtelt.

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 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"}'

Zweck	Endpunkt
Webhook registrieren	`POST /v3/webhooks/subscribe`
Registrierungen prüfen	`GET /v3/webhooks/subscriptions`
Verfügbare Ereignistypen	`GET /v3/webhooks/event/types`
Protokoll lesen	`POST /v3/webhooks/protocol`

Ereignisse rund um die Firma

Id	Ereignis	Cloud-Event	Bedeutung
`1379`	Company created (customer)	`io.talent360.customercreatedcustomer`	Firma als Kunde angelegt
`1380`	Company created (interested party)	`io.talent360.customercreatedinterestedparty`	Firma als Interessent angelegt
`1381`	Company office added	`io.talent360.customerofficeadded`	Betriebsstätte hinzugefügt
`1382`	Company location added	`io.talent360.customerlocationadded`	Einsatzort hinzugefügt
`1383`	Company contact added	`io.talent360.customercontactadded`	Ansprechpartner hinzugefügt

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"

Ein Aufruf genügt. Die Antwort enthält die Firma, darin offices[] mit den Betriebsstätten, in jeder Betriebsstätte locations[] mit den zugeordneten Einsatzorten, sowie contacts[] mit den Ansprechpartnern. Sie müssen die Unterobjekte nicht einzeln nachladen.

Struktur der Antwort:

CustomerReadDto
├─ id, name, description
├─ 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
│   └─ address, responsibility
└─ contacts[]                          Ansprechpartner

Nutzen Sie importExternalId. Das Feld ist beim Anlegen einer Firma schreibbar und wird beim Lesen zurückgeliefert — sowohl an der Firma als auch an jeder Betriebsstätte. Legen Sie dort Ihre ERP-Id ab, dann brauchen Sie keine separate Zuordnungstabelle und kein Matching über den Firmennamen. importedAtUtc hält fest, wann der Datensatz übernommen wurde.

Zweck	Endpunkt
Firma inkl. Betriebsstätten und Kontakten	`GET /v3/customers/{id}`
Betriebsstätte einzeln lesen	`GET /v3/customers/offices/{officeId}`
Einsatzort einzeln lesen	`GET /v3/customers/locations/{locationId}`
Ansprechpartner einzeln lesen	`GET /v3/customers/contacts/{contactId}`

Die Einzelabrufe brauchen Sie vor allem für gezielte Nachladungen nach den Ereignissen 1381–1383.

Schritt 3: Daten ändern

Zweck	Endpunkt
Firmenstammdaten ändern	`PUT /v3/customers/{customerId}`
Firmenstatus ändern	`PUT /v3/customers/{customerId}/customerstatus`
Vertragsstatus ändern	`PUT /v3/customers/{customerId}/contractstatus`
Betriebsstätte ändern	`PUT /v3/customers/{customerId}/offices/{officeId}`
Ansprechpartner ändern	`PUT /v3/customers/{customerId}/contacts/{contactId}`

Für Einsatzorte gibt es keinen Änderungsendpunkt. Einsatzorte lassen sich anlegen und lesen, aber nicht ändern. Eine Korrektur bedeutet in der Praxis: neuen Einsatzort anlegen und den alten fachlich außer Betrieb nehmen.

Schritt 4: Daten ergänzen

Zweck	Endpunkt
Firma anlegen	`POST /v3/customers`
Betriebsstätte anlegen	`POST /v3/customers/{customerId}/offices`
Einsatzort anlegen	`POST /v3/customers/{customerId}/offices/{officeId}/locations`
Ansprechpartner anlegen	`POST /v3/customers/{customerId}/contacts`
Beruf anlegen	`POST /v3/customers/{customerId}/professions`

Ein Einsatzort hängt immer an einer Betriebsstätte — die Reihenfolge ist damit vorgegeben: erst Firma, dann Betriebsstätte, dann Einsatzort.

Schritt 5: Daten löschen

Im Firmenbereich gibt es kein Löschen. Weder die Firma, noch Betriebsstätte, Einsatzort oder Ansprechpartner lassen sich über die API entfernen — es existieren dafür keine Endpunkte. Planen Sie Ihre Integration so, dass Löschen nicht Teil des Regelbetriebs ist. Soll eine Firma aus dem operativen Blick verschwinden, führt der Weg über den Status: PUT /v3/customers/{customerId}/customerstatus.

Das ist bewusst asymmetrisch zum Bewerberablauf: dort gibt es immerhin für vier Unterobjekte einen DELETE-Endpunkt, hier für keines.

Abgleich ohne Webhook

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

Zweck	Endpunkt
Firmenänderungen im Zeitraum	`GET /v3/customers/changes`
Firmenänderungen pro Tag	`GET /v3/customers/changes/{date}`
Firmenänderungen pro Stunde	`GET /v3/customers/changes/{date}/{hour}`

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

Firma über GET /v3/customers/{id} in einem Aufruf übernehmen, statt Unterobjekte einzeln zu laden.
importExternalId beim Anlegen setzen — an der Firma und an jeder Betriebsstätte.
Im Webhook-Handler sofort 200 antworten, Verarbeitung asynchron anstoßen.
Ereignis-id als Idempotenzschlüssel speichern.
Reihenfolge einhalten: Firma → Betriebsstätte → Einsatzort.
Löschen nicht einplanen; Statuswechsel vorsehen.
Access Token zwischenspeichern (siehe Authentifizierung).

Checkliste vor dem Go-Live

Registrierung für das passende Firmen-Ereignis ist angelegt und über GET /v3/webhooks/subscriptions geprüft.
Entschieden ist, ob auch Interessenten (1380) übernommen werden.
Nachtrags-Ereignisse (1381–1383) werden verarbeitet oder bewusst ignoriert.
importExternalId wird gesetzt und beim Rücklesen ausgewertet.
Der Fall „Einsatzort geändert" ist fachlich geklärt — ändern ist nicht möglich.
Ein Wiederherstellungslauf über /webhooks/protocol ist implementiert und getestet.