Cashbook Entry API

Introduction

The cashbook entry API provide endpoints to create or query cashbook entries for both cash register and vault settlements. Cashbook entries represent a record of money movement in or out of a vault or cash registers in a store. The cashbook entries created in this API are meant to record internal money movements in a retail store, for example: buying supplies, paying for services, getting revenues from vending machines, etc. These cashbook entries are not associated to retail transactions. They must be associated to active a settlement since they are taken into account when the total cash is calculated in process of previewing and closing the settlement. This API enables the staff in stores to create cashbook entries for active settlements for different reasons they define in their business operations.

For more details about this API usage check our API documentation

Preparation

  • Have an authenticated token from the authentication service, this token should be used as an authorization bearer token header for every request done in this API (more information about the authorization service here).
  • A settlementId of a settlement (cash register or vault) in OPEN state (more information about settlements here).
  • When creating a cashbook entry, make sure to have a valid account value the cashbook entry will be associated to (more information about cashbook accounts here).

Create cashbook entry for a cash register settlement

To create a cashbook entry a POST request needs to be done to the /cashbookentries endpoint with the following request body.

Example request body:

{
"settlementId": "879655de-09f3-433c-a001-8816b56a835f",
"account": "900",
"value": 20000,
"currency": "EUR"
}

These are some important attributes to keep in mind when making the request:

  • The settlementId is the settlement the cashbook entry will be associated to. The settlement should be in OPEN state.
  • The account value is the reason defined by internal business rules the cashbook entry will be done for, in this example, a numeric value is used. An existing and valid account should be used, and the user must be aware of its meaning. Is worth mentioning there are accounts that are only valid cash register or vault settlements but not both.
  • value is the monetary value of the cashbook entry, the units are represented in cents (20000 represents 200,00€).

Example response:

{
"cashbookEntryId": "550a5fdd-5f2d-4863-a8df-b6556d447dd9",
"settlementId": "879655de-09f3-433c-a001-8816b56a835f",
"amount": -20000,
"userName": "Paulo Zavaleta",
"timestamp": 1551183271256,
"paymentMethod": "CASH",
"cashbookEntryType": "NON_RETAIL_BOOKING",
"account": "186",
"isManualBooking": true,
"apiResponseStatus": {
"responseCode": "I06101",
"message": "Cashbook entry created successfully."
}
}

Here are some important observations in the response:

  • cashbookEntryId is an automatically generated UUID value of the newly created cashbook entry.
  • paymentMethod value is by default cash. So far, the cashbook entries in this API can only be created for money movements in cash.
  • cashbookEntryType is the type of cashbook entry, this indicates if the cashbook entry was created from a retail transaction (sale or refund) or not . Cashbook entries created on this API are not related to retail transactions, so their value is always NON_RETAIL_BOOKING.
  • isManualBooking is a flag to determine if the cashbook entry was manually created by the staff in the store. All the cashbook entries created in this API are manual bookings, so the value is always true.

Get cashbook entries for a store in a specific date

Sometimes the staff at a retail store might want to have details about the money movements happening in a given date, so they can elaborate reports based on them. For this kind of needs there is an endpoint available in this API. To get the cashbook entries generated in store for a specific date we need to make GET request with the following request parameters /cashbookentries/report?store=1337&date=22-07-2020. Make sure the date is provided in the format 'dd-MM-yyyy', no request body is required.

Response:

{
"cashbookEntries": [
{
"cashbookEntryId": "aa0c1f07-e346-48b2-9a53-f33ff4150226",
"settlementId": "a7d996b1-3406-4f32-886b-723252a9be4f",
"store": "1337",
"stationId": 9,
"amount": 50000,
"userName": "Erika Mustermann",
"timestamp": 1566294123243,
"currency": "EUR",
"cashbookEntryType": "NON_RETAIL_BOOKING",
"account": "901",
"isManualBooking": false,
"paymentMethod": "CASH",
"sequenceNumber": -1
},
{
"cashbookEntryId": "14719680-2e93-41f0-8750-a19986f54967",
"settlementId": "ca947a1a-0ebd-458b-bb69-1cf23613620f",
"store": "1337",
"stationId": 0,
"amount": -50000,
"userName": "Erika Mustermann",
"timestamp": 1566294123375,
"currency": "EUR",
"cashbookEntryType": "NON_RETAIL_BOOKING",
"account": "901",
"isManualBooking": false,
"paymentMethod": "CASH",
"sequenceNumber": -4
}
],
"apiResponseStatus": {
"responseCode": "I06102",
"message": "Cashbook entries retrieved successfully."
}
}

Here are some important observations in the response:

  • cashbookEntries is the list of cashbook entries created for all settlements created in the store and date provided. The list includes entries from retail transactions of non retail transactions.

Get cashbook entry XML printing instructions for cash register settlement

Part of the process of creating cashbook entries in this API is to print a receipt containing information about them. This API provides an endpoint to generate printing instructions in XML format that contains general information of them. To generate such printing instructions a GET request needs to be done to /cashbookentries/{cashbookEntryId}/xml, no request body is required.

Example response:

{
"xml": "<receipt><line><leftcol='3'>Es bediente Sie Erika Mustermann</left></line><line><br/></line>",
"apiResponseStatus": {
"responseCode": "I06103",
"message": "Cashbook entry XML printing instructions generated successfully."
}
}

Here are some important observations in the response:

  • xml contains a string with the specialized printing instructions of the cashbook entry provided in the request, is important to mention that only cashbook entries not related to retail transactions are allowed to have printing instructions. |