API – Faktura sprzedaży

Wskazówka
Poniższe metody dotyczą faktur sprzedaży i faktur finalnych

 

POBIERANIE FAKTUR SPRZEDAŻY

Pobieranie faktur sprzedaży: [GET] https://app.erpxt.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 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
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 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 tutaj
       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:

{
    "NetTotal": 100.00,
    "CurrencyNetTotal": 100.00,
    "GrossTotal": 123.00,
    "CurrencyGrossTotal": 123.00,
    "VatTotal": 23.00,
    "CurrencyVatTotal": 23.00,
    "CurrencyCode": "PLN",
    "CurrencyRateType": 0,
    "CurrencyRateDate": "2023-04-04T00:00:00+02:00",
    "CurrencyConverter": 1.0,
    "CurrencyRate": 1.0,
    "PaymentStatus": 0,
    "OSSProcedureCountryCode": "",
    "IsOSSProcedure": false,
    "IsFinal": false,
    "PurchasingPartyId": 125822,
    "PurchasingParty": {
        "Name": "COMARCH SPÓŁKA AKCYJNA",
        "NipPrefix": "",
        "Nip": "6770065406",
        "Country": "Polska",
        "City": "Kraków",
        "Street": "Aleja Jana Pawła II",
        "BuildingNumber": "39A",
        "FlatNumber": "4b",
        "BankName": "Bank Polska Kasa Opieki S.A. XI O. w Krakowie",
        "BankAccountNumber": "08 1240 4722 1111 0000 4851 1368",
        "CustomerType": 1
    },
    "ReceivingPartyId": null,
    "ReceivingParty": null,
    "PaymentTypeId": 4471,
    "PaymentType": 0,
    "PaymentDeadline": "2023-04-05T00:00:00+02:00",
    "BankAccountId": null,
    "BankAccountNumber": null,
    "SalesDate": "2023-04-05T00:00:00+02:00",
    "InvoiceType": 0,
    "Items": [
        {
            "ProductId": 130753,
            "Quantity": 1.0000,
            "ProductCurrencyPrice": 100.00,
            "ProductPrice": 100.00,
            "ProductName": "Mysz komputerowa przewodowa",
            "ProductDescription": "",
            "UnitOfMeasurement": "szt.",
            "VatRateId": 9,
            "Id": 375493
        }
    ],
    "Description": null,
    "IssueDate": "2023-04-05T00:00:00+02:00",
    "Number": "FS/23/4/5",
    "Status": 1,
    "Id": 278251
}

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

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

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

 

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

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

Przykładowe zapytanie: [GET] https://app.erpxt.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.erpxt.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 ERP XT. 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 ERP XT.
       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.erpxt.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=2901095):

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

 

ZATWIERDZANIE FAKTUR SPRZEDAŻY

Zatwierdzanie faktur sprzedaży: [PUT] https://app.erpxt.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:

Przykładowa odpowiedź JSON:

USUWANIE FAKTURY SPRZEDAŻY

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

Przykładowe zapytanie: [DEL] https://app.erpxt.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 pobrać wydruk faktury poprzez API – kliknij tutaj.

 

Czy ten artykuł był pomocny?