https://pomoc.comarchbetterfly.pl/dokumentacja/api-faktura-proforma-wersja-archiwalna-1-1/

API – Faktura proforma (wersja archiwalna 1.1)

Kategoria: API - archiwum Opublikowano: 8 stycznia 2021 Autor: Wydrukowano: 15 października 2026

POBIERANIE FAKTUR PROFORMA

Pobieranie faktur sprzedaży: [GET] https://app.comarchbetterfly.pl/api2/public/v1.1/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 naliczania (0 – od cen netto / 1 – od cen brutto)
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 sprzedaży
      ProductDescription
 Opis produktu
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:

[
    {
        „$id”: „1”,
        „PurchasingPartyId”: 2541748,
        „ReceivingPartyId”: 2541749,
        „PaymentTypeId”: 2016674,
        „BankAccountId”: null,
        „InvoiceType”: 0,
        „Items”: [
            {
                „$id”: „2”,
                „ProductId”: 2276109,
                „Quantity”: 6.0000,
                „ProductCurrencyPrice”: 100.00,
                „ProductDescription”: „”,
                „Id”: 4421127
            }
        ],
        „Description”: null,
        „IssueDate”: „2019-12-24T00:00:00+01:00”,
        „Number”: „PF/19/12/1”,
        „Status”: 0,
        „Id”: 2721058
    },
    {
        „$id”: „3”,
        „PurchasingPartyId”: 2541748,
        „ReceivingPartyId”: null,
        „PaymentTypeId”: 2016674,
        „BankAccountId”: null,
        „InvoiceType”: 0,
        „Items”: [
            {
                „$id”: „4”,
                „ProductId”: 2276109,
                „Quantity”: 6.0000,
                „ProductCurrencyPrice”: 100.00,
                „ProductDescription”: „”,
                „Id”: 4421128
            }
        ],
        „Description”: null,
        „IssueDate”: „2019-12-24T00:00:00+01:00”,
        „Number”: „PF/19/12/2”,
        „Status”: 0,
        „Id”: 2721059
    }
]
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.1/proformas/?$filter=InvoiceDocIdNum ne null

 

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

[GET] https://app.comarchbetterfly.pl/api2/public/v1.1/proformas/XXX (gdzie XXX to Id dokumentu faktury sprzedaży w bazie danych)

Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.1/proformas/2812310

Przykładowa odpowiedź JSON:

{
    „$id”: „1”,
    „PurchasingPartyId”: 2541748,
    „ReceivingPartyId”: null,
    „PaymentTypeId”: 2016674,
    „BankAccountId”: 2004259,
    „InvoiceType”: 0,
    „Items”: [
        {
            „$id”: „2”,
            „ProductId”: 2276109,
            „Quantity”: 1.0000,
            „ProductCurrencyPrice”: 100.00,
            „ProductDescription”: „”,
            „Id”: 4520499
        },
        {
            „$id”: „3”,
            „ProductId”: 2276109,
            „Quantity”: 1.0000,
            „ProductCurrencyPrice”: 100.00,
            „ProductDescription”: „”,
            „Id”: 4520500
        }
    ],
    „Description”: null,
    „IssueDate”: „2021-01-04T00:00:00+01:00”,
    „Number”: „PF/21/1/17”,
    „Status”: 0,
    „Id”: 2812310
}

 

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

[GET] https://app.comarchbetterfly.pl/api2/public/v1.1/proformas/number/XXX (gdzie XXX to numer dokumentu)

Przykładowe zapytanie: https://app.comarchbetterfly.pl/api2/public/v1.1/proformas/number/PF/21/1/17

Przykładowa odpowiedź JSON

{
    „$id”: „1”,
    „PurchasingPartyId”: 2541748,
    „ReceivingPartyId”: null,
    „PaymentTypeId”: 2016674,
    „BankAccountId”: 2004259,
    „InvoiceType”: 0,
    „Items”: [
        {
            „$id”: „2”,
            „ProductId”: 2276109,
            „Quantity”: 1.0000,
            „ProductCurrencyPrice”: 100.00,
            „ProductDescription”: „”,
            „Id”: 4520499
        },
        {
            „$id”: „3”,
            „ProductId”: 2276109,
            „Quantity”: 1.0000,
            „ProductCurrencyPrice”: 100.00,
            „ProductDescription”: „”,
            „Id”: 4520500
        }
    ],
    „Description”: null,
    „IssueDate”: „2021-01-04T00:00:00+01:00”,
    „Number”: „PF/21/1/17”,
    „Status”: 0,
    „Id”: 2812310
}
Wskazówka
W API obsługiwane są faktury w walucie PLN. Nie są obsługiwane faktury w walutach obcych.

DODAWANIE NOWEGO DOKUMENTU FAKTURY PROFORMA

Dodawanie faktury sprzedaży: [POST] https://app.comarchbetterfly.pl/api2/public/v1.1/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 naliczania (0 – od cen netto / 1 – od cen brutto) Nie1
Items Pozycje dokumentu Nie2
       ProductId Id produktu Tak
       Quantity Ilość Tak
       ProductCurrencyPrice Cena netto sprzedaży Tak
       ProductDescription
 Opis produktu Nie
IssueDate Data wystawienia dokumentu w formacie RRRR-MM-DD Nie3
Description Opis dokumentu Nie

1) W przypadku braku wartości w tym polu podstawiona będzie wartość domyślna dla dokumentu

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.

Przykładowe zapytanie JSON:

{
    „PurchasingPartyId”: 2541748,
    „ReceivingPartyId”: null,
    „PaymentTypeId”: 2016674,
    „BankAccountId”: 2004259,
    „InvoiceType”: 0,
    „Items”: [
        {
            „$id”: „2”,
            „ProductId”: 2276109,
            „Quantity”: 1.0000,
            „ProductCurrencyPrice”: 100.00,
            „ProductDescription”: „”
        }
    ],
    „Description”: „Opis”,
}

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

Przykładowa odpowiedź:

2814939
Wskazówka
Podczas dodawania nowej faktury proforma poprzez API, dokument będzie miał nadany numer zgodnie z domyślnym schematem numeracji, ustawionym w Comarch Betterfly.

EDYCJA FAKTURY PROFORMA

Edycja faktury sprzedaży: [PUT] https://app.comarchbetterfly.pl/api2/public/v1.1/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 naliczania (0 – od cen netto / 1 – od cen brutto) Nie1
Items Pozycje dokumentu Tak2
       ProductId Id produktu Tak
       Quantity Ilość Tak
       ProductCurrencyPrice Cena netto sprzedaży Tak
       ProductDescription
 Opis produktu Nie
       Id
 ID pozycji dokumentu w bazie danych Nie3
IssueDate Data wystawienia dokumentu w formacie RRRR-MM-DD Nie
Id Id dokumentu w bazie danych Tak

1) W przypadku braku wartości w tym polu podstawiona będzie wartość domyślna dla dokumentu

2) Jeśli edytowana faktura zawiera pozycje.

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

W odpowiedzi zostanie wysłany status i ewentualnie JSON odpowiedzi.

Przykładowe zapytanie JSON:

{
    „PurchasingPartyId”: 2541748,
    „ReceivingPartyId”: null,
    „PaymentTypeId”: 2016674,
    „BankAccountId”: 2004259,
    „InvoiceType”: 0,
    „Items”: [
        {
            „$id”: „2”,
            „ProductId”: 2276109,
            „Quantity”: 1.0000,
            „ProductCurrencyPrice”: 100.00,
            „ProductDescription”: „”,
            „Id”: 4520499
        }
    ],
    „Description”: null,
    „Id”: 2814939
}

 

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

brak treści
Uwaga
Opcja edycji faktury proforma jest dostępna tylko dla dokumentów bez przekształceń.

USUWANIE FAKTURY PROFORMA

Usuwanie faktur proforma: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.1/proformas/XXX (gdzie XXX to Id dokumentu faktury sprzedaży w bazie danych)

Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.1/proformas/12

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

brak treści

 

Usuwanie wielu faktur proforma: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.1/proformas, która przyjmuje obiekt o polu IdCollection który zawiera tablice reprezentującą numeru Id dokumentów do usunięcia.

Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.1/proformas

Opis struktury JSON zapytania:

{
    „IdCollection”: [
        19697349,
        19697317
    ]
}

Przykładowa odpowiedź JSON:

{
    „Statuses”: [
        {
            „Id”: 19697349
            „Success”: true
        },
        {
            „Id”: 19697317,
            „Success”: false,
            „Error”: {
            „Message”: „Tego dokumentu nie można zmodyfikować lub usunąć.”,
            „Code”: „DocumentException”
            }
        }
    ]
}
Uwaga
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.

Wydrukowano z Baza Wiedzy programu Comarch Betterfly dnia 15 października 2026 2:44 pm