API - Pozycje Dokumentu

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 dla dokumentu)
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)

Pola

Parametr	Opis	Uwagi	Typ danych
orderNo	Numer porządkowy (Lp.)	Tylko do odczytu	integer
idArticle	Identyfikator produktu (jeżeli produkt jest zapisany w bazie)		long
name	Nazwa produktu		string(512)
unit	Jednostka miary (domyślnie szt) nowe jednostki automatycznie dodawane do bazy		string(30)
vatRate	Stawka VAT (domyślnie 23)		string
price	Cena jednostkowa		string(999.99)
quantity	Ilość		string(999.9999)
discount	bonifikata/upust (domyślnie 0)	(0.00-100.00) od 0% do 100%	string(100.00)

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.00",
            "date": null,
            "table": null
        }
		"payment": {
            "method": "Przelew",
            "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": [
            {
                "id": 6853753,
                "idSaleDocument": null,
                "idArticle": null,
                "name": "PRODUKT X",
                "unit": "szt",
                "vatRate": "23",
                "price": "21.22",
                "quantity": "1.00",
                "discount": "0.00"
            }
        ],
        "currency": {
            "code": "PLN",
            "rate": "1.00",
            "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": [
            {
                "id": 6882115,
                "idArticle": 496332,
                "name": "TOWAR TESTOWY",
                "unit": "szt",
                "vatRate": "8",
                "price": "10.50",
                "quantity": "2.00",
                "discount": "0.00"
            }
        ],
        "currency": {
            "code": "PLN",
            "rate": "1.00",
            "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

Przykład CURL:

Żądanie (JSON):

Odpowiedź (JSON):

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."
}

API - Pozycje Dokumentu

Punkt dostępowy

Metody

Pola

Przykładowe zapytania

Streamsoft Firmino API