Dokumentacja API Moduł: Listy PEP
Wersja 1.1
Autoryzacja
Autoryzacja do API moduły Listy PEP, podobnie jak inne moduły dostępne 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 PEP.
Poprawna konfiguracja Klucza API dla potrzeb Listy PEP
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
| Komenda | Zapytanie o status PEP pojedyncze |
| Metoda HTTP | POST |
| URI | https://hyperflow.eu/api/route/pep |
| Format żądania (Request format) | JSON |
| Format odpowiedzi (Reponse format) | JSON |
| Kodowanie znaków | UTF-8 |
| Parametry | name – imię i nazwisko weryfikowanej osoby |
Przykład żądania:
{
“name”:”Andrzej Duda”
}
Przykład odpowiedzi:
{
"result": "ok",
"items": [
{
"name": "Andrzej Duda",
"isPEP": "T",
"secondName": "Sebastian",
"position": [
"Prezydent Rzeczypospolitej Polskiej",
"Członek Rady Politycznej partii Prawo i Sprawiedliwość"
],
"bornCity": "Kraków",
"category": [
"P1",
"P3"
],
"country": "PL",
"countryName": "Polska",
"pepRes": "Tak, ta osoba posiada status PEP"
}
]
}
Uwagi implementacje:
Parametr name stanowi jeden ciąg znaków (string) oddzielony spacjami, przyjmujący jedną z możliwych opcji:
- pierwsze imię <spacja> nazwisko (kolejność dowolna)
np. Jan Kowalski
- pierwsze imię <spacja> drugie imię <spacja> nazwisko (kolejność dowolna):
np. Jan Andrzej Kowalski
- pierwsze imię <spacja> nazwisko <spacja> miasto urodzenia (kolejność dowolna):
np. Jan Kowalski Kraków
- pierwsze imię <spacja> drugie imię <spacja> nazwisko <spacja> miasto urodzenia (kolejność dowolna):
np. Jan Andrzej Kowalski Kraków
Przykład żądania bez trafienia:
{
"name": "Alicja Nowak"
}
Przykład odpowiedzi:
{
"items": [
{
"name": "Alicja Nowak",
"isPEP": "N",
"secondName": null,
"position": null,
"bornCity": null,
"category": null,
"country": null,
"pepRes": "Nie, ta osoba nie posiada statusu PEP"
}
],
"consumeId": "4741",
"result": "ok"
}
Zapytanie zbiorowe
| Komenda | Zapytanie o status PEP zbiorowe |
| Metoda HTTP | POST |
| URI | https://hyperflow.eu/api/route/pepbatch |
| 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":["Adriana Banaszczyk","Kyriakos Mitsotakis","Bakir Izetbegović","Donald Tusk"]
}
Przykład odpowiedzi:
{
"result": "ok",
"batch": [
{
"items": [
{
"name": "Adriana Banaszczyk",
"isPEP": "T",
"secondName": "Maria",
"position": [
"EUROMOS Sp. z o.o., Członek Rady Nadzorczej"
],
"bornCity": "",
"category": ["P7"],
"country": "PL",
"countryName": "Polska",
"pepRes": "Tak, ta osoba posiada status PEP"
}
],
"consumeId": "4672",
"result": "ok"
},
{
"items": [
{
"name": "Kyriakos Mitsotakis",
"isPEP": "T",
"secondName": "",
"position": [
"Grecja - Premier"
],
"bornCity": "",
"category": ["P1"],
"country": "GR",
"countryName": "Grecja",
"pepRes": "Tak, ta osoba posiada status PEP"
}
],
"consumeId": "4673",
"result": "ok"
},
{
"items": [
{
"name": "Bakir Izetbegović",
"isPEP": "T",
"secondName": "",
"position": [
"Bośnia i Hercegowina - Członek Prezydium"
],
"bornCity": "",
"category": ["P1"],
"country": "BA",
"countryName": "Bośnia i Hercegowina",
"pepRes": "Tak, ta osoba posiada status PEP"
}
],
"consumeId": "4674",
"result": "ok"
},
{
"items": [
{
"name": "Donald Tusk",
"isPEP": "T",
"secondName": "Franciszek",
"position": [
"Przewodniczący Rady Europejskiej",
"Honorowy Przewodniczący Platformy Obywatelskiej"
],
"bornCity": "Gdańsk",
"category": [ "P1", "P3"],
"country": "PL",
"countryName": "Polska",
"pepRes": "Tak, ta osoba posiada status PEP"
}
],
"consumeId": "4675",
"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, czyli przyjmuje jedną z możliwych opcji:
- pierwsze imię <spacja> nazwisko (kolejność dowolna)
np. Jan Kowalski
- pierwsze imię <spacja> drugie imię <spacja> nazwisko (kolejność dowolna):
np. Jan Andrzej Kowalski
- pierwsze imię <spacja> nazwisko <spacja> miasto urodzenia (kolejność dowolna):
np. Jan Kowalski Kraków
- pierwsze imię <spacja> drugie imię <spacja> nazwisko <spacja> miasto urodzenia (kolejność dowolna):
np. Jan Andrzej Kowalski Kraków.
Przykład żądania:
{
"batch":["Zdzisława Franciszka Gątkiewicz","Konrad Wytrykowski Kamil Legnica","Ostrowiec Świętokrzyski Kamil Zieliński"]
}
Przykład odpowiedzi:
{
"result": "ok",
"batch": [
{
"items": [
{
"name": "Zdzisława Gątkiewicz",
"isPEP": "T",
"secondName": "Franciszka",
"position": [
"Zakłady Urządzeń Chemicznych i Armatury Przemysłowej \"CHEMAR\" S.A., Członek Rady Nadzorczej"
],
"bornCity": "",
"category": [ "P7"],
"country": "PL",
"countryName": "Polska",
"pepRes": "Tak, ta osoba posiada status PEP"
}
],
"consumeId": "2378",
"result": "ok"
},
{
"items": [
{
"name": "Konrad Wytrykowski",
"isPEP": "T",
"secondName": "Kamil",
"position": [
"Sędzia Izby Dyscyplinarnej"
],
"bornCity": "Legnica",
"category": ["P4"],
"country": "PL",
"countryName": "Polska",
"pepRes": "Tak, ta osoba posiada status PEP"
}
],
"consumeId": "2379",
"result": "ok"
},
{
"items": [
{
"name": "Kamil Zieliński",
"isPEP": "T",
"secondName": "",
"position": [
"Członek Rady Politycznej partii Prawo i Sprawiedliwość"
],
"bornCity": "Ostrowiec Świętokrzyski",
"category": ["P3"],
"country": "PL",
"countryName": "Polska",
"pepRes": "Tak, ta osoba posiada status PEP"
}
],
"consumeId": "2380",
"result": "ok"
}
]
}
Zapytanie z pliku zdalnego
| Komenda | Zapytanie o status PEP z pliku zdalnego CSV |
| Metoda HTTP | POST |
| URI | https://hyperflow.eu/api/route/pepbatch |
| 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_pep.csv",
"tmp_name": "https://zdalna lokalizacja.pl/test_pep.csv”
}
}
Gdzie zawartość pliku wygląda następująco:
Przykład odpowiedzi:
{
"result": "ok",
"batch": [
{
"items": [
{
"name": "Paweł Księżak",
"isPEP": "T",
"secondName": "Sławomir",
"position": [
"Sędzia Izby Kontroli Nadzwyczajnej i Spraw Publicznych"
],
"bornCity": "",
"category": [ "P4" ],
"country": "PL",
"countryName": "Polska",
"pepRes": "Tak, ta osoba posiada status PEP"
}
],
"consumeId": "4716",
"result": "ok"
},
{
"items": [
{
"name": "Ilze Fišere",
"isPEP": "T",
"secondName": "",
"position": [
"Sędzia, Sąd Rejonowy w Kurzeme (Ventspils)"
],
"bornCity": "",
"category": [ "P4"],
"country": "LV",
"countryName": "Łotwa",
"pepRes": "Tak, ta osoba posiada status PEP"
}
],
"consumeId": "4717",
"result": "ok"
},
{
"items": [
{
"name": "Miguel Skowron",
"isPEP": "T",
"secondName": "Antonio",
"position": [
"Konsul Honorowy Rzeczypospolitej Polskiej w Obera"
],
"bornCity": "",
"category": [ "P6" ],
"country": "AR",
"countryName": "Argentyna",
"pepRes": "Tak, ta osoba posiada status PEP"
}
],
"consumeId": "4718",
"result": "ok"
}
]
}
Zalecenia co do zapytań
Zalecanym sposobem odpytywania API jest podawanie wyłącznie pierwszego imienia i nazwiska. W przypadku niejednoznacznej odpowiedzi – gdy “trafienie” będzie dotyczyć więcej niż jednej osoby – zostaną zwrócone wszystkie wyniki.
W przypadku weryfikacji pozytywnej (jest PEP) każdorazowo zwracane są wszystkie dostępne informacje na temat danej osoby (drugie imię, miasto urodzenia, zajmowane stanowisko) – o ile występują w naszej bazie danych.
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 PEP.
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": "0000",
"redirect": "",
"result": "err",
"msg": "Nieznana komenda"
}
Przypadki:
- Niewłaściwie wprowadzone URI,
- Wybrana metoda jest niewłaściwa dla zapytania (POST/GET).
Przykład kodu:
{
"code": "2002",
"redirect": "",
"result": "err",
"msg": "Parametr name nie może być pusty"
}
Przypadki:
- Parametr „name” jest pusty.