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

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.

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 method	POST
URI	https://hyperflow.eu/api/route/nrbcheck
Request format	JSON
Response format	JSON
Character encoding	UTF-8
Parameters	Object (JSON) containing nip and nrb fields

Request example:

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

Response example:

VAT number and bank account request – mass JSON array

Command	VAT Whitelist Request – mass JSON Array
HTTP method	POST
URI	https://hyperflow.eu/api/route/nrbcheckarray
Request format	JSON
Response format	JSON
Character encoding	UTF-8
Parameters	JSON 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 method	POST
URI	https://hyperflow.eu/api/route/nrbcheck
Request format	JSON
Response format	JSON
Character encoding	UTF-8
Parameters	JSON 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 method	POST
URI	https://hyperflow.eu/api/route/nrbcheck
Request format	JSON
Response format	JSON
Character encoding	UTF-8
Parameters	JSON 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:

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:

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

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