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

POBIERANIE FAKTUR KORYGUJĄCYCH

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

Opis struktury JSON odpowiedzi:

Parametr	Opis
$id	Numer porządkowy w ramach odpowiedzi JSON
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
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)
Id	Id dokumentu w bazie danych

Przykładowa odpowiedź JSON:

[code_snippet id=8]

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.5/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.5/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
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.5/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.5/correctiveinvoices/XXX (gdzie XXX to Id dokumentu faktury korygującej w bazie danych)

Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.5/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.5/correctiveadvanceinvoices

[POST] https://app.comarchbetterfly.pl/api2/public/v1.5/correctiveadvanceinvoices?documentId=XXX

[PUT] https://app.comarchbetterfly.pl/api2/public/v1.5/correctiveadvanceinvoices

[PUT] https://app.comarchbetterfly.pl/api2/public/v1.5/correctiveadvanceinvoices/confirm

[DEL] https://app.comarchbetterfly.pl/api2/public/v1.5/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