API documentation: Polish VAT Scanner

Effective from: February 1st, 2019 – Version 1.0

Authorization

Authorization to the API of the Polish VAT Scanner module is done by the API Key sent in the request HTTP header called HFAPIKEY with proper API key

If you don’t have your API Key – use Hyperflow website to obtain a new key: enter the tab “”API Keys” in the application, and push “New API Key”.

API Keys

Correct API Key configuration for Polish VAT Scanner – VAT White List

New API key is disabled, so click “more”, and change its settings. The generated key must have the status “enabled” and have access to the Polish VAT Scanner module checked on. If you can’t choose Polish VAT Scanner module, purchase the license for the module first.

API Key configuration

If you need more details about key configuration, see the HyperFlow Service Platform user documentation chapter 9. API keys.

Language selection

To change a response language please use the HTTP Header called HFLANG in each request.  Supported values are:

  • EN – for English language
  • PL – for Polish language

Available API commands

VAT number and bank account request – single check

Command description VAT Whitelist Request – single check
HTTP methodPOST
URIhttps://hyperflow.eu/api/route/nrbcheck
Request formatJSON
Response formatJSON
Character encodingUTF-8
ParametersObject (JSON) containing nip and nrb fields

Request example:

{
"nip":"8652272094",
"nrb":"54114020040000330267182252"
}

Response example:

{
    "reports": [
        {
            "nip": "8652272094",
            "nrb": "54114020040000330267182252",
            "date": "2020-02-27",
            "taskId": "",
            "result": 1,
            "sha512": "2a9b5b4f8ba4d65a58d7c21102903f77e92030556713bf5cda0b9702de3a75ae42c84d3a6afade7857e251173255a56db7cb712e42978e26121a5640c570b4c7",
            "status": "Active",
            "bankAccount": "54114020040000330267182252"
        }
    ],
    "consumeId": "5400",
    "result": "ok"
}

VAT number and bank account request – mass JSON array

CommandVAT Whitelist Request – mass JSON Array
HTTP methodPOST
URIhttps://hyperflow.eu/api/route/nrbcheckarray
Request formatJSON
Response formatJSON
Character encodingUTF-8
ParametersJSON array containing objects with fields: nip, nrb

Request example:

[
  {
    "nip": "8652272094",
    "nrb": "54114020040000330267182252"
  },
  {
    "nip": "9542583988",
    "nrb": "14 1050 0086 1000 0023 1877 4961"
  },
  {
    "nip": "5260250972",
    "nrb": "28124060031111000049464636"
  }
]

Response example:

{
    "reports": [
        {
            "nip": "8652272094",
            "nrb": "54114020040000330267182252",
            "date": "2020-02-27",
            "taskId": "",
            "result": 1,
            "sha512": "2a9b5b4f8ba4d65a58d7c21102903f77e92030556713bf5cda0b9702de3a75ae42c84d3a6afade7857e251173255a56db7cb712e42978e26121a5640c570b4c7",
            "status": "Active",
            "bankAccount": "54114020040000330267182252"
        },
        {
            "nip": "9542583988",
            "nrb": "14105000861000002318774961",
            "date": "2020-02-27",
            "taskId": "",
            "result": 1,
            "sha512":
"420ad4f0d8c3e89b974d5d77a3fcb8842dab5502cf235a31e566dbe21a2a3bc7722a8db1abfb25eb40f71bf7d5e22ce186ace8f9b0d23f9ecefe203f0f18277",
            "status": "Active",
            "bankAccount": "14105000861000002318774961"
        },
        {
            "nip": "5260250972",
            "nrb": "28124060031111000049464636",
            "date": "2020-02-27",
            "taskId": "",
            "result": 1,
            "sha512": "5ac70a16cd84b98fd4000d57c760ad07b52734bdf589827a9e31c4ad53f2230e8861568549e7491ba38152699cd6d0caab8f79f501bf7fcdbe32304acf5f4469",
            "status": "Active",
            "bankAccount": "28124060031111000049464636"
        }
    ],
    "consumeId": "5401",
    "result": "ok"

Implementation notes:

The request accepts an array of objects, each of which has 2 attributes – NIP and NRB.

NIP – whitespaces and minus signs are removed – expecting 10 digits – for Polish VAT Number

NRB   – whitespace are removed – expecting 26 digits  – for bank account number

Vat number and bank account number request – batch check with  tab string – Spreadsheet

Command description VAT Whitelist Request – tab separated
HTTP methodPOST
URIhttps://hyperflow.eu/api/route/nrbcheck
Request formatJSON
Response formatJSON
Character encodingUTF-8
ParametersJSON object with one field: batch – string with \t and \n separators

Request example:

{
"batch":
"9542583988 \t 25 1240 13301111001032579368 \n
 9542583988 \t 14 1050 0086 1000 0023 1877 4961 \n
 8652272094 \t 54114020040000330267182252"
}
Response example:
{
    "reports": [
        {
            "nip": "9542583988",
            "nrb": "25124013301111001032579368",
            "date": "2020-02-27",
            "taskId": "",
            "result": 1,
            "sha512": "9567019e21041a88f708b878d37e5a750b3485615553cc7a16c114c0cc7455df8658889da6d0a60002ff07aa03379325d67a5f81ac986f9570d6d6ffdc2f60d2",
            "status": "Active",
            "bankAccount": "25124013301111001032579368"
        },
        {
            "nip": "9542583988",
            "nrb": "14105000861000002318774961",
            "date": "2020-02-27",
            "taskId": "",
            "result": 1,
            "sha512": "420ad4f0d8c3e89b974d5d77a3fcb8842dab5502cf235a31e566dbe21a2a3bc7722a8db1abfb25eb40f71bf7d5e22ce186ace8f9b0d23f9ecefe203f0f18277",
            "status": "Active",
            "bankAccount": "14105000861000002318774961"
        },
        {
            "nip": "8652272094",
            "nrb": "54114020040000330267182252",
            "date": "2020-02-27",
            "taskId": "",
            "result": 1,
            "sha512":
"2a9b5b4f8ba4d65a58d7c21102903f77e92030556713bf5cda0b9702de3a75ae42c84d3a6afade7857e251173255a56db7cb712e42978e26121a5640c570b4c7",
            "status": "Active",
            "bankAccount": "54114020040000330267182252"
        }
    ],
    "consumeId": "5403",
    "result": "ok"
}

Notes implementations:

The batch parameter accepts one string that represents a 2-column file (array) where the columns are separated by a tab character (\t) and the lines by a newline (\n). This is the representation corresponding to the format of the spreadsheet clipboard (e.g. Excel, Google Sheets, Open Office Calc) assuming that:

  • First column: VAT number (nip) – whitespace and minus signs are removed – expecting 10 digits,
  • Second column: bank account number – whitespaces are removed – expecting 26 digits.

Vat number and bank account number request – mass – CSV file

Command description VAT Whitelist Request – CSV file
HTTP methodPOST
URIhttps://hyperflow.eu/api/route/nrbcheck
Request formatJSON
Response formatJSON
Character encodingUTF-8
ParametersJSON Object – description of the remote file location  “hfFile”: {    “name”: “your_file.csv”,    “tmp_name”: “https://remoterlocation.pl/your_file.csv”}

Request example:

{
  "hfFile": {
 "name": "blv.csv",
 "tmp_name": "https://remoteLocation.pl/blv.csv”
  }
}

The content of the remote file (CSV) should look like this:

CSV file example

Response example:

{
  "reports": [
    {
      "nip": "9542583988",
      "nrb": "25124013301111001032579368",
      "date": "2020-02-27",
      "taskId": "",
      "result": 1,
      "sha512":
"9567019e21041a88f708b878d37e5a750b3485615553cc7a16c114c0cc7455df8658889da6d0a60002ff07aa03379325d67a5f81ac986f9570d6d6ffdc2f60d2",
      "status": "Active",
      "bankAccount": "25124013301111001032579368"
    },
    {
      "nip": "9542583988",
      "nrb": "14105000861000002318774961",
      "date": "2020-02-27",
      "taskId": "",
      "result": 1,
      "sha512":
"420ad4f0d8c3e89b974d5d77a3fcb8842dab5502cf235a31e566dbe21a2a3bcf7722a8db1abfb25eb40f71bf7d5e22ce186ace8f9b0d23f9ecefe203f0f18277",
      "status": "Active",
      "bankAccount": "14105000861000002318774961"
    },
    {
      "nip": "8652272094",
      "nrb": "54114020040000330267182252",
      "date": "2020-02-27",
      "taskId": "",
      "result": 1,
      "sha512": "2a9b5b4f8ba4d65a58d7c21102903f77e92030556713bf5cda0b9702de3a75ae42c84d3a6afade7857e251173255a56db7cb712e42978e26121a5640c570b4c7",
      "status": "Active",
      "bankAccount": "54114020040000330267182252"
    }
  ],
  "consumeId": "5404",
  "result": "ok"
}

Notes about the remote file:

  1. The file should be available to the public or through a VPN tunnel created on our server presentational. 
  2. CSV file format: separated by commas, UTF-8 – no headers, the first column- Polish VAT number, the second bank account number,
  3. It is possible to directly integrate with Google Sheets. just prepare Shared file using a link, according to the example:
Sharing the file

If the URL to share the file is as follows:
https://docs.google.com/spreadsheets/d/2xBE1C_O3cjCNWykoD4cHiyZE4UpkQywLbUSE4S99_8w/edit?usp=sharing
you have to build it to the correct path to get CSV:
https://docs.google.com/spreadsheets/d/2xBE1C_O3cjCNWykoD4cHiyZE4UpkQywLbUSE4S99_8w/export?format=csv&id=2xBE1C_O3cjCNWykoD4cHiyZE4UpkQywLbUSE4S99_8w

Original:
https://docs.google.com/spreadsheets/d/{id}/edit?usp=sharing
Processed:
https://docs.google.com/spreadsheets/d/{id}/export?format=csv&id={id}

Well formed request looks like:

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

Response format description

Top level result object

Every 200 HTTP response  code is the JSON object with the following fields on the top-level:

  • result – general result of the request. Possible values 
    • ok – command executed successfully 
    • err – error executing command
  • consumeId – Integer value – id of the successful command in the Hyperflow billing system – could be used as reference to locate particular co
  • code – numeric or alphanumeric code of error – only if the result value was err (see General Error Codes)
  • msg – language-dependent human readable description of the error =  only if the result value was err (see General Error Codes)

Object Report object description 

Each of the API commands presented in this document returns one or more report objects. The following fields describes each report object

  • nrb – input parameter nrb after whitespace removal 
  • bankAccount – same as nrb – for back-compatibility 
  • nip – input parameter nip after whitespace removal
  • result – integer – possible values:
    • -1 – empty or bad data (np 10 digit NIP or 26 digit for NRB not satisfied )
    • 0 – Not registered for VAT – can not be found on the whitelist
    • 1 – Active VAT status – found on whitelist
    • 2 – VAT-free status – found on whitelist with the : free for VAT status
  • status – same as result but alphanumeric and language-depended  , possible values or English:
    • Not registered for VAT
    • VAT-free
    • Active
  • taskId – could be used in request as external ID for client-side report identification – if not used in request – always empty
  • sha512 – if data is correct (result other than -1) – this is the SHA fingerprint of the result – this value is used as confirmation key – signature for verification result
  • date – date of request in YYYY-MM-DD format