Dokumentacja API BizIn Spis treści Wstęp .................................................................................................................................................... 1 Dostęp do API BizIn............................................................................................................................. 1 Identyfikatory API ................................................................................................................................ 1 Dostępne akcje ..................................................................................................................................... 3 Przykład wywołania API w języku PHP .............................................................................................. 3 Pobieranie danych ............................................................................................................................ 3 Wystawianie dokumentu – proforma ............................................................................................... 5 Opis pól XML dokumentu – proforma:........................................................................................ 6 Wystawianie dokumentu powiązanego ........................................................................................... 8 Opis pól XML dokumentu powiązanego: .................................................................................... 9 Dodawanie (import) dokumentu kosztowego.................................................................................. 9 Debugowanie ...................................................................................................................................... 12

Wstęp API BizIn umożliwia wprowadzanie oraz pobieranie danych przechowywanych w systemie BizIn, w celu integracji z innymi systemami teleinformatycznymi. Komunikacja odbywa się poprzez wymianę danych XML.

Dostęp do API BizIn Komunikacja zewnętrznych systemów IT z systemem BizIn odbywa się za pomocą przesyłania danych w formie dokumentów XML metodą POST. Dane powinny być przesyłane na specjalnie tworzony adres wg poniższego wzoru: https://bizin.pl/apiBizIn.html?idP=NUMER_IDP W miejsce NUMER_IDP, należy wstawić numer idP odczytany z zakładki moje konto, dostępnej w systemie BizIn. W tym samym miejscu znajduje się również klucz API, wykorzystywany podczas autoryzacji. Odpowiednio skonstruowany dokument trzeba przesłać żądaniem POST w polu o nazwie XML.

Zdjęcie 1: Dane dostępowe w zakładce moje konto

Dokumentacja API BizIn – ostatnia zmiana 25.11.2015

1

Identyfikatory API W komunikacji wykorzystywane są identyfikatory ApiId, które służą do wskazywania elementów w słownikach lub obiektach. System prezentuje identyfikatory w widokach większości słowników. np. identyfikator banku, możemy znaleźć w systemie w miejscu: moje konto => Firma => konta bankowe

Zdjęcie 2: ID konta bankowego w systemie BizIn a identyfikatory typów płatności za wystawiony dokument w systemie w miejscu: moje konto => Słowniki => typy płatności

Zdjęcie 3: ID typu płatności w systemie BizIn UWAGA: Identyfikatory prezentowane są jedynie w przypadku gdy firma ma wykupiony odpowiedni abonament z włączonym API.

Dokumentacja API BizIn – ostatnia zmiana 25.11.2015

2

Dostępne akcje addInvoice getInvoice getListInvoices getPurchaseInvoice getListPurchaseInvoices addPurchaseInvoice getStocks

dodawanie nowego dokumentu przychodowego => zwraca XML pobieranie dokumentu przychodowego => zwraca XML pobieranie listy dokumentów przychodowych => zwraca XML (uwaga! max 200 dokumentów w liście) pobieranie dodanego w systemie BizIn dokumentu kosztowego => zwraca XML pobieranie listy dokumentów kosztowych => zwraca XML (uwaga! max 200 dokumentów w liście) dodawanie nowego dokumentu kosztowego => zwraca XML pobieranie towaru z wybranego magazynu => zwraca XML

Przykład wywołania API w języku PHP Dane wymagane przez API BizIn, można wysłać za pomocą biblioteki CURL dostępnej dla wielu języków programowania.

Pobieranie danych Kod przedstawiony poniżej napisany został w języku PHP i zawiera kilka podstawowych akcji zapisanych w postaci gotowego wywołania XML. Wywołania te mogą być testowo przełączane poprzez przepisanie jednego z nich do zmiennej $xmlData. Zwrotnie wyświetlany jest dokument XML. $idP = "2"; $apiAdres = "https://bizin.pl/apiBizIn.html?idP=".$idP; $apiKey= 'ggen22tfhgi2jmq3k4n1tco2z1up12i7'; { ## pobieranie dokumentu przychodowego $xmlGetInvoice = " ".$apiKey." getInvoice 2110 "; } { ## pobieranie listy dokumentów przychodowych $xmlGetListInvoices = " ".$apiKey." getListInvoices ".date("Y-m-d", strtotime ("-12 month"))." ".date("Y-m-d")." "; }

Dokumentacja API BizIn – ostatnia zmiana 25.11.2015

3

{ ## pobieranie dokumentu kosztowego $xmlGetPurchaseInvoice = " ".$apiKey." getPurchaseInvoice 78 "; } { ## pobieranie listy dokumentów kosztowych $xmlGetListPurchaseInvoices = " ".$apiKey." getListPurchaseInvoices ".date("Y-m-d", strtotime ("-12 month"))." ".date("Y-m-d")." "; } { ## pobieranie towaru wybranego magazynu $xmlGetStocks = " ".$apiKey." getStocks 1 0 "; } $xmlData= $xmlGetInvoice; //$xmlData= $xmlGetListInvoices; //$xmlData= $xmlGetPurchaseInvoice; //$xmlData= $xmlGetListPurchaseInvoices; //$xmlData= $xmlGetStocks; $data = array('XML' => $xmlData); $handle = curl_init(); curl_setopt($handle, CURLOPT_URL, $apiAdres); curl_setopt($handle, CURLOPT_POST, 1); curl_setopt($handle, CURLOPT_POSTFIELDS, $data); curl_setopt($handle, CURLOPT_RETURNTRANSFER, 1); curl_setopt($handle, CURLOPT_ENCODING, 'UTF-8'); $result = curl_exec($handle); curl_close($handle);

header("Content-type: text/xml"); echo $result;

Ten przykład pokazał dość proste akcje z niewielką ilością danych w wywołaniu. Znacznie trudniejszą akcją jest tworzenie dokumentu. Poniżej przykłady (z opisami pól) tworzenia dokumentu proforma oraz dokumentu powiązanego. Dokumentacja API BizIn – ostatnia zmiana 25.11.2015

4

Wystawianie dokumentu – proforma klucz API addInvoice f8J949AD2SSYySqf 5 0 0 0 1 12/06/2014 2014-06-06 2014-06-06 14 0000-00-00 3 100 262 6571054616 Testowy wpis Piotr Czekaj 25-413 Kielce ul. Domaniówka 4 / 30 657-105-46-18 mBank 89712987112498723463264326 1 157 3 2 17 2 3 Usluga nr 2 7 szt. 23 400 Dokumentacja API BizIn – ostatnia zmiana 25.11.2015

5



Opis pól XML dokumentu – proforma: Lp. Nazwa pola

Opis pola

1

ROOT

główny korzeń dokumentu

2

api_key

klucz API wygenerowany z systemu BIZIN

3

action

parametr akcji przyjmuje: addInvoice lub getInvoice

4

transactionID

16 znakowy niepowtarzalny (losowy: alfanumeryczny) identyfikator transakcji (test dotyczy bieżącego dnia)

5

params

kontener parametrów

6

dokument_typ

typ dokumentu ( 3 – Faktura, 5 – proforma)

7

dokument_typ_procedury_marza

typ do róznych odmian marzy

8

dokument_id

podawane tylko w action=> getInvoice

9

dokument_id_doc_zrodlo

0 lub identyfikator (musi być int)

10 dokument_auto_nr_data

wartości 0 lub 1 - automatycznie pilnuje numeru dokumentu, daty wystawienia i daty sprzedaży

11 dokument_nr

numer dokumentu w formie string - tylko jeśli 'dokument_auto_nr_data' == 0

12 dokument_data_wystawienia

tylko jeśli 'dokument_auto_nr_data'==0

13 dokument_data_sprzedazy

tylko jeśli 'dokument_auto_nr_data'==0

14 dokument_typPlatnosciApiId

id typu płatności

15 dokument_data_splaty

0000-00-00 lub data

16 dokument_bankApiId

id banku z systemu bizin

17 dokument_towar_marza

???

18 dokument_uwagi

pusty string dodaje domyślny wpis ustawiony na podmiocie

19 kontrahent

kontener danych kontrahenta

20 kontrahentApiId

id kontrahenta - jeśli jest podany poprawny identyfikator nie porównuje reszty danych

21 kod_kontrahenta

nip lub pesel - same cyfry

22 nazwa

nazwa kontrahenta

23 imię

imię i nazwisko kontrahenta

24 kod

kod pocztowy, np. 25-314

25 miejscowosc

miejscowość, np. Kielce

26 ulica

ulica np. Pawia

27 nr_domu

numer domu, np. 4/39

28 nip

numer nip

29 pesel

numer pesel

30 uwagi

uwagi

31 bank_nazwa

nazwa banku (np. ING Bank Śląski)

32 bank_nr_konta

numer konta bankowego

33 pozycje

kontener zawierający pozycje faktury

Dokumentacja API BizIn – ostatnia zmiana 25.11.2015

6

34 pozycja_(nr)

pozycja numer (nr)

35 typ

Typ pozycji: 1 - id_magazyn, 2 - id_uslugi, 3 - dowolna pozycja

typ = 1 36 magazynApiId

ID magazynu z systemu BizIn. Jeśli typ = 1.

37 ilosc

ilość towaru / usługi

typ = 2 36 uslugiApiId

ID usługi z systemu BizIn. Jeśli typ = 2.

37 ilosc

ilość towaru / usługi

typ = 3 36 nazwa

nazwa usługi / produktu

37 ilosc

ilość towaru / usługi

38 jm

jednostka miary (np. szt, kg itd.)

39 vat

stawka podatku VAT (np. 23)

40 cena_n – cena netto (za 1 jm)

Wystarczy podać jedną z cen, system BizIn obliczy druga na podstawie stawki VAT.

41 cena_b - cena brutto (za 1 jm)

Wystarczy podać jedną z cen, system BizIn obliczy druga na podstawie stawki VAT.

Dokumentacja API BizIn – ostatnia zmiana 25.11.2015

7

Wystawianie dokumentu powiązanego Do wystawiania dokumentu powiązanego, np. Faktury na podstawie dokumentu proforma - należy użyć następującego wzoru dokumentu XML: wfn6mxu9smzmr37jnthgpqn9uo1arsi5 addInvoice 3 0 1026 1 14 2014-06-06 2 ., 0 2014-06-04 263 6571054608 Firma Jasia Fasoli Jaś Fasola Londek Zdrój ul. Wiśniowa 5 657-105-46-08

Dokumentacja API BizIn – ostatnia zmiana 25.11.2015

8

Opis pól XML dokumentu powiązanego: Lp. Nazwa pola

Opis pola

1

ROOT

główny korzeń dokumentu

2

api_key

klucz API wygenerowany z systemu BIZIN

3

action

parametr akcji przyjmuje: addInvoice lub getInvoice

4

transactionID

16 znakowy niepowtarzalny (losowy: alfanumeryczny) identyfikator transakcji (test dotyczy bieżącego dnia)

5

params

kontener parametrów

6

dokument_typ

typ dokumentu ( 3 – Faktura, 5 – proforma)

7

dokument_typ_procedury_marza

(np. 0)

8

dokument_id

podawane tylko w action = getInvoice

9

dokument_id_doc_zrodlo

0 lub identyfikator (musi być int)

10 dokument_auto_nr_data

Wartości 0 lub 1 - automatycznie pilnuje numeru dokumentu, daty wystawienia i daty sprzedaży

11 dokument_typPlatnosciApiId

id typu płatności z systemu BIZIN

12 dokument_data_splaty

0000-00-00 lub data

13 dokument_bankApiId

id banku z systemu BIZIN

14 dokument_dodatkowy_opis

Dodatkowy opis na dokumencie

15 zrodlo_status

Czy dokonać zmiany dokumentu źródłowego: pusty string - bez zmiany, 0 - nieaktywny, 1 - aktywny

16 zrodlo_dataSplaty

pusty string - bez zmiany

17 kontrahent

kontener danych kontrahenta

18 kontrahentApiId

Jeśli jest podany poprawny identyfikator nie porównuje reszty danych. Bark lub 0 oraz pusta reszta pól lub array() - pobiera ze źródła

19 kod_kontrahenta

nip lub pesel - same cyfry

20 nazwa

nazwa kontrahenta

21 imie

imię i nazwisko kontrahenta

22 kod

kod pocztowy, np. 25-314

23 miejscowosc

miejscowość, np. Kielce

24 ulica

ulica np. Pawia

25 nr_domu

numer domu, np. 4/39

26 nip

numer nip

27 pesel

numer pesel

28 uwagi

uwagi

29 bank_nazwa

nazwa banku (np. ING Bank Śląski)

30 bank_nr_konta

numer konta bankowego

Dodawanie (import) dokumentu kosztowego Dodawanie dokumentu kosztowego, wymaga podobnie jak akcja dodawania dokumentu przychodowego użycia dokumentu XML z podanym api_key, action oraz gałęzią params. Poniżej przedstawiamy przykładowe wywołanie. Dokumentacja API BizIn – ostatnia zmiana 25.11.2015

9

wfn6mxu9smzmr37jnthgpqn9uo1araqd addPurchaseInvoice BizIn 1 3 1 FV-2/11/2015 2015-11-23 2015-11-23 Biuro Informacyjne 00-950 Warszawa ul. Woronicza 17 123-154-48-85 Polska 41-344-75-75 [email protected] biuroinformacyjne.to 1231544885 GB28121761937 GB28121761937 4deWind - Barbara Stojko Lecha 10/7A 25-622 KIELCE Wyspy Owcze [email protected] trelemele 7 2015-11-30 1 3071 2 Rejestr usług 17 USŁUGI KSIĘGOWE zażółć gęślą jaźń 1 szt. 100 123 Dokumentacja API BizIn – ostatnia zmiana 25.11.2015

10

100 23 % 23 123 1 PLN 1.0000 1 2015-11-20

Uwagi: •

Zwrotnie generowany jest dokument XML.

•

Dane w gałęzi params to dokument w standardzie BizIn z usuniętymi niektórymi gałęziami.

•

Pozycje dodawane są jako towar handlowy magazynu oznaczonego jako domyślny.

•

Domyślnie podczas dodawania pozycji przypisywana jest pierwsza aktywna kategoria ze słownika.

Dokumentacja API BizIn – ostatnia zmiana 25.11.2015

11

Debugowanie API zawiera także tryb debug, który umożliwia sprawdzanie poprawności wysyłanych danych bez wprowadzania zmian w systemie BizIn. Uruchomienie trybu debug, jest możliwe poprzez dodanie do adresu API parametru &debug=yes https://bizin.pl/apiBizIn.html?idP=NUMER_IDP&debug=yes

Dokumentacja API BizIn – ostatnia zmiana 25.11.2015

12