Geben Sie Ihre Kundennummer und Ihr Passwort ein, um den Kundenbereich von easycompliance zu betreten. Sollten Sie Ihr Passwort vergessen haben, wenden Sie sich bitte an unseren Kundenservice!

Die API von easycompliance

Eigene Schnittstellen entwickeln
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.

Ausgabe

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

{
"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_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.

Wrong API-KEY: Ungültiger oder fehlerhafter API-Key. 


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.
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 allgmeine Fehler vor der Auswertung der API-Rückgabe beachtet werden.