Die API von easycompliance

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

Die API ist sehr einfach aufgebaut und kann über Parameter gesteuert werden. Die folgenden Parameter stehen zur Verfügung:

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 oder 2	1=Einzelprüfung. 2=Prüfung und Name wird auf die Liste für die automatische Listenprüfung gesetzt.
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)

Funktionsweise

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. Zusätzlich werden HTTP-Statuscodes übergeben.

Ausgabe

Ist die Ausgabe leer, wurde kein Treffer gefunden (HTTP-Statuscode: 204). Andernfalls erhalten Sie folgendes JSON-Objekt (bei Treffern auf mehreren Sanktionslisten stellt jede Sanktionsliste ein eigenständiges Objekt dar; HTTP-Statuscode: 200):

{
"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"
		}
	]
	}
}

Erklärung der Rückgabeparameter

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

Detailbeschreibung
Die einzelnen Parameter innerhalb der Rückgabeobjekte und -arrays erklären sich i.d.R. von selbst. Diese sind aus den Sanktionslisten des Bundesanzeiger Verlages übernommen. Eine Erklärung benötigen die folgenden Übergabewerte:

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

Beispielanfrage

Im Folgenden wird eine Anfrage mittels cURL dargestellt. So können bspw. Onlineshops an die Sanktionslistenprüfung angebunden werden:

//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;

Fehlerbehandlung

Die API gibt nur zwei Arten von Fehlern zurück:

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.