Dokumentacja API BizIn

Transkrypt

1 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 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: 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

2 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

3 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 = " $apikey= 'ggen22tfhgi2jmq3k4n1tco2z1up12i7'; { ## pobieranie dokumentu przychodowego $xmlgetinvoice = "<ROOT> <api_key>".$apikey."</api_key> <action>getinvoice</action> <dokument_id>2110</dokument_id> </ROOT>"; } { ## pobieranie listy dokumentów przychodowych $xmlgetlistinvoices = "<ROOT> <api_key>".$apikey."</api_key> <action>getlistinvoices</action> <listinvoicesdatastart>".date("y-m-d", strtotime ("-12 month"))."</listinvoicesdatastart> <listinvoicesdatastop>".date("y-m-d")."</listinvoicesdatastop> </ROOT>"; } Dokumentacja API BizIn ostatnia zmiana

4 { ## pobieranie dokumentu kosztowego $xmlgetpurchaseinvoice = "<ROOT> <api_key>".$apikey."</api_key> <action>getpurchaseinvoice</action> <dokument_id>78</dokument_id> </ROOT>"; } { ## pobieranie listy dokumentów kosztowych $xmlgetlistpurchaseinvoices = "<ROOT> <api_key>".$apikey."</api_key> <action>getlistpurchaseinvoices</action> <listinvoicesdatastart>".date("y-m-d", strtotime ("-12 month"))."</listinvoicesdatastart> <listinvoicesdatastop>".date("y-m-d")."</listinvoicesdatastop> </ROOT>"; } { ## pobieranie towaru wybranego magazynu $xmlgetstocks = "<ROOT> <api_key>".$apikey."</api_key> <action>getstocks</action> <miejsceapiid>1</miejsceapiid> <kategoriatowaruapiid>0</kategoriatowaruapiid> </ROOT>"; } $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

5 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> </dokument_data_wystawienia> <dokument_data_sprzedazy> </dokument_data_sprzedazy> <dokument_typplatnosciapiid>14</dokument_typplatnosciapiid> <dokument_data_splaty> </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> </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> </nip> <pesel></pesel> <uwagi></uwagi> <bank_nazwa>mbank</bank_nazwa> <bank_nr_konta> </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

6 </pozycja_3> </pozycje> </ROOT> 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 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 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

7 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 = ilosc ilość towaru / usługi typ = 2 36 uslugiapiid ID usługi z systemu BizIn. Jeśli typ = 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

8 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> </dokument_data_splaty> <dokument_bankapiid>2</dokument_bankapiid> <dokument_dodatkowy_opis>.,</dokument_dodatkowy_opis> <zrodlo_status>0</zrodlo_status> <zrodlo_datasplaty> </zrodlo_datasplaty> <kontrahent> <kontrahentapiid>263</kontrahentapiid> <kod_kontrahenta> </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> </nip> <pesel></pesel> <uwagi></uwagi> <bank_nazwa></bank_nazwa> <bank_nr_konta></bank_nr_konta> </kontrahent> </ROOT> Dokumentacja API BizIn ostatnia zmiana

9 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 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 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

10 <ROOT> <api_key>wfn6mxu9smzmr37jnthgpqn9uo1araqd</api_key> <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> </DATA_WYSTAWIENIA> <DATA_DOSTAWY> </DATA_DOSTAWY> <SPRZEDAWCA> <nazwa>biuro Informacyjne</nazwa> <kod>00-950</kod> <miejsc>warszawa</miejsc> <ul>ul. Woronicza</ul> <nr>17</nr> <nip> </nip> <kraj>polska</kraj> <dodatkowe_info></dodatkowe_info> <tel> </tel> <www>biuroinformacyjne.to</www> <nazwa_baner></nazwa_baner> <GLN> </GLN> <NAZWA_BANKU></NAZWA_BANKU> <NUMER_KONTA_BANKOWEGO></NUMER_KONTA_BANKOWEGO> </SPRZEDAWCA> <PLATNIK> <NIP>GB </NIP> <GLN>GB </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> < >p.czekaj@pcet.pl</ > <UWAGI>trelemele</UWAGI> <DATA_UTWORZENIA></DATA_UTWORZENIA> </DANE_UZUPELNIAJACE> </PLATNIK> <PLATNOSC> <FORMA>7</FORMA> <TERMIN> </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> Dokumentacja API BizIn ostatnia zmiana

11 <WARTOSC_NETTO>100</WARTOSC_NETTO> <STAWKA_VAT>23 %</STAWKA_VAT> <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> </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

12 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 Dokumentacja API BizIn ostatnia zmiana