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
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: [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 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.
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: [PUT] https://app.comarchbetterfly.pl/api2/public/v1.7/advanceInvoices/confirm
W odpowiedzi zostanie wysłany status i JSON odpowiedzi.
[code_snippet id=41]
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.
Aby dowiedzieć się jak pobrać poprzez API wydruk faktury proforma: API – Wydruki.