Dokumentacja API Moduł: Listy sankcyjne

Wersja 1.0

Autoryzacja

Autoryzacja do API modułu Listy Sankcyjne, podobnie jak do innych modułów dostępnych przez API Platformy usługowej HyperFlow, odbywa się za pomocą Klucza API wysłanego w nagłówku żądania o nazwie HFAPIKEY.

Wygenerowany klucz musi posiadać status Aktywny oraz mieć przypisany włączony dostęp do modułu Listy Sankcyjne.

Poprawna konfiguracja Klucza API dla modułu Listy Sankcyjne

Szczegóły na temat konfiguracji klucza są dostępne w dokumentacji użytkownika Platformy usługowej HyperFlow  rozdział 9. Klucze API.

Dostępne komendy

Zapytanie pojedyncze – listy sankcyjne dla podmiotów.

Komenda	Zapytanie pojedyncze – sprawdza na listach sankcyjnych dla podmiotów.
Metoda HTTP	POST
URI	https://hyperflow.eu/api/route/sls/entity
Format żądania (Request format)	JSON
Format odpowiedzi (Response format)	JSON
Kodowanie znaków	UTF-8
Parametry	name – nazwa firmy lub organizacji

Przykład żądania:

{
"name":"Asadullah"
}

Przykład odpowiedzi:

{
 "items": [
   {
     "name": "Asadullah",
     "slsResponse": "Nie występuje na listach sankcyjnych",
     "issls": "N"
   }
 ],
 "consumeId": "8016",
 "result": "ok"
}

Zapytanie pojedyncze – listy sankcyjne dla osób fizycznych

Komenda	Zapytanie pojedyncze – sprawdza na listach sankcyjnych dla osób.
Metoda HTTP	POST
URI	https://hyperflow.eu/api/route/sls/person
Format żądania (Request format)	JSON
Format odpowiedzi (Response format)	JSON
Kodowanie znaków	UTF-8
Parametry	name – imię i nazwisko weryfikowanej osoby

Przykład żądania:

{
"name":"Asadullah"
}

Przykład odpowiedzi:

{
   "items": [
       {
           "name": "Asadullah",
           "issls": "T",
           "listType": "EU",
           "objectType": "Osoba fizyczna",
           "src": "EU",
           "reference": "EU.3997.31",
           "name_aliases": [
               "Asad",
               "Asadullah",
               "Abu Sa’d at-Trinidadi",
               "Shane Dominic Crawford"
           ],
           "birthyear_aliases": null,
           "birthdate_aliases": [
               "1986-02-22"
           ],
           "comment": "Physical description: eye colour: brown; hair colour: dark; complexion: light brown; build: medium; height: 174cm; weight: 64kg; speaks English, Arabic.",
           "slsResponse": "Występuje na listach sankcyjnych"
       }
  ],
   "consumeId": "8010",
   "result": "ok"
}

Zapytanie pojedyncze – listy sankcyjne dla podmiotów i osób.

Komenda	Zapytanie pojedyncze – sprawdza na listach sankcyjnych zarówno dla podmiotów jak i osób.
Metoda HTTP	POST
URI	https://hyperflow.eu/api/route/sls
Format żądania (Request format)	JSON
Format odpowiedzi (Response format)	JSON
Kodowanie znaków	UTF-8
Parametry	name – imię i nazwisko weryfikowanej osoby lub nazwa firmy/organizacji

Przykład żądania:

{
"name":"Asadullah"
}

Przykład odpowiedzi:

{
   "items": [
       {
           "name": "Asadullah",
           "issls": "T",
           "listType": "EU",
           "objectType": "Osoba fizyczna",
           "src": "EU",
           "reference": "EU.3997.31",
           "name_aliases": [
               "Asad",
               "Asadullah",
               "Abu Sa’d at-Trinidadi",
               "Shane Dominic Crawford"
           ],
           "birthyear_aliases": null,
           "birthdate_aliases": [
               "1986-02-22"
           ],
         "comment": "Physical description: eye colour: brown; hair colour: dark; complexion: light brown; build: medium; height: 174cm; weight: 64kg; speaks English, Arabic.",
           "slsResponse": "Występuje na listach sankcyjnych"
       }
   ],
   "consumeId": "8010",
   "result": "ok"
}

Uwagi implementacje:

Parametr name stanowi jeden ciąg znaków (string) oddzielony spacjami.

Zapytanie zbiorowe – listy sankcyjne dla podmiotów.

Komenda	Zapytanie zbiorowe
Metoda HTTP	POST
URI	https://hyperflow.eu/api/route/slsbatch/entity
Format żądania (Request format)	JSON
Format odpowiedzi (Reponse format)	JSON
Kodowanie znaków	UTF-8
Parametry	„batch”:[”nazwa firmy”,”nazwa firmy”,”nazwa firmy”]

Przykład żądania:

{
    "batch":["Abdul Karim","Grupa Islamska","Jan Kowalski"]
}

Przykład odpowiedzi:

{
   "result": "ok",
   "batch": [
       {
           "items": [
               {
                   "name": "Abdul Karim",
                   "slsResponse": "Nie występuje na listach sankcyjnych",
                   "issls": "N"
               }
           ],
           "consumeId": "8164",
           "result": "ok"
       },
       {
           "items": [
               {
                   "name": "Grupa Islamska",
                   "issls": "T",
                   "listType": "EU",
                   "objectType": "Firma lub organizacja",
                   "name_aliases": [
                       "IG",
                       "Islamiska gruppen",
                       "Islamic Group - IG",
                       "Gama'a al-Islamiyya",
                       "Джамаа Ислямия",
                       "Grupo Islámico",
                       "Islámská skupina",
                       "Islamisk Gruppe",
                       "Islamische Gruppe",
                       "Islamirühmitus",
                       "Ισλαμική Ομάδα",
                       "Groupe islamique",
                       "Grúpa Ioslamach",
                       "Islamska skupina",
                       "Islamo grupuotė",
                       "Iszlám Csoport",
                       "il-Grupp Iżlamiku",
                       "Islamitische Groep",
                       "Grupa Islamska",
                       "Grupo Islâmico",
                       "Grupul Islamic",
                       "Islamská skupina",
                       "Islamistična skupina",
                       "Al-Gama'a al-Islamiyya"
                   ],
                   "src": "EU",
                   "reference": "EU.3512.47",
                   "comment": "",
                   "slsResponse": "Występuje na listach sankcyjnych"
               }
           ],
           "consumeId": "8165",
           "result": "ok"
       }, 
      {
           "items": [
               {
                   "name": "Jan Kowalski",
                   "slsResponse": "Nie występuje na listach sankcyjnych",
                   "issls": "N"
               }
           ],
           "consumeId": "8166",
           "result": "ok"
       }
   ]
}

Uwagi implementacje:

Parametr batch przyjmuje tablicę ciągów znaków oddzieloną przecinkami (JSONArray). Każdy ciąg znaków jest skonstruowany dokładnie na tych samych zasadach co pojedynczy parametr name.

Zapytanie zbiorowe – listy sankcyjne dla osób fizycznych.

Komenda	Zapytanie zbiorowe
Metoda HTTP	POST
URI	https://hyperflow.eu/api/route/slsbatch/person
Format żądania (Request format)	JSON
Format odpowiedzi (Reponse format)	JSON
Kodowanie znaków	UTF-8
Parametry	„batch”:[„imię nazwisko”,”imię nazwisko”,”imię nazwisko”,”imię nazwisko”]

Przykład żądania:

{
    "batch":["Abdul Karim","Grupa Islamska","Jan Kowalski"]
}

Przykład odpowiedzi:

{
   "result": "ok",
   "batch": [
       {
           "items": [
               {
                   "name": "Abdul Karim",
                   "issls": "T",
                   "listType": "EU",
                   "objectType": "Osoba fizyczna",
                   "src": "EU",
                   "reference": "EU.1518.29",
                   "name_aliases": [
                       "Abdul Hadi",
                       "Gun Gun Rusman Gunawan",
                       "Bukhory",
                       "Bukhori",
                       "Abdul Karim",
                       "Abd Al-Hadi",
                       "Rusman Gunawan"
                   ],
                   "birthyear_aliases": null,
                   "birthdate_aliases": [
                       "1977-07-06"
                   ],
                   "comment": "",
                   "slsResponse": "Występuje na listach sankcyjnych"
               },
               {
                   "name": "Abdul Karim",
                   "issls": "T",
                   "listType": "UN",
                   "objectType": "Osoba fizyczna",
                   "src": "UN",
                   "reference": "QDi.218",
                   "name_aliases": [
                       "GUN GUN RUSMAN GUNAWAN",
                       "Abd Al-Hadi",
                       "Abdul Hadi",
                       "Gunawan, Rusman",
                       "Bukhori",
                       "Abdul Karim",
                       "Bukhory"
                   ],
                   "birthyear_aliases": null,
                   "birthdate_aliases": [
                       "1977-07-06"
                   ],
                   "comment": "Brother of Nurjaman Riduan Isamuddin (QDi.087). Review pursuant to\nSecurity Council resolution 1822 (2008) was concluded on 8 Jun. 2010. Review pursuant to Security Council resolution 2368 (2017) was concluded on 4 Dec. 2019 INTERPOL-UN Security Council Special Notice
web link: https://www.interpol.int/en/How-we-work/Notices/View-UN
Notices-Individuals",
                   "slsResponse": "Występuje na listach sankcyjnych"
               }
           ],
           "consumeId": "8167",
           "result": "ok"
       },
       {
           "items": [
               {
                   "name": "Grupa Islamska",
                   "slsResponse": "Nie występuje na listach sankcyjnych",
                   "issls": "N"
               }
           ],
           "consumeId": "8168",
           "result": "ok"
       },
       {
           "items": [
               {
                   "name": "Jan Kowalski",
                   "slsResponse": "Nie występuje na listach sankcyjnych",
                   "issls": "N"
               }
           ],
           "consumeId": "8169",
           "result": "ok"
       }
   ]
}

Zapytanie zbiorowe – listy sankcyjne dla podmiotów i osób.

Komenda	Zapytanie zbiorowe
Metoda HTTP	POST
URI	https://hyperflow.eu/api/route/slsbatch
Format żądania (Request format)	JSON
Format odpowiedzi (Reponse format)	JSON
Kodowanie znaków	UTF-8
Parametry	„batch”:[„imię nazwisko”,”nazwa firmy”,”imię nazwisko”,”nazwa organizacji”]

Przykład żądania:

{
    "batch":["Abdul Karim","Grupa Islamska","Jan Kowalski"]
}

Przykład odpowiedzi:

{
   "result": "ok",
   "batch": [
       {
           "items": [
               {
                   "name": "Abdul Karim",
                   "issls": "T",
                   "listType": "EU",
                   "objectType": "Osoba fizyczna",
                   "src": "EU",
                   "reference": "EU.1518.29",
                   "name_aliases": [
                       "Abdul Hadi",
                       "Gun Gun Rusman Gunawan",
                       "Bukhory",
                       "Bukhori",
                       "Abdul Karim",
                       "Abd Al-Hadi",
                       "Rusman Gunawan"
                   ],
                   "birthyear_aliases": null,
                   "birthdate_aliases": [
                       "1977-07-06"
                   ],
                   "comment": "",
                   "slsResponse": "Występuje na listach sankcyjnych"
               },
               {
                   "name": "Abdul Karim",
                   "issls": "T",
                   "listType": "UN",
                   "objectType": "Osoba fizyczna",
                   "src": "UN",
                   "reference": "QDi.218",
                   "name_aliases": [
                       "GUN GUN RUSMAN GUNAWAN",
                       "Abd Al-Hadi",
                       "Abdul Hadi",
                       "Gunawan, Rusman",
                       "Bukhori",
                       "Abdul Karim",
                       "Bukhory"
                   ],
                   "birthyear_aliases": null,
                   "birthdate_aliases": [
                       "1977-07-06"
                   ],
                 "comment": "Brother of Nurjaman Riduan Isamuddin (QDi.087). Review pursuant to\nSecurity Council resolution 1822 (2008) was concluded on 8 Jun. 2010. Review pursuant to Security Council resolution 2368 (2017) was concluded on 4 Dec. 2019 INTERPOL-UN Security Council Special Notice web link: https://www.interpol.int/en/How-we-work/Notices/View-UN
Notices-Individuals",
                   "slsResponse": "Występuje na listach sankcyjnych"
               }
           ],
           "consumeId": "8170",
           "result": "ok"
       },
       {
           "items": [
               {
                   "name": "Grupa Islamska",
                   "issls": "T",
                   "listType": "EU",
                   "objectType": "Firma lub organizacja",
                   "name_aliases": [
                       "IG",
                       "Islamiska gruppen",
                       "Islamic Group - IG",
                       "Gama'a al-Islamiyya",
                       "Джамаа Ислямия",
                       "Grupo Islámico",
                       "Islámská skupina",
                       "Islamisk Gruppe",
                       "Islamische Gruppe",
                       "Islamirühmitus",
                       "Ισλαμική Ομάδα",
                       "Groupe islamique",
                       "Grúpa Ioslamach",
                       "Islamska skupina",
                       "Islamo grupuotė",
                       "Iszlám Csoport",
                       "il-Grupp Iżlamiku",
                       "Islamitische Groep",
                       "Grupa Islamska",
                       "Grupo Islâmico",
                       "Grupul Islamic",
                       "Islamská skupina",
                       "Islamistična skupina",
                       "Al-Gama'a al-Islamiyya"
                   ],
                   "src": "EU",
                   "reference": "EU.3512.47",
                   "comment": "",
                   "slsResponse": "Występuje na listach sankcyjnych"
               }
           ],
           "consumeId": "8171",
           "result": "ok"
       },
       {
           "items": [
               {
                   "name": "Jan Kowalski",
                   "slsResponse": "Nie występuje na listach sankcyjnych",|
                   "issls": "N"
               }
           ],
           "consumeId": "8172",
           "result": "ok"
       }
   ]
}

Zapytanie z pliku zdalnego

Komenda	Zapytanie na listach sankcyjnych z pliku zdalnego CSV
Metoda HTTP	POST
URI	https://hyperflow.eu/api/route/slsbatch
Format żądania (Request format)	JSON
Format odpowiedzi (Reponse format)	JSON
Kodowanie znaków	UTF-8
Parametry	„hfFile”: {    „name”: „twoj_plik.csv”,    „tmp_name”: „https://zdalnalokalizacja.pl/twoj_plik.csv”}

Przykład żądania:

{
  "hfFile": {
 "name": "test_plik.csv",
 "tmp_name": "https://zdalna lokalizacja.pl/test_plik.csv”
  }
}

Gdzie zawartość pliku wygląda następująco:

Zalecenia co do zapytań

Zalecanym sposobem odpytywania API jest podawanie pierwszego imienia i nazwiska, nazwy organizacji, nazwy firmy. W przypadku niejednoznacznej odpowiedzi – gdy “trafienie” będzie dotyczyć więcej niż jednej osoby/firmy – zostaną zwrócone wszystkie wyniki.

W przypadku weryfikacji pozytywnej (jest na listach sankcyjnych) każdorazowo zwracane są wszystkie dostępne informacje na temat danej osoby/firmy oraz nałożonych sankcji (w przypadku osoby są: to możliwe daty urodzenia lub rok urodzenia, możliwe stosowane nazwiska; w przypadku firmy/organizacji: możliwe stosowane nazwy; wszystkie odpowiedzi zawierają rodzaj listy sankcyjnej i jej numer referencyjny).

Przykład wywołania za pomocą klienta RESTED

Kody błędów

Przykład kodu:

{
    "code": "0089",
    "redirect": "",
    "result": "err",
    "msg": "Brak dostępu do usługi"
}

Przypadki:

• Użytkownik zużył całą pulę wykupionych zapytań lub termin, do którego usługa została wykupiona minął,
• Nieaktywny klucz API,
• Klucz API nie ma włączonej usługi Listy sankcyjne.

Przykład kodu:

{
    "code": "0404",
    "redirect": "",
    "result": "err",
    "msg": "Brak pliku lub plik jest pusty"
}

Przypadki:

• Podana ścieżka jest niewłaściwa,
• Plik nie zawiera danych, jest pusty,
• Niewłaściwy format pliku, plik nie jest plikiem CSV,
• Niewłaściwie wprowadzone nazwy parametrów: „name”,   „tmp_name”.

Przykład kodu:

{
    "code": "0009",
    "redirect": "",
    "result": "err",
    "msg": "Błędne dane"
}

Przypadki:

• Niewłaściwie wprowadzona nazwa parametru: „batch”,   „hfFile”,
• Niewłaściwy parametr dla żądania URI,
• Parametr „batch”,   „hfFile” jest pusty,
• Brak parametru w żądaniu.

Przykład kodu:

{
   "code": "1233",
   "redirect": "",
   "result": "err",
   "msg": "Nieznana komenda"
}

Przypadki:

• Niewłaściwie wprowadzone URI,
• Wybrana metoda jest niewłaściwa dla zapytania (POST/GET).