Authentifizierung
Alle verwaltenden Unternehmen müssen sich über einen zeitlich begrenztes Access-Token (oAuth Bearer Token) authentifizieren. Dafür erhälst du ü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
Funktionalitäten der Schnittstelle
- Meldung HR-Vorfall mit und ohne Stammdaten
- SOAP-Binding: NewIncident
- Hinweis: Bis zu 100 HR-Vorfälle können in einem Request übertragen werden.
- Leermeldung
- SOAP-Binding: NoIncident
- 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
POST EP2 (siehe oben)
with SOAP headers:
“Authorization: Bearer P7kmfo8HXItLLOReHq65o4%§ggg45dYhSm5ODc”
"Content-Type: text/xml;charset=UTF-8"
Leermeldung
REQUEST
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:car="http://n4.de/careflex">
<soapenv:Header/>
<soapenv:Body>
<car:NoIncidentRequest>
<careflexId>09ce3580d84bf090</careflexId>
<apitoken>maL0HMDszA2b9PKiqCAZRGh0ZDpVjmvc</apitoken>
<createdAt>2020-08-24</createdAt>
</car:NoIncidentRequest>
</soapenv:Body>
</soapenv:Envelope>
RESPONSE
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns3:NoIncidentResponse xmlns:ns3="http://n4.de/careflex"/>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Payload-Beispiele
Meldung mit und ohne Stammdaten
REQUEST
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://n4.de/careflex/2.0">
<soapenv:Header/>
<soapenv:Body>
<ns:NewIncidentRequest>
<careflexId>09ce3580d84bf087</careflexId>
<apitoken>88ea9396-386f-4130-bd00-1dd34e5636bd</apitoken>
<incidentList>
<plainIncident>
<employeeId>4711</employeeId>
<validFrom>2020-04-24</validFrom>
<createdAt>2020-04-24</createdAt>
<type>RST</type>
</plainIncident>
<neuIncident>
<employeeId>4811</employeeId>
<validFrom>2020-04-24</validFrom>
<createdAt>2020-04-24</createdAt>
<type>NEU</type>
<employee>
<title>Prof. Dr.</title>
<firstName>Thomas</firstName>
<lastName>Mustermann</lastName>
<birthday>1979-01-15</birthday>
<sex>m</sex>
<address>
<street>Musterstraße</street>
<houseNumber>9</houseNumber>
<addressSuffix>c/o Max Hauptmieter</addressSuffix>
<zipCode>01234</zipCode>
<city>Musterstadt</city>
<country>DE</country>
</address>
<job>
<employmentSite>Geschäftsstelle 1</employmentSite>
<employmentStatus>T</employmentStatus>
<startOfEmployment>2020-04-24</startOfEmployment>
<personnelNumber>123654789</personnelNumber>
<management>true</management>
</job>
<contact>
<emailBusiness>
thomas.mustermann@musterfirma.de
</emailBusiness>
<mobileBusiness>0123 12345678</mobileBusiness>
<landlineBusiness>030 12345678</landlineBusiness>
</contact>
</employee>
</neuIncident>
<plainIncident>
<externalId>KundenId-4711-2345</externalId>
<employeeId>35801170498</employeeId>
<validFrom>2020-04-24</validFrom>
<createdAt>2020-04-24</createdAt>
<type>RST</type>
</plainIncident>
</incidentList>
</ns:NewIncidentRequest>
</soapenv:Body>
</soapenv:Envelope>
RESPONSE
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns3:NewIncidentResponse xmlns:ns3="http://n4.de/careflex/2.0">
<importId>550a80b5-de70-4078-860e-c03d75b1dc49</importId>
<incidentResponseList>
<incident>
<rowNumber>0</rowNumber>
<incidentId>
3b2d4888-a25c-4c8b-9818-aa6b428bd2de
</incidentId>
<employeeId>4711</employeeId>
<type>RSTxxx</type>
</incident>
<incident>
<rowNumber>1</rowNumber>
<incidentId>
3615b6af-e2f2-4dcf-a945-d9ad8546228b
</incidentId>
<employeeId>4811</employeeId>
<type>NEU</type>
<incidentError>
<code>422</code>
<message>The validation failed: The content of the field 'type' is invalid with the reason: ungültiger Wert</message>
</incidentError>
</incident>
<incident>
<rowNumber>2</rowNumber>
<incidentId>
3b2d4888-a25c-4c8b-9818-aa6b428bd2df
</incidentId>
<externalId>KundenId-4711-2345</externalId>
<employeeId>35801170498</employeeId>
<type>RST</type>
</incident>
</incidentResponseList>
</ns3:NewIncidentResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>