W Taxxo możesz wystawić fakturę bezpośrednio przez dostępne API. Jednak, jeżeli posiadasz własny portal dla klientów i chciałbyś umożliwić im dostęp do faktur – Taxxo API da Ci możliwość przygotowania samoobsługowego portalu, który odciąży obsługę klienta umożliwiając m.in.:
- Dostęp do listy faktur wystawionej na rzecz klienta 24h/7dni w tygodniu
- Dane do płatności znajdujące się na fakturze (termin płatności, forma, numer konta itp.)
- Informację o statusie rozliczenia faktury
- Możliwość pobrania faktury w postaci PDF
- Możliwość automatycznego wystawienia duplikatu do faktury w postaci PDF
Jak zacząć budowę własnego portalu samoobsługowego?
Krok 1. Upewnij się, że masz aktywny dostęp do API w Taxxo - o tym jak rozpocząć integrację przeczytasz tutaj API - Jak rozpocząć integrację z Taxxo wykorzystując API?
Krok 2. Niezależnie od tego, w jakim języku będzie powstawał Twój portal (PHP, NodeJS, .NET, Java, itp.) – zaoszczędzisz sporo czasu generujące kodu klienckiego do Taxxo API na bazie definicji Swagger – więcej tutaj API - Jak automatycznie wygenerować kod kliencki?
Krok 3. Mimo, że faktur nie musisz dodawać przez API (równie dobrze mogą być dodawane klasycznie przez Platformę Taxxo) – dobrze zapoznać się z modelem faktury, sposobem kodowania PDF jako Base64 tutaj API - Jak wystawić fakturę przez Taxxo i pobrać ją w postaci PDF
Pobieranie listy faktur klienta
Mamy możliwość pobrania listy faktur na dwa sposoby:
- po numerze NIP klienta
- po wewnętrznym identyfikatorze klienta w Taxxo (opcja właściwa w przypadku synchronizacji słownika klientów w Państwa Portalu ze słownikiem klientów w Taxxo)
Aby pobrać faktury po numerze NIP – używamy metody GET /api/public/invoices/byContractorTaxId/{contractorTaxId} zmieniając {contractorTaxId} na numer NIP (bez spacji i znaków specjalnych)
curl <br>
--request GET \
--url https://platforma2.taxxo.pl/api/public/invoices/byContractorTaxId/8992630753 \
--header 'authorization: Klucz Sesji' \
--header 'content-type: application/json'
Aby pobrać faktury po ID używamy metody GET /api/public/invoices/byContractorId/{contractorId} zastępując {contractorId} na identyfikator klienta z Taxxo dostępny m.in. w metodzie GET /api/public/invoices/contractors
curl
--request GET
--url https://platforma2.taxxo.pl/api/public/invoices/byContractorId/21 \
--header 'authorization: 3_1602a4d8-2800-4ef1-a6a3-ff3644379cfc_444327365' \
--header 'content-type: application/json'
Należy zwrócić uwagę, że obie metody pozwalają opcjonalnie wykluczyć dokumenty typu faktura proforma – aby nie pojawiły się w wynikach.
Pełny opis metod oraz zwracanych wyników można odnaleźć pod adresem https://platforma2.taxxo.pl/api/documentation
Niezależnie od użytej metody w sekcji Data odpowiedzi w formacie JSON dostaniemy pełną listy wszystkich faktur danego klienta z potrzebnymi danymi do prezentacji listy faktur m.in.:
- InvoiceId – wewnętrzny identyfikator faktury (m.in. do pobrania PDF)
- General \ Number – numer faktury
- General \ MadeOutDate – data wystawienia faktury
- General \ SellingDate – data sprzedaży / zakończenia dostawy lub usługi
- BuyerDetails \ Name – nazwa klienta na fakturze
- RecieverDetails \ Name – nazwa odbiorcy na fakturze – jeżeli występuje
- Summary \ TotalNet – łączna wartość netto faktury (w walucie faktury)
- Summary \ TotalGross – łączna wartość brutto faktury (w walucie faktury)
- CurrencyDetails \ Currency – waluta dokumentu
- PaymentDetails\ PaymentForm – forma płatności
- PaymentDetails \ BankAccount \ BankAccountNumber – numer konta bankowego do przelewu
- PaymentDetails \ PaymentDeadline – termin płatności
- PaymentDetails \ PaidAmountForNow – pole określające, ile na dzień dzisiejszy z danej faktury jest już rozliczone (w walucie dokumentu). Jeżeli wartość jest równa z TotalGross – oznacza że dokument jest w całości rozliczony. Jeżeli wartość jest równa zero – oznacza że faktura nie jest rozliczona. Częściowe rozliczenie to wartość większa od zera a mniejszej od TotalGross
Pobieranie obrazu PDF wybranej faktury
Szczegółowy opis pobierania faktury do PDF znajduje się w opisie kroku 6 tutaj API - Jak wystawić fakturę przez Taxxo i pobrać ją w postaci PDF
W skrócie - należy wykonać metodę GET /api/public/invoice/{invoiceId}/pdf zamieniając {invoiceId} na identyfikator faktury pobrany w poprzednim kroku w liscie faktur jako pole InvoiceId.
Wynik otrzymany w sekcji Data będzie plikiem PDF zakodowanym w formacie Base64.
curl
--request GET \
--url https://platforma2.taxxo.pl/api/public/invoice/17/pdf \
--header 'authorization: 3_1622a4d8-2800-4ef1-a6a3-ff3644379cfc_444327365' \
--header 'content-type: application/json'
Wystawianie duplikatu faktury i pobieranie go w postaci PDF
Jeżeli klient potrzebuje duplikatu faktury (jest wymagany aby po upływie pewnego okresu od wystawienia faktury móc go zaksięgować w koszty) można wykorzystać gotową metodę
GET /api/public/invoice/{invoiceId}/duplicatePdf przekazując identyfiaktor faktury oraz obowiązkowo datę na którą ma być wystawiony duplikat w polu duplicateDate.
Wynik otrzymany w sekcji Data, podobnie jak przy pobieraniu zwykłej faktury, będzie plikiem PDF zakodowanym w formacie Base64.
curl
--request GET \
--url https://platforma2.taxxo.pl/api/public/invoice/17/pdf?duplicateDate=2020-12-31 \
--header 'authorization: 3_1623a4d8-2800-4ef1-a6a3-ff3644379cfc_444327365' \
--header 'content-type: application/json'
Pełen opis metody znajduje się pod adresem
https://platforma2.taxxo.pl/api/documentation/#!/Invoices/ApiPublicInvoiceByInvoiceIdDuplicatePdfGet
Podsumowanie
Warto zwrócić uwagę, że Platforma Taxxo może być chwilowo niedostępna podczas procesu aktualizacji oprogramowania – wówczas proces autoryzacji (pozyskiwania tokenu sesji) zwróci odpowiednią informację i należy ją odpowiedni zakomunikować użytkownikowi.
Istnieje możliwość weryfikacji stanu działania Taxxo za pomocą specjalnie przygotowanej metody GET /api/public/status.
Wszelkie prace staramy się przeprowadzać raz w miesiącu poza godzinami wzmożonej pracy użytkowników – ale przy dostępie 24/7 trzeba mieć na uwadze taki scenariusz.
Jeżeli w czasie implementacji pojawiłby się pytania lub sugestię dotyczące Taxxo API zapraszamy do kontaktu na api@taxxo.pl