Interfejs API

Wstęp

Interfejs API umożliwia integrację zewnętrznych aplikacji z systemem fakturowania i księgowości Intaxo. Komunikacja odbywa się za pomocą formatu wymiany danych JSON więc wspierany jest przez większość obecnie stosowanych języków programowania w tym C, C++, C#, PHP, Java, JavaScript, Python, Ruby.

Ścieżka dostępu

Ścieżka dostępu do interfejsu API jest następująca:

https://intaxo.pl/api.json

Sposób użycia

Za każdym razem w celu wymiany danych z intaxo należy podać: dane autoryzacji (CURLOPT_USERPWD) oraz metodą POST (CURLOPT_POSTFIELDS) parametry typ zasobu r i dane w formacie JSON q. Najprostszym sposobem odwołania się do zasobów API intaxo.pl jest użycie biblioteki CURL (przykład w PHP).

Przykład:

$curl_ = curl_init();
curl_setopt($curl_, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($curl_, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl_, CURLOPT_USERPWD, "login:hasło");
curl_setopt($curl_, CURLOPT_URL, "https://intaxo.pl/api.json");
curl_setopt($curl_, CURLOPT_POSTFIELDS, "r=login&q={}");
curl_exec($curl_);
curl_close($curl_);

Wywołanie powyższych poleceń wyśle zapytanie o autoryzację do konta Intaxo i zwróci:

{"cid":nr, "uid":uu} jeśli autoryzacja będzie pozytywna
 nr to ID konta, zawsze >= 1, UU to ID użytkownika (subkonta) >= 0
{"error":1,"message":"authentication error"} w przypadku błędu autoryzacji


Zasoby

nazwa	opis	przykładowe zapytania
login	służy tylko do sprawdzenia logowania	{ }
dictionaries	słowniki (stawki VAT, jednostki etc.)	{ "action":"list", "what":"taxrates" }
invoices	faktury sprzedażowe i kosztowe	{ "action":"list", "search":"Drutex s.c." }
items	pozycje wybranej faktury	{ "action":"list", "did":32501 }
customers	kontrahenci	{ "action":"list", "search":"kowalski" }
products	towary/usługi	{ "action":"list", "search":"drukarka" }
bookkeeping	księgowość	{ "action":"list", "what":"zus" }
files	operacje na plikach	{ "action":"get", "id":301345 }
reports	raporty

Akcje

nazwa	opis	wyjaśnienie / przykłady
add	dodanie faktury / kontrahenta / produktu	ID należy pominąć lub ustawić na 0
edit	edycja faktury / kontrahenta / produktu	wymaga podania ID zasobu zmienia tylko podane, zgodne z dokumentacją, wartości
list	wyświetlanie faktur / kontrahentów / produktów	wyniki wyszukiwania można zawęzić do konkretnego rekordu podając ID lub do właściwości (np. numer faktury, nazwa kontrahenta) można użyć także atrybutu search aby wyszukać frazę/wartość jednocześnie w kilku atrybutach (w przypadku faktur wyszukiwanie odbywa się po atrybutach nagłówka i po pozycjach faktury)

Sortowanie, stronicowanie i ustawienie limitu

Dane zapytań listujących można sortować, stronicować i ograniczyć ich ilość.

Sortowanie stosuje za pomocą atrybutu sortby np.:

{ "action":"list", "sortby":"nazwa kolumny" }
W celu użycia stronicowania należy użyć atrybutów page i cpp np.:

{ "action":"list", "page":3, "cpp":10 }
Powyższe zapytanie listujące faktury zwróci zawartość trzeciej strony - wiersze 21-30 (o ile faktur jest minimum 30, jeśli nie lista może być krótsza lub pusta).

Aby ograniczyć ilość danych (wierszy) bez stronicowania można użyć atrybutu limit np.:

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

Kody błędów

W przypadku wystąpienia błędu serwer zwróci jeden z poniższych komunikatów:

{"error":1,"message":"authentication error"} - błąd autoryzacji
{"error":2,"message":"incorrect resource"} - błędnie podana nazwa zasobu
{"error":3,"message":"invalid JSON format"} - błędna składnia JSON
{"error":4,"message":"incorrect dictionary"} - błędnie podany słownik
{"error":5,"message":"incorrect action"} - nieznana akcja
{"error":6,"message":"incorrect ID"} - błędny ID
{"error":7,"message":"account is not activated"}