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)

Pola

ParametrOpisUwagiTyp danych
idIdentyfikatorlong
ordinalNumberNumer porządkowy faktury (domyślnie najniższy dostępny numer na dzień wystawienia dokumentu)integer
documentNameNazwa dokumentu (przykład: Faktura VAT 1/11/2019)Tylko do odczytustring
documentDateData wystawienia dokumentu (domyślnie aktualna data)string(yyyy-mm-dd)
saleDateData sprzedaży (domyślnie aktualna data)string(yyyy-mm-dd)
salePlaceMiejsce sprzedaży (domyślnie miejsce prowadzenia firmy)string(60)
documentTypeTyp 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
Niedytowalnystring
documentFunctionRodzaj 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 odczytustring
documentStateStatus 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 odczytustring
priceTypeDokument liczony od Netto lub Brutto (domyślnie "net")



Dostępne:
  • net - netto
  • gross - brutto
string

Pozostałe pola

Przykładowe zapytania

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

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

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

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

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

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

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

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

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

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

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"

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