Dokumentacja API NIP Skaner

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

Klucze API

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

KomendaZapytanie o białą listę VAT – pojedyncze
Metoda HTTPPOST
URIhttps://hyperflow.eu/api/route/nrbcheck
Format żądania (Request format)JSON
Format odpowiedzi (Response format)JSON
Kodowanie znakówUTF-8
ParametryObiekt (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

KomendaZapytanie o białą listę VAT zbiorowe – JSON Array
Metoda HTTPPOST
URIhttps://hyperflow.eu/api/route/nrbcheckarray
Format żądania (Request format)JSON
Format odpowiedzi (Reponse format)JSON
Kodowanie znakówUTF-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

KomendaZapytanie o białą listę VAT zbiorowe – tab separated
Metoda HTTPPOST
URIhttps://hyperflow.eu/api/route/nrbcheck
Format żądania (Request format)JSON
Format odpowiedzi (Response format)JSON
Kodowanie znakówUTF-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

KomendaZapytanie do białej listy z pliku zdalnego CSV
Metoda HTTPPOST
URIhttps://hyperflow.eu/api/route/nrbcheck
Format żądania (Request format)JSON
Format odpowiedzi (Response format)JSON
Kodowanie znakówUTF-8
ParametryJSON 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:

Plik zdalny CSV

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"
    }
]}

Uwagi dotyczące pliku zdalnego:

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

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 pojedyncze NIP Skaner

Zapytanie plik tab-separated (Arkusz Kalkulacyjny) 

Zapytanie plik tab-separated NIP Skaner

Zapytanie JSON Array

Zapytanie JSON Array – NIP Skaner

Zapytanie o plik zdalny – integracja z Google sheets.

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