API – Faktura sprzedaży (wersja archiwalna 1.3) - Baza Wiedzy programu Comarch Betterfly

Wskazówka

Poniższe metody dotyczą faktur sprzedaży i faktur finalnych

POBIERANIE FAKTUR SPRZEDAŻY

Pobieranie faktur sprzedaży: [GET] https://app.comarchbetterfly.pl/api2/public/v1.3/invoices

Opis struktury JSON odpowiedzi:

Parametr	Opis
$id	Numer porządkowy w ramach odpowiedzi JSON
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 tutaj
IsOSSProcedure	Oznaczenie procedury OSS (true / false)
IsFinal	Oznaczenie typu faktury (true / false)
PurchasingPartyId	Id nabywcy na dokumencie
PurchasingParty	Dane nabywcy na dokumencie (CustomerType: 0 – osoba fizyczna, 1 – podmiot gospodarczy)
ReceivingPartyId	Id odbiorcy na dokumencie
ReceivingParty	Dane odbiorcy na dokumencie (CustomerType: 0 – osoba fizyczna, 1 – podmiot gospodarczy)
PaymentTypeId	Id 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
BankAccountNumber	Numer rachunku bankowego
SalesDate	Data sprzedaży
InvoiceType	Algorytm obliczania (0 – od netto / 1 – od brutto)
NetTotal	Wartość netto dla całego dokumentu
GrossTotal	Wartość brutto dla całego dokumentu
VatTotal	Wartość VAT dla całego dokumentu
Items	Pozycje dokumentu
$id	Numer porządkowy w ramach odpowiedzi JSON
ProductId	Id produktu
Quantity	Ilość
ProductCurrencyPrice	Cena sprzedaży
ProductName	Nazwa produktu
ProductDescription	Opis produktu
UnitOfMeasurement	Jednostka miary
VatRateId	Id stawki VAT – do pobrania ze słownika unijnych stawek VAT tutaj, pole jest powiązane z procedurą 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:

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

[GET] https://app.comarchbetterfly.pl/api2/public/v1.3/invoices/XXX (gdzie XXX to Id faktury sprzedaży w bazie danych)

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

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

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

Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.3/invoices?number=FS/21/7/1

Wskazówka

W API obsługiwane są faktury sprzedaży w walucie PLN. Nie są obsługiwane faktury w walutach obcych, oraz dokumenty anulowane. Faktury zaliczkowe oraz korekty są obsługiwane w innych metodach.

DODAWANIE NOWEGO DOKUMENTU FAKTURY SPRZEDAŻY

Dodawanie faktury sprzedaży: [POST] https://app.comarchbetterfly.pl/api2/public/v1.3/invoices

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. Status zapłaty podczas dodawania faktury sprzedaży 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).
OSSProcedureCountryCode	Kod kraju dla procedury OSS	Nie. Parametr należy określić w przypadku wskazania kontrahenta o statusie „Procedura OSS”.
IsOSSProcedure	Oznaczenie procedury OSS (true / false)	Nie
PurchasingPartyId	Id nabywcy na dokumencie	Tak
ReceivingPartyId	Id odbiorcy na dokumencie	Nie
PaymentTypeId	Id formy płatności	Tak
PaymentDeadline	Termin płatności	Nie
BankAccountId	Id rachunku bankowego	Nie
SalesDate	Data sprzedaży	Nie. W przypadku braku daty w parametrach, ustawiana będzie data bieżąca.
InvoiceType	Algorytm obliczania (0 – od netto / 1 – od brutto)	Nie. W przypadku braku wartości w tym polu, zostanie zastosowany algorytm od netto.
Items	Pozycje dokumentu	Nie. 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. Wystawienie faktury z produktem bez karty towarowej jest dostępne jedynie z poziomu aplikacji Comarch Betterfly.
ProductId	Id produktu	Tak
Quantity	Ilość	Tak
ProductCurrencyPrice	Cena sprzedaży	Tak
ProductDescription	Opis produktu	Nie
VatRateId	Id stawki VAT	Nie. Parametr należy określić w przypadku wskazania kontrahenta o statusie „Procedura OSS”.
Description	Opis dokumentu	Nie
IssueDate	Data wystawienia dokumentu	Nie. W przypadku braku daty w parametrach, ustawiana będzie data bieżąca.

Przykładowe zapytanie JSON:

W odpowiedzi zostanie wysłane ID dodanego dokumentu faktury sprzedaży.

EDYCJA FAKTURY SPRZEDAŻY

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

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 nabywcy na dokumencie	Tak
ReceivingPartyId	Id odbiorcy na dokumencie	Nie
PaymentTypeId	Id formy płatności	Tak
PaymentDeadline	Termin płatności	Nie
BankAccountId	Id rachunku bankowego	Nie
SalesDate	Data sprzedaży	Nie
InvoiceType	Algorytm obliczania (0 – od netto / 1 – od brutto)	Nie. W przypadku braku wartości w tym polu podstawiona będzie wartość domyślna dla dokumentu. Dla faktur finalnych nie ma możliwości zmiany algorytmu.
Items	Pozycje dokumentu	Nie, jeśli edytowana faktura zawiera pozycje.
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. W przypadku pominięcia numeru Id pozycji podczas operacji edycji, zostanie dodana kolejna pozycja do dokumentu ze wskazanymi parametrami.
Description	Opis dokumentu	Nie
IssueDate	Data wystawienia dokumentu	Nie
Id	Id dokumentu w bazie danych	Tak

Uwaga

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

Uwaga

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

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

Przykładowe zapytanie JSON (zmiana ilości sztuk i ceny na fakturze o Id=2901095):

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

ZATWIERDZANIE FAKTUR SPRZEDAŻY

Zatwierdzanie faktur sprzedaży: [PUT] https://app.comarchbetterfly.pl/api2/public/v1.3/invoices/confirm

W odpowiedzi zostanie wysłany status i JSON odpowiedzi.

Wskazówka

Metoda zatwierdza jedynie faktury sprzedaży. Korekty do tych dokumentów należy zatwierdzić oddzielną metodą.

Przykładowe zapytanie JSON:

Przykładowa odpowiedź JSON:

USUWANIE FAKTURY SPRZEDAŻY

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

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

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

Wskazówka

Opcja usuwania faktur sprzedaży jest dostępna tylko dla dokumentów będących w buforze.

Aby dowiedzieć się jak pobrać wydruk faktury poprzez API – kliknij tutaj.