API

Introduction


The API enables the integration of external applications with INVO system. Communication takes place via the JSON data exchange format, so it is supported by most of the currently used languages programming including C, C++, C #, PHP, Java, JavaScript, Python, Ruby.

Access path


The path to the API interface is as follows:

https://invo.io/api.json

Usage


Each time for data exchange with INVO, the following should be given: authorization data (CURLOPT_USERPWD) and POST method (CURLOPT_POSTFIELDS) resource type parameters r and data in JSON format q. The easiest way to refer to the INVO API resources is to use the CURL library (an example in PHP).

Example:

$curl_ = curl_init();
curl_setopt($curl_, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($curl_, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl_, CURLOPT_USERPWD, "login:password");
curl_setopt($curl_, CURLOPT_URL, "https://invo.io/api.json");
curl_setopt($curl_, CURLOPT_POSTFIELDS, "r=login&q={}");
curl_exec($curl_);
curl_close($curl_);

Calling the above commands will send a request for authorization to the INVO account and will return:

{"cid":nr, "uid":uu} if the authorization will be positive
 nr is the account ID, always >= 1, UU is the user ID (subaccount) >= 0

{"error":1,"message":"authentication error"} in the event of an authorization error

Resources


namedescriptionexamples of inquiries
loginit is only used to check login{ }
dictionariesdictionaries (VAT rates, units, etc.){ "action":"list", "what":"taxrates" }
invoicessales and cost invoices{ "action":"list", "search":"Drutex s.c." }
itemsitems of the selected invoice{ "action":"list", "did":32501 }
customerscontractors{ "action":"list", "search":"kowalski" }
productsgoods/services{ "action":"list", "search":"drukarka" }
bookkeepingbookkeeping{ "action":"list", "what":"zus" }
filesfile operations{ "action":"get", "id":301345 }
reportsreports

Actions


namedescriptionexplanation / examples
addadding an invoice / contractor / productID should be omitted or set to 0
editediting the invoice / contractor / productrequires resource ID
changes only the values specified in the documentation
listdisplaying invoices / contractors / productssearch results can be narrowed down to a specific record by giving ID or property (e.g. invoice number, contractor's name)
you can also use the search attribute to search for a phrase/value at the same time in several attributes (for invoices, search is carried out on the header and invoice items)

Sorting, paging and setting the limit


Listing query data can be sorted, paginated and limited.

Sorts using the attribute sortby e.g.:

{ "action":"list", "sortby":"column name" }
To use paging, you must use attributes page and cpp e.g.:

{ "action":"list", "page":3, "cpp":10 }
The above invoice listing query will return the contents of the third page - rows 21-30 (if the invoices are at least 30, if not the list may be shorter or empty).

To limit the amount of data (rows) without pagination, you can use the attribute limit e.g.:

{ "action":"list", "limit":10 }

Error codes


If an error occurs, the server returns one of the following messages:

{"error":1,"message":"authentication error"} - authorization error
{"error":2,"message":"incorrect resource"} - wrong resource name
{"error":3,"message":"invalid JSON format"} - incorrect JSON syntax
{"error":4,"message":"incorrect dictionary"} - incorrectly provided dictionary name
{"error":5,"message":"incorrect action"} - unknown action
{"error":6,"message":"incorrect ID"} - wrong ID
{"error":7,"message":"account is not activated"}

Invoices


Fields describing the invoice:

namedescriptionexplanation/examples
idDocument IDinteger
0 - if we add a new invoice, 1+ - for invoice editing/selection
langlanguagePL - Polish
EN - English
DE - German
kidCorrected invoice ID, only for correcting invoices (+KOR)integer
buyczy faktura kosztowa?0 - for sales invoices (default), 1 - cost invoice
defwhether the invoice is defined0 - no, 1 - yes, invoice defined
placeplace of issuing the documentif it is missing, the place of issue specified in the program configuration is used
cdescdescription of the cost
cost2cost type+KF - company cost (default)
+MD - media
+ZT - purchase of goods and services
+PA - fuel purchase
+PO - costs of the vehicle
+LE - leasing
+IN - other cost
car2
type2
titleinvoice titlepermanently saved for each invoice, it may change for newly issued invoices eg invoices issued from 01/01/2014 have the title Invoice and issued before 2014 VAT invoice.
c1idID (buyer and payer)Contractor's ID - they can be obtained by executing the contractor selection command, e.g. {"name":"%john brown%", "icase":1}
c1namecompany namedane served only for selection
c1streetstreet, number
c1codepostal code
c1citycity
c1taxidTAX ID
c1tueidVAT UE
c1traidBusiness ID Number
c1krsidKRS
c2idID (recipient)Counterparty ID (j.w.)
c2namecompany namedata provided only for selection
c2streetstreet, number
c2codepostal code
c2citycity
c2taxidTAX ID
c2tueidVAT UE
c2traidBusiness ID Number
c2krsidKRS
mdatedate of issueYYYY-MM-DD
sdatesale dateYYYY-MM-DD
sdchk
sdate2
tdatedate of paymentYYYY-MM-DD
pdatepayment dateYYYY-MM-DD
currdtthe date of the exchange rateYYYY-MM-DD
bank_idbank IDyou can receive them by doing a selection from bank accounts, e.g. {"action":"list", "what":"accounts"}
bank_namename of the seller's bankavailable only in list mode
bank_accountaccount number
bank_swiftSWIFT code of the bank
ptidID of form/term of paymentyou can receive them with the command of selecting forms and payment dates, e.g. {"action":"list", "what":"paytypes"}
issuingissuing the invoice
receivingreceiving the invoice
paidpaid
vnettothe net valuealways provided in the currency of the invoice
in order to obtain the value in default currency, multiply the value by the currval rate
vbruttogross value
currencycurrencye.g. PLN, EUR, USD
currtabECB tablee.g. 135/A/NBP/2014
currvalexchange ratee.g. 4.1520
bruttonet unit/gross unit prices0 - net (default)
1 - gross
nrdocinvoice number (printed)
nrxsequence number of the documentshould be in line with the invoice number, eg for 123/03/2014 it should be 123
noticesinvoice remarks
notices_privnotes for the seller (not printable)
statusinvoice/cost status0 - sketch
1 - sent
2 - printed
3 - paid
4 - not paid
5 - canceled
dwks
nupt
qucart
quofpcs
netweight
grossweight
container
delivery
accschAccounting template ID
accpowReason of taxation ID
aufc
aufq
auem
aumsg
itemsadditionally invoice items are included
only available in list mode (action "list")

works only for result narrowed to ID invoice
0 - no (default)
1 - yes
issuing/editing invoices
(action "add" or "edit")
invoice/bill items: it may contain one or more item items - item values described in the next table
beffor correcting invoices, narrows the result to correcting (0) or corrected (1)to use when used "items"

is not an attribute describing invoice items - apply only to listings

Fields describing items on the invoice/bill

namedescriptionexplanation / examples
idInvoice item IDthis is not #no number visible on invoices - there can not be two items with the same ID even if they refer to different invoices
didDocument ID (invoice)to be used only when listing the position (resources "items")
kidcorrected item IDuse only for listings
only appears on correction invoices
never points to items from another invoice
productname of product/service
pkwiuclass code
discountdiscountdetermined in percent
unitidUnit ID (e.g. 1034)
unitsmthe symbol of the unit (e.g. "szt.")
countquantity
vatidVAT tax ID (e.g. 5){io.page.api.invoices.items.xxxx.ex}
vatsmVAT symbol (np. "23%")
vatnametax name (np. "primary 23%"){io.page.api.invoices.items.xxxx.ex}
pnettonet unit price{io.page.api.invoices.items.xxxx.ex}
pbruttogross unit price
vnettothe net value
vbruttogross value
cartonsthe number of packagesapplies only to export invoices
orginoriginas above
ubif by-product, only for +ZT costs type1 - yes, 0 - no
beffor correcting invoices, narrows the result to correcting (0) or corrected (1)is not an attribute describing the invoice items - use only for listings

Examples of use:

Retrieving invoice data

{ "action":"list", "type2":"+FV", "mdate":"2014-10-01|2014-10-27" }
{ "action":"list", "type2":"+FV", "id":320450, "items":1 }
Displaying invoice of the contractor and invoices with the product (in both cases we give the ID of the contractor / product from the catalog)

{ "action":"list", "include_customer":123 }
{ "action":"list", "include_product":456 }
Adding a new invoice

{ "action":"add", "type2":"+FV", "nrdoc":"FV/15/10/2014", "nrx":15, "c1id":2063,
"items":[ {"product":"cos tam", "pkwiu":"72/20", "count":4, "unit":"szt.", "pnetto":100.00, "vatsm":"23%"} ] }

Adding a new correcting invoice

{ "action":"add", "type2":"+KOR", "nrdoc":"KOR/7/10/2014", "nrx":7, "kid":6167, "c1id":2063,
"items":[ {"product":"cos tam", "pkwiu":"72/20", "count":4, "unit":"szt.", "pnetto":100.00, "vatsm":"23%", "before":{"product":"cos tam", "pkwiu":"72/20", "count":3, "unit":"szt.", "pnetto":100.00, "vatsm":"23%"} } ] }

Default values for the new invoice

{ "action":"default", "type2":"+FV", "nrx":100, "mdate":"2015-03-25", "sdate":"2015-03-25", "currency":"EUR", "emt":52319 }

Sample answer:{ "pvat":1, "nrdoc":"0100\/02\/2015", "nrx":100, "type2s":"+FV", "title2s":"Faktura", "type2c":"+FV", "title2c":"Faktura", "currency":"EUR", "currval":4.1783, "currtab":"030\/A\/NBP\/2015", "currdt":"2015-02-13", "unitid":39879, "taxid":2, "dtpid":50293 }


Change of status

{ "action":"status", "id":345, "value":0-5 }

Deleting the invoice

{ "action":"delete", "id":345 }

Contractors


Fields describing the contractor:

namedescriptionexplanation / examples
groupcontractor group ID (optional)
symbolsymbol / short name
namefull company name / first and last name
streetstreet, number
codepostal code
citycity
countrycountry
regionstate / region
taxidVAT ID
tueidEU-VAT ID
traidBusiness Number
krsidKRS ID
bnamebank name
baccountaccount number
bswiftSWIFT code
sphonephone number
mphonemobile number
faxnrfax number
websiteweb page
emaile-mail adress
dptypedefault payment method ID
c1
c2
type of contractorc1=1 - client (default)
c2=1 - seller

Examples of use:

List of contractors

{ "action":"list", "name":"%kowalski%", "icase":1 }
Adding a contractor

{ "action":"add", "symbol":"K1", "name":"Jan Kowalski", "street":"Korfantego 100", "code":"40-154", "city":"Katowice", "taxid":"645-123-45-67", "bname":"mBank", "baccount":"00 1111 2222 3333 4444 5555" }
Changing the data of the contractor

{ "action":"edit", "id":99, "symbol":"K2", "name":"Jan Iksiński", "street":"Korfantego 101" }
Removal of the contractor

{ "action":"delete", "id":345 }

Products


Fields describing the product:

namedescriptionexplanation / examples
typeproduct type0 - good
1 - service
groupgroup of goods and services
symbolsymbol / short name
namefull product name
descdescription / product specification
pkwiuclass code
swwSWW code
vatidVAT rate ID
vatsmVAT rate symbol
unitidUnit ID
unitsmthe symbol of the unit
pnettonet price
pbruttogross price
currencycurrency
noticescomments
websitethe URL of the product page

Examples of use:

List of products

{ "action":"list", "name":"%laptop dell%", "icase":1 }
Adding a product

{ "action":"add", "type":0, "symbol":"Dell 3531", "name":"Laptop Dell Inspiron 3531", "desc":"Ekran 15.6'' HD, Intel Celeron N2830, 4GB RAM/500GB HDD, Bateria 6.25 h", "pkwiu":"26.20.11", "vatsm":"23%", "unitsm":"szt.", "brutto":1500.00 }
Change of product data

{ "action":"edit", "id":99, "symbol":"D3531", "name":"Dell Inspiron 3531", "brutto":1249.00 }
Product removal

{ "action":"delete", "id":345 }

Dictionaries


Downloading dictionary data:

VAT rates

Query: { "action":"list", "what":"taxrates" }
Answer: { "count":8,"rows":[
{ "c1":1,"c2":0,"c3":"Podatek VAT 23%","c4":"23%","c5":0.2300 },
{ "c1":2,"c2":0,"c3":"Podatek VAT 7%","c4":"7%","c5":0.0700 },
{ "c1":3,"c2":0,"c3":"Stawka VAT 5%","c4":"5%","c5":0.0500 },
{ "c1":4,"c2":0,"c3":"Podatek VAT 3%","c4":"3%","c5":0.0300 },
{ "c1":5,"c2":0,"c3":"Podatek VAT 0%","c4":"0%","c5":0.0000 },
{ "c1":6,"c2":0,"c3":"Zwolnienie z podatku VAT","c4":"zw","c5":0.0000 },
{ "c1":7,"c2":0,"c3":"Podatek eksportowy","c4":"ex","c5":0.0000 },
{ "c1":8,"c2":0,"c3":"Nie podlega","c4":"np","c5":0.0000 }
] }

Bank accounts

Query: { "action":"list", "what":"accounts" }
Answer: { "count":2,"rows":[
{ "c1":1,"c2":0,"c3":"mBank","c4":"00 1111 1111 1111 1111 1111","c5":"MBANK" },
{ "c1":2,"c2":0,"c3":"ING Bank Śląski","c4":"22 2222 2222 2222 2222","c5":"ING" } ] }

Employees (persons issuing invoices)

Query: { "action":"list", "what":"employees" }
Answer: { "count":2,"rows":[
{ "c1":1,"c2":0,"c3":"Jan","c4":"Kowalski" },
{ "c1":2,"c2":0,"c3":"Kazimierz","c4":"Iksiński" } ] }

Groups of contractors

Query: { "action":"list", "what":"groupcu" }
Answer: { "count":2,"rows":[
{ "c1":1,"c2":0,"c3":"Lokalni","c4":"klienci stali, z miasta i okolicy" },
{ "c1":2,"c2":0,"c3":"Zamiejscowi","c4":"klienci przejezdni" } ] }

Product groups

Query: { "action":"list", "what":"groupgs" }
Answer: { "count":2,"rows":[
{ "c1":1,"c2":0,"c3":"Komputery","c4":"komputery, monitory, urządzenia peryferyjne" },
{ "c1":2,"c2":0,"c3":"Sprzęt AGD","c4":"pralki, lodówki, inny sprzęt AGD" } ] }

Payment methods and dates

Query: { "action":"list", "what":"paytypes" }
Answer: { "count":3,"rows":[
{ "c1":1,"c2":0,"c3":"Gotówka","c4":0,"c5":100,"c6":0,"c7":0 },
{ "c1":2,"c2":0,"c3":"Przelew 14 dni","c4":14,"c5":0,"c6":1,"c7":0 },
{ "c1":3,"c2":0,"c3":"Przelew 7 dni","c4":7,"c5":0,"c6":1,"c7":0 } ] }

Units

Query: { "action":"list", "what":"units" }
Answer: { "count":3,"rows":[
{ "c1":1,"c2":0,"c3":"Sztuka","c4":"szt.","c5": },
{ "c1":2,"c2":0,"c3":"Godzina","c4":"h","c5":#1 },
{ "c1":3,"c2":0,"c3":"Metr kw.","c4":"m2","c5":#2 } ] }

Exchange rates

Query: { "action":"list", "what":"currencies", "columns":"date,curr_eur,curr_usd", "sortby":"date desc", "limit":3 }
Answer: {"count":3,"rows":[
{"c1":"2015-06-05","c2":4.16,"c3":3.6949},
{"c1":"2015-06-03","c2":4.1307,"c3":3.7108},
{"c1":"2015-06-02","c2":4.1374,"c3":3.7676}
]}

Poczta i skany


Poniżej opisane polecenia umożliwiają pobieranie faktur w formacie PDF i wysyłanie ich e-mailem oraz dołączanie zdjęć (skanów) i załączników.

Pola opisujące operacje na fakturach sprzedaży:


nazwaopiswyjaśnienie / przykłady
actionoperacjamożliwe operacje:
get - pobranie pliku
send - wysłanie pliku w załączniku
idID dokumentu
whattyp dokumentu0 - faktura (domyślnie)
emailemail adresatatylko dla operacji send

Przykłady użycia:

Pobranie faktury

{ "action":"get", "id":301345 }
Wysłanie faktury w załączniku

{ "action":"send", "id":301345, "email":"biuro@mojklient.pl" }

Pola opisujące operacje na skanach i załącznikach:


nazwaopiswyjaśnienie / przykłady
actionoperacjamożliwe operacje:
cost - załączenie zdjęcia (skanu) / załącznika
list - wyświetla listę skanów/załączników
idID dokumentu (opcjonalnie)skan zostanie dołączony do faktury kosztowej (jeśli podano ID) lub dodany luźnie
idatedata dołączenia skanuw formacie YYYY-MM-DD
fnamenazwa (tytuł) załącznika
ftypetyp plikunp. .jpg, .png, .pdf
filezawartość pliku kodowana w base64

Przykłady użycia:

Dołączenie skanu

{ "action":"cost", "id":301347, "fname":"FV/50/04/2015", "ftype":".jpg", "file":"/9j/4AAQSkZJRgABAQEASABIAAD/4TIraHR..." }
Lista skanów

{ "action":"list", "id":301345 }

{ "action":"list", "idate":"2015-03-01|2015-04-30", }

Raporty


W przygotowaniu

This site uses cookies - so-called cookies. Learn more about the purpose of their use and changes in cookie settings.
By using the website you agree to the use of cookies in accordance with current browser settings.