W Taxxo można wystawić fakturę „ręcznie” z poziomu Platformy Taxxo, można użyć funkcji fakturowania cyklicznego, która automatycznie wystawi fakturę na podstawie zadanego schematu. Inną możliwością jest dodanie faktury za pomocą API.
Jak dodać najprostszą fakturę do Taxxo za pomocą API?
Krok 1. Jeżeli nie posiadasz jeszcze Klucza API – zapoznaj się z artykułem API - Jak rozpocząć integrację z Taxxo wykorzystując API?
Krok 2. Wykonaj logowanie do Taxxo API za pomocą metody POST /api/public/authenticate przy użycia Klucza API i uzyskaj Token Sesji – szczegółowy przykład w artykule API - Proces autoryzacji na przykładzie pobrania listy faktur sprzedaży z e-Faktury
Krok 3. Stwórz opis faktury w formacie JSON z minimalną wymaga ilością informacji zgodnie z dokumentacją https://platforma2.taxxo.pl/api/documentation/#!/Invoices/ApiPublicInvoicePost
Należy wypełnić (minimalnie):
- W sekcji BuyerDetails – pola BuyerName oraz BuyerAddressCity
- Dodać jeden element Items z wypełnionym polem ProductName
Reszta danych zostanie uzupełniona wartościami domyślnymi.
Krok 4. Tak przygotowany obiekt wyślij do metody POST /api/public/invoice wpisując dodatkowo to nagłówka Authorization wartości otrzymanego w kroku drugim Token Sesji.
curl --request POST \
--url https://platforma2.taxxo.pl/api/public/invoice \
--header 'authorization: TOKEN_SESJI' \
--header 'content-type: application/json' \
--data '{
"BuyerDetails":
{
"BuyerName":"Moja firma",
"BuyerAddressCity":"Wrocław"
},
"Items":[
{
"ProductName":"Nazwa produktu"
}
]
}
Krok 5. Jeżeli operacja przebiegnie prawidłowo w odpowiedzi w sekcji Data znajdzie się ID Faktury
{
"Data": ID_FAKTURY,
"Status": 0,
"Message": "OK",
"ErrorCode": null
}
Jak pobrać dane nowej faktury oraz jej obraz PDF?
Krok 6. Jeżeli chcemy sprawdzić jakimi wartościami domyślnymi została wypełniona nasza przykładowa faktura – możemy wywołać metodę GET /api/public/invoice/{invoiceId} zastępując {invoiceId} otrzymanym w kroku piątym ID Faktury (pamiętając o wypełnieniu nagłówka Authorization posiadanym Tokenem Sesji)
curl --request GET \
--url https://platforma2.taxxo.pl/api/public/invoice/30241 \
--header 'authorization: 3_0502a4d8-2800-4ef1-a6a3-ff3644379cfc_444327365' \
--header 'content-type: application/json'
W odpowiedzi w sekcji Data otrzymamy dane dodanej w kroku piątym faktury – np.
{
"Data": {
"InvoiceId": 30241,
"General": {
"SeriesCode": null,
"Type": 0,
"Number": "FV 00125/05/2020",
"NumberPostscript": "",
"MadeOutDate": "2020-05-25",
"SellingDate": "2020-05-25",
"ItemsAmountCalculateType": 0,
"Notes": "coooos",
"MadeOutBy": "",
"ReceivedBy": null,
"AutoCreateInvoiceToPaidProform": null
},
Krok 7. Aby pobrać fakturę w postaci PDF należy użyć metody GET /api/public/invoice/{invoiceId}/pdf zastępując {invoiceId} otrzymanym w kroku piątym ID Faktury
W odpowiedzi w sekcji Data trzymamy plik PDF w postaci Base64. Dla celów testowych aby zamienić to na binarną postać pliku można użyć https://www.base64decode.org/
Dane faktury – formatowanie, znaczenie, uwagi
Pełny opis danych faktury znajduje się pod adresem https://platforma2.taxxo.pl/api/documentation/#!/Invoices/ApiPublicInvoicePost
Często pojawiające się kwestie przy integracji fakturowania z Taxxo przez API:
- Jeżeli chcesz użyć wartości domyślnej dla danego polu – po prostu nie podawaj go w żądaniu
- Pustych sekcji nie trzeba dodawać
- Wartość pusta (null) nie jest tożsama z 0 (zero) – np. w polu Discount
- Kwoty są wypełniane z kropkami jako separatorami dziesiętnymi
- Data/czas w JSON musi mieć odpowiedni format zgodny z opisem https://stackoverflow.com/questions/10286204/the-right-json-date-format
- Pole ProductId – to ID produktu w Taxxo – (nie ID w Państwa systemie!)– Jeżeli go używamy podawanie nazwy produktu nie ma sensu.
- Różnica między polem PaidAmount i PaidAmountForNow – pole PaidAmount określa zapłaconą wartość w momencie wystawiania faktury (ta kwota jest drukowana na fakturze jako „Zapłacono”). PaidAmountForNow – jest bieżącym statusem rozliczenia faktury (nie drukowany na fakturze ale widocznym na Platformie Taxxo w informacji ile jest zapłacone do dziś / ile pozostaje jeszcze do zapłaty)
- Dzięki sekcji PrintSettings można sterować parametrami wyglądu wydruku TEJ faktury (np. przed pobraniem jej w postaci PDF w kroku szóstym). Jeżeli faktura zostanie zmodyfikowana „ręcznie” na Platformie Taxxo, do jej ponownego generowania zostaną użyte globalne ustawienia klienta (a nie te podane podczas żądania API)
Pytania i sugestię dotyczące API – api@taxxo.pl