Dokumentacja API: NIP Skaner – Platforma Hyperflow

Wersja 1.0

Autoryzacja

Autoryzacja do API moduły NIP Skaner – Biała Lista VAT, 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 NIP Skaner – Biała Lista VAT.

Poprawna konfiguracja Klucza API dla potrzeb NIP Skaner – Biała Lista VAT

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 o NIP i rachunek bankowy – pojedyncze

Komenda	Zapytanie o białą listę VAT – pojedyncze
Metoda HTTP	POST
URI	https://hyperflow.eu/api/route/nrbcheck
Format żądania (Request format)	JSON
Format odpowiedzi (Response format)	JSON
Kodowanie znaków	UTF-8
Parametry	Obiekt (JSON) zawierający pola nip i nrb

Przykład żądania:
{ "nip":"8652272094", "nrb":"54114020040000330267182252" }

Przykład odpowiedzi:
{ "reports": [ { "nip": "8652272094", "nrb": "54114020040000330267182252", "date": "2020-02-18", "result": 1, "status": "Czynny", "bankAccount": "54114020040000330267182252" } ], "consumeId": "2889", "result": "ok" }

Zapytanie o NIP i rachunek bankowy – masowe – tablica JSON

Komenda	Zapytanie o białą listę VAT zbiorowe – JSON Array
Metoda HTTP	POST
URI	https://hyperflow.eu/api/route/nrbcheckarray
Format żądania (Request format)	JSON
Format odpowiedzi (Reponse format)	JSON
Kodowanie znaków	UTF-8
Parametry	Tablic JSON Array, zawierająca obiekty z polami: nip, nrb

Przykład żądania:
[ { "nip": "8652272094", "nrb": "54114020040000330267182252" }, { "nip": "9542583988", "nrb": "14 1050 0086 1000 0023 1877 4961" }, { "nip": "5260250972", "nrb": "28124060031111000049464636" } ]

Przykład odpowiedzi:
{ "reports": [ { "nip": "8652272094", "nrb": "54114020040000330267182252", "date": "2020-02-18", "result": 1, "status": "Czynny", "bankAccount": "54114020040000330267182252" }, { "nip": "9542583988", "nrb": "14105000861000002318774961", "date": "2020-02-18", "result": 1, "status": "Czynny", "bankAccount": "14105000861000002318774961" }, { "nip": "5260250972", "nrb": "28124060031111000049464636", "date": "2020-02-18", "result": 1, "status": "Czynny", "bankAccount": "28124060031111000049464636" } ], "consumeId": "4927", "result": "ok" }

Uwagi implementacyjne

Żądanie przyjmuje tablicę obiektów z których każdy posiada 2 atrybuty – nip oraz nrb.

Atrybut nip– białe znaki i znak minusa jest usuwany
Atrybut nrb (26 cyfr) – białe znaki są usuwane

Zapytanie o NIP i rachunek bankowy – masowe – ciąg znaków tabulacji – Arkusz kalkulacyjny

Komenda	Zapytanie o białą listę VAT zbiorowe – tab separated
Metoda HTTP	POST
URI	https://hyperflow.eu/api/route/nrbcheck
Format żądania (Request format)	JSON
Format odpowiedzi (Response format)	JSON
Kodowanie znaków	UTF-8
Parametry	Object JSON, zawierający jedno pole batch

Przykład żądania:
{ "batch":"9542583988 \t 25 1240 13301111001032579368 \n 9542583988 \t 14 1050 0086 1000 0023 1877 4961 \n 8652272094 \t 54114020040000330267182252" }

Przykład odpowiedzi:
{ "reports": [ { "nip": "9542583988", "nrb": "25124013301111001032579368", "date": "2020-02-18", "result": 1, "status": "Czynny", "bankAccount": "25124013301111001032579368" }, { "nip": "9542583988", "nrb": "14105000861000002318774961", "date": "2020-02-18", "result": 1, "status": "Czynny", "bankAccount": "14105000861000002318774961" }, { "nip": "8652272094", "nrb": "54114020040000330267182252", "date": "2020-02-18", "result": 1, "status": "Czynny", "bankAccount": "54114020040000330267182252" } ], "consumeId": "2887", "result": "ok" }

Uwagi implementacje:

Parametr batch przyjmuje jeden ciąg znaków, który reprezentuje 2 kolumnowy plik (tabelę) gdzie kolumny oddzielone są znakiem tabulacji (\t) a wiersze znakiem nowej linii (\n) Jest to reprezentacja odpowiadająca formatowi schowka arkuszy kalkulacyjnych (Np. Excel, Google Sheets, Open Office Calc) przy założeniu że

Pierwsza kolumna: numer NIP – białe znaki i znak minusa jest usuwany
Druga kolumna: numer rachunku bankowego (26 cyfr) – białe znaki są usuwane

Zapytanie o NIP i rachunek bankowy – masowe – z pliku zdalnego CSV

Komenda	Zapytanie do białej listy z pliku zdalnego CSV
Metoda HTTP	POST
URI	https://hyperflow.eu/api/route/nrbcheck
Format żądania (Request format)	JSON
Format odpowiedzi (Response format)	JSON
Kodowanie znaków	UTF-8
Parametry	JSON Object – opis położenia pliku zdalnego „hfFile”: { „name”: „twoj_plik.csv”, „tmp_name”: „https://zdalnalokalizacja.pl/twoj_plik.csv”}

Przykład żądania:
{ "hfFile": { "name": "blv.csv", "tmp_name": "https://zdalna lokalizacja.pl/blv.csv” } }

Gdzie zawartość zdalnego pliku (CSV) wygląda następująco:

Uwagi dotyczące pliku zdalnego:

Plik powinien być osiągalny publicznie lub za pomocą utworzonego tunelu VPN na naszym serwerze prezentacyjnym
Format pliku CSV: oddzielony przecinkami UTF-8 – bez nagłówka, w pierwszej kolumnie NIP w drugiej NRB
Możliwa jest bezpośrednia integracja z Google Sheets, wystarczy przygotować plik Współdzielony za pomocą linku, wedle przykładu:

W przypadku gdy URL do dzielenia pliku jest następujący:

https://docs.google.com/spreadsheets/d/1xCD1C_O3cjCNWykoD4cHiyZE4UpkQywLbUSE4S99_4r/edit?usp=sharing

Poprawną ścieżkę do uzyskania CSV jest:

https://docs.google.com/spreadsheets/d/1xCD1C_O3cjCNWykoD4cHiyZE4UpkQywLbUSE4S99_4r/export?format=csv&id=1xCD1C_O3cjCNWykoD4cHiyZE4UpkQywLbUSE4S99_4r

Całe żądanie wygląda wtedy następująco

{ "hfFile": { "name": "google.csv", "tmp_name": "https://docs.google.com/spreadsheets/d/1xCD1C_O3cjCNWykoD4cHiyZE4UpkQywLbUSE4S99_4r/export?format=csv&id=1xCD1C_O3cjCNWykoD4cHiyZE4UpkQywLbUSE4S99_4r" } }

Przykłady wywołania za pomocą klienta RESTED

Zapytanie pojedyncze

Zapytanie plik tab-separated (Arkusz Kalkulacyjny)

Zapytanie JSON Array

Zapytanie o plik zdalny – integracja z Google sheets.

Kody błędów

Przykład kodu:
{ "code": "0000", "redirect": "", "result": "err", "msg": "Access denied" }

Przyczyny:

Błędny klucz API
Nieaktywny klucz API,

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

Przyczyny:

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 NIP Skaner – Biała Lista VAT.

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

Przyczyny:

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,
Paramter „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).