POBIERANIE FAKTUR PROFORMA

Pobieranie faktur proforma: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/proformas Opis struktury JSON odpowiedzi:

Parametr	Opis
$id	Numer porządkowy w ramach odpowiedzi JSON
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
BankAccountId	Id rachunku bankowego
InvoiceType	Algorytm obliczania (0 - od netto / 1 - od brutto)
OSSProcedureCountryCode	Kod kraju dla procedury OSS - do pobrania ze słownika kodów krajów UE tutaj
IsOSSProcedure	Oznaczenie procedury OSS (true / false)
InvoiceDocIdNum	Id powiązanej faktury sprzedaży, faktury zaliczkowej lub powiązanego paragonu
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
$id	Numer porządkowy w ramach odpowiedzi JSON
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
VatRateId	Id stawki VAT - do pobrania ze słownika unijnych stawek VAT tutaj
Id	Id pozycji dokumentu w bazie danych
Description	Opis dokumentu
IssueDate	Data wystawienia dokumentu
Number	Numer dokumentu
Status	Status dokumentu: 0 – nieprzekształcony bezpośrednio do dokumentu sprzedażowego, 1 – przekształcony do faktury sprzedaży, faktury zaliczkowej lub paragonu
Id	Id dokumentu w bazie danych

Przykładowa odpowiedź JSON: [code_snippet id=5]

Przykład

Lista faktur proforma, które zostały przekształcone do faktury sprzedaży, faktury zaliczkowej lub paragonu: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/proformas/?$filter=InvoiceDocIdNum ne null

  Możliwe jest także pobranie danych na temat określonego dokumentu faktury proforma: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/proformas/XXX (gdzie XXX to Id dokumentu proforma w bazie danych) Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/proformas/2901092

Wskazówka

W API obsługiwane są faktury proforma w walucie PLN. W walucie obcej dostępne jest tylko pobieranie faktur. Nie są obsługiwane dokumenty anulowane.

DODAWANIE NOWEGO DOKUMENTU FAKTURY PROFORMA

Dodawanie faktury proforma: [POST] https://app.comarchbetterfly.pl/api2/public/v1.4/proformas

Wskazówka

Faktury proforma dodawane do Comarch Betterfly poprzez API zawsze będą miały status "Zapisane". Wszelkie dalsze przekształcenia należy wykonywać po zalogowaniu do aplikacji.

Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
PurchasingPartyId	Id kontrahenta na dokumencie	Tak
ReceivingPartyId	Id odbiorcy na dokumencie	Nie
PaymentTypeId	Id formy płatności	Tak
BankAccountId	Id rachunku bankowego	Nie
InvoiceType	Algorytm obliczania (0 - od netto / 1 - od brutto)	Nie1
OSSProcedureCountryCode	Kod kraju dla procedury VAT OSS	Nie4
IsOSSProcedure	Oznaczenie procedury VAT OSS	Nie
Items	Pozycje dokumentu	Nie2
ProductId	Id produktu	Tak
Quantity	Ilość	Tak
ProductCurrencyPrice	Cena netto sprzedaży	Tak
ProductDescription	Opis produktu	Nie
VatRateId	Id stawki VAT	Nie4
Description	Opis dokumentu	Nie
IssueDate	Data wystawienia dokumentu	Nie3

1) W przypadku braku oznaczenia algorytmu, domyślnie zostanie zastosowane obliczenie od netto. 2) 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. 3) W przypadku braku daty w parametrach, ustawiana będzie data bieżąca. 4) Parametry należy określić w przypadku wskazania kontrahenta o statusie "Procedura OSS". Przykładowe zapytanie JSON: [code_snippet id=13 format] W odpowiedzi zostanie wysłane ID dodanego dokumentu faktury proforma.

EDYCJA FAKTURY PROFORMA

Edycja faktury proforma: [PUT] https://app.comarchbetterfly.pl/api2/public/v1.4/proformas Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
PurchasingPartyId	Id kontrahenta na dokumencie	Tak
ReceivingPartyId	Id odbiorcy na dokumencie	Nie
PaymentTypeId	Id formy płatności	Tak
BankAccountId	Id rachunku bankowego	Nie
InvoiceType	Algorytm obliczania (0 - od netto / 1 - od brutto)	Nie
OSSProcedureCountryCode	Kod kraju dla procedury VAT OSS	Nie3
IsOSSProcedure	Oznaczenie procedury VAT OSS	Nie
Items	Pozycje dokumentu	Nie1
ProductId	Id produktu	Tak
Quantity	Ilość	Tak
ProductCurrencyPrice	Cena netto sprzedaży	Tak
ProductDescription	Opis produktu	Nie
VatRateId	Id stawki VAT	Nie3
Id	Id pozycji dokumentu w bazie danych	Nie2
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 pominięcia numeru Id pozycji podczas operacji edycji, zostanie dodana kolejna pozycja do dokumentu ze wskazanymi parametrami. 3) Parametry należy określić w przypadku wskazania kontrahenta o statusie "Procedura OSS".

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 bez przekształceń (Status = 0).

W odpowiedzi zostanie wysłany status i ewentualnie JSON odpowiedzi. Przykładowe zapytanie JSON (zmiana ilości sztuk na proformie o Id=28964885): [code_snippet id=14 format] Przykładowa odpowiedź JSON – status 204 No Content - operacja zakończona powodzeniem.  

USUWANIE FAKTURY PROFORMA

Usuwanie faktury proforma: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.4/proformas/XXX (gdzie XXX to Id dokumentu faktury proforma w bazie danych) Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/proformas/2901094 Przykładowa odpowiedź JSON – status 204 No Content - operacja zakończona powodzeniem.

Wskazówka

Opcja usuwania faktury proforma jest dostępna tylko dla dokumentów bez przekształceń.

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

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.7/invoices 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 opisanym w artykule API Procedura OSS
IsOSSProcedure	Oznaczenie procedury OSS (true / false)
IsFinal	Oznaczenie typu faktury  (true / false)
PaymentId	Id płatności
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
PaymentFormKsef	Forma płatności KSeF: 1 - Gotówka 2 - Karta 3 - Bon 4 - Czek 5 - Kredyt 6 - Przelew 7 - Płatność mobilna 8 - Płatność inna
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 - 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
BankAccountNumber	Numer rachunku bankowego
SalesDate	Data sprzedaży
InvoiceType	Algorytm obliczania (0 - od netto / 1 - od brutto)
NetTotal	Wartość netto dla całego dokumentu
CurrencyNetTotal	Wartość netto w walucie obcej dla całego dokumentu
GrossTotal	Wartość brutto dla całego dokumentu
CurrencyGrossTotal	Wartość brutto w walucie obcej dla całego dokumentu
VatTotal	Wartość VAT dla całego dokumentu
CurrencyVatTotal	Wartość VAT w walucie obcej dla całego dokumentu
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
DocumentCreatedByTaxPayer	Dokument utworzony przez: true - Płatnika VAT false - Podatnika zwolnionego z VAT
Items	Pozycje dokumentu
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
ProductName	Nazwa produktu
ProductDescription	Opis produktu
UnitOfMeasurement	Jednostka miary
VatRateId	Id stawki VAT - do pobrania ze słownika stawek VAT opisanym w artykule API Procedura 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)
Confirmed	Dokument zatwierdzony (true / false)
Cancelled	Dokument anulowany (true / false)
Id	Id dokumentu w bazie danych

Przykładowa odpowiedź JSON: [code_snippet id=64] Możliwe jest także pobranie danych dotyczących określonego dokumentu faktury sprzedaży: [GET] https://app.comarchbetterfly.pl/api2/public/v1.7/invoices/XXX (gdzie XXX to Id faktury sprzedaży w bazie danych) Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.7/invoices/2901096   Dostępna jest możliwość pobrania dokumentu o konkretnym numerze: [GET] https://app.comarchbetterfly.pl/api2/public/v1.7/invoices/invoices?number={number} Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.7/invoices?number=FS/21/7/1

Wskazówka

W API obsługiwane są faktury sprzedaży w walucie PLN. W walucie obcej dostępne jest tylko pobieranie faktur. Nie są obsługiwane dokumenty anulowane. Faktury zaliczkowe oraz korekty są obsługiwane w osobnych metodach.

DODAWANIE NOWEGO DOKUMENTU FAKTURY SPRZEDAŻY

Dodawanie faktury sprzedaży: [POST] https://app.comarchbetterfly.pl/api2/public/v1.7/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
KSeFData	Dane dokumentu związane z KSeF	Nie
PaymentFormKsef	Forma płatności KSeF	Nie. W przypadku braku wartości nastąpi auto mapowania na podstawie typu płatności z dokumentu. W przypadku ustawienia wartości 8 (Płatność inna) opis płatności do KSeF zostanie ustawiony na nazwę formy płatności wybranej na dokumencie.
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: [code_snippet id=15] 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.7/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
KSeFData	Dane dokumentu związane z KSeF	Nie
PaymentFormKsef	Forma płatności KSeF	Nie. W przypadku ustawienia wartości 8 (Płatność inna) opis płatności do KSeF zostanie ustawiony na nazwę formy płatności wybranej na dokumencie.
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=28964885): [code_snippet id=16] 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.7/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: [code_snippet id=17] Przykładowa odpowiedź JSON: [code_snippet id=18]

USUWANIE FAKTURY SPRZEDAŻY

Usuwanie faktury sprzedaży: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.7/invoices/XXX (gdzie XXX to Id dokumentu faktury w bazie danych) Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.7/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 poprzez interface API pobrać wydruk faktury: API – Wydruki.  

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.4/invoices 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 opisanym w artykule API Procedura OSS
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 - 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
BankAccountNumber	Numer rachunku bankowego
SalesDate	Data sprzedaży
InvoiceType	Algorytm obliczania (0 - od netto / 1 - od brutto)
NetTotal	Wartość netto dla całego dokumentu
CurrencyNetTotal	Wartość netto w walucie obcej dla całego dokumentu
GrossTotal	Wartość brutto dla całego dokumentu
CurrencyGrossTotal	Wartość brutto w walucie obcej dla całego dokumentu
VatTotal	Wartość VAT dla całego dokumentu
CurrencyVatTotal	Wartość VAT w walucie obcej dla całego dokumentu
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
DocumentCreatedByTaxPayer	Dokument utworzony przez: true - Płatnika VAT false - Podatnika zwolnionego z VAT
Items	Pozycje dokumentu
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
ProductName	Nazwa produktu
ProductDescription	Opis produktu
UnitOfMeasurement	Jednostka miary
VatRateId	Id stawki VAT - do pobrania ze słownika stawek VAT opisanym w artykule API Procedura 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=9] Możliwe jest także pobranie danych dotyczących określonego dokumentu faktury sprzedaży: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/invoices/XXX (gdzie XXX to Id faktury sprzedaży w bazie danych) Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/invoices/2901096   Dostępna jest możliwość pobrania dokumentu o konkretnym numerze: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/invoices/invoices?number={number} Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/invoices?number=FS/21/7/1

Wskazówka

W API obsługiwane są faktury sprzedaży w walucie PLN. W walucie obcej dostępne jest tylko pobieranie faktur. Nie są obsługiwane dokumenty anulowane. Faktury zaliczkowe oraz korekty są obsługiwane w osobnych metodach.

DODAWANIE NOWEGO DOKUMENTU FAKTURY SPRZEDAŻY

Dodawanie faktury sprzedaży: [POST] https://app.comarchbetterfly.pl/api2/public/v1.4/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: [code_snippet id=15] 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.4/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=28964885): [code_snippet id=16] 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.4/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: [code_snippet id=17] Przykładowa odpowiedź JSON: [code_snippet id=18]

USUWANIE FAKTURY SPRZEDAŻY

Usuwanie faktury sprzedaży: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.4/invoices/XXX (gdzie XXX to Id dokumentu faktury w bazie danych) Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.4/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 poprzez interface API pobrać wydruk faktury: API – Wydruki.  

POBIERANIE FAKTUR VAT MARŻA

Pobieranie faktur sprzedaży: [GET] https://app.comarchbetterfly.pl/api2/public/v1.5/profitmargininvoices Opis struktury JSON odpowiedzi:

Parametr	Opis
PaymentStatus	Status płatności (0 – niezapłacona, 1 – zapłacona całkowicie, 2 – zapłacona częściowo)
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 - 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
BankAccountNumber	Numer rachunku bankowego
SalesDate	Data sprzedaży
InvoiceType	Algorytm obliczania (0 - od netto / 1 - od brutto)
ProfitMarginInvoiceProcedureType	Rodzaj procedury VAT marża wg poniższego klucza: 0 - Brak 1 - Procedura marży dla biur podróży 2 - Procedura marży - towary używane 3 - Procedura marży – dzieła sztuki 4 - Procedura marży – przedmioty kolekcjonerskie i antyki
ProfitMarginTotal	Wartość marży dla całego dokumentu
GrossTotal	Wartość brutto dla całego dokumentu
CurrencyGrossTotal	Wartość brutto dla całego dokumentu, w walucie dokumentu
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
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
Items	Pozycje dokumentu
ProductId	Id produktu
Quantity	Ilość
ProductCurrencyPrice	Cena sprzedaży, po rabacie w walucie dokumentu, jeżeli InvoiceType = 0 - Cena sprzedaży netto w walucie dokumentu, jeżeli InvoiceType = 1 - Cena sprzedaży brutto w walucie dokumentu
ProductPrice	Cena sprzedaży, po rabacie jeżeli InvoiceType = 0 - Cena sprzedaży netto, jeżeli InvoiceType = 1 - Cena sprzedaży brutto
ProductName	Nazwa produktu
ProductDescription	Opis produktu
UnitOfMeasurement	Jednostka miary
VatRateId	Id stawki VAT - do pobrania ze słownika stawek VAT tutaj
ProfitMarginVatRateId	Id stawki VAT dla kwoty marży – do pobrania ze słownika stawek VAT
ProductProfitMarginValue	Kwota marży dla produktu
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=63]   Możliwe jest także pobranie danych dotyczących określonego dokumentu faktury VAT marża: [GET] https://app.comarchbetterfly.pl/api2/public/v1.5/profitmargininvoices/XXX (gdzie XXX to Id faktury VAT marża w bazie danych) Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.5/profitmargininvoices/2901096

Wskazówka

W API obsługiwane jest pobieraniu faktury VAT marża w walucie PLN i w walucie obcej. Nie są obsługiwane dokumenty anulowane i korekty.

Wskazówka

W API nie jest obsługiwana dodawanie, edycja i usuwania faktur VAT marża

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

POBIERANIE FAKTUR VAT MARŻA

Pobieranie faktur sprzedaży: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/profitmargininvoices Opis struktury JSON odpowiedzi:

Parametr	Opis
PaymentStatus	Status płatności (0 – niezapłacona, 1 – zapłacona całkowicie, 2 – zapłacona częściowo)
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 - 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
BankAccountNumber	Numer rachunku bankowego
SalesDate	Data sprzedaży
InvoiceType	Algorytm obliczania (0 - od netto / 1 - od brutto)
ProfitMarginInvoiceProcedureType	Rodzaj procedury VAT marża wg poniższego klucza: 0 - Brak 1 - Procedura marży dla biur podróży 2 - Procedura marży - towary używane 3 - Procedura marży – dzieła sztuki 4 - Procedura marży – przedmioty kolekcjonerskie i antyki
ProfitMarginTotal	Wartość marży dla całego dokumentu
GrossTotal	Wartość brutto dla całego dokumentu
CurrencyGrossTotal	Wartość brutto dla całego dokumentu, w walucie dokumentu
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
ProductId	Id produktu
Quantity	Ilość
ProductCurrencyPrice	Cena sprzedaży, po rabacie w walucie dokumentu, jeżeli InvoiceType = 0 - Cena sprzedaży netto w walucie dokumentu, jeżeli InvoiceType = 1 - Cena sprzedaży brutto w walucie dokumentu
ProductPrice	Cena sprzedaży, po rabacie jeżeli InvoiceType = 0 - Cena sprzedaży netto, jeżeli InvoiceType = 1 - Cena sprzedaży brutto
ProductName	Nazwa produktu
ProductDescription	Opis produktu
UnitOfMeasurement	Jednostka miary
VatRateId	Id stawki VAT - do pobrania ze słownika stawek VAT tutaj
ProfitMarginVatRateId	Id stawki VAT dla kwoty marży – do pobrania ze słownika stawek VAT
ProductProfitMarginValue	Kwota marży dla produktu
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=10]   Możliwe jest także pobranie danych dotyczących określonego dokumentu faktury VAT marża: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/profitmargininvoices/XXX (gdzie XXX to Id faktury VAT marża w bazie danych) Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/profitmargininvoices/2901096

Wskazówka

W API obsługiwane jest pobieraniu faktury VAT marża w walucie PLN i w walucie obcej. Nie są obsługiwane dokumenty anulowane i korekty.

Wskazówka

W API nie jest obsługiwana dodawanie, edycja i usuwania faktur VAT marża

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

POBIERANIE FAKTUR ZAKUPU

Pobieranie faktur zakupu: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/purchaseinvoices Opis struktury JSON odpowiedzi:

Parametr	Opis
PaymentStatus	Status płatności (0 – niezapłacona, 1 – zapłacona całkowicie, 2 – zapłacona częściowo)
SellingPartyId	Id dostawcy na dokumencie
ReceivingPartyId	Id nabywcy 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
SellingPartyBankAccountNumber	Numer rachunku bankowego dostawcy
SellingPartyBankAccountName	Nazwa banku dostawcy
BankAccountId	Id rachunku bankowego
BankAccountNumber	Numer rachunku bankowego
PurchaseDate	Data zakupu
InvoiceType	Algorytm obliczania (0 - od netto / 1 - od brutto)
NetTotal	Wartość netto dla całego dokumentu
CurrencyNetTotal	Wartość netto w walucie obcej dla całego dokumentu
GrossTotal	Wartość brutto dla całego dokumentu
CurrencyGrossTotal	Wartość brutto w walucie obcej dla całego dokumentu
VatTotal	Wartość VAT dla całego dokumentu
CurrencyVatTotal	Wartość VAT w walucie obcej dla całego dokumentu
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
ProductId	Id produktu
Quantity	Ilość
ProductCurrencyPrice	Cena sprzedaży, po rabacie, w walucie dokumentu: jeżeli InvoiceType = 0 - Cena zakupu netto jeżeli InvoiceType = 1 - Cena zakupu brutto
ProductPrice	Cena sprzedaży, po rabacie: jeżeli InvoiceType = 0 - Cena zakupu netto jeżeli InvoiceType = 1 - Cena zakupu brutto
ProductName	Nazwa produktu
ProductDescription	Opis produktu
UnitOfMeasurement	Jednostka miary
VatRateId	Id stawki VAT - do pobrania ze słownika stawek VAT tutaj
Id	Id pozycji dokumentu w bazie danych
Description	Opis dokumentu
IssueDate	Data wystawienia dokumentu
ReceiptDate	Data wpływu
Number	Numer wewnętrzny dokumentu
ReferenceNumber	Numer obcy 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=7]   Możliwe jest także pobranie danych konkretnego dokumentu faktury zakupu: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/purchaseinvoices/XXX (gdzie XXX to Id dokumentu faktury zakupu w bazie danych) Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/purchaseinvoices/2901092

Wskazówka

W ERP API obsługiwane jest tylko pobieranie faktur zakupu w waluce PLN i w walucie obcej. Nie są obsługiwane dokumenty anulowane. Korekty faktur zakupu obsługiwane są w innych metodach.

POBIERANIE FAKTUR ZALICZKOWYCH

Pobieranie faktur zaliczkowych: [GET] https://app.comarchbetterfly.pl/api2/public/v1.7/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
PaymentFormKsef	Forma płatności KSeF: 1 - Gotówka 2 - Karta 3 - Bon 4 - Czek 5 - Kredyt 6 - Przelew 7 - Płatność mobilna 8 - Płatność inna
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)
Confirmed	Dokument zatwierdzony (true / false)
Cancelled	Dokument anulowany (true / false)
Id	Id dokumentu w bazie danych

Przykładowa odpowiedź JSON: [code_snippet id=65]   Możliwe jest także pobranie danych dotyczących określonego dokumentu faktury zaliczkowej: [GET] https://app.comarchbetterfly.pl/api2/public/v1.7/advanceInvoices/XXX (gdzie XXX to id faktury zaliczkowej w bazie danych) Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.7/advanceInvoices/2901096   Dostępna jest możliwość pobrania dokumentu o konkretnym numerze: [GET] https://app.comarchbetterfly.pl/api2/public/v1.7/advanceInvoices/invoices?number={number} Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.7/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.7/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)	Nie1
OSSProcedureCountryCode	Kod kraju dla procedury OSS	Nie6
IsOSSProcedure	Oznaczenie procedury OSS (true / false)	Nie
KSeFData	Dane dokumentu związane z KSeF	Nie
PaymentFormKsef	Forma płatności KSeF	Nie8
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	Nie2
InvoiceType	Algorytm obliczania (0 - od netto / 1 - od brutto)	Nie3
Items	Pozycje dokumentu	Nie4
CurrencyAdvance	Wartość zaliczki	Nie7
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	Nie6
Description	Opis dokumentu	Nie
IssueDate	Data wystawienia dokumentu	Nie5

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ą 8) W przypadku braku wartości nastąpi auto mapowania na podstawie typu płatności z dokumentu. W przypadku ustawienia wartości 8 (Płatność inna) opis płatności do KSeF zostanie ustawiony na nazwę formy płatności wybranej na dokumencie.   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.7/advanceInvoices?advanceId={id} Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.7/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.7/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
KSeFData	Dane dokumentu związane z KSeF	Nie
PaymentFormKsef	Forma płatności KSeF	Nie4
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)	Nie2
Items	Pozycje dokumentu	Nie1
CurrencyAdvance	Wartość zaliczki	Nie2
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	Nie3
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. 4) W przypadku ustawienia wartości 8 (Płatność inna) opis płatności do KSeF zostanie ustawiony na nazwę formy płatności wybranej na dokumencie.

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.7/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.7/advanceInvoices/XXX (gdzie XXX to Id dokumentu faktury zaliczkowej w bazie danych) Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.7/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.  

POBIERANIE FAKTUR ZALICZKOWYCH

Pobieranie faktur zaliczkowych: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/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)
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=11]   Możliwe jest także pobranie danych dotyczących określonego dokumentu faktury zaliczkowej: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/advanceInvoices/XXX (gdzie XXX to id faktury zaliczkowej w bazie danych) Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/advanceInvoices/2901096   Dostępna jest możliwość pobrania dokumentu o konkretnym numerze: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/advanceInvoices/invoices?number={number} Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/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.4/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)	Nie1
OSSProcedureCountryCode	Kod kraju dla procedury OSS	Nie6
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	Nie2
InvoiceType	Algorytm obliczania (0 - od netto / 1 - od brutto)	Nie3
Items	Pozycje dokumentu	Nie4
CurrencyAdvance	Wartość zaliczki	Nie7
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	Nie6
Description	Opis dokumentu	Nie
IssueDate	Data wystawienia dokumentu	Nie5

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.4/advanceInvoices?advanceId={id} Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/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.4/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)	Nie2
Items	Pozycje dokumentu	Nie1
CurrencyAdvance	Wartość zaliczki	Nie2
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	Nie3
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.4/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.4/advanceInvoices/XXX (gdzie XXX to Id dokumentu faktury zaliczkowej w bazie danych) Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.4/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.    

API udostępnia możliwość filtrowania, sortowania i stronicowania zasobów. W tym celu należy wykorzystywać następująca słowa kluczowych:

• filtrowanie - filter
• sortowanie - orderby
• stronicowanie - skip oraz top

Do filtrowania danych dostępne są do użycia następujące operatory porównań:

• równość – eq
• nierówność – ne
• większe od – gt
• większe lub równe – ge
• mniejsze od – lt
• mniejsze lub równe – le

Przykład

Lista kontrahentów z numerem NIP równym 6770065406:

[GET] https://app.comarchbetterfly.pl/api2/public/customers/?$filter=CustomerTaxNumber eq '6770065406'

Przykład

Lista ostatnich 50 faktur sprzedaży posortowanych malejąco po dacie wystawienia:

[GET] https://app.comarchbetterfly.pl/api2/public/invoices/?&$orderby=IssueDate desc, Id desc &$skip=0 &$top=50

Przykład

Lista proform, które nie zostały przekształcone do faktury sprzedaży, faktury zaliczkowej lub paragonu:

[GET] https://app.comarchbetterfly.pl/api2/public/proformas/?$filter=InvoiceDocIdNum eq null

Przykład

Lista faktur, które zostały wystawione po dniu 2023.01.20:

[GET] https://app.comarchbetterfly.pl/api2/public/invoices/?&$filter=IssueDate gt datetime'2023-01-20'

Filtrować można także z użyciem kilku kryteriów stosując wspierane operatory logiczne:

• koniunkcja - and
• alternatywa - or
• zaprzeczenie - not

Przykład

Lista produktów z numerami Id zawartymi w przedziale od 100 do 1000

[GET] https://app.comarchbetterfly.pl/api2/public/products/?$filter=Id ge 100 and Id le 1000

  Do wyszukiwania można też zastosować mechanizm full-text search i odnajdywać frazy zawarte m.in. w opisie lub nazwie kontrahencie wybranego na dokumencie

Przykład

Lista faktur proforma zawierająca frazę przykładowy opis

[GET] https://app.comarchbetterfly.pl/api2/public/proformas/?$fts='przykładowy opis'

POBIERANIE FORM PŁATNOŚCI

[GET] https://app.comarchbetterfly.pl/api2/public/paymenttypes Opis struktury JSON odpowiedzi:

Parametr	Opis
$id	Numer porządkowy w ramach odpowiedzi JSON
Name	Nazwa formy płatności
Primary	Czy forma płatności jest jako "domyślna" - true (TAK) / false (NIE)
Type	Typ płatności: 0 - płatność gotówką 1 - płatność na konto 2 - płatność kartą
Id	Id formy płatności

Przykładowa odpowiedź JSON: [code_snippet id=25] Możliwe jest także pobranie danych na temat określonej formy płatności. [GET] https://app.comarchbetterfly.pl/api2/public/paymenttypes/XXX (gdzie XXX to Id formy płatności w bazie danych) Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/paymenttypes/5 Przykładowa odpowiedź JSON: [code_snippet id=26]

DODAWANIE NOWEJ FORMY PŁATNOŚCI

[POST] https://app.comarchbetterfly.pl/api2/public/paymenttypes Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
Name	Nazwa formy płatności	TAK
Primary	Czy forma płatności jest jako "domyślna" - true (TAK) / false (NIE)	NIE
Deadline	liczby całkowite z zakresu <0,366>	TAK
Type	Typ płatności: 0 - płatność gotówką 1 - płatność na konto 2 - płatność kartą	TAK

Wskazówka

Może istnieć tylko jedna domyślna forma płatności. Po zaznaczeniu parametru Primary na "true" dana płatność automatycznie staje się podstawową.

Przykładowe zapytanie JSON: [code_snippet id=27] W odpowiedzi zostanie wysłane ID dodanej formy płatności.

EDYCJA FORMY PŁATNOŚCI

[PUT] https://app.comarchbetterfly.pl/api2/public/paymenttypes Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
Name	Nazwa formy płatności	TAK
Primary	Czy forma płatności jest jako "domyślna" - true (TAK) / false (NIE)	NIE
Deadline	liczby całkowite z zakresu <0,366>	TAK
Type	Typ płatności: 0 - płatność gotówką 1 - płatność na konto 2 - płatność kartą	TAK
ID	Id formy płatności w bazie danych	TAK

Wskazówka

Podczas edycji formy płatności, która jest już domyślna (Primary = true), nie można zmienić jej na "false". Zawsze musi istnieć jedna domyślna forma płatności.

Uwaga

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

W odpowiedzi zostanie wysłany status i ewentualnie JSON odpowiedzi. Przykładowe zapytanie JSON (zmiana typu formy płatności o Id=29017): [code_snippet id=28] Przykładowa odpowiedź JSON – status 204 No Content – operacja zakończona powodzeniem.

USUWANIE FORMY PŁATNOŚCI

[DEL] https://app.comarchbetterfly.pl/api2/public/paymenttypes/XXX (gdzie XXX to Id formy płatności w bazie danych) Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/paymenttypes/29017 Przykładowa odpowiedź JSON – status 204 No Content – operacja zakończona powodzeniem.

Wskazówka

Nie można usuwać domyślnej formy płatności.

---

21.05.2023 Udostępniono nowe metody służące do pobierania płatności i aktualizacji ich statusu. Więcej informacji w artykule: API - Płatności  

---

16.03.2023 Udostępniono nowe wersje metod do pobierania danych dotyczących:

• faktur sprzedaży (wersja 1.4),
• faktur zaliczkowych (wersja 1.4),
• faktur proforma (wersja 1.4),
• korekt (wersja 1.4).

W zakresie tych metod poszerzono informacje o dokumenty wystawione w walutach obcych. Dodatkowo udostępniono nową metodę do pobierania faktur VAT marża. Więcej informacji w artykule Faktura VAT marża.  

---

22.06.2022 Udostępniono nową wersję metody do faktur sprzedaży (Faktura sprzedaży wersja 1.3), w której:

• rozszerzono zakres danych pobieranych z dokumentu,
• dodano funkcję pobierania i edycji terminu płatności.

Umożliwiono także wystawianie i zatwierdzanie faktur korygujących do faktur sprzedaży i faktur zaliczkowych oraz pobieranie wydruków tych dokumentów.  

---

16.03.2022 Dodano nowe funkcje w API w zakresie zatwierdzania faktur sprzedaży, wystawiania faktur zaliczkowych oraz przekształcania faktur zaliczkowych do faktur finalnych. Opisy do nowych i zaktualizowanych metod znajdują się w poszczególnych artykułach:

• Faktura sprzedaży wersja 1.2 - dodano metodę do zatwierdzania dokumentów będących w buforze
• Faktura zaliczkowa
• Przekształcanie faktur zaliczkowych

 

---

09.02.2022 Udostępniono możliwość dodawania i edycji rachunków bankowych oraz form płatności:

• Rachunki bankowe
• Formy płatności

 

---

23.07.2021 W związku z możliwością stosowania procedury OSS w API udostępniono nowe wersje metod:

• Kontrahenci wersja 1.2
• Faktura sprzedaży wersja 1.2
• Faktura proforma wersja 1.2

W tych metodach można m.in. wskazać kod kraju kontrahenta oraz jego status. Dla kontrahentów unijnych dodatkowe dane można pobrać ze słowników oznaczeń krajów UE i stawek VAT. Więcej informacji w artykule: API - Obsługa procedury OSS Zaktualizowana została także metoda do pobierania wydruków. Ponadto w dotychczasowej metodzie dotyczącej produktów dodano możliwość pobrania rodzaju produktu (ProductType):

• 0 - usługa
• 1 - towar
• 2 - towar z kontrolą stanu

 

---

17.06.2021 Udostępniono opcję usuwanie wielu faktur proforma w jednej operacji. Nowa metoda przyjmuje obiekt o polu IdCollection, który zawiera tablice reprezentującą numery Id faktur proforma do usunięcia. Więcej informacji znajduje się dokumentacji dla wersji 1.1 dostępnej pod adresem: Faktura proforma wersja 1.1  

---

27.04.2021 Dodano nowe pole InvoiceDocIdNum dla faktur proforma, które przechowuje numer Id powiązanej faktury sprzedaży, faktury zaliczkowej lub powiązanego paragonu. Szczegółowy opis całej struktury faktur proforma znajduje się pod następującymi linkami:

• Faktura proforma
• Faktura proforma wersja 1.1

 

---

22.07.2020 Udostępniono nowe wersje metod w zakresie dokumentów handlowych:

• https://app.comarchbetterfly.pl/api2/public/v1.1/invoices
• https://app.comarchbetterfly.pl/api2/public/v1.1/proformas
• https://app.comarchbetterfly.pl/api2/public/v1.1/invoices/print/{id}
• https://app.comarchbetterfly.pl/api2/public/v1.1/proformas/print/{id}

W wersjach 1.1 dla faktur sprzedaży i faktur proforma wprowadzono następujące nowości - od teraz można:

• wskazać odbiorcę na dokumentach faktury sprzedaży i fakturach proforma (ReceivingPartyId)
• ustawić algorytm naliczania - od cen netto (InvoiceType=0) oraz od cen brutto (InvoiceType=1)
• dodać opis na dokument (Description)
• pobrać wydruk dokumentu wg domyślnego szablonu przypisanego do kontrahenta

Uwaga

W związku z wprowadzeniem możliwości ustawiania algorytmu naliczania od cen netto/brutto zmieniono nazwę pola ProductCurrencyNetPrice na ProductCurrencyPrice.

Wskazówka

Nowe wersje metod funkcjonują równolegle z dotyczasowymi.

W dotychczasowych wersjach metod w zakresie produktów można dodatkowo:

• zapisać cenę sprzedaży produktu w kwotach brutto (ProductCurrencyPrice)
• pobrać informacje o stanie magazynowym towaru (Quantity)

Udostępniono także filtrowanie danych we wszystkich obsługiwanych metodach GET zwracających dane w formie listy - przykłady:

• produkty
  • wg nazwy (.../products/?$filter=Name eq {nazwa})
  • wg kodu (.../products/?$filter=ProductCode eq {kod_produktu})
• kontrahenci
  • wg NIP (.../customers/nip/{nr_nip})
  • wg nazwy (.../customers/?$filter=Name eq {nazwa})
  • wg adresu e-mail (.../customers/?$filter=Mail eq {adres_email})
• dokumenty
  • wg numeru faktury sprzedaży (.../invoices/number/{nr_dokumentu})
  • wg numeru faktury proforma (.../proformas/number/{nr_dokumentu})

Wskazówka

Dostępne jest także filtrowanie z użyciem kilku kryteriów - wspierane operatory logiczne: or, and, not. W filtrowaniu można wykorzystać następujące operatory do porównań: równość - eq nierówność - ne większe od - gt większe lub równe - ge mniejsze od - lt mniejsze lub równe - le

Przykład

https://app.comarchbetterfly.pl/api2/public/products/?$filter=Name eq 'Produkt' or ProductCode eq 'P/000001' https://app.comarchbetterfly.pl/api2/public/products/?$filter=SaleGrossPrice ge 199.99 and SaleGrossPrice le 300

 

---

17.12.2019 Udostępniono API w zakresie:

• pobieranie, dodawanie, modyfikowanie i usuwanie produktów
• pobieranie, dodawanie, modyfikowanie i usuwanie kontrahentów
• pobieranie form zapłaty,
• pobieranie rachunków bankowych,
• pobieranie faktur sprzedaży i faktur proforma
• dodawanie faktur sprzedaży i faktur proforma
• usuwanie faktur sprzedaży i faktur proforma
• pobieranie wydruku faktury sprzedaży i faktury proforma z możliwością wskazania szablonu

Szczegółowy opis powyższych funkcji znajduje się tutaj. Aby rozpocząć pracę z Comarch Betterfly API - dowiedz się więcej tutaj.

---

Comarch Betterfly API działa w oparciu o protokół HTTP i jego metody (GET, POST, PUT, DELETE) oraz zasoby, które odzwierciedlają poszczególne funkcjonalności serwisu. Uwierzytelnianie realizowane jest w standardzie OAuth 2.0 (więcej o uwierzytelnianiu - API Instrukcja Użytkownika). Dostęp do API odbywa się poprzez połączenie HTTPS do serwera app.comarchbetterfly.pl. Dane są wysyłane i odbierane z serwera w formacie JSON.

Wskazówka

Historia zmian w publicznym API Comarch Betterfly dostępna jest w artykule: API - Historia zmian

Dostęp do API jest możliwy z poziomu Konta Użytkownika > Zarządzaj kontem > Publiczne API. Użytkownik, który jest administratorem w ramach konta Comarch Betterfly, wnioskuje o przydzielenie dostępu (opcja "Zapytaj o API"). Po jego uzyskaniu generuje z tego poziomu dane dostępowe oraz rejestruje aplikację korzystającą z API. Wykorzystywane metody HTTP:

GET	pobieranie danych dotyczących wszystkich lub wskazanych elementów/zasobów, w tym pobieranie wydruków
POST	tworzenie nowego elementu/zasobu
PUT	edycja istniejącego elementu/zasobu
DELETE	usuwanie elementu/zasobu

Zasoby:

produkty	https://app.comarchbetterfly.pl/api2/public/products
kontrahenci	https://app.comarchbetterfly.pl/api2/public/v1.2/customers
formy płatności	https://app.comarchbetterfly.pl/api2/public/paymenttypes
rachunki bankowe	https://app.comarchbetterfly.pl/api2/public/bankaccounts
faktury sprzedaży	https://app.comarchbetterfly.pl/api2/public/v1.7/invoices
faktury proforma	https://app.comarchbetterfly.pl/api2/public/v1.4/proformas
szablony wydruków	https://app.comarchbetterfly.pl/api2/public/customprints
faktura VAT marża	https://app.comarchbetterfly.pl/api2/public/v1.5/profitmargininvoices
faktura zaliczkowa	https://app.comarchbetterfly.pl/api2/public/v1.7/advanceinvoices
faktura zakupu	https://app.comarchbetterfly.pl/api2/public/v1.4/purchaseinvoices
rejestr VAT Zakupu	https://app.comarchbetterfly.pl/api2/public/v1.4/vatpurchasebooks
korekta faktury sprzedaży	https://app.comarchbetterfly.pl/api2/public/v1.7/correctiveinvoices
korekta faktury zaliczkowej	https://app.comarchbetterfly.pl/api2/public/v1.7/correctiveadvanceinvoices
korekta faktury zakupu	https://app.comarchbetterfly.pl/api2/public/v1.4/correctivepurchaseinvoices

Każde żądanie do API zwraca status HTTP informujący o wyniku przetwarzania. Poniższa lista zawiera najczęściej używane statusy:

• 200 OK - pomyślnie przesłano dane w metodzie GET, POST
• 204 No Content - pomyślnie zakończono akcję w metodzie PUT, DELETE
• 400 Bad Request - błąd w treści żądanie
• 401 Unauthorized - brak uwierzytelniania
• 403 Forbidden - dostęp zablokowany
• 404 Not Found - nie znaleziono zasobu
• 405 Method Not Allowed - nieobsługiwana metoda
• 500 Internal Server Error - wewnętrzny błąd serwera

Operacje wykonywane poprzez API są zapisywane w historii zmian kontrahenta oraz dokumentu. W opisie operacji znajduje się informacja na temat nazwy aplikacji, poprzez którą dokonano zmian.

Wskazówka

Użytkownik Comarch Betterfly ma możliwość korzystania z API również w przypadku posiadania wersji testowej aplikacji.

POBIERANIE KATEGORII ZAKUPU

Uwaga

Aby pobrać listę kategorii spełnione być muszą dwa warunki: 1. Połączenie IWD z Biurem Rachunkowym musi być skonfigurowane i aktywne. 2. W konfiguracji musi być włączona opcja korzystania z kategorii otrzymanych z Biura Rachunkowego.

Pobieranie kategorii zakupu z Biura Rachunkowego: [GET] https://app.comarchbetterfly.pl/api2/public/v1.8/categories Opis struktury JSON odpowiedzi:

Parametr	Opis
SourceId	Unikalny identyfikator źródłowy, który pozwala powiązać kategorię z jej definicją pochodzenia
GeneralCode	Kod kategorii ogólnej (nadrzędnej), która grupuje powiązane kategorie. Wiele kategorii szczegółowych może mieć ten sam kod ogólny co tworzy dwupoziomową hierarchię.
Code	Kod konkretnej kategorii, unikalny w obrębie grupy ogólnej.
General	Znacznik czy kategorie ogólna (true - nagłówek grupujący, false - kategoria ogólna).
Type	Rodzaj: przychód czy koszt (0 - przychód, 1 - koszt). Ten endpoint zwraca tylko koszty, więc zawsze zwraca 1.
Description	Opis kategorii tłumaczący jej zastosowanie.
Inactive	Czy kategoria jest dezaktywowana (true - nieaktywna, false - aktywna). Nieaktywne są ukrywane z list wyboru, ale zachowane dla dokumentów historycznych, które już z nich korzystają.
Version	Znacznik czasu ostanie modyfikacji, automatycznie aktualizowany przy każdym zapisie.
Id	Unikalny numeryczny identyfikator, nadawany automatycznie przy pierwszym zapisie rekordu.
ExtendedPropertiesXml	Mechanizm na rozszerzone pola, które następnie będą serializowane do XML (puste - brak takich właściwości).

Przykładowa odpowiedź JSON: [code_snippet id=67]  

POBIERANIE KONTRAHENTÓW

Pobieranie kontrahentów: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/customers Opis struktury JSON odpowiedzi:

Parametr	Opis
$id	Numer porządkowy w ramach odpowiedzi JSON
Name	Nazwa kontrahenta
CountryCode	Oznaczenie kodu kraju kontrahenta (prefix NIP) Możliwa jest pusta wartość, która powinna być stosowana dla kontrahenta krajowego niezarejestrowanego w VAT-UE
CustomerTaxNumber	Identyfikator podatkowy NIP/PESEL - w zależności od pola CustomerType
CustomerCode	Kod kontrahenta
Mail	Adres e-mail kontrahenta
PhoneNumber	Nr telefonu kontrahenta
CustomerType	Rodzaj kontrahenta (0 – osoba fizyczna / 1 – podmiot gospodarczy)
RepresentativeFirstName	Imię przedstawiciela
RepresentativeLastName	Nazwisko przedstawiciela
Address	Sekcja z adresem kontrahenta
$id	Numer porządkowy w ramach odpowiedzi JSON
Street	Ulica
BuildingNumber	Numer budynku
FlatNumber	Lokal
PostalCode	Kod pocztowy
City	Poczta
Id	ID adresu w bazie danych
CustomerStatus	Status kontrahenta: 0 - krajowy 1 - wewnątrzunijny 2 - pozaunijny 3 - wewnątrzunijny trójstronny 10 - procedura OSS
Id	ID kontrahenta w bazie danych

Przykładowa odpowiedź JSON: [code_snippet id=33] Możliwe jest także pobranie karty określonego kontrahenta: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/customers/{id} oraz pobieranie danych o określonym NIP: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/customers/?nip={nip} Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/customers/?nip=6770065406   Dostępne jest również filtrowanie listy kontrahentów:

• wg nazwy: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/customers/?$filter=Name eq {nazwa}
• wg adresu e-mail: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/customers/?$filter=Mail eq {adres_email}

Wskazówka

Filtrować można z użyciem kilku kryteriów wykorzystując wspierane operatory logiczne: or, and, not oraz operatory do porównań: eq (równość), ne (nierówność), gt (większe od), ge (większe lub równe), lt (mniejsze od), le (mniejsze lub równe)

Przykład

https://app.comarchbetterfly.pl/api2/public/v1.2/customers/?$filter=Name eq 'Comarch' https://app.comarchbetterfly.pl/api2/public/v1.2/customers/?$filter=Mail eq 'demo@comarch.pl'

DODAWANIE NOWEGO KONTRAHENTA

Dodawanie kontrahenta: [POST] https://app.comarchbetterfly.pl/api2/public/v1.2/customers Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
Name	Nazwa kontrahenta	Tak
CountryCode	Oznaczenie kraju kontrahenta	W wybranych przypadkach, zależnie od rodzaju kontrahenta4
CustomerTaxNumber	Identyfikator podatkowy NIP/PESEL	Nie
CustomerCode	Kod kontrahenta	Nie1
Mail	Adres e-mail kontrahenta	Nie
PhoneNumber	Nr telefonu kontrahenta	Nie
CustomerType	Rodzaj kontrahenta (0 – osoba fizyczna / 1 – podmiot gospodarczy)	Nie2
RepresentativeFirstName	Imię przedstawiciela	Nie
RepresentativeLastName	Nazwisko przedstawiciela	Nie
Address	Sekcja z adresem kontrahenta
Street	Ulica	Nie
BuildingNumber	Numer domu	Nie
FlatNumber	Lokal	Nie
PostalCode	Kod pocztowy	Nie
City	Poczta	Nie
CustomerStatus	Status kontrahenta: 0 - krajowy 1 - wewnątrzunijny 2 - pozaunijny 3 - wewnątrzunijny trójstronny 10 - procedura OSS	Nie3

1) W przypadku braku kodu zostanie on nadany poprzez serwer. 2) W przypadku braku rodzaju zostanie zastosowane ustawienie domyślne (podmiot gospodarczy). 3) W przypadku braku statusu zostanie on nadany wg kodu kraju, a w przypadku braku kodu kraju zostanie zastosowane ustawienie domyślne (kontrahent krajowy) 4) Kod kraju jest obowiązkowy dla kontrahentów wewnątrzunijnych i procedury OSS. Przykładowe zapytanie JSON: [code_snippet id=34] W odpowiedzi zostanie wysłane ID dodanego kontrahenta.

EDYCJA KONTRAHENTA

Edycja kontrahenta: [PUT] https://app.comarchbetterfly.pl/api2/public/v1.2/customers Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
Name	Nazwa kontrahenta	Tak
CountryCode	Oznaczenie kraju kontrahenta	W wybranych przypadkach, zależnie od rodzaju kontrahenta.
CustomerTaxNumber	Identyfikator podatkowy NIP/PESEL	Nie
CustomerCode	Kod kontrahenta	Nie
Mail	Adres e-mail kontrahenta	Nie
PhoneNumber	Nr telefonu kontrahenta	Nie
CustomerType	Rodzaj kontrahenta (0 – osoba fizyczna / 1 – podmiot gospodarczy)	Nie
RepresentativeFirstName	Imię przedstawiciela	Nie
RepresentativeLastName	Nazwisko przedstawiciela	Nie
Address	Sekcja z adresem kontrahenta
Street	Ulica	Nie
BuildingNumber	Numer domu	Nie
FlatNumber	Lokal	Nie
PostalCode	Kod pocztowy	Nie
City	Poczta	Nie
Id	Id adresu	Nie
Id	Id kontrahenta	Tak
CustomerStatus	Status kontrahenta: 0 - krajowy 1 - wewnątrzunijny 2 - pozaunijny 3 - wewnątrzunijny trójstronny 10 - procedura OSS	Nie

Uwaga

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

W odpowiedzi zostanie wysłany status i ewentualnie JSON odpowiedzi: Przykładowe zapytanie JSON (dodanie adresu e-mail dla kontrahenta o Id=2): [code_snippet id=35] Przykładowa odpowiedź JSON – status 204 No Content - operacja zakończona powodzeniem.

USUWANIE KARTY KONTRAHENTA

Usuwanie kontrahenta: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.2/customers/XXX (gdzie XXX to Id kontrahenta w bazie danych) Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/customers/3 Przykładowa odpowiedź JSON – status 204 No Content - operacja zakończona powodzeniem.

POBIERANIE FAKTUR KORYGUJĄCYCH

Pobieranie faktur sprzedaży: [GET] https://app.comarchbetterfly.pl/api2/public/v1.7/correctiveinvoices Opis struktury JSON odpowiedzi:

Parametr	Opis
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 - 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
BankAccountNumber	Numer rachunku bankowego
SalesDate	Data sprzedaży
InvoiceType	Algorytm obliczania (0 - od netto / 1 - od brutto)
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)
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
PaymentFormKsef	Forma płatności KSeF: 1 - Gotówka 2 - Karta 3 - Bon 4 - Czek 5 - Kredyt 6 - Przelew 7 - Płatność mobilna 8 - Płatność inna
CorrectedId	Id dokumentu korygowanego
CorrectionReasonText	Przyczyna korekty
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
DocumentCreatedByTaxPayer	Dokument utworzony przez: true - Płatnika VAT false - Podatnika zwolnionego z VAT
Items	Pozycje dokumentu
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
ProductName	Nazwa produktu
ProductDescription	Opis produktu
UnitOfMeasurement	Jednostka miary
VatRateId	Id stawki VAT - do pobrania ze słownika unijnych stawek VAT tutaj
CorrectedId	Id pozycji korygowanej w bazie danych (pozycji na dokumencie korygowanym)
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)
Confirmed	Dokument zatwierdzony (true / false)
Cancelled	Dokument anulowany (true / false)
Id	Id dokumentu w bazie danych

Przykładowa odpowiedź JSON: [code_snippet id=66]

Wskazówka

W API obsługiwane są korekty w walucie PLN. W walucie obcej dostępne jest tylko pobieranie korekt. Nie są obsługiwane dokumenty anulowane.

DODAWANIE NOWEGO DOKUMENTU FAKTURY KORYGUJĄCEJ

Dodawanie faktury korygującej: [POST] https://app.comarchbetterfly.pl/api2/public/v1.7/correctiveinvoices?documentId=XXX (gdzie XXX to Id dokumentu faktury korygowanej w bazie danych) W odpowiedzi zostanie wysłane ID dodanego dokumentu faktury korygującej z wartościami identycznymi jak na fakturze korygowanej. W kolejnym kroku należy przy wykorzystaniu metody [PUT] nanieść odpowiednie modyfikacje wynikające z procesu korygowania dokumentu.

EDYCJA FAKTURY KORYGUJĄCEJ

Edycja faktury sprzedaży: [PUT] https://app.comarchbetterfly.pl/api2/public/v1.7/correctiveinvoices Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
PaymentStatus	Status płatności (0 – niezapłacona, 1 – zapłacona całkowicie)	Nie
KSeFData	Dane dokumentu związane z KSeF	Nie
PaymentFormKsef	Forma płatności KSeF	Nie. W przypadku ustawienia wartości 8 (Płatność inna) opis płatności do KSeF zostanie ustawiony na nazwę formy płatności wybranej na dokumencie.
PaymentTypeId	Id formy płatności	Tak
PaymentDeadline	Termin płatności	Nie
BankAccountId	Id rachunku bankowego	Nie
SalesDate	Data sprzedaży	Nie
Items	Pozycje dokumentu	Nie, chyba że korekta dotyczy pozycji (korygowana jest ilość, cena netto stawka VAT lub opis) - wtedy należy podać wszystkie poniższe parametry
ProductId	Id produktu	Nie, jw.
Quantity	Ilość	Nie, jw.
ProductCurrencyPrice	Cena sprzedaży	Nie, jw.
ProductDescription	Opis produktu	Nie, jw.
VatRateId	Id stawki VAT - do pobrania ze słownika stawek VAT tutaj	Nie, jw.
Id	Id pozycji dokumentu w bazie danych	Nie, jw.
Description	Opis dokumentu	Nie
CorrectionReasonText	Przyczyna korekty	Nie
IsOSSProcedure	Oznaczenie procedury OSS (true / false)	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 interfejs API można edytować jednie faktury zapisane do bufora.

  W odpowiedzi zostanie wysłany status i ewentualnie JSON odpowiedzi. Przykładowe zapytanie JSON (zwrot towaru, faktura korygująca o Id=23323962): [code_snippet id=42] Przykładowa odpowiedź JSON – status 204 No Content - operacja zakończona powodzeniem.

ZATWIERDZANIE FAKTUR KORYGUJĄCYCH

Zatwierdzanie faktur korygujących: [PUT] https://app.comarchbetterfly.pl/api2/public/v1.7/correctiveinvoices/confirm W odpowiedzi zostanie wysłany status i JSON odpowiedzi. [code_snippet id=43]

USUWANIE FAKTURY KORYGUJĄCYCH

Usuwanie faktury korygującej: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.7/correctiveinvoices/XXX (gdzie XXX to Id dokumentu faktury korygującej w bazie danych) Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.7/correctiveinvoices/23324066 Przykładowa odpowiedź JSON – status 204 No Content - operacja zakończona powodzeniem.

Wskazówka

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

  Aby dowiedzieć się jak pobrać wydruk faktury korygującej poprzez API - kliknij tutaj.  

KOREKTY DO FAKTUR ZALICZKOWYCH

W przypadku dokumentów korygujących do faktur zaliczkowych należy skorzystać z analogicznych metod jak opisane powyżej dla faktur sprzedaży: [GET] https://app.comarchbetterfly.pl/api2/public/v1.7/correctiveadvanceinvoices [POST] https://app.comarchbetterfly.pl/api2/public/v1.7/correctiveadvanceinvoices?documentId=XXX [PUT] https://app.comarchbetterfly.pl/api2/public/v1.7/correctiveadvanceinvoices [PUT] https://app.comarchbetterfly.pl/api2/public/v1.7/correctiveadvanceinvoices/confirm [DEL] https://app.comarchbetterfly.pl/api2/public/v1.7/correctiveadvanceinvoices/XXX

Wskazówka

W przypadku faktur zaliczkowych dodatkowo zwracane jest pole dotyczące zaliczki: "CurrencyAdvance". Pole jest możliwe do edycji. W odróżnieniu od korekt do faktur sprzedaży, w przypadku korekt do faktur zaliczkowych nie można edytować ilości, ceny oraz stawki VAT produktów.

KOREKTY DO FAKTUR ZAKUPU

W przypadku dokumentów korygujących do faktur zakupu należy skorzystać z poniższych metod: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/correctivepurchaseinvoices [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/correctivepurchaseinvoices/XXX (gdzie XXX to Id dokumentu)

Wskazówka

Możliwe jest tylko pobierania korekt do faktu zakupu w walucie PLN i w walucie obcej

KOREKTY DO FAKTUR VAT MARŻA

W przypadku dokumentów korygujących do faktur VAT marża należy skorzystać z poniższych metod: [GET] https://app.comarchbetterfly.pl/api2/public/v1.5/correctiveprofitmargininvoices [GET] https://app.comarchbetterfly.pl/api2/public/v1.5/correctiveprofitmargininvoices/XXX (gdzie XXX to Id dokumentu)

Wskazówka

Możliwe jest tylko pobierania korekt do faktur VAT marża w walucie PLN i w walucie obcej

PROCEDURA OSS

W systemie Comarch Betterfly istnieje możliwość zastosowania procedury OSS w odniesieniu do transakcji handlowych zawieranych z kontrahentami z krajów UE. Więcej informacji na temat procedury OSS znajduje się tutaj: Jak obsłużyć pakiet VAT e-commerce w Handlu? Aby wystawić dokument w procedurze OSS należy:

• wskazać na dokumencie kontrahenta ze statusem "Procedura OSS". Dodanie takiego kontrahenta jest możliwe także przez interfejs API – przy użyciu metody Kontrahenci w wersji 1.2
• określić czy do danej transakcji będą stosowane mechanizmy procedury OSS. W związku z tym w API zostały dodane dwie nowe metody: Faktura sprzedaży i Faktura proforma w wersji 1.2, zawierające nowe pola związane z OSS.
• podać kraj i stawkę VAT, wg której powinna być realizowana sprzedaż w procedurze OSS. Do tego celu można skorzystać z dodatkowych metod opisanych poniżej.

 

POBIERANIE KODÓW KRAJÓW UE

Pobieranie kodów krajów UE: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/vatrates/countries  

POBIERANIE ZAGRANICZNYCH STAWEK VAT

Pobieranie zagranicznych stawek VAT dla krajów UE: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/vatrates Opis struktury JSON zapytania:

Parametr	Opis
RateId	Id stawki VAT
Rate	Wartość stawki VAT
Symbol	Oznaczenie stawki VAT
CountryCode	Kod kraju

 

POBIERANIE PRODUKTÓW

Pobieranie produktów: [GET] https://app.comarchbetterfly.pl/api2/public/products Opis struktury JSON odpowiedzi:

Parametr	Opis
$id	Numer porządkowy w ramach odpowiedzi JSON
Name	Nazwa produktu
Description	Opis produktu
ItemCode	Numer klasyfikacyjny PKWiU
ProductCode	Kod produktu
UnitOfMeasurment	Jednostka miary
Rate	Oznaczenie odpowiedniej stawki VAT wg poniższego klucza: 9 – 23% 8 – 8% 7 – 5% 6 – 4% 2 – 0% 1 – zwolniony 0 – nie podlega
SaleNetPrice	Cena netto sprzedaży w PLN
SaleGrossPrice	Cena brutto sprzedaży w PLN
Quantity	Ilość produktu na stanie magazynowym
ProductType	Rodzaj produktu: 0 - usługa 1 - towar 2 - towar z kontrolą stanu
Id	ID produktu w bazie danych

Przykładowa odpowiedź JSON: [code_snippet id=19] Możliwe jest także pobranie karty określonego produktu. [GET] https://app.comarchbetterfly.pl/api2/public/products/XXX (gdzie XXX to Id produktu w bazie danych) Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/products/10951199 Przykładowa odpowiedź JSON: [code_snippet id=20] Dostępne jest również opcja filtrowanie listy produktów:

• wg nazwy: [GET] https://app.comarchbetterfly.pl/api2/public/products/?$filter=Name eq {nazwa}
• wg kodu: [GET] https://app.comarchbetterfly.pl/api2/public/products/?$filter=ProductCode eq {kod_produktu}

Wskazówka

Filtrować można z użyciem kilku kryteriów wykorzystując wspierane operatory logiczne: or, and, not oraz operatory do porównań: eq (równość), ne (nierówność), gt (większe od), ge (większe lub równe), lt (mniejsze od), le (mniejsze lub równe)

Przykład

[GET] https://app.comarchbetterfly.pl/api2/public/products/?$filter=Name eq 'Produkt' or ProductCode eq 'P/000001' [GET] https://app.comarchbetterfly.pl/api2/public/products/?$filter=SaleGrossPrice ge 199.99 and SaleGrossPrice le 300

 

DODAWANIE NOWEGO PRODUKTU

Dodawanie produktu: [POST] https://app.comarchbetterfly.pl/api2/public/products Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
Name	Nazwa produktu	Tak
Description	Opis produktu	Nie
ItemCode	Numer klasyfikacyjny PKWiU	Nie
ProductCode	Kod produktu	Nie1
UnitOfMeasurment	Jednostka miary	Tak
SaleNetPrice	Cena netto sprzedaży w PLN	Nie2
SaleGrossPrice	Cena brutto sprzedaży w PLN	Nie2
Rate	Oznaczenie odpowiedniej stawki VAT wg poniższego klucza: 9 – 23% 8 – 8% 7 – 5% 6 – 4% 2 – 0% 1 – zwolniony 0 – nie podlega	Tak

1) W przypadku braku kodu zostanie on nadany poprzez serwer. 2) W przypadku podania ceny brutto, cena netto zostanie wyliczona automatycznie. W przypadku podania ceny netto, cena brutto zostanie wyliczona automatycznie. W przypadku podania obu cen, system wyliczy cenę brutto od podanej ceny netto. Przykładowe zapytanie JSON: [code_snippet id=21] W odpowiedzi zostanie wysłane ID dodanego produktu.

EDYCJA KARTY PRODUKTU

Edycja produktu: [PUT] https://app.comarchbetterfly.pl/api2/public/products Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
Name	Nazwa produktu	Tak
Description	Opis produktu	Nie
ItemCode	Numer klasyfikacyjny PKWiU	Nie
ProductCode	Kod produktu	Nie
UnitOfMeasurment	Jednostka miary	Tak
SaleNetPrice	Cena netto sprzedaży w PLN	Nie
SaleGrossPrice	Cena brutto sprzedaży w PLN	Nie
Rate	Oznaczenie odpowiedniej stawki VAT wg poniższego klucza: 9 – 23% 8 – 8% 7 – 5% 6 – 4% 2 – 0% 1 – zwolniony 0 – nie podlega	Tak
Id	ID produktu w bazie danych	Tak

Uwaga

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

W odpowiedzi zostanie wysłany status i ewentualnie JSON odpowiedzi: Przykładowe zapytanie JSON (zmiana ceny dla produktu o Id=12156943): [code_snippet id=22] Przykładowa odpowiedź JSON – status 204 No Content - operacja zakończona powodzeniem.

USUWANIE PRODUKTU

Usuwanie produktu: [DEL] https://app.comarchbetterfly.pl/api2/public/products/XXX (gdzie XXX to Id produktu w bazie danych) Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/products/4 Przykładowa odpowiedź JSON – status 204 No Content - operacja zakończona powodzeniem.

Uwaga

Nie można usuwać produktów, które posiadają aktywną funkcję kontroli stanu magazynowego.

PRZEKSZTAŁCANIE FAKTUR ZALICZKOWYCH

W programie Comarch Betterfly można wystawić m.in.:

• jedną fakturę zaliczkową i przekształcić ją do jednej faktury finalnej
• wiele powiązanych faktur zaliczkowych i przekształcić je do jednej faktury finalnej
• wiele powiązanych faktur zaliczkowych i przekształcić je do wielu faktur finalnych

[POST] https://app.comarchbetterfly.pl/api2/public/v1.2/advanceInvoices/{id}/finalize?convertAll=false Metoda pozwala na przekształcenie tylko wskazanej faktury zaliczkowej (id) do faktury finalnej. Przykładowe zapytanie: [POST] https://app.comarchbetterfly.pl/api2/public/v1.2/advanceInvoices/2901096/finalize?convertAll=false [POST] https://app.comarchbetterfly.pl/api2/public/v1.2/advanceInvoices/{id}/finalize?convertAll=true Metoda pozwala na przekształcenie wskazanej faktury zaliczkowej (id) oraz wszystkich faktur z nią powiązanych do jednej faktury finalnej. Przykładowe zapytanie: [POST] https://app.comarchbetterfly.pl/api2/public/v1.2/advanceInvoices/2901096/finalize?convertAll=true W odpowiedzi przesyłana jest faktura finalna będąca efektem przekształcenia dokumentów. Przykładowa odpowiedź JSON: [code_snippet id=36]   Dodatkowo użytkownik może wcześniej sprawdzić czy dany dokument kwalifikuje się do przekształcenia do faktury finalnej metodą weryfikującą: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/advanceInvoices/{id}/canFinalize?convertAll=true Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/advanceInvoices/2901096/canFinalize?convertAll=true W odpowiedzi zostanie wysłana informacja true albo false. W operacji przekształcania lub weryfikowania faktury zaliczkowej mogą pojawić się następujące komunikaty, które dotyczą ostatniego powiązanego dokumentu: 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=37]

POBIERANIE RACHUNKÓW BANKOWYCH

[GET] https://app.comarchbetterfly.pl/api2/public/bankaccounts Opis struktury JSON odpowiedzi:

Parametr	Opis
$id	Numer porządkowy w ramach odpowiedzi JSON
AccountNumber	Numer rachunku
BankName	Nazwa banku
Symbol	Symbol banku
ReportingPeriod	Okres raportów 1 – Dzienny 2 – Tygodniowy 3 – Miesięczny 4 – Bezterminowy
Primary	Czy rachunek jest jako "domyślny" - true (TAK) / false (NIE)
Id	Id rachunku bankowego

Przykładowa odpowiedź JSON: [code_snippet id=29] Możliwe jest także pobranie danych dla określonego rachunku. [GET] https://app.comarchbetterfly.pl/api2/public/bankaccounts/XXX (gdzie XXX to Id rachunku bankowego w bazie danych) Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/bankaccounts/8844 Przykładowa odpowiedź JSON: [code_snippet id=30]

Wskazówka

Metoda pobierania rachunków bankowych pomija pozycje, które oznaczono jako "Rachunek VAT", ponieważ nie jest możliwe wskazanie ich na fakturze sprzedaży.

 

DODAWANIE NOWEGO RACHUNKU BANKOWEGO

[POST] https://app.comarchbetterfly.pl/api2/public/bankaccounts Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
AccountNumber	Numer rachunku	TAK
BankName	Nazwa banku	NIE
Symbol	Symbol banku	TAK
ReportingPeriod	Okres raportów 1 – Dzienny 2 – Tygodniowy 3 – Miesięczny 4 – Bezterminowy	TAK
Primary	Czy rachunek jest jako "domyślny" - true (TAK) / false (NIE)	NIE

 

Wskazówka

Rachunki bankowe dodawane są w walucie PLN.

Wskazówka

Zmiana domyślnego rachunku bankowego (parametr: Primary) w aplikacji na stronie www jest widoczna dopiero po ponownym zalogowaniu bądź odświeżeniu strony konfiguracji Comarch Betterfly (ctr+F5).

Przykładowe zapytanie JSON: [code_snippet id=31] W odpowiedzi zostanie wysłane ID dodanego rachunku bankowego.  

EDYCJA RACHUNKU BANKOWEGO

[PUT] https://app.comarchbetterfly.pl/api2/public/bankaccounts Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
AccountNumber	Numer rachunku	TAK
BankName	Nazwa banku	NIE
Symbol	Symbol banku	TAK1
ReportingPeriod	Okres raportów 1 – Dzienny 2 – Tygodniowy 3 – Miesięczny 4 – Bezterminowy	TAK
Primary	Czy rachunek jest jako "domyślny" - true (TAK) / false (NIE)	NIE
ID	Id rachunku bankowego w bazie danych	TAK

Uwaga

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

1) Symbol banku nadawany jest podczas dodawania rachunku i nie można go edytować. Przykładowe zapytanie JSON (zmiana okresu raportu dla rachunku bankowego o Id=8844): [code_snippet id=32] Przykładowa odpowiedź JSON – status 204 No Content – operacja zakończona powodzeniem.  

USUWANIE RACHUNKU BANKOWEGO

Usuwanie rachunku bankowego: [DEL] https://app.comarchbetterfly.pl/api2/public/bankaccounts/XXX (gdzie XXX to Id rachunku bankowego w bazie danych)

Uwaga

Nie można usunąć domyślnego rachunku bankowego.

Uwaga

Usunięcie rachunku bankowego nie jest możliwe gdy jest powiązany z dokumentem, zapłatą, raportem lub został podany w konfiguracji jako rachunek płatności dla deklaracji.

Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/bankaccounts/8844 Przykładowa odpowiedź JSON – status 204 No Content – operacja zakończona powodzeniem.

POBIERANIE FAKTUR ZAKUPU Z REJESTRU VAT ZAKUPU

Pobieranie faktur z rejestru VAT zakupu: [GET] https://app.comarchbetterfly.pl/api2/public/v1.8/vatpurchasebooks Opis struktury JSON odpowiedzi:

Parametr	Opis
PaymentStatus	Status płatności (0 – niezapłacona, 1 – zapłacona całkowicie, 2 – zapłacona częściowo)
CustomerId	Id dostawcy na dokumencie
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
CustomerBankAccountNumber	Numer rachunku bankowego dostawcy
CustomerBankAccountName	Nazwa banku dostawcy
BankAccountId	Id rachunku bankowego
BankAccountNumber	Numer rachunku bankowego
PurchaseDate	Data zakupu
NetTotal	Wartość netto dla całego dokumentu
CurrencyNetTotal	Wartość netto w walucie obcej dla całego dokumentu
GrossTotal	Wartość brutto dla całego dokumentu
CurrencyGrossTotal	Wartość brutto w walucie obcej dla całego dokumentu
VatTotal	Wartość VAT dla całego dokumentu
CurrencyVatTotal	Wartość VAT w walucie obcej dla całego dokumentu
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
Description	Opis dokumentu
IssueDate	Data wystawienia dokumentu
ReceiptDate	Data wpływu
Number	Numer obcy dokumentu
Correction	Oznaczenie czy faktura korygująca
CorrectedDocumentNumber	Numer korygowanej faktury
InternalDocument	Oznaczenie czy dokument wewnętrzny
IncludedInJPKV7	Kwalifikacja dokumentu do deklaracji JPK_V7
VATDeclatationDate	Rok i miesiąc, w którym faktura jest zakwalifikowana do JPK_V7
IncludedInVATUE	Kwalifikacja dokumentu do deklaracji VAT-UE
VATUEDeclarationDate	Rok i miesiąc, w którym faktura jest zakwalifikowana do deklaracji VAT-UE
JpkProceduresSymbols	Tablica kodów JPK_V7
KsefNumber	Numer KSeF
KsefDate	Data przyjęcia dokumentu przez KSeF
CategoryId	Identyfikator kategorii księgowej (słownik kategorii dostępny tutaj: Kategorie)
AccountingDescription	Opis księgowy
Items	Pozycje dokumentu
VatRateId	Id stawki VAT – do pobrania ze słownika stawek VAT
ItemNetValue	Kwota netto na pozycji
ItemNetValueCurrency	Kwota netto na pozycji w walucie dokumentu
ItemVATValue	Kwota VAT na pozycji
ItemVATValueCurrency	Kwota VAT na pozycji w walucie dokumentu
ItemGrossValue	Kwota brutto na pozycji
ItemGrossValueCurrency	Kwota VAT na pozycji
FieldInJPKV7	Pole w pliku JPK_V7. Oznaczenie słownika pola JPK_V7 wg poniższego klucza: 0 - Nie uwzględniaj w pliku JPK_V7 21 - (P_40) Nabycie środków trwałych 22 - (P_42) Nabycie pozostałe 24 - (P_44) Korekta podatku naliczonego od nabycia środków trwałych 25 - (P_45) Korekta podatku naliczonego od pozostałych nabyć
FieldInVATUE	Pole na deklaracji VAT-UE. Oznaczenie słownika pola VAT-UE wg poniższego klucza: 0 - Nie uwzględniaj w deklaracji 2 - D. Nabycie towarów
ItemType	Rodzaj produktu: 0 - usługa, 1 - towar
VAT50deduction	Czy odliczenie 50% VAT, 1 - tak, 0 - nie
PercentAsExpenses	Ile procent w koszty
AccountNumber	Numer konta księgowego
Id	Id pozycji dokumentu w bazie danych

Przykładowa odpowiedź JSON: [code_snippet id=68]   Możliwe jest także pobranie danych konkretnego dokumentu faktury zakupu: [GET] https://app.comarchbetterfly.pl/api2/public/v1.8/vatpurchasebooks/XXX (gdzie XXX to Id dokumentu faktury zakupu w bazie danych) Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.8/vatpurchasebooks/14785511  

EDYCJA KATEGORII DLA REJESTRU VAT ZAKUPU

Seryjna edycja kategorii w rejestrze vat zakupu: [PUT] https://app.comarchbetterfly.pl/api2/public/v1.8/vatpurchasebooks/category Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
EntitiesIds	Identyfikatory rejestrów VAT zakupu. Operacja jest zbiorcza czyli można podać wiele dokumentów naraz.	Tak
CategoryId	Identyfikator kategorii księgowej (słownik kategorii dostępny tutaj: Kategorie)	Tak

Przykładowe zapytanie JSON (zmiana kategorii na zapisach w rejestrze VAT zakupu o Id=1283138, Id=1283123): [code_snippet id=69] Przykładowa odpowiedź JSON – status 204 No Content – operacja zakończona powodzeniem.

EDYCJA OPISU KSIĘGOWEGO DLA REJESTRU VAT ZAKUPU

Seryjna edycja opisu księgowego w rejestrze vat zakupu: [PUT] https://app.comarchbetterfly.pl/api2/public/v1.8/vatpurchasebooks/accountingdescription Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
EntitiesIds	Identyfikatory rejestrów VAT zakupu. Operacja jest zbiorcza czyli można podać wiele dokumentów naraz.	Tak
AccountingDescription	Opis księgowy do przypisania wskazanym dokumentom. Podanie null oznacza wyczyszczenie (usunięcie) opisu z tych dokumentów.	Tak

Przykładowe zapytanie JSON (zmiana opisu księgowego na zapisach w rejestrze VAT zakupu o Id=1283138, Id=1283123): [code_snippet id=70] Przykładowa odpowiedź JSON – status 204 No Content – operacja zakończona powodzeniem.  

WYDRUKI DOKUMENTÓW

 

1) Wydruk dokumentu z szablonem przypisanym do kontrahenta

Pobieranie wydruku dokumentu:

faktura sprzedaży	[GET] https://app.comarchbetterfly.pl/api2/public/v1.4/invoices/{id}/print
faktura proforma	[GET] https://app.comarchbetterfly.pl/api2/public/v1.4/proformas/{id}/print
faktura zaliczkowa	[GET] https://app.comarchbetterfly.pl/api2/public/v1.4/advanceInvoices/{id}/print
faktura korygująca	[GET] https://app.comarchbetterfly.pl/api2/public/v1.4/correctiveinvoices/{id}/print
faktura korygująca do faktury zaliczkowej	[GET] https://app.comarchbetterfly.pl/api2/public/v1.4/correctiveadvanceinvoices/{id}/print
faktura VAT marża	[GET] https://app.comarchbetterfly.pl/api2/public/v1.4/profitmargininvoices/{id}/print

W odpowiedzi zostanie wysłany wydruk domyślny – tzn. wydruk standardowy lub wydruk użytkownika przypisany do kontrahenta i zapisany w formacie Base64. Tak zakodowany wydruk można otworzyć w dowolnej przeglądarce internetowej i zapisać jako PDF.  

2) Wydruk dokumentu z szablonem utworzonym przez użytkownika

Pobieranie wydruku dokumentu:

faktura sprzedaży	[GET] https://app.comarchbetterfly.pl/api2/public/v1.4/invoices/{id}/print?customPrintId={customPrintId}
faktura proforma	[GET] https://app.comarchbetterfly.pl/api2/public/v1.4/proformas/{id}/print?customPrintId={customPrintId}
faktura zaliczkowa	[GET] https://app.comarchbetterfly.pl/api2/public/v1.4/advanceInvoices/{id}/print?customPrintId={customPrintId}
faktura korygująca	[GET] https://app.comarchbetterfly.pl/api2/public/v1.4/correctiveinvoices/{id}/print?customPrintId={customPrintId}
faktura korygująca do faktury zaliczkowej	[GET] https://app.comarchbetterfly.pl/api2/public/v1.4/correctiveadvanceinvoices/{id}/print?customPrintId={customPrintId}
faktura VAT marża	[GET] https://app.comarchbetterfly.pl/api2/public/v1.4/profitmargininvoices/{id}/print?customPrintId={customPrintId}

W odpowiedzi zostanie wysłany wydruk dokumentu zapisany w formacie Base64. Tak zakodowany wydruk można otworzyć w dowolnej przeglądarce internetowej i zapisać jako PDF.  

Wskazówka

Listę szablonów można pobrać poprzez żądanie: [GET] https://app.comarchbetterfly.pl/api2/public/customprints

Parametr	Opis
$id	Numer porządkowy w ramach odpowiedzi JSON
Name	Nazwa wydruku
Language	Wersja językowa (PL / EN / DE / FR)
Type	0 – faktura sprzedaży, 1 - faktura zaliczkowa, 2 - faktura finalna, 3 - korekta faktury sprzedaży, 4 - korekta faktury zaliczkowej, 7 – faktura proforma, 15 - faktura VAT marża
Id	Id szablonu wydruku

Przykładowa odpowiedź JSON: [code_snippet id=24]

  Potrzebujesz więcej informacji na temat wydruków? Zobacz artykuły powiązane: Jak wstawić swoje logo na wydruku?  

POBIERANIE PŁATNOŚCI

Pobieranie płatności: [GET] https://app.comarchbetterfly.pl/api2/public/v1.5/paymentdetails Opis struktury JSON odpowiedzi:

Parametr	Opis
PaymentId	Id płatności
PaymentType	INCOME - faktura sprzedaży OUTCOME - faktura zakupu INCOME_TAX - zaliczki i deklaracje dotyczące podatku dochodowego TAX_OR_FEE - inne podatki i opłat (składki PPK) VAT - podatek VAT SOCIAL_INSURANCE – składki ZUS
DocumentNumber	Numer dokumentu
CorrectedDocumentId	Jeżeli płatność jest do korekty - Id dokumentu korygowanego
CorrectedDocumentType	Jeżeli płatność jest do korekty - typ dokumentu korygowanego, przyjmuje wartości zgodne z opisem do pola DocumentType
CorrectionReason	Jeżeli płatność jest do korekty - przyczyna korekty jeżeli uzupełniono na fakturze
CreationDate	Data utworzenia płatności
UpdateDate	Data ostatniej aktualizacji płatności
IssueDate	Data płatności/dokumentu
DueDate	Termin płatności
SenderTaxId	NIP nadawcy płatności
SenderName	Nazwa firmy nadawcy płatności
SenderAddress	Adres firmy nadawcy płatności
Street	Ulica
HouseNumber	Numer domu
ApartmentNumbe	Numer lokalu
ZipCode	Kod pocztowy
City	Miasto
Region	Województwo
RecipientTaxId	NIP odbiorcy płatności
RecipientName	Nazwa firmy odbiorcy płatności
RecipientAddress	Adres firmy odbiorcy płatności
Street	Ulica
HouseNumber	Numer domu
ApartmentNumbe	Numer lokalu
ZipCode	Kod pocztowy
City	Miasto
Region	Województwo
RecipientAccountNumber	Numer rachunku bankowego odbiorcy płatności (w formacie IBAN czyli z prefiksem kraju)
SenderAccountNumber	Numer rachunku bankowego nadawcy płatności (w formacie IBAN czyli z prefiksem kraju)
Amount	Kwota płatności/dokumentu
VatAmount	Kwota VAT z dokumentu
SplitPayment	Czy zastosowano Metodę Podzielonej Płatności: true - tak, false - nie
Payable	Czy podlega rozliczeniu: true - tak, status płatności Nie rozliczono lub Częściowo rozliczono false - nie, status płatności to Anulowany lub Całkowicie rozliczony
Currency	Waluta płatności
Balance	Kwota pozostająca do zapłaty
Title	Tytuł płatności (opis do banku)
PaymentStatus	Status płatności: 0 - nierozliczona 1 - częściowo rozliczona 2 - całkowicie rozliczona 4 - niemożliwa do rozliczenia np. płatności do dokumentu, który został anulowany 5 - anulowana
PaymentDirection	Kierunek płatności: 0 - przychód (płatność przychodząca) 1 - rozchód (płatność wychodząca)
ExportStatus	Status wysyłania płatności do banku: 0 - nie wysłana 1 - wysłana do banku/utworzono przelew 2 - przelew zrealizowany po stronie banku
CashAccounting	Czy płatność została wystawiona przez podatnika rozliczającego się metodą kasową: true - tak na powiązanym z płatnością zapisie w rejestrze VAT wybrano kod JPK_V7: MK false - nie
DocumentType	Typ dokumentu źródłowego: Invoice - faktura sprzedaży zwykła lub finalna AdvanceInvoice - faktura zaliczkowa PurchaseInvoice - faktura zakupu CorrectiveInvoice - korekta do faktury sprzedaży CorrectiveAdvanceInvoice - korekta do faktury sprzedaży zaliczkowej CorrectiveFiscalReceipt - korekta do paragonu CorrectivePurchaseInvoice - korekta do faktury zakupu FiscalReceipt - paragon Receipt - rachunek VatSaleBook - faktura sprzedaży dodana bezpośrednio w Rejestrze sprzedaży VAT VatPurchaseBook - faktura zakupu dodana bezpośrednio w Rejestrze zakupów VAT Vat7Declaration - deklaracja VAT/JPK_V7 Pit36Advance - zaliczka na PIT-36 Pit36LAdvance - zaliczka na PIT-36L Pit36Declaration - deklaracja PIT-36 Pit36LDeclaration - deklaracja PIT-36L ProfitMarginInvoice - faktura sprzedaży VAT marża CorrectiveProfitMarginInvoice - korekta faktury sprzedaży VAT marża OpeningBalanceItem - bilansu otwarcia BookEntryItem - zapis księgowegy Cit8Advance - zaliczka na CIT-8 Cit8Declaration - deklaracja CIT-8 PPKContributions - składka PPK ViudoDeclaration - deklaracja VIU-DO Pit28Advance - zaliczka na PIT-28 Pit28Declaration - deklaracja PIT-28 CostBook - dokument w Ewidencji Dodatkowej Kosztów RevenueBook - dokument w Ewidencji Dodatkowej Przychodów None - płatności zaimportowane z Optimy przez IWD

Przykładowa odpowiedź JSON: [code_snippet id=52] Możliwe jest także pobranie szczegółów dla jednej płatności: [GET] https://app.comarchbetterfly.pl/api2/public/v1.5/paymentdetails/XXX (gdzie XXX to Id płatności w bazie danych) Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.5/paymentdetails/2692651 Przykładowa odpowiedź JSON: [code_snippet id=53]  

POBIERANIE STATUSU PŁATNOŚCI

Pobieranie statusu płatności: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/payments W zapytaniu należy podać Id płatności, które mają zostać pobrane W odpowiedzi zostanie wysłany status płatności.

Parametr	Opis
PaymentId	Id płatności
PaymentStatus	0 - nierozliczona 1 - częściowo rozliczona 2 - całkowicie rozliczona 4 - do dokumentu anulowanego 5 - anulowana
Amount	Kwota płatności/dokumentu
Balance	Kwota pozostająca do zapłaty w walucie płatności, dla płatności anulowanej: 0
Currency	Waluta dokumentu/płatności

[code_snippet id=46]   Możliwe jest także pobranie statusu dla jednej płatności: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/payments/XXX (gdzie XXX to Id płatności w bazie danych) Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.4/payments/2692651 Przykładowa odpowiedź JSON: [code_snippet id=47]  

AKTUALIZACJA STATUSU PŁATNOŚCI

Aktualizacja statusu płatności: [PUT] https://app.comarchbetterfly.pl/api2/public/v1.4/payments Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
PaymentIds	Identyfikator płatności, które ma zostać rozliczone. Można podać więcej niż jedną płatność oddzielając Id przecinkami. Oznacza to, że dana wpłata będzie rozliczała więcej dokumentów. Kolejność rozliczania wg kolejności przesłanych Id płatności.	Tak
Cancelled	Czy płatność anulowana: true - tak, false - nie	Tak
PaymentDate	Data płatności	Tak, jeżeli Cancelled jest false
AmountPaid	Kwota zapłacona w walucie dokumentu, znak kwoty warunkuje kierunek płatności	Tak, jeżeli Cancelled jest false
BankAccountNumber	Rachunek bankowy: - dla wpłat - numer rachunku, na który przyszedł przelew, - dla wypłat - numer rachunku, z którego wyszedł przelew	Tak, jeżeli Cancelled jest false
CurrencyCode	Symbol waluty	Nie
CurrencyRateType	Typ kursu waluty	Nie
CurrencyRateDate	Data kursu	Nie
CurrencyConverter	Mianownik kursu waluty	Nie
CurrencyRate	Licznik kursu waluty	Nie
CustomerBankAccountNumber	Rachunek bankowy: - dla wpłat - numer rachunku, na który przyszedł przelew, - dla wypłat - numer rachunku, z którego wyszedł przelew	Nie
CustomerTIN	NIP kontrahenta	Nie
Description	Opis, tytuł płatności	Nie

[code_snippet id=48] W odpowiedzi JSON, mogą pojawić się następujące komunikaty błędów: ErrorCode 0 - Płatność jest już rozliczona i nie może zostać anulowana. ErrorCode 1 - Płatność jest już całkowicie rozliczona (jeżeli status całkowicie rozliczona) ErrorCode 2 - Płatność nie podlega rozliczeniu (jeżeli inny status) ErrorCode 3 - Kierunek płatności nie zgadza się z kierunkiem zapłaty ErrorCode 4 - Waluta płatności różna od waluty zapłaty ErrorCode 5 - W Comarch Betterfly nie ma rachunku o numerze .... Utwórz rachunek. ErrorCode 6 - Nie można rozliczać niezatwierdzonych płatności ErrorCode 7 - Płatność nie została rozliczona ErrorCode 8 - Waluta przypisana do rachunku bankowego nie zgadza się z walutą aktualizowanej płatności. [code_snippet id=49] Zobacz także: API - Historia zmian

POBIERANIE FAKTUR PROFORMA

Pobieranie faktur proforma: [GET] https://app.comarchbetterfly.pl/api2/public/proformas Opis struktury JSON odpowiedzi:

Parametr	Opis
$id	Numer porządkowy w ramach odpowiedzi JSON
PurchasingPartyId	Id kontrahenta na dokumencie
PaymentTypeId	Id formy płatności
BankAccountId	Id rachunku bankowego
InvoiceDocIdNum	Id powiązanej faktury sprzedaży, faktury zaliczkowej lub powiązanego paragonu
Items	Pozycje dokumentu
$id	Numer porządkowy w ramach odpowiedzi JSON
ProductId	Id produktu
Quantity	Ilość
ProductCurrencyNetPrice	Cena netto sprzedaży
ProductDescription	Opis produktu
Id	ID pozycji dokumentu w bazie danych
IssueDate	Data wystawienia dokumentu
Number	Numer dokumentu
Status	Status dokumentu: 0 – nieprzekształcony bezpośrednio do dokumentu sprzedażowego, 1 – przekształcony do faktury sprzedaży, faktury zaliczkowej lub paragonu
Id	ID dokumentu w bazie danych

Przykładowa odpowiedź JSON:

Przykład

Lista faktur proforma, które zostały przekształcone do faktury sprzedaży, faktury zaliczkowej lub paragonu: [GET] https://app.comarchbetterfly.pl/api2/public/proformas/?$filter=InvoiceDocIdNum ne null

  Możliwe jest także pobranie danych na temat określonego dokumentu faktury proforma: [GET] https://app.comarchbetterfly.pl/api2/public/proformas/XXX (gdzie XXX to Id dokumentu proforma w bazie danych) Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/proformas/12 Przykładowa odpowiedź JSON:

DODAWANIE NOWEGO DOKUMENTU FAKTURY PROFORMA

Dodawanie faktury proforma: [POST] https://app.comarchbetterfly.pl/api2/public/proformas

Wskazówka

Faktury proforma dodawane do Comarch Betterfly poprzez API zawsze będą miały status "Zapisane". Wszelkie dalsze przekształcenia należy wykonywać po zalogowaniu do aplikacji.

Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
PurchasingPartyId	Id kontrahenta na dokumencie	Tak
PaymentTypeId	Id formy płatności	Tak
BankAccountId	Id rachunku bankowego	Nie
Items	Pozycje dokumentu	Nie1
ProductId	Id produktu	Tak
Quantity	Ilość	Tak
ProductCurrencyNetPrice	Cena netto sprzedaży	Tak
ProductDescription	Opis produktu	Nie
IssueDate	Data wystawienia dokumentu w formacie RRRR-MM-DD	Nie2

1) 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. 2) 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 proforma. Przykładowa odpowiedź:

EDYCJA FAKTURY PROFORMA

Edycja faktury proforma: [PUT] https://app.comarchbetterfly.pl/api2/public/proformas Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
PurchasingPartyId	Id kontrahenta na dokumencie	Tak
PaymentTypeId	Id formy płatności	Tak
BankAccountId	Id rachunku bankowego	Nie
Items	Pozycje dokumentu	Tak1
ProductId	Id produktu	Tak
Quantity	Ilość	Tak
ProductCurrencyNetPrice	Cena netto sprzedaży	Tak
ProductDescription	Opis produktu	Nie
Id	ID pozycji dokumentu w bazie danych	Nie2
IssueDate	Data wystawienia dokumentu w formacie RRRR-MM-DD	Nie
Id	Id dokumentu w bazie danych	Tak

1) Jeśli edytowana faktura zawiera pozycje. 2) 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 bez przekształceń (Status = 0).

W odpowiedzi zostanie wysłany status i ewentualnie JSON odpowiedzi. Przykładowe zapytanie JSON (zmiana formy płatności na proformie o Id=13): Przykładowa odpowiedź JSON – status 204 No Content - operacja zakończona powodzeniem:  

USUWANIE FAKTURY PROFORMA

Usuwanie faktury proforma: [DEL] https://app.comarchbetterfly.pl/api2/public/proformas/XXX (gdzie XXX to Id dokumentu faktury proforma w bazie danych) Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/proformas/14 Przykładowa odpowiedź JSON – status 204 No Content - operacja zakończona powodzeniem:

Wskazówka

Opcja usuwania faktury proforma jest dostępna tylko dla dokumentów bez przekształceń.

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

POBIERANIE FAKTUR PROFORMA

Pobieranie faktur proforma: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/proformas Opis struktury JSON odpowiedzi:

Parametr	Opis
$id	Numer porządkowy w ramach odpowiedzi JSON
PurchasingPartyId	Id kontrahenta na dokumencie
ReceivingPartyId	Id odbiorcy na dokumencie
PaymentTypeId	Id formy płatności
BankAccountId	Id rachunku bankowego
InvoiceType	Algorytm obliczania (0 - od netto / 1 - od brutto)
OSSProcedureCountryCode	Kod kraju dla procedury OSS - do pobrania ze słownika kodów krajów UE tutaj
IsOSSProcedure	Oznaczenie procedury OSS (true / false)
InvoiceDocIdNum	Id powiązanej faktury sprzedaży, faktury zaliczkowej lub powiązanego paragonu
Items	Pozycje dokumentu
$id	Numer porządkowy w ramach odpowiedzi JSON
ProductId	Id produktu
Quantity	Ilość
ProductCurrencyPrice	Cena netto sprzedaży
ProductDescription	Opis produktu
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 – nieprzekształcony bezpośrednio do dokumentu sprzedażowego, 1 – przekształcony do faktury sprzedaży, faktury zaliczkowej lub paragonu
Id	Id dokumentu w bazie danych

Przykładowa odpowiedź JSON:

Przykład

Lista faktur proforma, które zostały przekształcone do faktury sprzedaży, faktury zaliczkowej lub paragonu: [GET] https://app.comarchbetterfly.pl/api2/public/proformas/?$filter=InvoiceDocIdNum ne null

  Możliwe jest także pobranie danych na temat określonego dokumentu faktury proforma: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/proformas/XXX (gdzie XXX to Id dokumentu proforma w bazie danych) Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/proformas/2901092

DODAWANIE NOWEGO DOKUMENTU FAKTURY PROFORMA

Dodawanie faktury proforma: [POST] https://app.comarchbetterfly.pl/api2/public/v1.2/proformas

Wskazówka

Faktury proforma dodawane do Comarch Betterfly poprzez API zawsze będą miały status "Zapisane". Wszelkie dalsze przekształcenia należy wykonywać po zalogowaniu do aplikacji.

Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
PurchasingPartyId	Id kontrahenta na dokumencie	Tak
ReceivingPartyId	Id odbiorcy na dokumencie	Nie
PaymentTypeId	Id formy płatności	Tak
BankAccountId	Id rachunku bankowego	Nie
InvoiceType	Algorytm obliczania (0 - od netto / 1 - od brutto)	Nie1
OSSProcedureCountryCode	Kod kraju dla procedury VAT OSS	Nie4
IsOSSProcedure	Oznaczenie procedury VAT OSS	Nie
Items	Pozycje dokumentu	Nie2
ProductId	Id produktu	Tak
Quantity	Ilość	Tak
ProductCurrencyPrice	Cena netto sprzedaży	Tak
ProductDescription	Opis produktu	Nie
VatRateId	Id stawki VAT	Nie4
Description	Opis dokumentu	Nie
IssueDate	Data wystawienia dokumentu	Nie3

1) W przypadku braku oznaczenia algorytmu, domyślnie zostanie zastosowane obliczenie od netto. 2) 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. 3) W przypadku braku daty w parametrach, ustawiana będzie data bieżąca. 4) Parametry należy określić w przypadku wskazania kontrahenta o statusie "Procedura OSS". Przykładowe zapytanie JSON: W odpowiedzi zostanie wysłane ID dodanego dokumentu faktury proforma.

EDYCJA FAKTURY PROFORMA

Edycja faktury proforma: [PUT] https://app.comarchbetterfly.pl/api2/public/v1.2/proformas Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
PurchasingPartyId	Id kontrahenta na dokumencie	Tak
ReceivingPartyId	Id odbiorcy na dokumencie	Nie
PaymentTypeId	Id formy płatności	Tak
BankAccountId	Id rachunku bankowego	Nie
InvoiceType	Algorytm obliczania (0 - od netto / 1 - od brutto)	Nie
OSSProcedureCountryCode	Kod kraju dla procedury VAT OSS	Nie3
IsOSSProcedure	Oznaczenie procedury VAT OSS	Nie
Items	Pozycje dokumentu	Nie1
ProductId	Id produktu	Tak
Quantity	Ilość	Tak
ProductCurrencyPrice	Cena netto sprzedaży	Tak
ProductDescription	Opis produktu	Nie
VatRateId	Id stawki VAT	Nie3
Id	Id pozycji dokumentu w bazie danych	Nie2
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 pominięcia numeru Id pozycji podczas operacji edycji, zostanie dodana kolejna pozycja do dokumentu ze wskazanymi parametrami. 3) Parametry należy określić w przypadku wskazania kontrahenta o statusie "Procedura OSS".

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 bez przekształceń (Status = 0).

W odpowiedzi zostanie wysłany status i ewentualnie JSON odpowiedzi. Przykładowe zapytanie JSON (zmiana ilości sztuk na proformie o Id=2901094): Przykładowa odpowiedź JSON – status 204 No Content - operacja zakończona powodzeniem.  

USUWANIE FAKTURY PROFORMA

Usuwanie faktury proforma: [DEL] https://app.comarchbetterfly.pl/api2/public/proformas/XXX (gdzie XXX to Id dokumentu faktury proforma w bazie danych) Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/proformas/2901094 Przykładowa odpowiedź JSON – status 204 No Content - operacja zakończona powodzeniem.

Wskazówka

Opcja usuwania faktury proforma jest dostępna tylko dla dokumentów bez przekształceń.

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

POBIERANIE FAKTUR SPRZEDAŻY

Pobieranie faktur sprzedaży: [GET] https://app.comarchbetterfly.pl/api2/public/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)
PurchasingPartyId	Id kontrahenta na dokumencie
PaymentTypeId	Id formy płatności
BankAccountId	Id rachunku bankowego
SalesDate	Data sprzedaży
Items	Pozycje dokumentu
$id	Numer porządkowy w ramach odpowiedzi JSON
ProductId	Id produktu
Quantity	Ilość
ProductCurrencyNetPrice	Cena netto sprzedaży
ProductDescription	Opis produktu
Id	ID pozycji dokumentu w bazie danych
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/invoices/XXX (gdzie XXX to Id dokumentu faktury sprzedaży w bazie danych) Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/invoices/11 Przykładowa odpowiedź JSON:

Wskazówka

W Comarch Betterfly API obsługiwane są faktury sprzedaży w buforze. Dodatkowo można pobrać dane i wydruki dla faktur zatwierdzonych na stałe. Nie są obsługiwane faktury zaliczkowe, faktury finalne, dokumenty anulowane oraz korekty.

Wskazówka

W ERP API obsługiwane są faktury w walucie PLN. Nie są obsługiwane faktury w walutach obcych.

DODAWANIE NOWEGO DOKUMENTU FAKTURY SPRZEDAŻY

Dodawanie faktury sprzedaży: [POST] https://app.comarchbetterfly.pl/api2/public/invoices Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
PaymentStatus	Status płatności (0 - niezapłacona, 1 - zapłacona całkowicie)1	Nie1
PurchasingPartyId	Id kontrahenta na dokumencie	Tak
PaymentTypeId	Id formy płatności	Tak
BankAccountId	Id rachunku bankowego	Nie
SalesDate	Data sprzedaży w formacie RRRR-MM-DD	Nie2
Items	Pozycje dokumentu	Nie3
ProductId	Id produktu	Tak
Quantity	Ilość	Tak
ProductCurrencyNetPrice	Cena netto sprzedaży	Tak
ProductDescription	Opis produktu	Nie
IssueDate	Data wystawienia dokumentu w formacie RRRR-MM-DD	Nie2

1) 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). 2) W przypadku braku daty w parametrach, ustawiana będzie data bieżąca. 3) 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. Przykładowe zapytanie JSON: W odpowiedzi zostanie wysłane ID dodanego dokumentu faktury sprzedaży. Przykładowa odpowiedź:

Wskazówka

Podczas dodawania nowej faktury sprzedaży poprzez API, dokument będzie miał nadany numer zgodnie z domyślnym schematem numeracji, ustawionym w Comarch Betterfly.

Wskazówka

Faktury sprzedaży dodawane do Comarch Betterfly poprzez API zawsze będą miały status "Zapisane" (w buforze). Wszelkie dalsze operacje - np. zatwierdzenia i księgowania dokumentu - należy wykonywać po zalogowaniu do aplikacji.

EDYCJA FAKTURY SPRZEDAŻY

Edycja faktury sprzedaży: [PUT] https://app.comarchbetterfly.pl/api2/public/invoices Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
PaymentStatus	Status płatności (0 - niezapłacona, 1 - zapłacona całkowicie)	Tak
PurchasingPartyId	Id kontrahenta na dokumencie	Tak
PaymentTypeId	Id formy płatności	Tak
BankAccountId	Id rachunku bankowego	Nie
SalesDate	Data sprzedaży w formacie RRRR-MM-DD	Nie
Items	Pozycje dokumentu	Tak1
ProductId	Id produktu	Tak
Quantity	Ilość	Tak
ProductCurrencyNetPrice	Cena netto sprzedaży	Tak
ProductDescription	Opis produktu	Nie
Id	ID pozycji dokumentu w bazie danych	Nie2
IssueDate	Data wystawienia dokumentu w formacie RRRR-MM-DD	Nie
Id	Id dokumentu w bazie danych	Tak

1) Jeśli edytowana faktura zawiera pozycje. 2) 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 API można edytować jednie faktury zapisane do bufora.

W odpowiedzi zostanie wysłany status i ewentualnie JSON odpowiedzi. Przykładowe zapytanie JSON (zmiana formy płatności i ilości sztuk produktów): Przykładowa odpowiedź JSON – status 204 No Content - operacja zakończona powodzeniem:

Przykład

Usuwanie pozycji z faktury sprzedaży poprzez edycję dokumentu: [PUT] https://app.comarchbetterfly.pl/api2/public/invoices Przykładowe zapytanie: Przykładowa odpowiedź JSON – status 204 No Content - operacja zakończona powodzeniem:

Uwaga

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

USUWANIE FAKTURY SPRZEDAŻY

Usuwanie faktury sprzedaży: [DEL] https://app.comarchbetterfly.pl/api2/public/invoices/XXX (gdzie XXX to Id dokumentu faktury sprzedaży w bazie danych) Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/invoices/12 Przykładowa odpowiedź JSON – status 204 No Content - operacja zakończona powodzeniem:

Uwaga

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

  Aby dowiedzieć się jak pobrać wydruk faktury sprzedaży poprzez API - kliknij tutaj.  

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.2/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 kontrahenta na dokumencie
ReceivingPartyId	Id odbiorcy na dokumencie
PaymentTypeId	Id formy płatności
BankAccountId	Id rachunku bankowego
SalesDate	Data sprzedaży
InvoiceType	Algorytm obliczania (0 - od netto / 1 - od brutto)
Items	Pozycje dokumentu
$id	Numer porządkowy w ramach odpowiedzi JSON
ProductId	Id produktu
Quantity	Ilość
ProductCurrencyPrice	Cena sprzedaży
ProductDescription	Opis produktu
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: Przykładowa odpowiedź JSON dla faktury w procedurze VAT OSS:   Możliwe jest także pobranie danych dotyczących określonego dokumentu faktury sprzedaży: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/invoices/XXX (gdzie XXX to Id faktury sprzedaży w bazie danych) Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/invoices/2901096   Dostępna jest możliwość pobrania dokumentu o konkretnym numerze: [GET] https://app.comarchbetterfly.pl/api2/public/v1.1/invoices/invoices?number={number} Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/invoices?number=FS/21/7/1

Wskazówka

W Comarch Betterfly API obsługiwane są faktury sprzedaży w walucie PLN. Nie są obsługiwane faktury w walutach obcych, anulowane oraz korekty.

DODAWANIE NOWEGO DOKUMENTU FAKTURY SPRZEDAŻY

Dodawanie faktury sprzedaży: [POST] https://app.comarchbetterfly.pl/api2/public/v1.2/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)	Nie1
OSSProcedureCountryCode	Kod kraju dla procedury OSS	Nie6
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	Nie2
InvoiceType	Algorytm obliczania (0 - od netto / 1 - od brutto)	Nie3
Items	Pozycje dokumentu	Nie4
ProductId	Id produktu	Tak
Quantity	Ilość	Tak
ProductCurrencyPrice	Cena sprzedaży	Tak
ProductDescription	Opis produktu	Nie
VatRateId	Id stawki VAT	Nie6
Description	Opis dokumentu	Nie
IssueDate	Data wystawienia dokumentu	Nie5

1) 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). 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".   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.2/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 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)	Nie2, 4
Items	Pozycje dokumentu	Nie1
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	Nie3
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. 4) Dla faktur finalnych nie ma możliwości zmiany algorytmu.

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.2/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ć w aplikacji.

Przykładowe zapytanie JSON: Przykładowa odpowiedź JSON:

USUWANIE FAKTURY SPRZEDAŻY

Usuwanie faktury sprzedaży: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.2/invoices/XXX (gdzie XXX to Id dokumentu faktury w bazie danych) Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.2/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.  

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.  

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.5/invoices 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 opisanym w artykule API Procedura OSS
IsOSSProcedure	Oznaczenie procedury OSS (true / false)
IsFinal	Oznaczenie typu faktury  (true / false)
PaymentId	Id płatności
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 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 - 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
BankAccountNumber	Numer rachunku bankowego
SalesDate	Data sprzedaży
InvoiceType	Algorytm obliczania (0 - od netto / 1 - od brutto)
NetTotal	Wartość netto dla całego dokumentu
CurrencyNetTotal	Wartość netto w walucie obcej dla całego dokumentu
GrossTotal	Wartość brutto dla całego dokumentu
CurrencyGrossTotal	Wartość brutto w walucie obcej dla całego dokumentu
VatTotal	Wartość VAT dla całego dokumentu
CurrencyVatTotal	Wartość VAT w walucie obcej dla całego dokumentu
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
DocumentCreatedByTaxPayer	Dokument utworzony przez: true - Płatnika VAT false - Podatnika zwolnionego z VAT
Items	Pozycje dokumentu
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
ProductName	Nazwa produktu
ProductDescription	Opis produktu
UnitOfMeasurement	Jednostka miary
VatRateId	Id stawki VAT - do pobrania ze słownika stawek VAT opisanym w artykule API Procedura 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=61] Możliwe jest także pobranie danych dotyczących określonego dokumentu faktury sprzedaży: [GET] https://app.comarchbetterfly.pl/api2/public/v1.5/invoices/XXX (gdzie XXX to Id faktury sprzedaży w bazie danych) Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.5/invoices/2901096   Dostępna jest możliwość pobrania dokumentu o konkretnym numerze: [GET] https://app.comarchbetterfly.pl/api2/public/v1.5/invoices/invoices?number={number} Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.5/invoices?number=FS/21/7/1

Wskazówka

W API obsługiwane są faktury sprzedaży w walucie PLN. W walucie obcej dostępne jest tylko pobieranie faktur. Nie są obsługiwane dokumenty anulowane. Faktury zaliczkowe oraz korekty są obsługiwane w osobnych metodach.

DODAWANIE NOWEGO DOKUMENTU FAKTURY SPRZEDAŻY

Dodawanie faktury sprzedaży: [POST] https://app.comarchbetterfly.pl/api2/public/v1.5/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: [code_snippet id=15] 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.5/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=28964885): [code_snippet id=16] 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.5/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: [code_snippet id=17] Przykładowa odpowiedź JSON: [code_snippet id=18]

USUWANIE FAKTURY SPRZEDAŻY

Usuwanie faktury sprzedaży: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.5/invoices/XXX (gdzie XXX to Id dokumentu faktury w bazie danych) Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.5/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 poprzez interface API pobrać wydruk faktury: API – Wydruki.  

POBIERANIE FAKTUR ZALICZKOWYCH

Pobieranie faktur zaliczkowych: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/advanceInvoices 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)
PurchasingPartyId	Id kontrahenta na dokumencie
ReceivingPartyId	Id odbiorcy na dokumencie
PaymentTypeId	Id formy płatności
BankAccountId	Id rachunku bankowego
SalesDate	Data sprzedaży
InvoiceType	Algorytm obliczania (0 - od netto / 1 - od brutto)
Items	Pozycje dokumentu
$id	Numer porządkowy w ramach odpowiedzi JSON
CurrencyAdvance	Wartość zaliczki
ProductId	Id produktu
Quantity	Ilość
ProductCurrencyPrice	Cena sprzedaży
ProductDescription	Opis produktu
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: Przykładowa odpowiedź JSON dla faktury w procedurze VAT OSS:   Możliwe jest także pobranie danych dotyczących określonego dokumentu faktury zaliczkowej: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/advanceInvoices/XXX (gdzie XXX to id faktury zaliczkowej w bazie danych) Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/advanceInvoices/2901096   Dostępna jest możliwość pobrania dokumentu o konkretnym numerze: [GET] https://app.comarchbetterfly.pl/api2/public/v1.1/advanceInvoices/invoices?number={number} Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/advanceInvoices?number=FAZAL/2022/8  

Wskazówka

W Comarch Betterfly API obsługiwane są faktury zaliczkowe w walucie PLN. Nie są obsługiwane faktury w walutach obcych, anulowane oraz korekty.

DODAWANIE NOWEGO DOKUMENTU FAKTURY ZALICZKOWEJ

Dodawanie faktury zaliczkowej: [POST] https://app.comarchbetterfly.pl/api2/public/v1.2/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)	Nie1
OSSProcedureCountryCode	Kod kraju dla procedury OSS	Nie6
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	Nie2
InvoiceType	Algorytm obliczania (0 - od netto / 1 - od brutto)	Nie3
Items	Pozycje dokumentu	Nie4
CurrencyAdvance	Wartość zaliczki	Nie7
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	Nie6
Description	Opis dokumentu	Nie
IssueDate	Data wystawienia dokumentu	Nie5

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: 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.2/advanceInvoices?advanceId={id} Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/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:

EDYCJA FAKTURY ZALICZKOWEJ

Edycja faktury sprzedaży: [PUT] https://app.comarchbetterfly.pl/api2/public/v1.2/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)	Nie2
Items	Pozycje dokumentu	Nie1
CurrencyAdvance	Wartość zaliczki	Nie2
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	Nie3
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 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): 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.2/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.

Przykładowe zapytanie JSON: Przykładowa odpowiedź JSON:

USUWANIE FAKTURY ZALICZKOWEJ

Usuwanie faktury sprzedaży: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.2/advanceInvoices/XXX (gdzie XXX to Id dokumentu faktury zaliczkowej w bazie danych) Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.2/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ć wydruk faktury zaliczkowej poprzez API - kliknij tutaj.    

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)	Nie1
OSSProcedureCountryCode	Kod kraju dla procedury OSS	Nie6
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	Nie2
InvoiceType	Algorytm obliczania (0 - od netto / 1 - od brutto)	Nie3
Items	Pozycje dokumentu	Nie4
CurrencyAdvance	Wartość zaliczki	Nie7
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	Nie6
Description	Opis dokumentu	Nie
IssueDate	Data wystawienia dokumentu	Nie5

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)	Nie2
Items	Pozycje dokumentu	Nie1
CurrencyAdvance	Wartość zaliczki	Nie2
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	Nie3
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.