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
| 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:
| Niedytowalny | string |
| documentFunction | Rodzaj dokumentu (domyślnie "normal" - zwykły dokument) Dostępne:
| Tylko do odczytu | string |
| documentState | Status dokumentu (domyślnie "new" - Nowy, wystawiony) Dostępne:
| Tylko do odczytu | string |
| priceType | Dokument liczony od Netto lub Brutto (domyślnie "net") Dostępne:
| 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
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."
}
