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

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:

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

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).