API - Rozliczenie 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

ParametrOpisUwagiTyp danych
methodMetoda płatności (domyślnie "transfer" - Przelew)



Dostępne:
  • transfer - Przelew
  • cash - Gotówka
  • card - Karta
  • electro - Płatność elektroniczna
  • compens - Kompensata
  • prepay - Przedpłata
  • split - Metoda podzielonej płatności
  • cod - Za pobraniem
  • other - Inna
string
paymentDateData opłacenia dokumentu (wartość pusta jeżeli dokument nie został opłacony)Tylko do odczytustring(yyyy-mm-dd)
termDateTermin zapłatystring(yyyy-mm-dd)
totalKwota dokumentuTylko do odczytustring(999.99)
paidKwota zapłaconaTylko do odczytustring(999.99)
remainKwota pozostała do zapłatyTylko do odczytustring(999.99)

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