Reports API has a number of endpoints available that can be used to generate reports.
This article shows some of the connections to the existing API/back office Z-report and how something similar could be composed using this API.
Service Endpoints
Use the “getServiceEndpoints” call from Erply API to get the correct endpoint for your account.
Authentication
Reports API uses Erply session key and client code for authentication. These must be provided in the header of the requests:
clientCode- Account numbersessionKey- The erply API session key.
Swagger Documentation
The sandbox swagger doc is located in https://api-reports-eu10.erply.com/documentation/index.html
Z Report
The original report output can be divided into separate sections. Let's look at each section separately.
Opened And Closed Days (Shifts)
The biggest block on the report. To generate something similar we need to use a couple of different requests.
We will use the following requests for this:
/v1/POSDay
/v1/POSDay/transaction/cashflow
/v1/POSDay/transaction/total-by-type
/v1/POSDay
With this request we get the main details of the shift. This includes information on when the day was opened and when it was closed (if it was closed).
Following sections can be obtained from the json content. Since the API also provides ids to objects they could be used to request further information from Erply API.
We now have the day start and (if it has ended) end dates and additional details.
/v1/POSDay/transaction/cashflow
The cashflow endpoint gives out the cash in and out movements as an array. We use the register ID and the timestamps to associate the records with the correct shift. To get the total amount moved we need to add the amounts as a total.
/v1/POSDay/transaction/total-by-type
With this request we will be able to calculate daily totals and get the details for totals by transaction types. As with cash-in and cash-out operations, the totals can be associated with shifts using the register ID and timestamps (data that we got with the /v1/POSDay request).
Now we can use the data from all 3 requests to calculate totals for some values that were not immediately given:
Day income, Day income + all cash in & out, over/short total and transitions total. We can use the cash flow amount totals with transactions totals by type totals to get these values.
Transactions by type
In the existing report this composes the blocks that basically show all transactions by the transaction type.
For this we use the /v1/POSDay/transaction request:
The response does not provide totals. This would need to be calculated manually by the result set.
Added and paid store credits
For this we use the following requests:
/v1/POSDay/transaction/credit-added
/v1/POSDay/transaction/credit-paid
To make a connection to a certain day we can again use the POS id and the timestamps from the first /v1/POSDay request.
The output of this section is very straightforward and can pretty much be composed using the results of the request. Similarly to the transactions request.
{
"amount": 0,
"currency": {
"code": "string",
"id": 0
},
"dateTimeUnix": 0,
"document": {
"documentNo": "string",
"id": 0,
"typeId": 0
},
"pointOfSale": {
"id": 0,
"name": "string",
"shopName": "string"
},
"warehouse": {
"code": "string",
"id": 0
}
}
}Void transactions
For this we use the /v1/POSDay/transaction/void request.
To make a connection to a certain day we can again use the POS id and the timestamps from the first /v1/POSDay request.
The output here is also simple and can be used to form any kind of table/chart etc.
{
"amount": 0,
"currency": {
"code": "string",
"id": 0
},
"dateTimeUnix": 0,
"document": {
"documentNo": "string",
"id": 0,
"typeId": 0
},
"paymentType": {
"cardType": "string",
"id": 0,
"type": "string"
},
"pointOfSale": {
"id": 0,
"name": "string",
"shopName": "string"
}
}