SOAP interface

Information for companies

Authentication

All managing organisations must authenticate themselves using a time-limited access token (OAuth Bearer Token). To do this, the portal (in the ‘Data Import Settings’ tab) provides you with the details for the service user (ID and secret). Using these details, the organisation can request a time-limited access token via the interface. The access token must then be transmitted to the incident interface as a bearer token within the authentication header during HTTP communication with the interface.

If a company manages several other companies, the access token must be created exclusively for the CareFlex ID of the managing company. All other reports relating to different CareFlex IDs must be submitted using the managing company’s access token. Consequently, only one service user/service user secret combination is required to manage all companies assigned to the main CareFlex ID.

Authorisation

All companies must submit both an API token and a CareFlex ID when making a declaration. When submitting the
declaration, they must include the CareFlex ID (of the eligible company) and the API token (of the declaring company).
The API token can be generated in the company portal under “CRM” / “Data import settings”. There is only one API token for all entities managed by a company.

The validity of the CareFlex ID in conjunction with the API token is not checked when the message is sent, but can be verified via the feedback function once the message has been successfully imported into the portal.

Functionalities of the interface

  • Reporting HR incidents with and without master data
  • SOAP binding: NewIncident
  • Note: Up to 100 HR incidents can be transferred in a single request.
  • Empty message
  • SOAP binding: NoIncident
  • Description: This request must be made if no HR incidents have occurred in the current month.

Communication example

Access token query

POST EP1 (see above)
with a JSON body:
{
"grant_type":"password",
"username":"<user_id (service user)>",
"password":"<user_secret (service user)>"
}
and headers:
"Content-Type: application/json"

The response contains an access token that is valid for 12 hours

{
"access_token":"P7kmfo8HXItLLOReHq65o4%§ggg45dYhSm5ODc",
"token_type":"Bearer",
"expires_in":43200,
                "created_at":1589887223
}

The access token is used as a bearer token when communicating with the interface

POST EP2 (see above)
with SOAP headers:
“Authorization: Bearer
P7kmfo8HXItLLOReHq65o4%§ggg45dYhSm5ODc” “Content-Type: text/xml;charset=UTF-8”

Empty message

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 examples

Notification with and without master data

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>
<newIncident>
<employeeId>4811</employeeId>
<validFrom>2020-04-24</validFrom>
<createdAt>2020-04-24</createdAt>
<type>NEW</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>Branch 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>
</newIncident>
<plainIncident>
<externalId>CustomerId-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: invalid value</message>
</incidentError>
</incident>
<incident>
<rowNumber>2</rowNumber>
<incidentId>
3b2d4888-a25c-4c8b-9818-aa6b428bd2df
</incidentId>
<externalId>CustomerId-4711-2345</externalId>
<employeeId>35801170498</employeeId>
<type>RST</type>
</incident>
</incidentResponseList>
</ns3:NewIncidentResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>