API - Dokumenty sprzedażowe

Punkt dostępowy

Punkt dostępowy znajduje się pod adresem: https://app.firmino.pl/app/services/rest/api/sale-documents/

Metody

add – dodawanie nowego dokumentu
get – pobieranie danych dokumentu (wymagany id)
find – pobieranie listy dokumentów
update – aktualizowanie danych dokumentu (wymagany id)
delete – usuwanie dokumentu (wymagany id)
init – inicjalizowanie pustego dokumentu (zwraca dostępny numer porządkowy i domyślne ustawienia)
mail – wysyłanie maila z dołączonym dokumentem sprzedaży PDF (wymagany id)
download – pobieranie dokumentu jako PDF (wymagany id)
payoff – spłacanie dokumentu (wymagany id)
unpaid – oznaczenie dokumentu jako niezapłacony – usunięcie rozliczeń ( wymagany id )
find-notes – pobranie listy uwag do dokumentów

Pola

Parametr	Opis	Uwagi	Typ danych
id	Identyfikator		long
ordinalNumber	Numer porządkowy faktury (domyślnie najniższy dostępny numer na dzień wystawienia dokumentu)		integer
documentName	Nazwa dokumentu (przykład: Faktura VAT 1/11/2019)	Tylko do odczytu	string
documentDate	Data wystawienia dokumentu (domyślnie aktualna data)		string(yyyy-mm-dd)
saleDate	Data sprzedaży (domyślnie aktualna data)		string(yyyy-mm-dd)
salePlace	Miejsce sprzedaży (domyślnie miejsce prowadzenia firmy)		string(60)
documentType	Typ dokumentu (domyślnie "fas" - Faktura VAT) Dostępne: fas - Faktura sprzedaży fe - Faktura eksportowa fhan - Rachunek par - Paragon VAT pa - Paragon zamo - Zamówienie fzal - Zaliczka fdw - Dostawa wewnątrzwspólnotowa fvoss - Faktura VAT OSS	Niedytowalny	string
documentFunction	Rodzaj dokumentu (domyślnie "normal" - zwykły dokument) Dostępne: normal - zwykły dokument correction - korekta proforma - proforma order - zamówienie advance - faktura zaliczkowa (końcowa)	Tylko do odczytu	string
documentState	Status dokumentu (domyślnie "new" - Nowy, wystawiony) Dostępne: new - nowy printed - wydrukowany partpaid - częściowo zapłacony paid - zapłacony cancelled - anulowany unpaid - niezapłacony	Tylko do odczytu	string
priceType	Dokument liczony od Netto lub Brutto (domyślnie "net") Dostępne: net - netto gross - brutto		string
printNotes	Dokument liczony od Netto lub Brutto (domyślnie "net") Dostępne: net - netto gross - brutto		string(1000)
ossProcedure	Procedura OSS (tylko dla faktur VAT OSS, domyślnie "wsto") Dostępne: wsto - WSTO (procedura unijna) ioss - IOSS (procedura importu) servicesEu - Usługi (procedura unijna) services - Usługi (procedura nieunijna)		string

Pozostałe pola

kontrahent (customer)
pozycje dokumentu (items)
waluta + kurs (currency)
rozliczenie dokumentu (payment)

Filtry

Obiekt filtrów

{
  "sortField": "fieldName",
  "sortOrder": "desc",
  "text": "searchText",
  "filters": [
    {
      "name": "filterName",
      "value": "filterValue"
    }
  ]
}

Dostępne filtry

Opis	Nazwa filtru	Dostępne wartości
Od daty	„fromDate”	wartości daty w formacie "RRRR-MM-DD"
Do daty	„toDate”	wartości daty w formacie "RRRR-MM-DD"
Po roku	„year”	dostępne wartości integer
Po miesiącu	„month”	dostępne wartości integer
Funkcja dokumentu	„documentFunction”	dostępne wartości: normal, correction, proforma, order, advance
Typ dokumentu	„documentType”	dostępne wartości: fas, par, pa, fe, fdw, fhan, fmar, fzal, fpz, faz, fhanz, fi, fnw, fzmar, fvoss
Stan dokumentu	„documentState”	dostępne wartości: new, printed, partpaid, paid, cancelled, unpaid, sended, editrequired

Przykładowe zapytania

Dodawanie dokumentu sprzedaży (tylko wymagane pola)

https://app.firmino.pl/app/services/rest/api/sale-documents/add

Przykład CURL:

curl -POST --user login:haslo -H "Content-type: application/json" https://app.firmino.pl/app/services/rest/api/sale-documents/add -d '{"customer":{"id":4195100}}'

Żądanie (JSON):

{
	"customer" : {
		"id": 4195100
	}
}

Odpowiedź (JSON):

{
    "success": true,
    "response": {
        "id": 19284001,
        "ordinalNumber": 1,
        "documentName": "Faktura VAT 1/12/2019",
        "documentDate": "2019-12-04",
        "saleDate": "2019-12-04",
        "salePlace": "Zielona Góra",
        "documentType": "fas",
        "documentFunction": "normal",
        "documentState": "new",
        "priceType": "net",
        "customer": {
            "id": 4195100,
            "fullName": "KONTRAHENT TESTOWY",
            "shortName": "TEST KONTRAH",
            "countryCode": "PL",
            "locality": "Zielona Góra",
            "tin": "1111111111",
            "regon": null,
            "street": "Testowa",
            "houseNo": "2",
            "flatNo": "1",
            "postCode": "65-140",
            "post": "Zielona Góra",
            "phone": null,
            "email": null,
            "bankAccount": null,
            "fax": null,
            "website": null,
            "note": null
        },
        "items": [],
        "currency": {
            "code": "PLN",
            "rate": "1.000000",
            "date": null,
            "table": null
        }
        "payment": {
            "method": "transfer",
            "paymentDate": null,
            "termDate": "2019-12-24",
            "total": "0.00",
            "paid": "0.00",
            "ramain": "0.00"
        }
    }
}

Dodanie dokumentu sprzedaży z pozycjami

https://app.firmino.pl/app/services/rest/api/sale-documents/add

Przykład CURL:

curl -POST --user login:haslo -H "Content-type: application/json" https://app.firmino.pl/app/services/rest/api/sale-documents/add -d '{"customer": {"id": 765012}, "items":[{"name": "PRODUKT X", "quantity": "1", "price": "21.22", "unit": "szt"}]}'

Żądanie (JSON):

{
	"documentDate": "2019-09-13",
	"ordinalNumber": 2,
	"customer": {
		"id" : 765012
	},
	"items":
	[ 
		{
			"name": "PRODUKT X",
			"unit": "szt",
			"vatRate": "23",
			"price": "21.22",
			"quantity": "1"
		}
	]
}

Odpowiedź (JSON):

{
    "success": true,
    "response": {
        "id": 3098578,
        "ordinalNumber": 3,
        "documentName": "Faktura VAT 3/09/2019",
        "documentDate": "2019-09-13",
        "saleDate": "2019-09-13",
        "salePlace": "Zielona Góra",
        "documentType": "fas",
        "documentFunction": "normal",
        "documentState": "new",
        "priceType": "net",
        "customer": {
            "id": 765012,
            "fullName": "Testowy kontrahent sp. z o.o.",
            "shortName": "KONTRAHENT TEST",
            "countryCode": "PL",
            "locality": "Warszawa",
            "tin": null,
            "regon": null,
            "street": null,
            "houseNo": null,
            "flatNo": null,
            "postCode": null,
            "post": "Warszawa",
            "phone": null,
            "email": null,
            "bankAccount": null,
            "fax": null,
            "website": null,
            "note": null
        },
        "items": [
            {
                "orderNo": 1,
                "idArticle": null,
                "name": "PRODUKT X",
                "unit": "szt",
                "vatRate": "23",
                "price": "21.22",
                "quantity": "1.0000",
                "discount": "0.00"
            }
        ],
        "currency": {
            "code": "PLN",
            "rate": "1.000000",
            "date": null,
            "table": null
        },
        "payment": {
            "method": "transfer",
            "paymentDate": null,
            "termDate": "2019-09-27",
            "total": "26.10",
            "paid": "0.00",
            "ramain": "26.10"
        }
    }
}

Przykład odpowiedzi z błędem

https://app.firmino.pl/app/services/rest/api/sale-documents/add

Przykład CURL:

curl -POST --user login:haslo -H "Content-type: application/json" https://app.firmino.pl/app/services/rest/api/sale-documents/add -d '{"customer":{"id":41951002}}'

Żądanie (JSON):

{
	"customer" : {
		"id": 41951002
	}
}

Odpowiedź (JSON):

{
    "success": false,
    "response": "Nie znaleziono obiektu o id=41951002"
}

Pobieranie danych dokumentu sprzedaży

https://app.firmino.pl/app/services/rest/api/sale-documents/get/{id}

Przykład CURL:

curl -POST --user login:haslo -H "Content-type: application/json" https://app.firmino.pl/app/services/rest/api/sale-documents/get/3112414

Odpowiedź (JSON):

{
    "success": true,
    "response": {
        "id": 3112414,
        "ordinalNumber": 7,
        "documentName": "Faktura VAT 7/01/2020",
        "documentDate": "2020-01-30",
        "saleDate": "2020-01-30",
        "salePlace": "Dobra",
        "documentType": "fas",
        "documentFunction": "normal",
        "documentState": "partpaid",
        "priceType": "net",
        "customer": {
            "id": 738023,
            "fullName": "KONTRAHENT 1 - TEST",
            "shortName": "KONTRAHENT1",
            "countryCode": "PL",
            "locality": "Zielona Góra",
            "tin": null,
            "regon": null,
            "street": null,
            "houseNo": null,
            "flatNo": null,
            "postCode": null,
            "post": "Zielona Góra",
            "phone": null,
            "email": null,
            "bankAccount": null,
            "fax": null,
            "website": null,
            "note": null
        },
        "items": [
            {
                "orderNo": 1,
                "idArticle": 496332,
                "name": "TOWAR TESTOWY",
                "unit": "szt",
                "vatRate": "8",
                "price": "10.50",
                "quantity": "2.0000",
                "discount": "0.00"
            }
        ],
        "currency": {
            "code": "PLN",
            "rate": "1.000000",
            "date": null,
            "table": null
        },
        "payment": {
            "method": "transfer",
            "paymentDate": null,
            "termDate": "2020-02-13",
            "total": "22.68",
            "paid": "2.00",
            "ramain": "20.68"
        }
    }
}

Pobieranie listy dokumentów

https://app.firmino.pl/app/services/rest/api/sale-documents/find

Przykład CURL:

curl -POST --user login:haslo -H "Content-type: application/json" https://app.firmino.pl/app/services/rest/api/sale-documents/find -d '{}'

Żądanie (JSON):

{}

Odpowiedź (JSON):

{
    "success": true,
    "response": {
        "params": {
            "total": 3,
            "page": 1,
            "size": 15,
            "text": null,
            "filters": null
        },
        "list": [
            {
                "id": 2924781,
                "ordinalNumber": 1,
                "documentName": "FAS 1/11/2019",
                "documentDate": "2019-11-27",
                "idCustomer": 765012,
                "customerName": "Testowy kontrahent sp. z o.o.",
                "documentType": "fas",
                "documentFunction": "normal",
                "documentState": "new",
                "currencyCode": "PLN",
                "paymentTotal": "0.00",
                "paymentPaid": "0.00",
                "paymentRemain": "0.00"
            },
            {
                "id": 3098578,
                "ordinalNumber": 3,
                "documentName": "FAS 3/09/2019",
                "documentDate": "2019-09-13",
                "idCustomer": 765012,
                "customerName": "Testowy kontrahent sp. z o.o.",
                "documentType": "fas",
                "documentFunction": "normal",
                "documentState": "new",
                "currencyCode": "PLN",
                "paymentTotal": "26.10",
                "paymentPaid": "0.00",
                "paymentRemain": "26.10"
            },
            {
                "id": 2707213,
                "ordinalNumber": 1,
                "documentName": "FAS 1/09/2019",
                "documentDate": "2019-09-13",
                "idCustomer": 738023,
                "customerName": "KONTRAHENT 1 - TEST",
                "documentType": "fas",
                "documentFunction": "normal",
                "documentState": "paid",
                "currencyCode": "PLN",
                "paymentTotal": "0.00",
                "paymentPaid": "0.00",
                "paymentRemain": "0.00"
            }
        ]
    }
}

Pobieranie listy dokumentów (filtry)

https://app.firmino.pl/app/services/rest/api/sale-documents/find

Przykład CURL:

curl -POST --user login:haslo -H "Content-type: application/json" https://app.firmino.pl/app/services/rest/api/sale-documents/find -d '{"page":1,"size":10,"text":"","filters":[{"name":"year","value":2019}]}'

Żądanie (JSON):

{
	"page" : 1,
	"size" : 10,
	"text" : "",
	"filters":
		[ 
			{
				"name": "year",
				"value": 2019
			}
		]
}

Odpowiedź (JSON):

{
    "success": true,
    "response": {
        "params": {
            "total": 2,
            "page": 1,
            "size": 10,
            "text": "",
            "filters": [
                {
                    "name": "year",
                    "value": "2019"
                }
            ]
        },
        "list": [
            {
                "id": 2924781,
                "ordinalNumber": 1,
                "documentName": "FAS 1/11/2019",
                "documentDate": "2019-11-27",
                "idCustomer": 765012,
                "customerName": "Testowy kontrahent sp. z o.o.",
                "documentType": "fas",
                "documentFunction": "normal",
                "documentState": "new",
                "currencyCode": "PLN",
                "paymentTotal": "0.00",
                "paymentPaid": "0.00",
                "paymentRemain": "0.00"
            },
            {
                "id": 3098578,
                "ordinalNumber": 3,
                "documentName": "FAS 3/09/2019",
                "documentDate": "2019-09-13",
                "idCustomer": 765012,
                "customerName": "Testowy kontrahent sp. z o.o.",
                "documentType": "fas",
                "documentFunction": "normal",
                "documentState": "new",
                "currencyCode": "PLN",
                "paymentTotal": "26.10",
                "paymentPaid": "0.00",
                "paymentRemain": "26.10"
            }
        ]
    }
}

Edytowanie dokumentu sprzedaży

https://app.firmino.pl/app/services/rest/api/sale-documents/update

Przykład CURL:

curl -POST --user login:haslo -H "Content-type: application/json" https://app.firmino.pl/app/services/rest/api/sale-documents/update -d {"id":19340101,"ordinalNumber":7,"documentDate":"2020-02-15","saleDate":"2020-02-15","salePlace":"Warszawa","priceType":"gross","customer":{"fullName":"KONTRAHENT NOWY","shortName":"EDYTOWANY","countryCode":"PL","locality":"Poznań","postCode":"60-001","note":"edytowany"},"items":[{"name":"PRODUKT","unit":"szt","vatRate":"23","price":"12.00","quantity":"3.00","discount":"0.00"}],"currency":{"code":"EUR"},"payment":{"method":"cash","termDate":"2020-02-22"}}

Żądanie (JSON):

{
    "id" : 19340101,
    "ordinalNumber": 7,
    "documentDate": "2020-02-15",
    "saleDate": "2020-02-15",
    "salePlace": "Warszawa",
    "priceType": "gross",
    "customer": {
        "fullName": "KONTRAHENT NOWY",
        "shortName": "EDYTOWANY",
        "countryCode": "PL",
        "locality": "Poznań",
        "postCode": "60-001",
        "note": "edytowany"
    },
    "items": [
        {
            "name": "PRODUKT",
            "unit": "szt",
            "vatRate": "23",
            "price": "12.00",
            "quantity": "3.00",
            "discount": "0.00"
        }
    ],
    "currency": {
        "code": "EUR"
    },
    "payment": {
        "method": "cash",
        "termDate": "2020-02-22"
    }
}

Odpowiedź (JSON):

{
    "success": true,
    "response": {
        "id": 19340101,
        "ordinalNumber": 7,
        "documentName": "Faktura VAT 7/02/2020",
        "documentDate": "2020-02-15",
        "saleDate": "2020-02-15",
        "salePlace": "Warszawa",
        "documentType": "fas",
        "documentFunction": "normal",
        "documentState": "new",
        "priceType": "gross",
        "customer": {
            "id": 4558600,
            "fullName": "KONTRAHENT NOWY",
            "shortName": "EDYTOWANY",
            "countryCode": "PL",
            "locality": "Poznań",
            "tin": null,
            "regon": null,
            "street": null,
            "houseNo": null,
            "flatNo": null,
            "postCode": "60-001",
            "post": "Poznań",
            "phone": null,
            "email": null,
            "bankAccount": null,
            "fax": null,
            "website": null,
            "note": "edytowany"
        },
        "items": [
            {
                "orderNo": 1,
                "idArticle": null,
                "name": "PRODUKT",
                "unit": "szt",
                "vatRate": "23",
                "price": "12.00",
                "quantity": "3.0000",
                "discount": "0.00"
            }
        ],
        "currency": {
            "code": "EUR",
            "rate": "4.240200",
            "date": "2020-02-14",
            "table": "031/A/NBP/2020"
        },
        "payment": {
            "method": "transfer",
            "paymentDate": null,
            "termDate": "2020-02-28",
            "total": "36.00",
            "paid": "0.00",
            "ramain": "36.00"
        }
    }
}

Usuwanie dokumentu sprzedaży

https://app.firmino.pl/app/services/rest/api/sale-documents/delete/{id}

Przykład CURL:

curl -POST --user login:haslo -H "Content-type: application/json" https://app.firmino.pl/app/services/rest/api/sale-documents/delete/19284001

Odpowiedź (JSON):

{
    "success": true,
    "response": "Usunięto dokument."
}

Inicjalizowanie dokumentu (dostępny numer porządkowy)

https://app.firmino.pl/app/services/rest/api/sale-documents/init

Przykład CURL:

curl -POST --user login:haslo -H "Content-type: application/json" https://app.firmino.pl/app/services/rest/api/sale-documents/init -d '{"documentDate":"2020-01-01","documentType":"fas","documentFunction":"normal"}'

Żądanie (JSON):

{
	"documentDate" : "2020-01-01",
	"documentType" : "fas",
	"documentFunction" : "normal"
}

Odpowiedź (JSON):

{
    "success": true,
    "response": {
        "id": null,
        "ordinalNumber": 1,
        "documentName": "Faktura VAT 1/01/2020",
        "documentDate": "2020-01-01",
        "saleDate": "2020-01-01",
        "salePlace": "Dobra",
        "documentType": "fas",
        "documentFunction": "normal",
        "documentState": "new",
        "priceType": "net",
        "customer": {
            "id": null,
            "fullName": null,
            "shortName": null,
            "countryCode": "PL",
            "locality": null,
            "tin": null,
            "regon": null,
            "street": null,
            "houseNo": null,
            "flatNo": null,
            "postCode": null,
            "post": null,
            "phone": null,
            "email": null,
            "bankAccount": null,
            "fax": null,
            "website": null,
            "note": null
        },
        "items": [],
        "currency": {
            "code": "PLN",
            "rate": "1.00",
            "date": null,
            "table": null
        },
        "payment": {
            "method": "transfer",
            "paymentDate": null,
            "termDate": "2020-01-15",
            "total": "0.00",
            "paid": "0.00",
            "ramain": "0.00"
        }
    }
}

Wysyłanie dokumentu mailem (PDF)

https://app.firmino.pl/app/services/rest/api/sale-documents/mail

Przykład CURL:

curl -POST --user login:haslo -H "Content-type: application/json" https://app.firmino.pl/app/services/rest/api/sale-documents/mail -d '{"idDocument":3112414,"mail":"pomoc@firmino.pl","title":"Tytuł maila","content":"Treść maila"}'

Żądanie (JSON):

{
	"idDocument" : 3112414,
	"mail" : "pomoc@firmino.pl",
	"title" : "Tytuł maila",
	"content" : "Treść maila"
}

Odpowiedź (JSON):

{
    "success": true,
    "response": {
        "idDocument": 3112414,
        "documentName": "Faktura VAT 8/01/2020",
        "mail": "pomoc@firmino.pl"
    }
}

Pobranie dokumentu (PDF)

https://app.firmino.pl/app/services/rest/api/sale-documents/download/{id}

Przykład CURL:

curl -POST --user login:haslo -H "Content-type: application/json" https://app.firmino.pl/app/services/rest/api/sale-documents/download/3112414

Odpowiedź:

Zwracany jest plik PDF o nazwie "dokument_3112414.pdf"

Spłacenie dokumentu

https://app.firmino.pl/app/services/rest/api/sale-documents/payoff/{id}

Przykład CURL:

curl -POST --user login:haslo -H "Content-type: application/json" https://app.firmino.pl/app/services/rest/api/sale-documents/payoff/3112414

Odpowiedź (JSON):

{
    "success": true,
    "response": "Dokument został spłacony."
}

Oznaczenie dokumentu jako niezapłacony - usunięcie rozliczeń

https://app.firmino.pl/app/services/rest/api/sale-documents/unpaid/{id}

Przykład CURL:

curl -POST --user login:haslo -H "Content-type: application/json" https://app.firmino.pl/app/services/rest/api/sale-documents/unpaid/3112414

Odpowiedź (JSON):

{
    "success": true,
    "response": "Usunięto wszystkie spłaty."
}

Pobieranie listy notatek

https://app.firmino.pl/app/services/rest/api/sale-documents/find-notes

Przykład CURL:

curl -POST --user login:haslo -H "Content-type: application/json" https://app.firmino.pl/app/services/rest/api/sale-documents/find-notes -d '{}'

Odpowiedź (JSON):

{
    "success": true,
    "response": {
        "params": {
            "total": 2,
            "page": 1,
            "size": 15,
            "sortField": null,
            "sortOrder": null,
            "text": null,
            "filters": null
        },
        "list": [
            {
                "id": 19908800,
                "ordinalNumber": 1,
                "documentName": "FAS 1/2023",
                "notes": "Przykładowa uwaga do dokumentu"
            },
            {
                "id": 19904300,
                "ordinalNumber": 64,
                "documentName": "FAS 64/2024",
                "notes": "Przykładowa uwaga do dokumentu"
            }
        ]
    }
}

Pobieranie listy notatek (filtry)

https://app.firmino.pl/app/services/rest/api/sale-documents/find-notes

Przykład CURL:

curl -POST --user login:haslo -H "Content-type: application/json" https://app.firmino.pl/app/services/rest/api/sale-documents/find-notes -d '{"page":1,"size":10,"text":"","filters":[{"name":"year","value":2023}]}'

Żądanie (JSON):

{
    "page": 1,
    "size": 170,
    "filters":
        [ 
            {
                "name": "year",
                "value": 2023
            }
        ]
}

Odpowiedź (JSON):

{
    "success": true,
    "response": {
        "params": {
            "total": 1,
            "page": 1,
            "size": 170,
            "sortField": null,
            "sortOrder": null,
            "text": null,
            "filters": [
                {
                    "name": "year",
                    "value": "2023"
                }
            ]
        },
        "list": [
            {
                "id": 19908800,
                "ordinalNumber": 1,
                "documentName": "FAS 1/2023",
                "notes": "Przykładowa uwaga do dokumentu"
            }
        ]
    }
}

Pobranie dokumentu PDF (wybór języka)

https://app.firmino.pl/app/services/rest/api/sale-documents/download/{lang}/{id}

Przykład CURL:

curl -POST --user login:haslo -H "Content-type: application/json" https://app.firmino.pl/app/services/rest/api/sale-documents/download/it/3112414

Zwracany jest plik PDF o nazwie „dokument_3112414.pdf”

Dostępne języki:

pl – polski
en – angielski
fr – francuski
ru – rosyjski
it – włoski
es – hiszpański
ua – ukraiński
de – niemiecki

API - Dokumenty sprzedażowe

Punkt dostępowy

Metody

Pola

Pozostałe pola

Filtry

Obiekt filtrów

Dostępne filtry

Przykładowe zapytania

Streamsoft Firmino API