API – Faktura zaliczkowa

POBIERANIE FAKTUR ZALICZKOWYCH

Pobieranie faktur zaliczkowych: [GET] https://app.erpxt.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:

{
    "NetTotal": 10.00,
    "CurrencyNetTotal": 10.00,
    "GrossTotal": 12.30,
    "CurrencyGrossTotal": 12.30,
    "VatTotal": 2.30,
    "CurrencyVatTotal": 2.30,
    "CurrencyCode": "PLN",
    "CurrencyRateType": 0,
    "CurrencyRateDate": "2023-04-04T00:00:00+02:00",
    "CurrencyConverter": 1.0,
    "CurrencyRate": 1.0,
    "PaymentStatus": 0,
    "OSSProcedureCountryCode": "",
    "IsOSSProcedure": 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": [
        {
            "CurrencyAdvance": 10.00,
            "ProductId": 130753,
            "Quantity": 1.0000,
            "ProductCurrencyPrice": 100.00,
            "ProductPrice": 100.00,
            "ProductName": "Mysz komputerowa przewodowa",
            "ProductDescription": "",
            "UnitOfMeasurement": "szt.",
            "VatRateId": 9,
            "Id": 375500
        }
    ],
    "Description": "",
    "IssueDate": "2023-04-05T00:00:00+02:00",
    "Number": "FAZAL/2023/4/1",
    "Status": 1,
    "Id": 278258
}
Przykładowa odpowiedź JSON dla faktury w procedurze VAT OSS: 
{
    "NetTotal": 50.00,
    "CurrencyNetTotal": 50.00,
    "GrossTotal": 59.50,
    "CurrencyGrossTotal": 59.50,
    "VatTotal": 9.50,
    "CurrencyVatTotal": 9.50,
    "CurrencyCode": "PLN",
    "CurrencyRateType": 0,
    "CurrencyRateDate": "2023-04-04T00:00:00+02:00",
    "CurrencyConverter": 1.0,
    "CurrencyRate": 1.0,
    "PaymentStatus": 0,
    "OSSProcedureCountryCode": "DE",
    "IsOSSProcedure": true,
    "PurchasingPartyId": 127870,
    "PurchasingParty": {
        "Name": "Musterfirma GmbH",
        "NipPrefix": "DE",
        "Nip": "78964867884",
        "Country": "",
        "City": "",
        "Street": "",
        "BuildingNumber": "",
        "FlatNumber": "",
        "BankName": "",
        "BankAccountNumber": "",
        "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": [
        {
            "CurrencyAdvance": 50.00,
            "ProductId": 130753,
            "Quantity": 1.0000,
            "ProductCurrencyPrice": 100.00,
            "ProductPrice": 100.00,
            "ProductName": "Mysz komputerowa przewodowa",
            "ProductDescription": "",
            "UnitOfMeasurement": "szt.",
            "VatRateId": 74,
            "Id": 375502
        }
    ],
    "Description": "",
    "IssueDate": "2023-04-05T00:00:00+02:00",
    "Number": "FAZAL/2023/4/2",
    "Status": 1,
    "Id": 278260
}

 

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

[GET] https://app.erpxt.pl/api2/public/v1.4/advanceInvoices/XXX (gdzie XXX to id faktury zaliczkowej w bazie danych)

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

 

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

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

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

{
    "PurchasingPartyId": 529611,
    "PaymentTypeId": 1508,
    "Items": [
        {
            "ProductId": 2028,
            "Quantity": 1.0,
            "ProductCurrencyPrice": 81.30,
            "CurrencyAdvance": 10.00
        }
    ]
}

W odpowiedzi zostanie wysłane ID dodanego dokumentu faktury zaliczkowej.

 

DODAWANIE POWIĄZANEJ FAKTURY ZALICZKOWEJ

Dodawanie powiązanej faktury zaliczkowej: [POST] https://app.erpxt.pl/api2/public/v1.4/advanceInvoices?advanceId={id}

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

{
    "Message": "Dla tego dokumentu nie można wystawić kolejnej powiązanej faktury zaliczkowej.",
    "Code": "DocumentException",
    "Data": {
        "ErrorCode": "5"
    }
}

EDYCJA FAKTURY ZALICZKOWEJ

Edycja faktury sprzedaży: [PUT] https://app.erpxt.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 XT 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):

{
    "PurchasingPartyId": 529611,
    "PaymentTypeId": 1508,
    "Items": [
        {
            "ProductId": 2028,
            "Quantity": 1.0,
            "ProductCurrencyPrice": 81.30,
            "CurrencyAdvance": 10.00
        }
    ],
    "Id": 2994705
}

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

 

ZATWIERDZANIE FAKTUR ZALICZKOWYCH

Zatwierdzanie faktur zaliczkowych: [PUT] https://app.erpxt.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.
Przykładowe zapytanie JSON: 
{
    "IdCollection": [
        1995472, 1995473
    ]
}
Przykładowa odpowiedź JSON: 
[
    {
        "Confirmed": true,
        "ErrorMessage": "",
        "ErrorCode": "",
        "DocumentNumber": "FS/24/6/8",
        "DocumentId": 1995472
    },
    {
        "Confirmed": true,
        "ErrorMessage": "",
        "ErrorCode": "",
        "DocumentNumber": "FS/24/6/9",
        "DocumentId": 1995473
    }
]

USUWANIE FAKTURY ZALICZKOWEJ

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

Przykładowe zapytanie: [DEL] https://app.erpxt.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.

 

 

Czy ten artykuł był pomocny?

Wyślij opnie