REST-Schnittstelle
Authentifizierung
Alle verwaltenden Unternehmen müssen sich über einen zeitlich begrenztes Access-Token (oAuth Bearer Token) authentifizieren. Dafür erhalten sie über das Portal (im Tab "Einstellungen für den Datenimport") die Daten für den Service-User zur Verfügung gestellt (ID und Secret). Mit diesen Daten kann das Unternehmen ein zeitlich begrenztes Access-Token über die Schnittstelle anfragen. Das Access-Token muss dann bei der HTTP-Kommunikation mit der Schnittstelle an die Vorfalls-Schnittstelle als Bearer-Token innerhalb der Authentication-Header übermittelt werden.
Sofern ein Unternehmen mehrere weitere Unternehmen mit verwaltet, so muss das Access-Token ausschließlich für die CareFlex ID des verwaltenden Unternehmens erstellt werden. Alle weiteren Meldungen zu unterschiedlichen CareFlex IDs werden mit dem Access-Token des verwaltenden Unternehmens gemeldet. Es wird demnach nur eine Service-User/Service-User-Secret Kombination zur Verwaltung aller der Haupt-CareFlex ID zugeordneten Unternehmen benötigt.
Autorisierung
Alle Unternehmen müssen bei der Meldung sowohl API-Token und CareFlex ID übermitteln.
Sie schicken mit der Meldung die CareFlex ID (des anspruchsberechtigten Unternehmens) und den API-Token (des meldenden Unternehmens) mit.
Der API-Token kann im Unternehmensportal unter “CRM” / “Einstellungen für den Datenimport” generiert werden. Es gibt nur einen API-Token für alle durch ein Unternehmen verwalteten Entitäten.
Die Korrektheit der CareFlex ID in Verbindung mit dem API-Token wird nicht beim Absetzen der Nachricht geprüft, sondern kann nach erfolgreichem Import der gesendeten Nachricht in das Portal über die Feedback-Funktion überprüft werden.
Schnittstellenbeschreibung
Endpunkte
Die REST-Schnittstelle bietet folgende Funktionalität:
Meldung von HR-Vorfällen mit und ohne Stammdaten
REST-Endpunkt: incident/new
Hinweis: Bis zu 100 HR-Vorfälle können in einem REST-Request übertragen werden.
Leermeldung
REST-Endpunkt: incident/none
Beschreibung: Dieser Request muss gemacht werden, wenn im aktuellen Monat keine HR-Vorfälle aufgetreten sind.
Kommunikationsbeispiel
Access-Token Abfrage:
Endpunkte
Die REST-Schnittstelle bietet folgende Funktionalität:
Meldung von HR-Vorfällen mit und ohne Stammdaten
REST-Endpunkt: incident/new
Hinweis: Bis zu 100 HR-Vorfälle können in einem REST-Request übertragen werden.
Leermeldung
REST-Endpunkt: incident/none
Beschreibung: Dieser Request muss gemacht werden, wenn im aktuellen Monat keine HR-Vorfälle aufgetreten sind.
Kommunikationsbeispiel
Access-Token Abfrage:
POST EP1 (siehe oben)
with json body:
{
"grant_type":"password",
"username":"<user_id (service user)>",
"password":"<user_secret (service user)>"
}
and headers:
"Content-Type: application/json"
Die Antwort enthält Access-Token das 12 Stunden gültig ist:
{
"access_token":"P7kmfo8HXItLLOReHq65o4%§ggg45dYhSm5ODc",
"token_type":"Bearer",
"expires_in":43200,
"created_at":1589887223
}
Das Access-Token wird bei der Kommunikation mit der Schnittstelle als Bearer-Token verwendet:
REST
POST EP3 (siehe oben)
with REST headers:
"Authorization: Bearer P7kmfo8HXItLLOReHq65o4%§ggg45dYhSm5ODc"
"Content-Type: application/json;charset=UTF-8"
Payload-Beispiele
Meldung mit und ohne Stammdaten:
REQUEST
{
"careflexId": "09ce3580d84bf087",
"apiToken": "maL0HMDszA2b9PKiqCAZRGh0ZDpVjmvc",
"incidentList": [
{
"externalId": "1000" ,
"type": "NEU",
"employeeId": "49239697103",
"createdAt": "2020-10-24",
"validFrom": "2020-10-24",
"employee": {
"title": "Prof. Dr.",
"firstName": "Thomas",
"lastName": "Mustermann",
"birthday": "1979-01-15",
"sex": "m",
"address": {
"street": "Musterstraße",
"houseNumber": 9,
"addressSuffix": "c/o Max Hauptmieter",
"zipCode": "01234",
"city": "Musterstadt",
"country": "DE"
},
"job": {
"employmentSite": "Geschäftsstelle 1",
"employmentStatus": "T",
"startOfEmployment": "2020-04-24",
"personnelNumber": "string",
"management": false
},
"contact": {
"emailBusiness": "thomas.mustermann@musterfirma.de",
"mobileBusiness": "0123 12345678",
"landlineBusiness": "030 12345678"
}
}
},
{
"externalId": "1234-xx",
"type": "SDB",
"createdAt": "2021-06-30",
"validFrom": "2021-07-01",
"employeeId": "12345678901",
"employee": {
"firstName": "Thomas",
"lastName": "Mustermann"
}
},
{
"type": "WIK",
"employeeId": "49239697103",
"createdAt": "2020-09-24",
"validFrom": "2020-08-24"
}
]
}
RESPONSE
{
"importId": "8d2adbc0-4d63-4cec-a8f4-445b08a3e33e",
"incidentResponseList": [
{
"rowNumber": 0,
"incidentId": "8ba8977c-a75b-4ec0-9798-7a7f14209720",
"externalId": "1000",
"employeeId": "49239697103",
"type": "NEU"
},
{
"rowNumber": 1,
"incidentId": "916aebfc-2feb-429b-8631-52703a195ad9",
"externalId": "1234-xx",
"employeeId": "12345678901",
"type": "SDB"
},
{
"rowNumber": 2,
"incidentId": "e8b77933-2a31-404c-9e23-8b547b37068f",
"externalId": null,
"employeeId": "49239697103",
"type": "WIK"
}
]
}
Leermeldung:
REQUEST
{
"careflexId": "09ce3580d84bf087",
"apiToken": "maL0HMDszA2b9PKiqCAZRGh0ZDpVjmvc",
"createdAt": "2020-10-24"
}
RESPONSE
HTTP-RESPONSE: 201 Created