Dokumentacja API: AML Skaner
Wersja 1.0
Autoryzacja
Autoryzacja do API modułu AML Skaner, 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 AML Skaner.
Poprawna konfiguracja Klucza API dla modułu AML Skaner
![](https://pl.hyperflow.eu/wp-content/uploads/2020/09/p1pl-1024x547.png)
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 – AML skaner dla podmiotów
Komenda | Zapytanie pojedyncze – weryfikacja firmy lub organizacji po numerze NIP lub VAT EU. |
Metoda HTTP | POST |
URI | https://hyperflow.eu/api/route/amlcheck |
Format żądania (Request format) | JSON |
Format odpowiedzi (Response format) | JSON |
Kodowanie znaków | UTF-8 |
Parametry | aml – numer NIP lub VAT UE firmy lub organizacjitype -”company” |
Przykład żądania:
{
"aml":"67XXXXX517",
"type":"company"
}
Przykład odpowiedzi:
{
"respGus": {
"companyName": "Jan Kowalski XXX SERWIS",
"vatno": "67XXXXX517",
"legalFormType": "Osoba Fizyczna",
"legalForm": "Jednoosobowa Działalność Gospodarcza",
"address": "ul. XXX 10",
"city": "XXX",
"postCode": "XX-XXX",
"country": "PL",
"countryName": "Polska",
"startUp": "1994-02-08",
"suspension": "",
"resumption": "",
"termination": "",
"statusREGON": "Aktywny",
"stat": "A",
"dateREGON": "2020-08-13",
"regon": "XXXXXXXXX",
"companyNo": "XXXXXXXXX",
"email": "",
"krs": ""
},
"respVat": {
"nip": "67XXXXX517",
"requestDate": "2020-08-13",
"resultVat": "ok",
"vatApiRequestId": "bgn29-XXXb83",
"name": "JAN KOWALSKI",
"vatStatus": "Czynny",
"vats": "C",
"vatFrom": "1999-12-21",
"vatBankAccounts": [
"11109020530000000540000859"
]
},
"respVies": {
"countryCode": "PL",
"vatNumber": "67XXXXX517",
"requestDate": "2020-08-13",
"valid": true,
"name": "JAN KOWALSKI",
"address": "XXX",
"viesStatus": "Czynny",
"viess": "A",
"resultVies": "ok"
},
"nipStatus": "needsAttention",
"persons": [
{
"name": "Jan Kowalski",
"respSls": {
"items": [
{
"name": "Jan Kowalski",
"slsResponse": "Nie występuje na listach sankcyjnych",
"isSanctioned": "F"
}
]
},
"respPep": {
"items": [
{
"name": "Jan Kowalski",
"isPEP": "T",
"secondName": "Edmund",
"position": [
"Dyrektor Biura Programu „Niepodległa”"
],
"bornCity": "",
"category": [
"P9"
],
"country": "PL",
"countryName": "Polska",
"pepRes": "Tak, ta osoba posiada status PEP"
}
],
"consumeId": "10265",
"result": "ok"
}
}
],
"respSls": {
"items": [
{
"name": "Jan Kowalski XXX SERWIS",
"slsResponse": "Nie występuje na listach sankcyjnych",
"isSanctioned": "F"
}
]
},
"companyName": "Jan Kowalski XXX SERWIS",
"peopleQuantity": 1,
"vatno": "67XXXXX517",
"type": "company",
"consumeId": "10265",
"result": "ok"
}
Zapytanie pojedyncze – AML skaner dla osób fizycznych
Komenda | Zapytanie pojedyncze – weryfikacja osoby na podstawie imienia i nazwiska. |
Metoda HTTP | POST |
URI | https://hyperflow.eu/api/route/amlcheck |
Format żądania (Request format) | JSON |
Format odpowiedzi (Response format) | JSON |
Kodowanie znaków | UTF-8 |
Parametry | aml – imię i nazwiskotype -”person” |
Przykład żądania:
{
"aml":"Jan Kowalski",
"type":"person"
}
Przykład odpowiedzi:
{
"nipStatus": "needsAttention",
"persons": [
{
"name": "Jan Kowalski",
"respSls": {
"items": [
{
"name": "Jan Kowalski",
"slsResponse": "Nie występuje na listach sankcyjnych",
"isSanctioned": "F"
}
]
},
"respPep": {
"items": [
{
"name": "Jan Kowalski",
"isPEP": "T",
"secondName": "Edmund",
"position": [
"Dyrektor Biura Programu „Niepodległa”"
],
"bornCity": "",
"category": [
"P9"
],
"country": "PL",
"countryName": "Polska",
"pepRes": "Tak, ta osoba posiada status PEP"
}
],
"consumeId": "10268",
"result": "ok"
},
"personId": 0
}
],
"type": "person",
"consumeId": "10268",
"result": "ok"
}
Uwagi implementacje:
Parametr aml stanowi :
– Imię i nazwisko – jeden ciąg znaków (string) oddzielony spacjami,
– Numer identyfikacji podatkowej – jeden ciąg znaków (string), znaki “-” oraz spacje są usuwane.
Zapytanie zbiorowe – Batch Screening AML
Komenda | Zapytanie zbiorowe – masowe wprowadzenie danych i uruchomienie analizy |
Metoda HTTP | POST |
URI | https://hyperflow.eu/api/route/amlbatch |
Format żądania (Request format) | JSON |
Format odpowiedzi (Response format) | JSON |
Kodowanie znaków | UTF-8 |
Parametry | „batch”:[”numer NIP”,”imię nazwisko”,”numer NIP”] |
Przykład żądania:
{
"batch":["Abdul Karim","Grupa Islamska","Jan Kowalski"]
}
Przykład odpowiedzi:
{
"result": "ok",
"msg": "Scanner running"
}
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 aml. Ta metoda wprowadza dane do analizy i uruchamia ją. Zakończenie procesu nie oznacza zakończenia analizy.
Zapytanie zbiorowe z pliku zdalnego
Komenda | Zapytanie z pliku zdalnego CSV – wprowadzenie danych do analizy z pliku zdalnego |
Metoda HTTP | POST |
URI | https://hyperflow.eu/api/route/amlbatch |
Format żądania (Request format) | JSON |
Format odpowiedzi (Response 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:
![](https://pl.hyperflow.eu/wp-content/uploads/2020/09/testAML-Google-Sheets-1024x547.png)
Zapytanie zbiorowe – pobranie statystyk analizy
Komenda | Zapytanie zbiorowe – zwraca statystyki analizy dla wprowadzonych danych |
Metoda HTTP | GET |
URI | https://hyperflow.eu/api/route/amlbatch/statistics |
Format żądania (Request format) | JSON |
Format odpowiedzi (Response format) | JSON |
Kodowanie znaków | UTF-8 |
Przykład odpowiedzi:
{
"pending": 3,
"error": false,
"total": 10,
"statistics": [
{
"statusType": "needsAttention",
"size": 4,
"quantity": "6",
"desc": "Wymaga uwagi"
},
{
"statusType": "safe",
"size": 4,
"quantity": "1",
"desc": "Bezpieczny"
},
{
"statusType": "pending",
"size": 4,
"quantity": "3",
"desc": "Oczekujący"
}
],
"result": "ok"
}
Uwagi implementacje:
Zapytanie zwraca statystyki z wykonywanej analizy. Jeżeli analiza została zakończona poprawnie,”pending”:0.
Zapytanie zbiorowe – wynik analizy wg statusu
Komenda | Zapytanie zbiorowe – zwraca wyniki analizy wg statusów |
Metoda HTTP | POST |
URI | https://hyperflow.eu/api/route/amlbatch/status |
Format żądania (Request format) | JSON |
Format odpowiedzi (Response format) | JSON |
Kodowanie znaków | UTF-8 |
Parametry | „status”:[„pending”,”safe”,”needsAttention”] |
Przykład żądania:
{
"status":["needsAttention"]
}
Przykład odpowiedzi:
{
"report": [
{
"date": "2020-08-11",
"aml": "525XXXXXX4",
"type": "company",
"consumeId": "10223",
"status": "Wymaga uwagi"
},
{
"date": "2020-08-11",
"aml": "554XXXXX56",
"type": "company",
"consumeId": "10221",
"status": "Wymaga uwagi"
},
{
"date": "2020-08-11",
"aml": "PL67XXXXXX17",
"type": "company",
"consumeId": "10219",
"status": "Wymaga uwagi"
},
{
"date": "2020-08-11",
"aml": "87XXXXXXX7",
"type": "company",
"consumeId": "10217",
"status": "Wymaga uwagi"
}
],
"result": "ok"
}
Uwagi implementacje:
Wysłanie zapytania z pustym parametrem: “status”:[] lub “status”:””, lub z pominięciem tego parametru zwraca raport z wszystkich wykonanych analiz.
Zapytanie zbiorowe – wznowienie analizy
Komenda | Zapytanie zbiorowe – Wznowienie przerwanej analizy z powodu braku dostępu do usługi lub innych błędów |
Metoda HTTP | GET |
URI | https://hyperflow.eu/api/route/amlbatch/resume |
Format żądania (Request format) | JSON |
Format odpowiedzi (Response format) | JSON |
Kodowanie znaków | UTF-8 |
Przykład odpowiedzi:
{
"result": "ok",
"msg": "Scanner running"
}
Zapytanie zbiorowe – czyszczenie bufora analizy
Komenda | Zapytanie zbiorowe- usuwa rekordy poprzedniej analizy |
Metoda HTTP | GET |
URI | https://hyperflow.eu/api/route/amlbatch/emptyBuffer |
Format żądania (Request format) | JSON |
Format odpowiedzi (Response format) | JSON |
Kodowanie znaków | UTF-8 |
Przykład odpowiedzi:
{
"result": "ok",
"msg": "Dane zostały usunięte"
}
Uwagi implementacje:
Polecenie usuwa wszystkie rekordy wprowadzone do analizy.
Zapytanie – historia weryfikacji
Komenda | Zapytanie o historię zwraca wynik 100 ostatnich zapytań zarówno pojedynczych jak i grupowych |
Metoda HTTP | GET |
URI | https://hyperflow.eu/api/route/amlhistory |
Format żądania (Request format) | JSON |
Format odpowiedzi (Response format) | JSON |
Kodowanie znaków | UTF-8 |
Przykład odpowiedzi:
{
"report": [
{
"date": "2020-08-14",
"company": "7XXXXXXXX8",
"consumeId": "10276",
"sls": "bg-success",
"pep": "bg-grey",
"isSanctioned": "F",
"isPEP": "U”,
"slsStatus": "Nie występuje na listach sankcyjnych",
"pepStatus": "Nieznany",
"person": ""
},
{
"date": "2020-08-14",
"company": "7XXXXXXXX8",
"consumeId": "10276",
"person": "Jacek Malinowski",
"sls": "bg-success",
"pep": "bg-success",
"isSanctioned": "F",
"isPEP": "F”,
"slsStatus": "Nie występuje na listach sankcyjnych",
"pepStatus": "Nie, ta osoba nie posiada statusu PEP"
},
{
"date": "2020-08-13",
"company": "6XXXXXXXX5",
"consumeId": "10264",
"sls": "bg-success",
"pep": "bg-grey",
"isSanctioned": "F",
"isPEP": "U”,
"slsStatus": "Nie występuje na listach sankcyjnych",
"pepStatus": "Nieznany",
"person": ""
},
{
"date": "2020-08-13",
"company": "6XXXXXXXX5",
"consumeId": "10264",
"person": "Jan Kowalski",
"sls": "bg-success",
"pep": "bg-danger",
"isSanctioned": "F",
"isPEP": "T”,
"slsStatus": "Nie występuje na listach sankcyjnych",
"pepStatus": "Tak, ta osoba posiada status PEP"
},
{
"date": "2020-08-10",
"company": "",
"consumeId": "10089",
"sls": "bg-success",
"pep": "bg-success",
"isSanctioned": "F",
"isPEP": "F”,
"slsStatus": "Nie występuje na listach sankcyjnych",
"pepStatus": "Nie, ta osoba nie posiada statusu PEP",
"person": "Monika Kowalska"
}
],
"result": "ok"
}
Uwagi implementacje:
Każdy rekord zawiera dane na temat firmy i/lub osoby. Jeżeli rekord zawiera zarówno niepusty parametr “company” jak i parametr “person”, oznacza to, że osoba jest powiązana z daną firmą jako beneficjent rzeczywisty lub reprezentant. W takim przypadku weryfikacja firmy jak i osoby zawiera ten sam numer “consumeId”.
Zapytanie – przeszukiwanie historia weryfikacji po dacie lub treści zapytania
Komenda | Zapytanie zwraca wyniki analizy wg daty lub zawierające wprowadzone dane w treści zapytania |
Metoda HTTP | POST |
URI | https://hyperflow.eu/api/route/amlhistory/find |
Format żądania (Request format) | JSON |
Format odpowiedzi (Response format) | JSON |
Kodowanie znaków | UTF-8 |
Parametry | “query”:”2020-08-14” |
Przykład żądania:
{
"query":"2020-08-14"
}
Przykład odpowiedzi:
{
"report": [
{
"date": "2020-08-14",
"company": "7XXXXXXXX8",
"consumeId": "10276",
"sls": "bg-success",
"pep": "bg-grey",
"isSanctioned": "F",
"isPEP": "U”,
"slsStatus": "Nie występuje na listach sankcyjnych",
"pepStatus": "Nieznany",
"person": ""
},
{
"date": "2020-08-14",
"company": "7XXXXXXXX8",
"consumeId": "10276",
"person": "Jacek Malinowski",
"sls": "bg-success",
"pep": "bg-success",
"isSanctioned": "F",
"isPEP": "F”,
"slsStatus": "Nie występuje na listach sankcyjnych",
"pepStatus": "Nie, ta osoba nie posiada statusu PEP"
},
{
"date": "2020-08-14",
"company": "6XXXXXXXX5",
"consumeId": "10264",
"sls": "bg-success",
"pep": "bg-grey",
"isSanctioned": "F",
"isPEP": "U”,
"slsStatus": "Nie występuje na listach sankcyjnych",
"pepStatus": "Nieznany",
"person": ""
}
],
"result": "ok"
}
Uwagi implementacje:
Parametry: „isSanctioned” i „isPEP” to parametry definiujące status na listach sankcyjnych/listach PEP i przyjmują trzy wartości:
- „U” – undefined,
- “T” – true -jest na listach sankcyjnych / jest PEP,
- „F” – false -nie jest na listach sankcyjnych / nie jest PEP,
Zalecenia co do zapytań
Zalecanym sposobem odpytywania API jest podawanie pierwszego imienia i nazwiska, numeru NIP lub numeru VAT UE organizacji/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/jest PEP) 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
![](https://pl.hyperflow.eu/wp-content/uploads/2020/09/p2pl-1-1024x541.png)
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": "0448",
"redirect": "",
"result": "err",
"msg": Brak rodzaju podmiotu"
}
Przypadki:
- Niewłaściwie wprowadzona nazwa parametru: „type”,
- Parametr “type” jest pusty lub jego wartość jest inna niż ”company” lub “person”,
- Brak parametru w żądaniu.
Przykład kodu:
{
"code": "0445",
"redirect": "",
"result": "err",
"msg": "Brak danych"
}
Przypadki:
- Niewłaściwie wprowadzona nazwa parametru: „aml”,
- Parametr “aml” jest pusty,
- Brak parametru “aml” w żądaniu.
Przykład kodu:
{
"code": "0333",
"redirect": "",
"result": "err",
"msg": "Błędny identyfikator kraju"
}
Przypadki:
- Wprowadzony numer VAT UE posiada niewłaściwy identyfikator kraju (np: GF1232343445 – GF brak kraju o takim kodzie).
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).