Connector API
Search…
Bills

Get all bills

Returns all bills, possibly filtered by customers, identifiers and other filters.

Request

[PlatformAddress]/api/connector/v1/bills/getAll
1
{
2
"ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
3
"AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
4
"Client": "Sample Client 1.0.0",
5
"BillIds": [
6
"e654f217-d1b5-46be-a820-e93ba568dfac"
7
],
8
"CustomerIds": [
9
"fe795f96-0b64-445b-89ed-c032563f2bac"
10
],
11
"State": "Closed",
12
"ClosedUtc": {
13
"StartUtc": "2020-02-05T00:00:00Z",
14
"EndUtc": "2020-02-10T00:00:00Z"
15
},
16
"CreatedUtc": {
17
"StartUtc": "2020-02-05T00:00:00Z",
18
"EndUtc": "2020-02-10T00:00:00Z"
19
},
20
"DueUtc": null,
21
"PaidUtc": null,
22
"Extent": {
23
"Items": false
24
}
25
}
Copied!
Property
Type
Contract
Description
ClientToken
string
required
Token identifying the client application.
AccessToken
string
required
Access token of the client application.
Client
string
required
Name and version of the client application.
BillIds
array of string
optional, max 1000 items
Unique identifiers of the Bills. Required if no other filter is provided.
CustomerIds
array of string
optional, max 1000 items
Unique identifiers of the Customers.
State
string
optional
Bill state the bills should be in. If not specified Open and Closed bills are returned.
ClosedUtc
optional, max length 3 months
Interval in which the Bill was closed.
CreatedUtc
optional, max length 3 months
Interval in which the Bill was created.
DueUtc
optional , max length 3 months
Interval in which the Bill is due to be paid.
PaidUtc
optional, max length 3 months
Interval in which the Bill was paid.
Extent
required
Extent of data to be returned. E.g. it is possible to specify that together with the bills, payments and revenue items should be also returned.

Time interval

Property
Type
Contract
Description
StartUtc
string
required
Start of the interval in UTC timezone in ISO 8601 format.
EndUtc
string
required
End of the interval in UTC timezone in ISO 8601 format.

Bill state

  • Open
  • Closed

Bill extent

Property
Type
Contract
Description
Items
bool
required
Whether the response should contain payments and revenue items.

Response

1
{
2
"Bills": [
3
{
4
"Id": "26afba60-06c3-455b-92db-0e3983be0b1d",
5
"AccountId": "fe795f96-0b64-445b-89ed-c032563f2bac",
6
"CustomerId": "fe795f96-0b64-445b-89ed-c032563f2bac",
7
"CompanyId": null,
8
"CounterId": null,
9
"State": "Closed",
10
"Type": "Invoice",
11
"Number": "29",
12
"VariableSymbol": null,
13
"CreatedUtc": "2017-01-31T10:48:06Z",
14
"IssuedUtc": "2017-01-31T10:58:06Z",
15
"TaxedUtc": null,
16
"PaidUtc": null,
17
"DueUtc": null,
18
"Notes": "",
19
"Options": {
20
"DisplayCustomer": true,
21
"DisplayTaxation": true,
22
"TrackReceivable": true,
23
"DisplayCid": false
24
},
25
"OrderItems": [],
26
"PaymentItems": [],
27
"AssigneeData": {
28
"Discriminator": "BillCustomerData",
29
"Value": {
30
"ItalianFiscalCode": null
31
}
32
}
33
}
34
]
35
}
Copied!
Property
Type
Contract
Description
Bills
array of Bill
required
The filtered bills.

Bill

Property
Type
Contract
Description
Id
string
required
Unique identifier of the bill.
AccountId
string
required
Unique identifier of the account (for example Customer) the bill is issued to.
CustomerId
string
optional
Unique identifier of the Customer the bill is issued to.
CompanyId
string
optional
Unique identifier of the Company the bill is issued to.
CounterId
string
optional
Unique identifier of the bill Counter.
State
string Bill state
required
State of the bill.
Type
string Bill type
required
Type of the bill.
Number
string
required
Number of the bill.
VariableSymbol
string
optional
Variable symbol of the bill.
CreatedUtc
string
required
Date and time of the bill creation in UTC timezone in ISO 8601 format.
IssuedUtc
string
required
Date and time of the bill issuance in UTC timezone in ISO 8601 format.
TaxedUtc
string
optional
Taxation date of the bill in UTC timezone in ISO 8601 format.
PaidUtc
string
optional
Date when the bill was paid in UTC timezone in ISO 8601 format.
DueUtc
string
optional
Bill due date and time in UTC timezone in ISO 8601 format.
Notes
string
optional
Additional notes.
Options
required
Options of the bill.
OrderItems
array of Order item
required
The order items (consumed items such as nights or products) on the bill.
PaymentItems
array of Payment item
required
The payment items (such as cash, credit card payments or invoices) on the bill.
AssigneeData
optional
Additional information about assignee of the bill. Persisted at the time of closing of the bill.

Bill type

A bill is either a Receipt which means that it has been fully paid, or Invoice that is supposed to be paid in the future.
  • Receipt - the bill has already been fully paid.
  • Invoice - the bill is supposed to be paid in the future. Before closing it is balanced with an invoice payment.

Bill options

Property
Type
Contract
Description
DisplayCustomer
boolean
required
Display customer information on a bill.
DisplayTaxation
boolean
required
Display taxation detail on a bill.
TrackReceivable
boolean
required
Tracking of payments is enabled for bill, only applicable for Invoice.
DisplayCid
boolean
required
Display CID number on bill, only applicable for Invoice.

Bill assignee data

Property
Type
Contract
Description
Discriminator
required
Determines type of value.
Value
object
required
Structure of object depends on Bill assignee data discriminator.

Bill assignee data discriminator

  • BillCustomerData - Assignee data specific to a customer.
  • BillCompanyData - Assignee data specific to a company.

Bill customer data

Property
Type
Contract
Description
ItalianFiscalCode
string
optional
Italian fiscal code.

Bill company data

Add bill

Creates new empty bill assigned to specified account.

Request

[PlatformAddress]/api/connector/v1/bills/add
1
{
2
"ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
3
"AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
4
"Client": "Sample Client 1.0.0",
5
"Bills": [
6
{
7
"AccountId": "a5786a7b-a388-43cc-a838-abd7007b5ff7"
8
}
9
]
10
}
Copied!
Property
Type
Contract
Description
ClientToken
string
required
Token identifying the client application.
AccessToken
string
required
Access token of the client application.
Client
string
required
Name and version of the client application.
Bills
array of Bill parameters
required, max 1000 items
Information about bills to be created.

Bill parameters

Property
Type
Contract
Description
AccountId
string
required
Unique identifier of the account (for example Customer) the bill is issued to.

Response

1
{
2
"Bills": [
3
{
4
"Id": "177966b7-f3d9-42b7-ba49-abd80057329b",
5
"AccountId": "fe795f96-0b64-445b-89ed-c032563f2bac",
6
"CustomerId": "a5786a7b-a388-43cc-a838-abd7007b5ff7",
7
"CompanyId": null,
8
"CounterId": null,
9
"State": "Open",
10
"Type": "Receipt",
11
"Number": null,
12
"VariableSymbol": null,
13
"CreatedUtc": "2020-06-12T05:17:28Z",
14
"IssuedUtc": null,
15
"TaxedUtc": null,
16
"PaidUtc": null,
17
"DueUtc": null,
18
"Notes": null,
19
"OrderItems": [],
20
"PaymentItems": []
21
}
22
]
23
}
Copied!
Property
Type
Contract
Description
Bills
array of Bill
required
The created bills.

Delete bill

Removes selected bills. Bill must be empty, otherwise it's not possible to delete it.

Request

[PlatformAddress]/api/connector/v1/bills/delete
1
{
2
"ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
3
"AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
4
"Client": "Sample Client 1.0.0",
5
"BillIds": [
6
"177966b7-f3d9-42b7-ba49-abd80057329b"
7
]
8
}
Copied!
Property
Type
Contract
Description
ClientToken
string
required
Token identifying the client application.
AccessToken
string
required
Access token of the client application.
Client
string
required
Name and version of the client application.
BillIds
array of string
required
Unique identifiers of the Bills to be deleted.

Response

1
{}
Copied!

Close bill

Closes a bill so no further modification to it is possible.

Request

[PlatformAddress]/api/connector/v1/bills/close
1
{
2
"ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
3
"AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
4
"Client": "Sample Client 1.0.0",
5
"BillId": "44eba542-193e-47c7-8077-abd7008eb206",
6
"Type": "Receipt",
7
"BillCounterId": "84b25778-c1dd-48dc-8c00-ab3a00b6df14",
8
"FiscalMachineId": null,
9
"Options": {
10
"DisplayCustomer": {
11
"Value": false
12
},
13
"DisplayTaxation": null
14
},
15
"TaxedDate": {
16
"Value": "2020-07-07"
17
},
18
"DueDate": {
19
"Value": "2020-07-14"
20
},
21
"VariableSymbol": {
22
"Value": "5343"
23
},
24
"TaxIdentifier": {
25
"Value": "446768"
26
},
27
"Notes": {
28
"Value": "Bill closing note"
29
}
30
}
Copied!
Property
Type
Contract
Description
ClientToken
string
required
Token identifying the client application.
AccessToken
string
required
Access token of the client application.
Client
string
required
Name and version of the client application.
BillId
string
required
Unique identifier of the Bill to be closed.
Type
string Bill type
required
Specifies the mode bill should be closed in.
BillCounterId
string
optional
Unique identifier of the Counter to be used for closing. Default one is used when no value is provided.
FiscalMachineId
string
optional
Unique identifier of the Fiscal Machine to be used for closing. Default one is used when no value is provided.
Options
optional
Options of the bill. If not provided both DisplayCustomer and DisplayTaxation are set by default.
TaxedDate
optional
Date of consumption for tax purposes. Can be used only with Bill type Invoice.
DueDate
optional
Deadline when Bill is due to be paid. Can be used only with Bill type Invoice.
VariableSymbol
optional
Optional unique identifier of requested payment. Can be used only with Bill type Invoice.
TaxIdentifier
optional
Tax identifier of account to be put on a bill.
Notes
optional
Notes to be attached to bill.
Address
optional
Address of the account to be displayed on bill. Overrides the default one taken from account profile.

Bill options parameters

Property
Type
Contract
Description
DisplayCustomer
required
Display customer information on a bill.
DisplayTaxation
required
Display taxation detail on a bill.

String update value

Property
Type
Contract
Description
Value
string
optional
Value which is to be updated.

Bool update value

Property
Type
Contract
Description
Value
bool
optional
Value which is to be updated.

Response

1
{
2
"Bills": [
3
{
4
"Id": "44eba542-193e-47c7-8077-abd7008eb206",
5
"CustomerId": "7eaf9da6-7229-454a-8cb0-abd700804bd2",
6
"CompanyId": null,
7
"CounterId": "84b25778-c1dd-48dc-8c00-ab3a00b6df14",
8
"State": "Closed",
9
"Type": "Receipt",
10
"Number": "84",
11
"VariableSymbol": null,
12
"CreatedUtc": "2020-06-11T08:39:32Z",
13
"IssuedUtc": "2020-06-25T08:49:38Z",
14
"TaxedUtc": "2020-06-25",
15
"PaidUtc": null,
16
"DueUtc": null,
17
"Notes": null,
18
"Options": {
19
"DisplayCustomer": false,
20
"DisplayTaxation": true,
21
"TrackReceivable": false,
22
"DisplayCid": false
23
},
24
"OrderItems": [],
25
"PaymentItems": []
26
}
27
]
28
}
Copied!
Property
Type
Contract
Description
Bills
array of Bill
required
The closed bill.

Get bill PDF

Creates a PDF version of the specified bill. In case it's not possible to return PDF immediately, you must retry the call later while providing the unique event identifier that is returned from the first invocation.

Request

[PlatformAddress]/api/connector/v1/bills/getPdf
1
{
2
"ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
3
"AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
4
"Client": "Sample Client 1.0.0",
5
"BillId": "44eba542-193e-47c7-8077-abd7008eb206",
6
"BillPrintEventId": null
7
}
Copied!
Property
Type
Contract
Description
ClientToken
string
required
Token identifying the client application.
AccessToken
string
required
Access token of the client application.
Client
string
required
Name and version of the client application.
BillId
string
required
Unique identifier of the Bill to be printed.
BillPrintEventId
string
optional
Unique identifier of the Bill print event returned by previous invocation.

Response

1
{
2
"BillId": "44eba542-193e-47c7-8077-abd7008eb206",
3
"Result": {
4
"Discriminator": "BillPdfFile",
5
"Value": {
6
"Base64Data": "JVBER....."
7
}
8
}
9
}
Copied!
Property
Type
Contract
Description
BillId
string
required
The unique identifier of printed Bill.
Result
object Bill PDF result
required
The result of operation.

Bill PDF result

Property
Type
Contract
Description
Discriminator
required
Determines type of result.
Value
object
required
Structure of object depends on Bill PDF result discriminator.

Bill PDF result discriminator

  • BillPdfFile - PDF version of a Bill was successfully created, Value is Bill PDF file.
  • BillPrintEvent - PDF version of a Bill couldn't be created at this moment (for example bill haven't been reported to authorities yet), Value is Bill print event.

Bill PDF file

Property
Type
Contract
Description
Base64Data
string
required
BASE64 encoded PDF file.

Bill print event

Property
Type
Contract
Description
BillPrintEventId
string
required
Unique identifier of print event. Must be used in retry calls to retrieve the PDF.