API – Faktura zaliczkowa (wersja archiwalna 1.5) - Baza Wiedzy programu Comarch Betterfly

POBIERANIE FAKTUR ZALICZKOWYCH

Pobieranie faktur zaliczkowych: [GET] https://app.comarchbetterfly.pl/api2/public/v1.5/advanceInvoices

Opis struktury JSON odpowiedzi:

Parametr	Opis
PaymentStatus	Status płatności (0 – niezapłacona, 1 – zapłacona całkowicie, 2 – zapłacona częściowo)
OSSProcedureCountryCode	Kod kraju dla procedury OSS – do pobrania ze słownika kodów krajów UE: API – Obsługa procedury OSS
IsOSSProcedure	Oznaczenie procedury OSS (true / false)
KSeFData	Dane dokumentu związane z KSeF
TaskStatus	Status przetwarzania dokumentu 0 – zadanie nigdy nie było uruchomione na tym dokumencie (domyślny status dla wszystkich dokumentów) 1 – zadanie zostało uruchomione 2 – zadanie jest w trakcie 3 – trwa wysyłanie do KSeF 4 – trwa pobieranie UPO 5 – trwa wysyłanie dokumentu za pomocą IWD 6 – zadanie zostało przerwane 7 – zadanie się zakończyło 8 – trwa księgowanie 9 – zadanie nie zostało uruchomione ze względu na niespełnienie warunków początkowych
InvoiceStatus	Status dokumentu wysłanego do Krajowego Systemu e-Faktur 0 – nie wysłano, 1 – wysłano (można teraz pobrać UPO) 2 – odrzucono 3 – pobrano UPO 4 – tryb awaryjny
DocumentNumber	Numer dokumentu KSeF
UPOReceiveDate	Data odebrania UPO
PurchasingPartyId	Id kontrahenta na dokumencie
ReceivingPartyId	Id odbiorcy na dokumencie
PaymentTypeId	Id formy płatności – do pobrania z zasobu API Formy płatności
PaymentType	Typ płatności (0 – płatność gotówką, 1- płatność na konto, 2 – płatność kartą)
PaymentDeadline	Termin płatności
BankAccountId	Id rachunku bankowego
SalesDate	Data sprzedaży
InvoiceType	Algorytm obliczania (0 – od netto / 1 – od brutto)
CurrencyCode	Symbol waluty dokumentu
CurrencyRateType	Typ kursu: 0 – Średni kurs NBP, 1 – kurs ręczny
CurrencyRateDate	Data kursu waluty
CurrencyConverter	Mianownik kursu walutowego
CurrencyRate	Licznik kursu walutowego
Items	Pozycje dokumentu
CurrencyAdvance	Wartość zaliczki
ProductId	Id produktu
Quantity	Ilość
ProductCurrencyPrice	Cena sprzedaży, po rabacie, w walucie dokumentu: jeżeli InvoiceType = 0 – Cena sprzedaży netto jeżeli InvoiceType = 1 – Cena sprzedaży brutto
ProductPrice	Cena sprzedaży, po rabacie jeżeli InvoiceType = 0 – Cena sprzedaży netto, jeżeli InvoiceType = 1 – Cena sprzedaży brutto
ProductDescription	Opis produktu
UnitOfMeasurement	Jednostka miary
VatRateId	Id stawki VAT – do pobrania ze słownika unijnych stawek VAT: API – Obsługa procedury OSS
Id	Id pozycji dokumentu w bazie danych
Description	Opis dokumentu
IssueDate	Data wystawienia dokumentu
Number	Numer dokumentu
Status	Status dokumentu (0 – dokument w buforze / 1 – dokument zatwierdzony na stałe)
Id	Id dokumentu w bazie danych

Przykładowa odpowiedź JSON:

[code_snippet id=62]

Możliwe jest także pobranie danych dotyczących określonego dokumentu faktury zaliczkowej:

[GET] https://app.comarchbetterfly.pl/api2/public/v1.5/advanceInvoices/XXX (gdzie XXX to id faktury zaliczkowej w bazie danych)

Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.5/advanceInvoices/2901096

Dostępna jest możliwość pobrania dokumentu o konkretnym numerze:

[GET] https://app.comarchbetterfly.pl/api2/public/v1.5/advanceInvoices/invoices?number={number}

Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.5/advanceInvoices?number=FAZAL/2022/8

Wskazówka

W API obsługiwane są faktury zaliczkowe w walucie PLN. W walucie obcej dostępne jest tylko pobieranie faktur zaliczkowych. Nie są obsługiwane dokumenty anulowane. Korekty są obsługiwane w innych metodach.

DODAWANIE NOWEGO DOKUMENTU FAKTURY ZALICZKOWEJ

Dodawanie faktury zaliczkowej: [POST] https://app.comarchbetterfly.pl/api2/public/v1.5/advanceInvoices

Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
PaymentStatus	Status płatności (0 – niezapłacona, 1 – zapłacona całkowicie, 2 – zapłacona częściowo)	Nie¹
OSSProcedureCountryCode	Kod kraju dla procedury OSS	Nie⁶
IsOSSProcedure	Oznaczenie procedury OSS (true / false)	Nie
PurchasingPartyId	Id kontrahenta na dokumencie	Tak
ReceivingPartyId	Id odbiorcy na dokumencie	Nie
PaymentTypeId	Id formy płatności	Tak
BankAccountId	Id rachunku bankowego	Nie
SalesDate	Data sprzedaży	Nie²
InvoiceType	Algorytm obliczania (0 – od netto / 1 – od brutto)	Nie³
Items	Pozycje dokumentu	Nie⁴
CurrencyAdvance	Wartość zaliczki	Nie⁷
ProductId	Id produktu	Tak
Quantity	Ilość	Tak
ProductCurrencyPrice	Cena sprzedaży	Tak
ProductDescription	Opis produktu	Nie
VatRateId	Id stawki VAT – do pobrania ze słownika unijnych stawek VAT tutaj, pole jest powiązane z procedurą OSS	Nie⁶
Description	Opis dokumentu	Nie
IssueDate	Data wystawienia dokumentu	Nie⁵

1) Status zapłaty podczas dodawania faktury zaliczkowej może przyjmować jedynie wartość: 0 – niezapłacona lub wartość: 1 – zapłacona całkowicie. Status 2 – zapłacona częściowo jest możliwy do odnotowania jedynie z poziomu aplikacji Comarch Betterfly. W przypadku braku oznaczenia statusu płatności, domyślnie dokument zostanie oznaczony jako brak zapłaty (0).

2) W przypadku braku daty w parametrach, ustawiana będzie data bieżąca.

3) W przypadku braku wartości w tym polu, zostanie zastosowany algorytm od netto.

4) Można wystawić dokument bez dodanych pozycji. Jeśli jednak Użytkownik zdecyduje się użyć sekcji „Items”, wówczas należy wypełnić pola obowiązkowe.

5) W przypadku braku daty w parametrach, ustawiana będzie data bieżąca.

6) Parametry należy określić w przypadku wskazania kontrahenta o statusie „Procedura OSS”.

7) W przypadku braku uzupełnienia tego pola dokument zostanie wystawiony z zerową zaliczką

Przykładowe zapytanie JSON:

[code_snippet id=38]

W odpowiedzi zostanie wysłane ID dodanego dokumentu faktury zaliczkowej.

DODAWANIE POWIĄZANEJ FAKTURY ZALICZKOWEJ

Dodawanie powiązanej faktury zaliczkowej: [POST] https://app.comarchbetterfly.pl/api2/public/v1.5/advanceInvoices?advanceId={id}

Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.5/advanceInvoices?advanceId=3006043

W odpowiedzi zostanie wysłane ID nowej powiązanej faktury zaliczkowej. Faktura będzie zapisana do bufora oraz wartość zaliczki będzie wynosić zero PLN.

W przypadku podania w zapytaniu błędnego id, w odpowiedzi JSON, mogą pojawić się następujące komunikaty:

ErrorCode 1 – kontrahent jest zanonimizowany
ErrorCode 2 – dokument nie jest fakturą zaliczkową
ErrorCode 3 – dokument posiada korektę w buforze
ErrorCode 4 – dokument jest anulowany
ErrorCode 5 – dokument jest w buforze
ErrorCode 6 – dokument jest korektą faktury zaliczkowej
ErrorCode 7 – dokument już został przekształcony do finalnej
ErrorCode 8 – dokument nie jest możliwy do przekształcenia (wystawiony przed 2019 rokiem)
ErrorCode 9 – dokument jest fakturą finalną

Przykładowa odpowiedź JSON:

[code_snippet id=39]

EDYCJA FAKTURY ZALICZKOWEJ

Edycja faktury sprzedaży: [PUT] https://app.comarchbetterfly.pl/api2/public/v1.5/advanceInvoices

Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
PaymentStatus	Status płatności (0 – niezapłacona, 1 – zapłacona całkowicie, 2 – zapłacona częściowo)	Nie
OSSProcedureCountryCode	Kod kraju dla procedury VAT OSS – do pobrania ze słownika kodów krajów UE tutaj	Nie
IsOSSProcedure	Oznaczenie procedury VAT OSS (true / false)	Nie
PurchasingPartyId	Id kontrahenta na dokumencie	Tak
ReceivingPartyId	Id odbiorcy na dokumencie	Nie
PaymentTypeId	Id formy płatności	Tak
BankAccountId	Id rachunku bankowego	Nie
SalesDate	Data sprzedaży	Nie
InvoiceType	Algorytm obliczania (0 – od netto / 1 – od brutto)	Nie²
Items	Pozycje dokumentu	Nie¹
CurrencyAdvance	Wartość zaliczki	Nie²
ProductId	Id produktu	Tak
Quantity	Ilość	Tak
ProductCurrencyPrice	Cena sprzedaży	Tak
ProductDescription	Opis produktu	Nie
VatRateId	Id stawki VAT – do pobrania ze słownika stawek VAT tutaj, pole jest powiązane z procedurą VAT OSS	Nie
Id	Id pozycji dokumentu w bazie danych	Nie³
Description	Opis dokumentu	Nie
IssueDate	Data wystawienia dokumentu	Nie
Id	Id dokumentu w bazie danych	Tak

1) Jeśli edytowana faktura zawiera pozycje.

2) W przypadku braku wartości w tym polu podstawiona będzie wartość domyślna dla dokumentu

3) W przypadku pominięcia numeru Id pozycji podczas operacji edycji, zostanie dodana kolejna pozycja do dokumentu ze wskazanymi parametrami.

Uwaga

W przypadku pominięcia parametrów nieobowiązkowych, zostaną one nadpisane domyślnymi lub pustymi wartościami.

Uwaga

Poprzez Comarch Betterfly API można edytować jednie faktury zapisane do bufora.

Wskazówka

Dedykowany schemat numeracji dla faktur zaliczkowych można utworzyć w aplikacji. W przypadku jego braku dokumenty będą dodawane ze schematem faktur sprzedaży.

W odpowiedzi zostanie wysłany status i ewentualnie JSON odpowiedzi.

Przykładowe zapytanie JSON (zmiana kwoty zaliczki na fakturze o Id=2994705):

[code_snippet id=40]

Przykładowa odpowiedź JSON – status 204 No Content – operacja zakończona powodzeniem.

ZATWIERDZANIE FAKTUR ZALICZKOWYCH

Zatwierdzanie faktur zaliczkowych: [PUT] https://app.comarchbetterfly.pl/api2/public/v1.5/advanceInvoices/confirm

W odpowiedzi zostanie wysłany status i JSON odpowiedzi.

Wskazówka

Metoda zatwierdza jedynie faktury zaliczkowe. Korekty do tych dokumentów należy zatwierdzić w aplikacji.

[code_snippet id=41]

USUWANIE FAKTURY ZALICZKOWEJ

Usuwanie faktury sprzedaży: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.5/advanceInvoices/XXX (gdzie XXX to Id dokumentu faktury zaliczkowej w bazie danych)

Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.5/advanceInvoices/2901095

Przykładowa odpowiedź JSON – status 204 No Content – operacja zakończona powodzeniem.

Wskazówka

Opcja usuwania faktury zaliczkowej jest dostępna tylko dla dokumentów będących w buforze.

Aby dowiedzieć się jak pobrać poprzez API wydruk faktury proforma: API – Wydruki.