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... 7 Opis pól XML dokumentu proforma:... 8 Wystawianie dokumentu powiązanego... 10 Opis pól XML dokumentu powiązanego:... 11 Dodawanie (import) dokumentu kosztowego... 11 Debugowanie... 14 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 22.01.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 22.01.2015 2
Dostępne akcje apitestconnection addinvoice removeinvoice getinvoice getlistinvoices getpurchaseinvoice getlistpurchaseinvoices addpurchaseinvoice getstocks getclient Test poprawności wywołania => zwraca XML dodawanie nowego dokumentu przychodowego => zwraca XML usuwanie 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 Pobieranie danych klienta zapisanych w systemie => zwraca XML System przyjmuje i zwraca dane w formacie XML. W przypadku błędu wywołania lub przetwarzania danych komunikat zwrotny może wyglądać następująco: <ROOT> <status>error</status> <statusopis>błąd obliczania kolejnego numeru dla nowego dokumentu.</statusopis> <statusopis>api ERROR - Add document error (1)</statusOpis> </ROOT> 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'; { ## BizIn - apitestconnection $xmlapitestconnection = "<ROOT> <action>apitestconnection</action> {## pobieranie dokumentu przychodowego $xmlgetinvoice = "<ROOT> Dokumentacja API BizIn ostatnia zmiana 22.01.2015 3
<action>getinvoice</action> <dokument_id>2110</dokument_id> { ## pobieranie listy dokumentów przychodowych $xmlgetlistinvoices = "<ROOT> <action>getlistinvoices</action> <listinvoicesdatastart>".date("y-m-d", strtotime ("-12 month"))."</listinvoicesdatastart> <listinvoicesdatastop>".date("y-m-d")."</listinvoicesdatastop> { ## przeœlij dokument do kontrahenta $xmlsendinvoiceinfo = "<ROOT> <action>sendinvoiceinfo</action> <dokument_id>2263</dokument_id> { ## usuwanie dokumentu przychodowego $xmlremoveinvoice = "<ROOT> <action>removeinvoice</action> <dokument_id>www2263</dokument_id> { ## pobieranie dokumentu kosztowego $xmlgetpurchaseinvoice = "<ROOT> <action>getpurchaseinvoice</action> <dokument_id>78</dokument_id> { ## pobieranie listy dokumentów kosztowych $xmlgetlistpurchaseinvoices = "<ROOT> <action>getlistpurchaseinvoices</action> <listinvoicesdatastart>".date("y-m-d", strtotime ("-12 month"))."</listinvoicesdatastart> Dokumentacja API BizIn ostatnia zmiana 22.01.2015 4
<listinvoicesdatastop>".date("y-m-d")."</listinvoicesdatastop> { ## pobieranie towaru wybranego magazynu $xmlgetstocks = "<ROOT> <action>getstocks</action> <miejsceapiid>1</miejsceapiid> <kategoriatowaruapiid>0</kategoriatowaruapiid> { ## pobierz dane klienta - wyszukiwanie po pierwszym znalezionym obiekcie $xmlgetclient= "<ROOT> <action>getclient</action> <kontrahentapiid></kontrahentapiid> <kontrahentnip>657-28-39-511</kontrahentnip> <kontrahentpesel></kontrahentpesel> /* $xmlapitestconnection; $xmlgetinvoice; $xmlremoveinvoice; $xmlsendinvoiceinfo; $xmlgetlistinvoices; $xmlgetpurchaseinvoice; $xmlgetlistpurchaseinvoices; $xmlgetstocks; $xmldata= $xmlgetclient; */ $data = array('xml' => $xmlremoveinvoice); $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; Dokumentacja API BizIn ostatnia zmiana 22.01.2015 5
Ten przykład pokazał dość proste akcje z niewielką ilością danych w wywołaniu. Znacznie trudniejszą akcją jest tworzenie dokumentów. Poniżej przykłady (z opisami pól) tworzenia dokumentu proforma oraz dokumentu powiązanego. Dokumentacja API BizIn ostatnia zmiana 22.01.2015 6
Wystawianie dokumentu proforma <?xml version="1.0"?> <ROOT> <api_key>klucz API</api_key> <action>addinvoice</action> <transactionid>f8j949ad2ssyysqf</transactionid> <dokument_typ>5</dokument_typ> <dokument_typ_procedury_marza>0</dokument_typ_procedury_marza> <dokument_id>0</dokument_id> <dokument_id_doc_zrodlo>0</dokument_id_doc_zrodlo> <dokument_auto_nr_data>1</dokument_auto_nr_data> <dokument_nr>12/06/2014</dokument_nr> <dokument_data_wystawienia>2014-06-06</dokument_data_wystawienia> <dokument_data_sprzedazy>2014-06-06</dokument_data_sprzedazy> <dokument_typplatnosciapiid>14</dokument_typplatnosciapiid> <dokument_data_splaty>0000-00-00</dokument_data_splaty> <dokument_bankapiid>3</dokument_bankapiid> <dokument_towar_marza>100</dokument_towar_marza> <dokument_uwagi></dokument_uwagi> <kontrahent> <kontrahentapiid>262</kontrahentapiid> <kod_kontrahenta>6571054616</kod_kontrahenta> <nazwa>testowy wpis</nazwa> <imie>piotr Czekaj</imie> <kod>25-413</kod> <miejscowosc>kielce</miejscowosc> <ulica>ul. Domaniówka</ulica> <nr_domu>4 / 30</nr_domu> <nip>657-105-46-18</nip> <pesel></pesel> <uwagi></uwagi> <bank_nazwa>mbank</bank_nazwa> <bank_nr_konta>89712987112498723463264326</bank_nr_konta> </kontrahent> <pozycje> <pozycja_1> <typ>1</typ> <magazynapiid>157</magazynapiid> <ilosc>3</ilosc> </pozycja_1> <pozycja_2> <typ>2</typ> <uslugiapiid>17</uslugiapiid> <ilosc>2</ilosc> </pozycja_2> <pozycja_3> <typ>3</typ> <nazwa>usluga nr 2</nazwa> <ilosc>7</ilosc> <jm>szt.</jm> <vat>23</vat> <cena_n></cena_n> <cena_b>400</cena_b> Dokumentacja API BizIn ostatnia zmiana 22.01.2015 7
</pozycja_3> </pozycje> </ROOT> Opis pól XML dokumentu proforma: Lp. Nazwa pola Opis pola ROOT główny korzeń dokumentu 1 api_key klucz API wygenerowany z systemu BIZIN 2 action parametr akcji przyjmuje: addinvoice lub getinvoice 3 transactionid 16 znakowy niepowtarzalny (losowy: alfanumeryczny) identyfikator transakcji (test dotyczy bieżącego dnia) 4 params kontener parametrów 4.1 dokument_typ typ dokumentu ( 3 Faktura, 5 proforma) 4.2 dokument_typ_procedury_marza typ do róznych odmian marzy 4.3 dokument_id podawane tylko w action=> getinvoice 4.4 dokument_id_doc_zrodlo 0 lub identyfikator (musi być int) 4.5 dokument_auto_nr_data wartości 0 lub 1 - automatycznie oblicza numeru dokumentu na podstawie daty wystawienia 4.6 dokument_nr numer dokumentu w formie string - tylko jeśli 'dokument_auto_nr_data' == 0 4.7 dokument_data_wystawienia Jeśli pole jest puste -> ustawiana jest bieżąca data 4.8 dokument_data_sprzedazy Jeśli pole jest puste -> ustawiana jest bieżąca data 4.9 dokument_typplatnosciapiid id typu płatności 4.10 dokument_data_splaty 0000-00-00 lub data 4.11 dokument_bankapiid id banku z systemu bizin 4.12 dokument_towar_marza??? 4.13 dokument_uwagi pusty string dodaje domyślny wpis ustawiony na podmiocie 4.14 kontrahent kontener danych kontrahenta 4.14.1 kontrahentapiid id kontrahenta - jeśli jest podany poprawny identyfikator nie porównuje reszty danych 4.14.2 kod_kontrahenta nip lub pesel - same cyfry 4.14.3 nazwa nazwa kontrahenta 4.14.4 imię imię i nazwisko kontrahenta 4.14.5 kod kod pocztowy, np. 25-314 4.14.6 miejscowosc miejscowość, np. Kielce 4.14.7 ulica ulica np. Pawia 4.14.8 nr_domu numer domu, np. 4/39 4.14.9 nip numer nip 4.14.10 pesel numer pesel 4.14.12 uwagi uwagi 4.14.13 bank_nazwa nazwa banku (np. ING Bank Śląski) 4.14.14 bank_nr_konta numer konta bankowego 4.15 pozycje kontener zawierający pozycje faktury Dokumentacja API BizIn ostatnia zmiana 22.01.2015 8
4.15.1 pozycja_(nr) pozycja numer (nr) typ 4.15.1.1 typ = 1 Typ pozycji: 1 - id_magazyn, 2 - id_uslugi, 3 - dowolna pozycja 4.15.1.2 magazynapiid ID magazynu z systemu BizIn. Jeśli typ = 1. 4.15.1.3 ilosc ilość towaru / usługi 4.15.1.1 typ = 2 4.15.1.2 uslugiapiid ID usługi z systemu BizIn. Jeśli typ = 2. 4.15.1.3 ilosc ilość towaru / usługi 4.15.1.1 typ = 3 4.15.1.2 nazwa nazwa usługi / produktu 4.15.1.3 ilosc ilość towaru / usługi 4.15.1.4 jm jednostka miary (np. szt, kg itd.) 4.15.1.5 vat stawka podatku VAT (np. 23) 4.15.1.6 cena_n cena netto (za 1 jm) Wystarczy podać jedną z cen, system BizIn obliczy druga na podstawie stawki VAT. 4.15.1.7 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 22.01.2015 9
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: <?xml version="1.0"?> <ROOT> <api_key>wfn6mxu9smzmr37jnthgpqn9uo1arsi5</api_key> <action>addinvoice</action> <dokument_typ>3</dokument_typ> <dokument_typ_procedury_marza>0</dokument_typ_procedury_marza> <dokument_id_doc_zrodlo>1026</dokument_id_doc_zrodlo> <dokument_auto_nr_data>1</dokument_auto_nr_data> <dokument_typplatnosciapiid>14</dokument_typplatnosciapiid> <dokument_data_splaty>2014-06-06</dokument_data_splaty> <dokument_bankapiid>2</dokument_bankapiid> <dokument_dodatkowy_opis>.,</dokument_dodatkowy_opis> <zrodlo_status>0</zrodlo_status> <zrodlo_datasplaty>2014-06-04</zrodlo_datasplaty> <kontrahent> <kontrahentapiid>263</kontrahentapiid> <kod_kontrahenta>6571054608</kod_kontrahenta> <nazwa>firma Jasia Fasoli</nazwa> <imie> Jaś Fasola</imie> <kod></kod> <miejscowosc>londek Zdrój</miejscowosc> <ulica>ul. Wiśniowa</ulica> <nr_domu>5</nr_domu> <nip>657-105-46-08</nip> <pesel></pesel> <uwagi></uwagi> <bank_nazwa></bank_nazwa> <bank_nr_konta></bank_nr_konta> </kontrahent> </ROOT> Dokumentacja API BizIn ostatnia zmiana 22.01.2015 10
Opis pól XML dokumentu powiązanego: Lp. Nazwa pola Opis pola ROOT główny korzeń dokumentu 1 api_key klucz API wygenerowany z systemu BIZIN 2 action parametr akcji przyjmuje: addinvoice lub getinvoice 3 transactionid 16 znakowy niepowtarzalny (losowy: alfanumeryczny) identyfikator transakcji (test dotyczy bieżącego dnia) 4 params kontener parametrów 4.1 dokument_typ typ dokumentu ( 3 Faktura, 5 proforma) 4.2 dokument_typ_procedury_marza (np. 0) 4.3 dokument_id podawane tylko w action = getinvoice 4.4 dokument_id_doc_zrodlo 0 lub identyfikator (musi być int) 4.5 dokument_typplatnosciapiid id typu płatności z systemu BIZIN 4.6 dokument_data_splaty 0000-00-00 lub data 4.7 dokument_bankapiid id banku z systemu BIZIN 4.8 dokument_dodatkowy_opis Dodatkowy opis na dokumencie 4.9 zrodlo_status Czy dokonać zmiany dokumentu źródłowego: pusty string - bez zmiany, 0 - nieaktywny, 1 - aktywny 4.10 zrodlo_datasplaty pusty string - bez zmiany 4.11 kontrahent kontener danych kontrahenta 4.11.1 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 4.11.2 kod_kontrahenta nip lub pesel - same cyfry 4.11.3 nazwa nazwa kontrahenta 4.11.4 imie imię i nazwisko kontrahenta 4.11.5 kod kod pocztowy, np. 25-314 4.11.6 miejscowosc miejscowość, np. Kielce 4.11.7 ulica ulica np. Pawia 4.11.8 nr_domu numer domu, np. 4/39 4.11.9 nip numer nip 4.11.10 pesel numer pesel 4.11.11 uwagi uwagi 4.11.12 bank_nazwa nazwa banku (np. ING Bank Śląski) 4.11.13 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. <ROOT> <api_key>wfn6mxu9smzmr37jnthgpqn9uo1araqd</api_key> Dokumentacja API BizIn ostatnia zmiana 22.01.2015 11
<action>addpurchaseinvoice</action> <DOKUMENT> <GENERATOR>BizIn</GENERATOR> <TYP_DOKUMENTU>1</TYP_DOKUMENTU> <NAGLOWEK> <RODZAJ_DOKUMENTU>3</RODZAJ_DOKUMENTU> <DOKUMENT_Z_VAT>1</DOKUMENT_Z_VAT> <NUMER_PELNY>FV-2/11/2015</NUMER_PELNY> <DATA_WYSTAWIENIA>2015-11-23</DATA_WYSTAWIENIA> <DATA_DOSTAWY>2015-11-23</DATA_DOSTAWY> <SPRZEDAWCA> <nazwa>biuro Informacyjne</nazwa> <kod>00-950</kod> <miejsc>warszawa</miejsc> <ul>ul. Woronicza</ul> <nr>17</nr> <nip>123-154-48-85</nip> <kraj>polska</kraj> <dodatkowe_info></dodatkowe_info> <tel>41-344-75-75</tel> <mail>biuro@biuroinformacyjne.to</mail> <www>biuroinformacyjne.to</www> <nazwa_baner></nazwa_baner> <GLN>1231544885</GLN> <NAZWA_BANKU></NAZWA_BANKU> <NUMER_KONTA_BANKOWEGO></NUMER_KONTA_BANKOWEGO> </SPRZEDAWCA> <PLATNIK> <NIP>GB28121761937</NIP> <GLN>GB28121761937</GLN> <PESEL></PESEL> <NAZWA>4deWind - Barbara Stojko</NAZWA> <ADRES> <ULICA>Lecha 10/7A</ULICA> <KOD_POCZTOWY>25-622</KOD_POCZTOWY> <MIASTO>KIELCE</MIASTO> <KRAJ>Wyspy Owcze</KRAJ> </ADRES> <DANE_UZUPELNIAJACE> <E-MAIL>p.czekaj@pcet.pl</E-MAIL> <UWAGI>trelemele</UWAGI> <DATA_UTWORZENIA></DATA_UTWORZENIA> </DANE_UZUPELNIAJACE> </PLATNIK> <PLATNOSC> <FORMA>7</FORMA> <TERMIN>2015-11-30</TERMIN> </PLATNOSC> </NAGLOWEK> <POZYCJE> <POZYCJA_1> <LP>1</LP> <ID_SPRZEDAZY>3071</ID_SPRZEDAZY> <TYP_POZYCJI>2</TYP_POZYCJI> <TYP_POZYCJI_OPIS>Rejestr usług</typ_pozycji_opis> <ID_REJESTR>17</ID_REJESTR> <NAZWA>USŁUGI KSIĘGOWE zażółć gęślą jaźń</nazwa> <ILOSC>1</ILOSC> <JM>szt.</JM> <CENA_NETTO>100</CENA_NETTO> <CENA_BRUTTO>123</CENA_BRUTTO> <WARTOSC_NETTO>100</WARTOSC_NETTO> <STAWKA_VAT>23 %</STAWKA_VAT> Dokumentacja API BizIn ostatnia zmiana 22.01.2015 12
<WARTOSC_VAT>23</WARTOSC_VAT> <WARTOSC_BRUTTO>123</WARTOSC_BRUTTO> </POZYCJA_1> </POZYCJE> <PODLICZENIE> <WALUTA> <SYMBOL>1</SYMBOL> <SYMBOL_OPIS>PLN</SYMBOL_OPIS> <KURS>1.0000</KURS> <KURS_TYP>1</KURS_TYP> <KURS_DATA>2015-11-20</KURS_DATA> </WALUTA> </PODLICZENIE> </DOKUMENT> </ROOT> 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 22.01.2015 13
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 22.01.2015 14