DATECS Integration for KRA Approved TIMS ETR/ESD
Integrating a KRA-approved Datecs TIMS-compliant control unit and an electronic tax register (ETR/ESD) with a Json API
The Datecs API is a strong and adaptable Webservice for connecting dissimilar software applications. The APIs enable a wide range of unrelated software applications to integrate and communicate with other KRA-approved TIMS Compliant Control Units. The API also enables developers to add a diverse set of queries for other information from the device to their software, such as the status of the control unit, printing copies of previously issued receipts, and other capabilities.
The Advantages of Datecs ETR
- No installations
- No driver or API installations are required for Datecs ETR Control Unit.
- Quick Integration
- With its simplified & seamless use, KRA Approved & TIMS-compliant Datecs ESD/ ETR are fast to integrate.
- Manage your Network Security
- Keep your network secured and allows you to manage communications on the ports with Easily configurable ports on the Datecs Control Unit (ESD/ETR).
- JSON integration – reduces time and cost of integration
- JSON is a data interchange format that is a common data format with diverse uses and the majority of the systems have JSON exchange readily available thus allowing users to quickly integrate and move to Datecs TIMS compliant ESD/ETR.
- Transmit data seamless with multiple connections
- Smaller data interchange, less traffic on the network, reduced cost and increased speed allows Datecs KRA Approved & TIMS-compliant devices to transmit data seamlessly and the device allows multiple authentications.
- Major programming languages
- KRA Approved & TIMS-compliant Datecs devices use JSON for communication. JSON is an abbreviation for JavaScript Object Notation. It is a data exchange format, which is another way of stating it is a method of storing and exchanging data. And, despite the name, JSON is so basic that support for reading and writing is built into practically every system or programming language used for Web applications.
The Datecs API is compatible with a variety of operating systems.
With No Installations Required, Datecs KRA Approved TIMS Compliant ETR can be used from any operating system as long as they support network communication and browser.
Basic Network Scheme for Datecs ETR
Step 1: Data collection for transmission to the
ETR/ESD
API
A Control Unit or otherwise called Middleware is a device responsible for Validating the data from the end user’s system through API calls. A control unit will take a set of information as per request transactions and validate the same and return information of signature which is QRCode URL, Middleware transaction number or Control Unit Invoice Number, Control Unit Serial Number, Date-Time, Type of Transaction, Total Items and Related Invoice Number.
The Datecs Control Unit (Type B or Type C), validates 3 types of transactions
- Invoices (Cash receipt, POS Sales, Credit Invoices and any other related data )
- Credit Notes (Goods Return, Credit note – Partial or full )
- Debit Notes
Data/Information passed to Datecs Control Unit.
Header Information
To validate the transactions, various bits of information from the transaction header are sent to the control unit. These details are mostly contained in the transaction’s header section.
- Cashier: Name of the Cashier (Optional)
- Invoice Type: Indicates whether the Original Invoice or Copy of the invoice is being transmitted to Control Unit
- Transaction Type: Invoice/Credit Note/Debit Note
- Trader System invoice Number: Software-generated Transaction numbers
- Exemption Number: It represents the respective exemption number given to the Buyer (Optional).
Buyer Information
The buyer’s information is located in the header section of the transaction, When selling to a VAT Registered buyer the Control Unit will require this information to validate.
- Pin Of Buyer: The Pin is an 11-character string Starting with either A/P – 9 digits and a Character at the end(P123456789Z).
- Name of Buyer: Company name or Buyer’s Name(Optional)
- Address of Buyer: Address of the Buyer(Optional)
- Buyer’s Phone: The registered phone number of the buyer (Optional)
Items List
The item list is generally found in the detail section of the transaction, the item list can consist of numerous lines and data depending on the type of Billing software used. Typical billing software will have an Item name, Quantity of Items sold, Prices and Discounts.
When it comes to storing transaction data in the Control Unit, Datecs ETR Devices are one of the most flexible. Though not all data is transferred to TIMS the information is stored in the Control Unit for future reference and ease of printing.
- GTIN: The Global Trade Item Number which is widely known as a barcode number can be passed with every single item.
- Name: PLU Name or Item name
- Quantity: The Item Quantity in the transaction
- HS Code: The Tax of the Item is identified from the HS Code supplied. As HS Codes are not given from the trader system then the default of 16% tax will be applied however, HS Codes are mandatory for all the other Vat (The 8% Items, Zero Rated and Exempted Items)
- Unit Price: The Inclusive price of the item in the transaction.
- Discounts: Amount of Discount for each item
Apart from the Item Name, the extra description tag allows 10 Extra fields of information for the product and this info is stored in the control unit.
Other Information
- Relevant Number: The Relevant number refers to the previously received invoice number from the control unit to which a credit or debit note is to be issued. The relevant number is only used when doing a Credit Note or a Debit Note.
Step 2: Transmitting data to Datecs ETR Control Unit
Before using the Datecs API, the data must be preformatted in JSON. Data is exchanged through HTTP Methods.
The Hypertext Transfer Protocol (HTTP) allows clients and servers to communicate with one another. It also specifies a set of request methods for the Datecs API to conduct a certain action. JSON API in Datecs supports the GET and POST HTTP protocols.
All request made to Datecs API needs Header information. The headers in the Request depend on the type interchange done by the API.
General Example of Request Headers:
- Accept: application/json
- Content-Type: application/json
- Content-Length: <calculated when request is sent>
Step 3: Acknowledgement and Response
The Datecs API responds back by providing the object of either success or error on Transmitting the data to the control unit for a transaction. On success, the client will receive information such as
- Date Time: The date and time the transaction on the Control Unit was validated.
- Invoice Extension: Transaction type, such as Invoice, Credit Note, or Debit Note.
- Transaction Number: A 19-digit transaction number that identifies the entry in the control Unit and on the TIMS Server. Verification Url: A QrCode URL that refers to the TIMS Server transaction.
- Message: The Control Unit logged a Success message indicating that the transaction was successful.
- Total Amount: The Total Amount for the current Transaction as recorded in the Control Unit.
- Total Items: The total number of items recorded in the current transaction.
- Serial Number: The Serial Number of the Control Unit that logged this Transaction. It is also referred to as a CSN (Control Unit Serial Number) or an MSN (Middleware Serial Number).
Understanding Errors
When an error occurs, the API returns an Error Object with additional information about the error type.
- Message: This generally implies that a Bad Request was made to the Control Unit.
- Model State: The Model State returns a list of Errors encountered during the request. It is made up of the Property and Errors.
- Property & Error Code: Indicates the error type and details, such as
- There are no items for a credit note! (1999 Error Code).
- A pin code is required! (Error Code: 1500)
Download the step-by-step document for Simplified Datecs API User Manual to test the API or request for a Postman Collection below.
To check some of our ready-to-use Integrated Applications click here.