Die API von easycompliance ermöglicht es Anwendungen aller Art, direkt auf die Sanktionslistenprüfung von easycompliance zuzugreifen. So können bspw. Onlineshops noch während des Bestellvorgangs den Kunden gegen die aktuellsten Sanktionslisten prüfen. Ebenso kann die Sanktionslistenprüfung in alle anderen (Web-)Anwendungen direkt integriert werden.
| Parameter | Wert | Beschreibung |
|---|---|---|
| api_key | (varchar) | Eindeutiger Schlüssel für die Authentifizierung. Wird Ihnen vom Kundendienst mitgeteilt. Ohne API-Key ist ein Zugriff auf die API nicht möglich |
| method | (int) 1, 2, 3 oder 4 | 1=Einzelprüfung. 2=Prüfung und Name wird auf die Liste für die automatische Listenprüfung gesetzt. 3=Ausgabe der Treffer, die die Listenprüfung innerhalb der letzten 24h generiert hat. 4=Datum des letzten Sanktionslistenupdates im Format dd.mm.yyyy. |
| accuracy | (int) Wert > 50 | Suchgenauigkeit. Wert kann zwischen 50 und 100 liegen (Ganzzahl). Ist kein Wert definiert oder liegt dieser unter 50, wird das eingestellte Suchmuster des Kunden übernommen |
| name | (varchar) | Name der zu prüfenden Organisation oder Person (utf8). Bitte beachten Sie die Hinweise zur Datenqualität aus unserem Handbuch. |
| ref | (varchar) | Ihre Referenz. Bspw. Kunden-, Lieferanten-, oder Personalnummer. (Optional) |
Um die API nutzen zu können, muss ein POST-Request an die API-URL gesendet werden. Die API-URL erhalten Sie zusammen mit Ihrem API-Key vom Kundendienst. Die oben genannten Parameter werden durch die POST-Methode zur Verarbeitung an easycompliance übergeben. Als Rückantwort erhalten Sie eine Ausgabe im JSON-Format (bei method=1, 2 oder 3) bzw. als plain text (bei method=4). Zusätzlich werden HTTP-Statuscodes übergeben.
{
"percent":100,
"data":{
"header":{
"validFrom":"2015-03-28",
"validTo":"4000-01-01",
"entryDate":"2015-03-28",
"entityType":"P",
"datAkt":"2015-04-02",
"source":"CHSECO - RUSSIA",
"comm":"KOMMENTAR DER SANKTIONSLISTE",
"commEn":"KOMMENTAR AUF ENGLISCH",
"dob":"1991-01-30 - 1991-01-30 oder 1991-04-30 - 1991-04-30",
"pob":"St. Petersburg",
"status":"i"
},
"name":[
{
"datAkt":"2015-04-02",
"status":"i",
"name":"BEISPIELNAME",
"nationality":"RU",
"passNo":"123456",
"identNo":"R456123789"
},
{
"datAkt":"2015-04-02",
"status":"i",
"name":"BEISPIEL ALIAS",
"nationality":"RU",
"passNo":"4445466",
"identNo":"987654321"
}
],
"address":[
{
"datAkt":"2015-04-02",
"status":"i",
"street":"",
"houseNo":"",
"nameCo":"",
"building":"",
"roomNo":"",
"poCode":"",
"poBox":"",
"city":"Nimroz",
"state":"",
"dist":"",
"country":"AF"
},
{
"datAkt":"2015-04-02",
"status":"i",
"street":"",
"houseNo":"",
"nameCo":"",
"building":"",
"roomNo":"",
"poCode":"",
"poBox":"",
"city":"Kabul",
"state":"",
"dist":"",
"country":"AF"
}
]
}
}
| Parameter | Typ | Beschreibung |
|---|---|---|
| name | string | Name, der durch die Listenprüfung geprüft wurde |
| ref | string | Referenznummer (bspw. Ihre Kunden- oder Lieferantennummer). Wenn leer ist die Ausgabe null |
| time | int | Zeitstempel des Treffers im UNIX-Format |
| Parameter | Typ | Beschreibung |
|---|---|---|
| percent | string | Enthält die prozentuale Übereinstimmung des gesuchten Namens mit dem Treffer |
| data | objekt | Enthält alle Informationen der Sanktionsliste |
| header | objekt | Enthält die "Kopfdaten" der Sanktionsliste |
| name | array | Enthält alle zugeordneten Namen und Namensinformationen als Objekt |
| address | array | Enthält alle zugeordneten Adressen und Adressinformationen als Objekt |
| Parameter | Wert | Beschreibung |
|---|---|---|
| validTo | Datum im Format: YYYY-MM-DD | Wenn Datum = 4000-01-01 dann ist die Sanktion unbegrenzt gültig |
| dob | 1991-01-30 - 1991-01-30 oder... | Geburtsdaten (date of birth) |
| pob | (varchar) | Geburtsort (place of birth) |
| status | i oder u | i=Initialeintrag; u=aktualisierter Datensatz |
//POST-Parameter definieren
$query_vals = array(
'api_key' => 'IHR-API-KEY',
'method' => '2',
'accuracy' => '90',
'name' => 'NAME FÜR PRÜFUNG',
'ref' => '12345'
);
//POST-String Generieren
foreach($query_vals as $key => $value) {
$request .= $key.'='.urlencode($value).'&';
}
$request = rtrim($request, '&');
//cURL mit API-URL initialisieren und Anfrage senden
$ch = curl_init("https://www.easycompliance-api-url.de");
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 4);
curl_setopt($ch, CURLOPT_TIMEOUT, 8);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
$response = curl_exec($ch);
curl_close ($ch);
//Ergebnis ausgeben
echo $response;
Permission Denied: Die Anfrage enthält keine POST-Elemente (HTTP-Statuscode: 405). Wrong API-KEY: Ungültiger oder fehlerhafter API-Key (HTTP-Statuscode: 401).
Es ist empfehlenswert, grundsätzliche Fehler, die im Zusammenhang mit API-Abfragen auftreten können, in der zu entwickelnden Schnittstelle zu beachten. So sollte, um beim Beispiel mit cURL zu bleiben, curl_error() genutzt werden. So kann bspw. ausgeschlossen werden, dass die API-URL nicht erreichbar ist (Hinweis: Im o.g. Beispiel werden hierzu CONNECTTIMEOUT und TIMEOUT verwendet. Die Nichterreichbarkeit der API behindert somit bspw. keine Bestellprozesse).
Ferner sollte beachtet werden, dass bei einer korrekten Abfrage eine leere Rückgabe der API bedeutet, dass kein Treffer auf den Sanktionslisten gefunden wurde. Da eine fehlerhafte Abfrage bei unzureichendem Error Handling in zu entwickelnden Schnittstellen jedoch auch eine leere Rückgabe erzeugen kann, sollten allgemeine Fehler vor der Auswertung der API-Rückgabe beachtet werden.