API – jak wystawić zaliczkę przez Taxxo

Instrukcja w PDF : API - jak wystawic zaliczke przez Taxxo

API – jak wystawić zaliczkę przez Taxxo

Przygotowanie

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

Scenariusz 1: Dodanie zaliczki do istniejącej w Taxxo faktury proforma

Scenariusz opisuje sposób wystawienia przez API faktury zaliczkowej do istniejącej w Taxxo faktury proforma. Wszystkie dane przepisywane są z faktury proforma poza kwotą zaliczki, która musi zostać podana w żądaniu.

Krok 1. Stwórz opis zaliczki w formacie JSON z minimalną wymaganą ilością informacji zgodnie z dokumentacją https://platforma2.taxxo.pl/api/documentation/#!/Invoices/ApiPublicInvoiceAdvancePost

Należy wypełnić (minimalnie):

W sekcji ParentDetails – pole IDParentInvoice – ID Faktury (proformy), do której zostanie wystawiona zaliczka
W sekcji AdvanceDetails – pole TotalAdvanceAmount – wartość tej zaliczki
W sekcji ParentDetails – pole IDParentInvoice – ID Faktury (zaliczki), do której zostanie wystawiona zaliczka
W sekcji AdvanceDetails – pole TotalAdvanceAmount – wartość tej zaliczki (np. 50.000)

Reszta danych zostanie uzupełniona danymi z proformy, do której wystawiana jest zaliczka.

Krok 2. Tak przygotowany obiekt wyślij do metody POST /api/public/invoice/advance wpisując dodatkowo do nagłówka Authorization wartość otrzymanego w sekcji Przygotowanie/Krok2 Tokenu Sesji

Krok 3. Jeżeli operacja przebiegnie prawidłowo w odpowiedzi w sekcji Data znajdzie się ID Faktury Zaliczkowej (wystawionej)

{ "Data": ID_FAKTURY_ZALICZKOWEJ, "Status": 0, "Message": "OK", "ErrorCode": null, "AdditionalData": NUMER_FAKTURY_ZALICZKOWEJ }

Uwaga! Istnieje możliwość zmodyfikowania danych faktury zaliczkowej zarówno nagłówkowych (np. numeru konta bankowego) jak i pozycji (wymaga podania „od nowa” pozycji, która zastąpi listę z poprzedzającej faktury) – wówczas podczas wystawiania faktury należy do żądania API dodać zmieniane sekcje.

Scenariusz 2: Dodanie zaliczki wskazując numer zamówienia, którego nie ma w platformie Taxxo

Uwaga! Istnieje możliwość zmodyfikowania danych faktury zaliczkowej - zarówno danych nagłówkowych (np. numeru konta bankowego) jak i pozycji (co wymaga podania „od nowa” pozycji, które zastąpią poprzednio podane). Aby to zrobić, należy podczas wystawiania faktury do żądania API dodać modyfikowane sekcje.

Należy wypełnić (minimalnie):

W sekcji ParentDetails – pole ParentDocumentNumber – numer zamówienia/umowy/itp.
W sekcji BuyerDetails – pola BuyerName oraz BuyerAddressCity
Dodać jeden element Items z wypełnionym polem ProductName
W sekcji AdvanceDetails – pole TotalAdvanceAmount – wartość tej zaliczki

Reszta danych zostanie uzupełniona wartościami domyślnymi

curl --request POST \ --url https://platforma2.taxxo.pl/api/public/invoice/advance \ --header 'authorization: TOKEN_SESJI' \ --header 'content-type: application/json' \ --data '{ "ParentDetails": { "ParentDocumentNumber ": "ZAM 001/11/2022" }, "BuyerDetails": { "BuyerName": "Moja firma", "BuyerAddressCity": "Wrocław" }, "Items": [ { "ProductName": "Nazwa produktu" } ], "AdvanceDetails": { "TotalAdvanceAmount": 100 }

Krok 3. Jeżeli operacja przebiegnie prawidłowo w odpowiedzi w sekcji Data znajdzie się ID Faktury Zaliczkowej (wystawionej)

{ "Data": ID_FAKTURY_ZALICZKOWEJ, "Status": 0, "Message": "OK", "ErrorCode": null, "AdditionalData": NUMER_FAKTURY_ZALICZKOWEJ }

Scenariusz 3: Dodanie zaliczki do istniejącej w Taxxo faktury zaliczkowej (kolejna wpłata od klienta)

Scenariusz opisuje sposób wystawienia kolejnej faktury zaliczkowej po dokonania kolejnej wpłaty przez klienta. Np. Klient kupuje nieruchomość za 300.000 zł. Pierwsza zaliczka została wystawiona na 100.000 zł, a teraz zakończył się kolejny etap budowy i chcemy, aby klient wpłacił kolejne 50.000 zł.

Należy wypełnić (minimalnie):

Reszta danych zostanie uzupełniona danymi z poprzedniej zaliczki, do której wystawiana jest zaliczka

Krok 3. Jeżeli operacja przebiegnie prawidłowo w odpowiedzi w sekcji Data znajdzie się ID Faktury Zaliczkowej (wystawionej)

{ "Data": ID_FAKTURY_ZALICZKOWEJ, "Status": 0, "Message": "OK", "ErrorCode": null, "AdditionalData": NUMER_FAKTURY_ZALICZKOWEJ }

Scenariusz 4: Wystawienie korekty do zaliczki (korekta do zera, klient zrezygnował)

Scenariusz opisuje wystawienie korekty zaliczki „do zera” w przypadku rezygnacji klienta z zakupu i potrzeby rozliczenia wpłaconej wcześniej zaliczki.

Uwaga! Korekty zmieniające zakres / kwoty przedmiotu zaliczki można realizować wg scenariusza 3 z modyfikacją listy pozycji faktury.

Krok 1. Stwórz opis korekty w formacie JSON z minimalną wymaganą ilością informacji zgodnie z dokumentacją https://platforma2.taxxo.pl/api/documentation/#!/Invoices/ApiPublicInvoiceByInvoiceIdCorrectionToZeroPost

Nieuzupełnione dane zostaną uzupełnione wartościami domyślnymi

Krok 2. Tak przygotowany obiekt wyślij do metody POST /api/public/invoice/{invoiceId}/correctionToZero zastępując {invoiceId} ID Faktury, wpisując dodatkowo do nagłówka Authorization wartość otrzymanego w sekcji Przygotowanie/Krok2 Tokenu Sesji

Krok 3. Jeżeli operacja przebiegnie prawidłowo w odpowiedzi w sekcji Data znajdzie się ID Faktury Korekty (wystawionej)

{ "Data": ID_FAKTURY_KOREKTA, "Status": 0, "Message": "OK", "ErrorCode": null, "AdditionalData": NUMER_FAKTURY_KOREKTA }

Scenariusz 5: Wystawienie faktury końcowej do zaliczki (zakończenie transakcji)

Scenariusz opisuje wystawienie faktury końcowej do zaliczki/zaliczek. Proces ten kończy możliwość wystawiania kolejnych zaliczek. Od tego momentu można wystawiać „standardowe” faktury korygujące do tej faktury.

Uwaga! Istnieje możliwość zmodyfikowania danych faktury końcowej - zarówno danych nagłówkowych (np. numeru konta bankowego) jak i pozycji (co wymaga podania „od nowa” pozycji, które zastąpią poprzednio podane). Aby to zrobić, należy podczas wystawiania faktury do żądania API dodać modyfikowane sekcje.

Krok 1. Stwórz opis faktury w formacie JSON z minimalną wymaga ilością informacji zgodnie z dokumentacją https://platforma2.taxxo.pl/api/documentation/#!/Invoices/ApiPublicInvoicePost

Aby wystawić fakturę końcową do zaliczki:

W sekcji General – pole Type musi być [Invoice]
W sekcji ParentDetails – pole IDParentInvoice – ID Faktury (zaliczki), do której zostanie wystawiona faktura końcowa

Krok 2. Tak przygotowany obiekt wyślij do metody POST /api/public/invoice wpisując dodatkowo do nagłówka Authorization wartość otrzymanego w sekcji Przygotowanie/Krok2 Tokenu Sesji

curl --request POST \ -url https://platforma2.taxxo.pl/api/public/invoice \ --header 'authorization: TOKEN_SESJI \ --header 'Content-Type: application/json' \ --data '{ "General": { "Type": "Invoice" }, "ParentDetails": { "IDParentInvoice": ID_FAKTURY_ZALICZKOWEJ } }'

Krok 3. Jeżeli operacja przebiegnie prawidłowo w odpowiedzi w sekcji Data znajdzie się ID Faktury Końcowej

{ "Data": ID_FAKTURY_KONCOWEJ, "Status": 0, "Message": "OK", "ErrorCode": null, "AdditionalData": NUMER_FAKTURY_KONCOWEJ }

Pytania i sugestię dotyczące API – api@taxxo.pl

Still puzzling over something?

API - Proces autoryzacji na przykładzie pobrania listy faktur sprzedaży z e-Faktury

Webhooki – Jak rozpocząć integrację przy użyciu wywołań zwrotnych?

API - Jak wystawić fakturę przez Taxxo i pobrać ją w postaci PDF

Integracja księgowa - z jakimi systemami księgowymi współpracuje Taxxo?

Jak połączyć Taxxo z systemem e-commerce - np. Shopify, WooCommerce, BaseLinker lub innym?