Dokumentacja API BizIn

Transkrypt

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://system.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 20.12.2016
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.
2
Dostępne akcje
apiTestConnection
addInvoice
removeInvoice
getInvoice
getListInvoices
getPurchaseInvoice
getListPurchaseInvoices
addPurchaseInvoice
getStocks
getClient
getListBanks
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
Pobieranie listy aktywnych banków zarejestrowanych w podmiocie
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>
<api_key>".$apiKey."</api_key>
<action>apiTestConnection</action>
</ROOT>";
}
{ ## pobieranie dokumentu przychodowego
3
$xmlGetInvoice = "<ROOT>
<action>getInvoice</action>
<params>
<dokument_id>2110</dokument_id>
</params>
</ROOT>";
}
{ ## pobieranie listy dokumentów przychodowych
$xmlGetListInvoices = "<ROOT>
<action>getListInvoices</action>
<params>
<listInvoicesDataStart>".date("Y-m-d", strtotime ("-12 month"))."</listInvoicesDataStart>
<listInvoicesDataStop>".date("Y-m-d")."</listInvoicesDataStop>
<kontrahentApiId></kontrahentApiId>
</params>
</ROOT>";
}
{ ## przeœlij dokument do kontrahenta
$xmlSendInvoiceInfo = "<ROOT>
<action>sendInvoiceInfo</action>
<params>
</params>
</ROOT>";
}
{ ## usuwanie dokumentu przychodowego
$xmlRemoveInvoice = "<ROOT>
<action>removeInvoice</action>
<params>
<dokument_id>www2263</dokument_id>
</params>
</ROOT>";
}
{ ## pobieranie dokumentu kosztowego
$xmlGetPurchaseInvoice = "<ROOT>
<action>getPurchaseInvoice</action>
<params>
</params>
</ROOT>";
}
{ ## pobieranie listy dokumentów kosztowych
$xmlGetListPurchaseInvoices = "<ROOT>
<action>getListPurchaseInvoices</action>
4
<params>
<listInvoicesDataStart>".date("Y-m-d", strtotime ("-12 month"))."</listInvoicesDataStart>
<listInvoicesDataStop>".date("Y-m-d")."</listInvoicesDataStop>
</params>
</ROOT>";
}
{ ## pobieranie towaru wybranego magazynu
$xmlGetStocks = "<ROOT>
<action>getStocks</action>
<params>
<miejsceApiId>1</miejsceApiId>
<kategoriaTowaruApiId></kategoriaTowaruApiId>
<numerPN>PN5436286A</numerPN>
<magazynApiId></magazynApiId>
</params>
</ROOT>";
}
{ ## pobierz dane klienta - wyszukiwanie po pierwszym znalezionym obiekcie <params>
$xmlGetClient= "<ROOT>
<action>getClient</action>
<params>
<kontrahentApiId></kontrahentApiId>
<kontrahentNIP>657-28-39-511</kontrahentNIP>
<kontrahentPESEL></kontrahentPESEL>
</params>
</ROOT>";
}
{ ## BizIn Fiskalizator - lista dokumentów do zafiskalizowania
$xmlListBanks = "<ROOT>
<action>getListBanks</action>
</ROOT>";
}
##
/*
$xmlApiTestConnection;
$xmlGetInvoice;
$xmlRemoveInvoice;
$xmlSendInvoiceInfo;
$xmlGetListInvoices;
$xmlGetPurchaseInvoice;
$xmlGetListPurchaseInvoices;
$xmlGetStocks;
$xmlData= $xmlGetClient;
$xmlData= $xmlListBanks;
*/
$data = array('XML' => $xmlRemoveInvoice);
$handle = curl_init();
5
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 dokumentów. Poniżej przykłady (z opisami pól) tworzenia dokumentu proforma oraz
dokumentu powiązanego.
6
Wystawianie dokumentu – proforma
<?xml version="1.0"?>
<ROOT>
<api_key>klucz API</api_key>
<action>addInvoice</action>
<transactionID>f8J949AD2SSYySqf</transactionID>
<params>
<dokument_typ>5</dokument_typ>
<dokument_typ_procedury_marza>0</dokument_typ_procedury_marza>
<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>
<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>
</pozycja_3>
7
</pozycje>
</params>
</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 (jeśli puste lub niepoprawne ustawia domyślne)
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 trzeba
podawać reszty danych. Podanie ich spowoduje aktualizacją kontrahenta
4.14.2
nazwa
nazwa kontrahenta
4.14.3
imię
imię i nazwisko kontrahenta
4.14.4
kod
kod pocztowy, np. 25-314
4.14.5
miejscowosc
miejscowość, np. Kielce
4.14.6
ulica
ulica np. Pawia
4.14.7
nr_domu
numer domu, np. 4/39
4.14.8
nip
numer nip
4.14.9
pesel
numer pesel
4.14.10
uwagi
uwagi
4.14.11
bank_nazwa
nazwa banku (np. ING Bank Śląski)
4.14.12
bank_nr_konta
numer konta bankowego
4.15
pozycje
kontener zawierający pozycje faktury
4.15.1
pozycja_(nr)
pozycja numer (nr)
8
typ
Typ pozycji:
1 - id_magazyn,
2 - id_uslugi,
3 - dowolna pozycja
4.15.1.1
typ = 1
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
4.15.1.1
typ = 3
4.15.1.2
nazwa
nazwa usługi / produktu
4.15.1.3
ilosc
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.
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>
<params>
<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>
</params>
</ROOT>
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>
11
<action>addPurchaseInvoice</action>
<params>
<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>[email protected]</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>[email protected]</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>
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>
</params>
</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.
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://system.bizin.pl/apiBizIn.html?idP=NUMER_IDP&debug=yes
14

Dokumentacja API BizIn

Transkrypt

Podobne dokumenty

Programowanie na platformę Android

Mobile + Kontekst Otoczenia

Dr Piotr Kotlarz Wydział Technologiczny Instytut Informatyki i

Tytuł szkolenia: HTML5 API dla programistów JavaScript

broszura

Sylwester Zakopane API 1 DW HB 6 dni (4389/2330)

Pracownik ds. Logistyki i Wsparcia Sprzedaży