Table of Contents

1. Document revision. ....................................................................................................................... 4

2. Introduction ................................................................................................................................... 2
2.1. Overview ................................................................................................................... 2
2.2. Audience ................................................................................................................... 2
3. Technical Reference ...................................................................................................................... 2
3.1. VSDC Environments................................................................................................ 2
3.2. Authentication .......................................................................................................... 3
3.3. Data Types ................................................................................................................ 3
3.4. Request and Response Bodies.................................................................................. 3
3.5. Process Flow ............................................................................................................. 3
3.6. Response Codes ........................................................................................................ 3
4. Getting Started .............................................................................................................................. 4
4.1. Signup and Registration .......................................................................................... 4
4.2. VSDC Setup and Initialization ................................................................................ 4
4.3. VSDC Services .......................................................................................................... 5
4.4. VSDC API Versions ................................................................................................. 6
4.5. Interacting with the VSDC API............................................................................... 6
4.6. Sample Request Illustration using Postman API Client ........................................ 6
5. VSDC API Services ....................................................................................................................... 8
5.1. Device Initialization.................................................................................................. 8
5.2. Standard Codes (Constants) .................................................................................. 10
5.3. Classification Codes ............................................................................................... 12
5.4. Notices ..................................................................................................................... 14
5.5. Branch Information ............................................................................................... 15
5.6. Customer Information ........................................................................................... 18
5.7. Item Information .................................................................................................... 21
5.8. Import Information................................................................................................ 32
5.9. Sales Information ................................................................................................... 37
5.10. Purchase Information ............................................................................................ 81
5.11. Stock Information .................................................................................................. 89
6. Code Definition............................................................................................................................ 98
6.1. Tax Type ................................................................................................................. 98
6.2. Product Type .......................................................................................................... 98
6.3. Countries code ........................................................................................................ 98
6.4. Packaging Unit ..................................................................................................... 106
6.5. Units of measure ................................................................................................... 108
6.6. Currency ............................................................................................................... 109
6.7. Transaction Type ................................................................................................. 109
6.8. Sales Receipt Type................................................................................................ 110
6.9. Payment Method .................................................................................................. 110
6.10. Transaction Progress ........................................................................................... 110
6.11. Registration Type ................................................................................................. 110
6.12. Purchase Receipt Type......................................................................................... 111
6.13. API Response Code .............................................................................................. 111
6.14. Stock In/Out Type ................................................................................................ 112
6.15. Refund Reason Code ............................................................................................ 112
6.16. Item code Generation ........................................................................................... 112
6.17. Import Item status................................................................................................ 113
6.18. Debit note reason. ................................................................................................. 113
1. Document revision.

VSDC Service What’s New Affected Endpoint

Device Initialization No Changes N/A
Standard System Codes No Changes N/A
Classification Codes No Changes N/A
Branch Information No Changes N/A
Notices No Changes N/A
Item Information Adjusted length of item_code /item/saveItem
Import Information No Changes N/A

Sales Information 1. Added endpoint to retrieve uploaded /trnsSales/selectInvoice

invoice.
2. Added functionality to issue credit note orgSdcId field added to allow
from different branch. for this
3. Fixed issues with tax amount validations
on all sales endpoints.
Purchase Information No Changes N/A
Stock Information No Changes N/A
Acronyms
ZRA – Zambia Revenue Authority
VSDC – Virtual Sales Data Controller
API – Application Programming Interface
ERP – Enterprise Resource Planning
CIS – Certified Invoicing Solution
TPIN – Taxpayer Identification Number
REST – Representational State Transfer
JSON – JavaScript Object Notation
HTTP – Hypertext Transfer Protocol
UAT – User Acceptance Testing
WAR – Web Application Archive
JAR – Java Archive
ASYCUDA - Automated System for Customs Data

1
2. Introduction
2.1. Overview
Smart Invoice is a software solution implemented by the Zambia Revenue Authority (ZRA) to
facilitate and execute electronic invoicing processes and optimize stock management. It serves
as a comprehensive tool utilized by all taxpayers and business proprietors to oversee and
conduct various invoice transactions, monitor stock levels, track stock movements, and
efficiently manage operations across multiple branches or locations. In instances where
taxpayers utilize their independent invoicing solutions, ZRA extends support through a Virtual
Sales Data Controller (VSDC), that acts as a seamless bridge between Certified invoicing
systems and ZRA Smart Invoice. This document is designed to provide developers and third-
party integrators with comprehensive information on essential components, including API
endpoints, data models, and guidance on seamlessly integrating their invoicing systems with
the Smart Invoice through the VSDC API.
2.2. Audience
The target audience of this document comprise individuals utilizing private Enterprise
Resource Planning Systems (ERPs) and developers/vendors of these third-party invoicing
solutions.

3. Technical Reference
3.1. VSDC Environments
The VSDC API provides functionality in two distinct environments: Test and Production. The
Test VSDC API is utilized in a test environment, ensuring no impact on production data during
integration testing and development. The test VSDC API allows access to data that is
specifically linked to the taxpayer's Taxpayer Identification Number (TPIN) and device
registration information captured within Smart Invoice sandbox. By using the Test VSDC API,
you can securely validate and test your integration without the possibility of unintended
alterations to actual sales, import, purchase, and stock information in the production
environment.
After development and testing, and once the integration with the test VSDC has successfully
passed User Acceptance Testing (UAT), the CIS is rolled out in the live environment for
smooth integration and operational purposes. In the production environment, the production
VSDC API manages and processes actual sales, import, purchase, and stock information.

2
Other technical details to be used for reference are outlined in the table below.

Title Content
Supported Programming Languages All
Architectural Style REST
Communication Protocol HTTP
Data Exchange Format JSON
Supported Operating System Windows Server/10+, Unix, Linux
Supported Webservers Apache HTTPd server, Apache Tomcat,
Eclipse Jetty, Oracle WebLogic
VSDC Java Version Java 1.8
VSDC Distributed Package WAR/JAR
VSDC API Base URL (Production/Test) http://<hostname>:
<server.port>/<vsdcpath>
e.g. https://localhost:8080/zravsdc

3.2. Authentication
The VSDC API utilizes API keys as a security mechanism to authenticate all requests
originating from third-party systems to Smart Invoice. These unique API keys are retrieved by
the VSDC during the device initialization process and stored securely on the server where the
VSDC is hosted. Every subsequent API request sent via the VSDC will inherently contain these
keys, removing the necessity for developers to acquire or add them manually to any request.
3.3. Data Types
The VSDC API operates with data types that align with JSON formatting standards. It is
essential to adhere strictly to the prescribed data formats and structures for requests and
responses as outlined in their respective sections when interacting with each endpoint.

3.4. Request and Response Bodies

The VSDC API utilizes JSON data format for communication. When sending requests, ensure
the data is structured as JSON objects. Similarly, all responses from the API will be encoded
in JSON format for consistent handling and interpretation.

3.5. Process Flow

Some VSDC API endpoints depend on prior operations being finished before they can carry
out the desired transaction or process effectively. In these interconnected endpoints, the
documentation will clearly indicate the prerequisite operations within the corresponding
endpoint section.
3.6. Response Codes
The VSDC API utilizes standard HTTP response codes to communicate API request success
or failure. In addition, custom response codes have been added to the JSON response body to
indicate the specifics of the API request. Refer to Section 5 the API response codes section for
further details.

3
4. Getting Started
4.1. Signup and Registration
To access the VSDC API, users are required to register on the Smart Invoice Taxpayer Portal
initially. Subsequently, they must apply for a VSDC service, undergo technical and
administrative verification, and await approval. Once approved by the Zambia Revenue
Authority (ZRA), users receive the VSDC as a WAR/JAR file, accessible for download from
the Portal under 'Device Management.' They can then deploy and configure it on their local
server for use. The diagram below illustrates this process visually.

Sign Up for Request Download

Approval by
Smart VSDC and deploy
ZRA
Invoice Service VSDC.

Note: Signup and registration take place in both the test and production environments. The
access to each environment depends on the taxpayer's current stage of integration.
4.2. VSDC Setup and Initialization
Once you've installed the VSDC API on your local server, follow the specified steps during
device initialization to activate it for data transmission and reception. Upon completing this
initialization, you can start sending and receiving transaction data with Smart Invoice. The
diagram below visually illustrates this communication process.

4
 4.3. VSDC Services
The VSDC services are categorized into eight (8) groups according to their specific purposes.
Below is a concise overview introducing the purpose of each category.
1. Device initialization
a. The initialization process is used to verify the device's identity, retrieve security
keys, save configuration settings, and prepare the device for interaction with
Smart Invoice.
b. The methods in this category are only invoked during the initial setup of the
VSDC.
2. Code Data
a. The methods in this category are used to fetch standard codes from Smart
Invoice such as item classification codes, tax category codes, package type,
units of measurement, and weight codes.
3. Branch Information
a. The methods in this category are used to transmit specific branch information,
including details about customers and staff and to fetch information about all
registered branches by a taxpayer.
4. Item Information
a. The methods in this category are used to transmit details of products or services
that are registered in a taxpayer's CIS.
5. Import Information
a. The methods in this category facilitate the exchange of all data associated with
imported items by a taxpayer, which have been declared in the ZRA customs
system ASYCUDA. Using these endpoints, a taxpayer can fetch imported items
and register acknowledgement of importation of these items of Smart Invoice.
6. Sales Information
a. The methods in this category are used to transmit sales data from a taxpayer’s
CIS to Smart Invoice.
7. Purchase Information
a. The methods in this category are used to fetch purchases made by a taxpayer
from another Smart invoice user from Smart Invoice, and to transmit purchase
information from a non-Smart Invoice user, from a CIS to Smart Invoice. This
information encompasses precise particulars related to each purchase, including
supplier details, invoice number, item specifics, and the transaction's date and
time.
8. Stock Information
a. The methods in this category are used to transmit information related to the
taxpayer's inventory, including details about stock status, movements, and
adjustments.

5
 4.4. VSDC API Versions
The API version is determined by the release date of a new version. Taxpayers will receive
notifications regarding the latest additions and modifications to the API version through the
publication of the new specifications document on the ZRA website.
4.5. Interacting with the VSDC API
This section demonstrates how to make an API request to the VSDC:
1. VSDC Setup
a. Install the VSDC WAR file, which is acquired after completing the registration
process, onto your server and proceed to run the application.

2. Initiate a request.
a. Select an endpoint and specify the HTTP method to indicate the desired
operation. For example, the 'device initialization' endpoint uses the HTTP
method POST and the path 'initializer/selectInitInfo'.
b. Ensure to identify any necessary parameters that should be included in the
request header, request body, or as part of the path.
c. Upon invocation of the selected endpoint, the API will provide response status
codes, response headers, and a response body.
4.6. Sample Request Illustration using Postman API Client
Request

6
Response

7
5. VSDC API Services
5.1. Device Initialization
The Device Initialization API streamlines the secure establishment of a connection between the VSDC and ZRA’s Smart Invoice backend. It
retrieves security keys from Smart Invoice, which will be used to verify the identity of the communicating device and limit API access to authorized
devices. Additionally, it facilitates the loading of essential configuration settings necessary for seamless integration operations onto the server
hosting the VSDC.

• Endpoint: /initializer/selectInitInfo
• Request method: POST.
• Requirement: MANDATORY
• Description: Initializes the device for interaction between CIS and Smart Invoice. Initial endpoint, only called once for any new device
registration on smart invoice. Retrieves APIs keys used to authenticate and verify user.
• Request Parameters: TPIN, Branch Id, Device Serial No (All provided by ZRA)
• Response: Returns confirmation of successful device initialization along with generated security keys and loaded configuration settings.
• Note: This endpoint is only required to be called once. Details returned in the response MUST be stored locally for future reference.
ERP VSDC API
Device Initialized, API keys
Integration POST /initializer/selectInitInfo
are generated and stored.

Initialization Request
Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length

InitInfoReq Device Initialization tpin Taxpayer’s identification number as TPIN VARCHAR Y 10

Request registered on core Tax Administration
System TaxOnline
bhfId Taxpayer branch (store) locations Branch ID VARCHAR Y 3
identifier
dvcSrlNo VSDC identifier. Supplied by ZRA Device Serial Number VARCHAR Y 100
JSON REQUEST SAMPLE
Request Body {"tpin":"9999999999","bhfId":"000","dvcSrlNo":"20180520000000"}

8
Initialization Response
Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Data Length

InitInfoRes Device Initialization resultCd This is the VSDC response code Result Code VARCHAR 3
Response
resultMsg This is the VSDC response message Result Message VARCHAR 2000
resultDt This is the VSDC response date-time Result Date VARCHAR 14
tpin This is the taxpayer identification number TPIN VARCHAR 10
taxprNm This is the taxpayer’s name as registered on the core Taxpayer Name VARCHAR 255
tax administration system
bsnsActv This is the taxpayer’s main business activity as Business Activity VARCHAR 100
registered on the core Tax Administration system
bhfId Taxpayer branch (store) location identifier Branch Office Id VARCHAR 3
bhfNm Taxpayer branch (store) name Branch Office Name VARCHAR 60
bhfOpenDt This is the date when the branch was initialized Branch Date Created VARCHAR 8
prvncNm This is the taxpayer’s registered province Province Name VARCHAR 100
dstrtNm This is the taxpayer’s registered district District Name VARCHAR 100
sctrNm This is the taxpayer’s registered sector (town) Sector Name VARCHAR 100
locDesc This is the taxpayer’s registered location Location Description VARCHAR 100
hqYn This is an indication of whether the branch is HQ or Head Quarter VARCHAR 1
otherwise. It is registered by ZRA and communicated
with the taxpayer in this endpoint
mgrNm This is the registered name of the applicant for VSDC Manager Name VARCHAR 60
mgrTelNo This is the registered mobile number of the Manager Contract Number VARCHAR 20
VSDC applicant
mgrEmail This is the registered email of the applicant for VSDC Manager Email VARCHAR 50
sdicId This is a unique device identifier supplied by ZRA SDC id VARCHAR 12
mrcNo This is an identifier supplied by ZRA MRC No VARCHAR 11
lastSaleInvcNo This is the last sales invoice number Last Sale Invoice Number NUMBER 38
processed by the device. On initial request the
returned value is 0.
lastPchsInvcNo This is the last purchase invoice number processed by Last Purchase Invoice Number NUMBER 38
the device. On initial request the returned value is 0.
lastSaleRcptNo This is the last sales receipt number processed Last Sale Receipt Number NUMBER 38
by the device. On initial request the returned
value is 0.
lastInvcNo This is the last invoice number processed by the device. Last CIS invoice number NUMBER 38
On initial request the returned value is 0.

9
 lastTrainInvcNo This is the last training invoice number processed Last Training Invoice Number NUMBER 38
by the device. On initial request the returned
value is 0.
lastProfrmInvcNo This is the last proforma invoice number processed by Last Proforma Invoice Number NUMBER 38
the device. On initial request the returned value is 0.
lastCopyInvcNo This is the last copy invoice number processed by Last Copy Invoice Number NUMBER 38
the device. On initial request the returned value is
0.
JSON RESPONSE SAMPLE

Response Body { "resultCd": "000", "resultMsg": "It is succeeded", "resultDt": "20240507072439", "data": { "info": { "tin": "9999999999", "taxprNm": "SMART INVOICE USER", "bsnsActv": null, "bhfId":
"000","bhfNm": "Headquarter","bhfOpenDt": "20240430","prvncNm": "COPPERBELT PROVINCE","dstrtNm": null,"sctrNm": "Ndola","locDesc": "100, SMART INVOICE, STREET
1","hqYn": "Y","mgrNm": " SMART INVOICE USER ","mgrTelNo": "09000000000","mgrEmail": "smartuser@email.org.zm","sdcId": "SDC0010000553","mrcNo": "WIS00001092
","lastPchsInvcNo": 0,"lastSaleRcptNo": 3,"lastInvcNo": null,"lastSaleInvcNo": 2,"lastTrainInvcNo": null,"lastProfrmInvcNo": null, "lastCopyInvcNo": null } }}

5.2. Standard Codes (Constants)

The Standard Codes API facilitates access to predefined values utilized in API requests to represent specific attributes concisely. These constant
codes convey essential information such as units of measurement, packaging units, sale types, product types etc.

• Endpoint: /code/selectCodes
• Request method: POST.
• Requirement: MANDATORY
• Description: Retrieves a comprehensive list of standard codes along with their descriptions to be stored and used for all transaction requests
in taxpayer’s third-party system.
• Request Parameters: TPIN, Branch Id, Last Request Date.
• Response: Returns a list of standard codes along with detailed descriptions to be stored in third-party system.
• Note: Details returned in the response MUST be stored locally for future reference.

ERP VSDC API

Retrieves Constant Codes from
Get Standard Codes POST /code/selectCodes
Smart Invoice and stores it in ERP

10
Standard Codes Request
Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length

CodeReq Search code tpin Taxpayer’s identification number as registered on core Tax TPIN VARCHAR Y 10
Request Administration System TaxOnline
bhfId Taxpayer branch (store) location identifier Branch ID VARCHAR Y 3

lastReqDt This is the date depicting the last time an endpoint was called. By default, Last Request Date VARCHAR Y 14
this defaults to 20160523000000
JSON REQUEST SAMPLE

Request Body {"tpin": "9999999999","bhfId": "000","lastReqDt":"20231215000000"}

Standard Codes Response

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Data Length

CodeRes Search resultCd This is the VSDC response code Result Code VARCHAR 3
code
resultMsg This is the VSDC response message Result Message VARCHAR 200
Response
resultDt This is the VSDC response date-time Result Date VARCHAR 14

cdCls This is the standard code class Code Class VARCHAR 2

cdClsNm This is the standard code class name Code Class Name VARCHAR 60
cd This is the standard code Standard Code VARCHAR 5

cdNm This is the standard code name Standard Code Name VARCHAR 60

userDfnNm1 This is the standard code value User Define Name 1 VARCHAR 60
JSON RESPONSE SAMPLE

{"resultCd":"000","resultMsg":"It is succeeded","resultDt":"20240508142729","data":{"clsList":[{"cdCls":"04","cdClsNm":"Taxation Type","dtlList":[{"cd":"A","cdNm":"Standard

Rated"},{"cd":"B","cdNm":"MTV"},{"cd":"C1","cdNm":"Exports"},{"cd":"C2","cdNm":"Zero-rating LPO"},{"cd":"C3","cdNm":"Zero-rated by nature"},{"cd":"D","cdNm":"Exempt"},{"cd":"RVAT","cdNm":"Reverse
VAT"},{"cd":"E","cdNm":"Disbursement"},{"cd":"TOT","cdNm":"TOT"}]}]}}

11
 5.3. Classification Codes
Smart Invoice utilizes the United Nations Standard Products and Services Code (UNSPSC) as the standardized classification system for products
and services. The Classification Codes API allows third-party systems to integrate the UNSPSC, enabling accurate categorization of
products/items.
This API provides developers with access to the updates of the UNSPSC code list stored on Smart Invoice. A complete list of these codes will be
shared with the developer during the development phase. This is also accessible on the ZRA website under the Smart Invoice tab.

• Endpoint: /itemClass/selectItemsClass
• Request method: POST.
• Requirement: MANDATORY
• Description: Retrieves and stores updates to classification codes used for item management. Due to the substantial size of classification
codes, the API implements pagination. Developers can retrieve codes in batches of 1000, optimizing performance and minimizing data
transfer overhead.
• Request Parameters: TPIN, Branch Id, Last Request Date
• Response: Returns the requested classification codes in the JSON-encoded format, ready to be stored and utilized within the third-party
system.
• Note: Details returned in the response MUST be stored/updated locally.

ERP VSDC API

Retrieves Class Codes from Smart

Get Classification Codes POST /itemClass/selectItemsClass
Invoice and stores it in ERP

12
Item Class Codes Request
Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length
ItemClsReq Search tpin Taxpayer’s identification number as registered on core Tax TPIN VARCHAR Y 10
Classification Administration System TaxOnline
Request bhfId Taxpayer branch (store) location identifier Branch ID VARCHAR Y 3

lastReqDt This is the date depicting the last time an endpoint was called. By Last Request Date VARCHAR Y 14
default, this defaults to 20231215000000
JSON REQUEST SAMPLE

Request Body {"tpin": "9999999999","bhfId": "000","lastReqDt":"20231215000000"}

Item Class Codes Response

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Data Length Format

ItemClsRes Search resultCd This is the VSDC response code Result Code VARCHAR 3
Classification
resultMsg This is the VSDC response message Result Message VARCHAR 200
Response
resultDt This is the VSDC response date-time Result Date VARCHAR 14

itemClsCd This is the item classification code Item Class Code VARCHAR 10
(UNSPSC)
itemClsNm This is the item name Item Class Name VARCHAR 200
itemClsLvl This is the item class level Item Class Level NUMBER 10
taxTyCd This is the item tax type code Taxation Type Code VARCHAR 5 See ‘6.1 Tax
Type’
mjrTgYn Whether it is Major Target VARCHAR 1

useYn This is the active status of the item class Used / UnUsed VARCHAR 1
code
JSON RESPONSE SAMPLE

{"resultCd":"000","resultMsg":"It is succeeded","resultDt":"20240129000001","data":{"itemClsList":[{"itemClsCd":"15121513","itemClsNm":"Graphite
lubricants","itemClsLvl":4,"taxTyCd":null,"mjrTgYn":null,"useYn":"Y"},{"itemClsCd":"50122001","itemClsNm":"Wild caught alaska
pollock","itemClsLvl":4,"taxTyCd":null,"mjrTgYn":null,"useYn":"Y"}]}}

13
 5.4. Notices
The Notices API serves as a means for ZRA to communicate important announcements and upcoming events/updates to users of Smart Invoice.
This API specification enables the retrieval of all notices published by ZRA.

• Endpoint: /notices/selectNotices
• Request method: POST.
• Requirement: OPTIONAL
• Description: Retrieves details of all notices published by ZRA on Smart Invoice.
• Request Parameter: TPIN, Branch Id, Last Request Date
• Response: Returns a list of notices published by ZRA.
Notices Request
Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length

NoticeReq Search tpin Taxpayer’s identification number as registered on core Tax TPIN VARCHAR Y 10
Notice Administration System TaxOnline
Request bhfId Taxpayer branch (store) location identifier Branch ID VARCHAR Y 3

lastReqDt This is the date depicting the last time an endpoint was called. By Last Request Date VARCHAR Y 14
default, this defaults to 20231215000000
JSON REQUEST SAMPLE

Request Body {"tpin": "9999999999","bhfId": "000","lastReqDt":"20231215000000"}

Notices Response
Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Data Length

NoticeRes Search resultCd This is the VSDC response code Result Code VARCHAR 3
Notice
resultMsg This is the VSDC response message Result Message VARCHAR 200
Response
resultDt This is the VSDC response date Result Date time VARCHAR 14
noticeNo This is the Notice number Notice Number NUMBER 10
title This is the Notice title Title VARCHAR 1000
cont This is the content of the notice Contents VARCHAR 4000

14
 dtlUrl This is the Notice URL detail URL VARCHAR 200
regrNm This is the username of the uploader of the Notice Registration name VARCHAR 60
regDt This is the reg date of the Notice Registration date time VARCHAR 14
JSON RESPONSE SAMPLE
{"resultCd":"000","resultMsg":"It is succeeded","resultDt":"20240509170304","data”: {"noticeList":[{"noticeNo":1,"title":"Smart Invoice Full Roll-out","cont":"Roses are Red, Penalties are Red\r\nDo not forget to
issue a valid Tax Invoice!! Use Smart Invoice...","dtlUrl":"https://sandboxapi.zra.org.zm/SmartInvoiceExtApi//common/link/sip/receipt/indexSiNotice?noticeNo=1","regrNm":"ZRA","regDt":"20231215000000"}]
}}

5.5. Branch Information

The Branch API facilitates the seamless integration of branch information from third-party systems into Smart Invoice. This API allows businesses
to efficiently manage and retrieve data pertaining to branches and branch users within Smart Invoice that has been shared by the third-party system.

SAVE BRANCH USER

• Endpoint: /branches/saveBrancheUser
• Request method: POST.
• Requirement: OPTIONAL
• Description: Saves branch user accounts created in the third-party system to Smart Invoice.
• Request Parameters: Branch user data including name, contact information, address, etc.
• Response: Returns confirmation of successful creation of branch user on Smart Invoice.

15
Save Branch User Request
Object ID Object Name Attribute Attribute Description Attribute Name Data Type Required Data Length
ID
BhfUserSaveReq Save Branch User tpin Taxpayer’s identification number as registered on TPIN VARCHAR Y 10
Request core Tax Administration System TaxOnline
bhfId Taxpayer branch (store) location identifier Branch ID VARCHAR Y 3
userId This is the unique identifier assigned to the users User ID VARCHAR Y 20
of the system
userNm This is the username assigned to the user of the Username VARCHAR Y 60
system
adrs This is the user’s address Address VARCHAR N 200
useYn This is the user active status on the system Used / UnUsed VARCHAR Y 1
regrNm This is the username of the creator of branch user Registrant Name VARCHAR Y 60
regrId This is the user id of the creator of the branch user Registrant ID VARCHAR Y 20
modrNm This is the username of the modifier of the details Modifier Name VARCHAR Y 60
of the branch user
modrId This is the user id of the modifier of the details of Modifier ID VARCHAR Y 20
the branch user
JSON REQUEST SAMPLE
{"tpin":"9999999999","bhfId":"000","userId":"SMART USER","userNm":"SMART USER","adrs":"Smart Invoice Street
1234","useYn":"Y","regrNm":"Admin","regrId":"Admin","modrNm":"Admin","modrId":"Admin"}

Save Branch User Response

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Data Length
BhfUserSaveRes Save Branch User Response resultCd This is the VSDC response code Result Code VARCHAR 3
resultMsg This is the VSDC response message Result Message VARCHAR 200
resultDt This is the response date Result Date VARCHAR 14

JSON RESPONSE SAMPLE

{"resultCd":"000","resultMsg":"It is succeeded","resultDt":”20231120193115","data”: null}

16
GET BRANCHES

• Endpoint: /branches/selectBranches
• Request method: POST.
• Requirement: OPTIONAL
• Description: Retrieve details of all registered branches from Smart Invoice.
• Request Parameters: TPIN, Branch Id, Last Request Date.
• Response: Retrieves a comprehensive list of all branches registered in Smart Invoice, including detailed information such as the branch
name, physical address, manager's name, etc.
Get Branches Request
Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length

BhfReq Search tpin Taxpayer’s identification number as registered on core Tax TPIN VARCHAR Y 10
Branch Administration System TaxOnline
Request bhfId Taxpayer branch (store) location identifier Branch ID VARCHAR Y 3

lastReqDt This is the date depicting the last time an endpoint was called. By Last Request Date VARCHAR Y 14
default, this defaults to 20160523000000
JSON REQUEST SAMPLE

Request Body {"tpin": "999999999","bhfId": "000","lastReqDt":"20231215000000"}

Response
Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Data Length

BhfRes Search Branch resultCd This is the VSDC response code Result Code VARCHAR 3
Response resultMsg VARCHAR 200
This is the VSDC response Result Message
message
resultDt This is the VSDC response date Result Date VARCHAR 14
tpin This is the taxpayer identification TPIN VARCHAR 10
number
bhfId This is the branch (store) Branch Office ID VARCHAR 3

17
 identifier
bhfNm This is the branch name Branch Office Name VARCHAR 60
bhfSttsCd This is the branch status code Branch Status Code VARCHAR 5
prvncNm This is the branch province name Province Name VARCHAR 100
dstrtNm This is the branch district name District Name VARCHAR 100
sctrNm This is the branch sector Sector Name VARCHAR 100
locDesc This is the branch location Location Description VARCHAR 100
mgrNm This is the branch applicant name Manager Name VARCHAR 60
mgrTelNo This is the branch applicant Manager Contact VARCHAR 20
contact
mgrEmail This is the branch applicant email Manager Email VARCHAR 100
hqYn This is the branch location Head Office Yes/No VARCHAR 1

JSON RESPONSE SAMPLE

{"resultCd":"000","resultMsg":"It is succeeded","resultDt":"20240509173301","data":{"bhfList":[{"tin":"9999999999","bhfId":"000","bhfNm":"Headquarter","bhfSttsCd":"01","prvncNm":"LUSAKA
PROVINCE","dstrtNm":null,"sctrNm":"Lusaka","locDesc":null,"mgrNm":"SMART
USER","mgrTelNo":"07xxxxxxxx","mgrEmail":"smartuser@email.org.zm","hqYn":"Y"},{"tin":"9999999999","bhfId":"001","bhfNm":"Secondary Branch","bhfSttsCd":"01","prvncNm":"LUSAKA
PROVINCE","dstrtNm":null,"sctrNm":"Chilanga","locDesc":null,"mgrNm":"Smart User","mgrTelNo":"+26xxxxxxxxxx","mgrEmail":"smartuser@email.org.zm","hqYn":"N"}]}}

5.6. Customer Information

The Customer API acts as a connection point linking your third-party system with Smart Invoice, allowing smooth transfer and handling of
customer data. This API specification allows for the creation, retrieval, and editing of customer details in Smart Invoice based on data provided
by the third-party system.
GET CUSTOMERS

• Endpoint: /customers/selectCustomer
• Request method: POST.
• Requirement: OPTIONAL
• Description: Retrieves customer details based on the provided customer TPIN.
• Request Parameters: TPIN, Branch Id, Customer TPIN

18
 • Response: Returns customer details saved on Smart Invoice including name, contact information, address, etc.
Get Customer Request
Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length

CustReq Search tpin Taxpayer’s identification number as registered on core Tax TPIN VARCHAR Y 10
Customer Administration System TaxOnline
Request bhfId Taxpayer branch (store) location identifier Branch ID VARCHAR Y 3

custmTpin This is the TPIN of a previously saved customer Last Request Date VARCHAR Y 14

JSON REQUEST SAMPLE

Request Body {"tpin":"9999999999","bhfId": "000","custmTpin": "8888888888"}

Get Customer Response

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Data Length Format
CustRes Search resultCd This is the VSDC response code Result Code VARCHAR 3
Customer
resultMsg This is the VSDC response message Result Message VARCHAR 200
Response
resultDt This is the VSDC response date Result Date VARCHAR 14
tpin This is the taxpayer identification number Taxpayer TPIN VARCHAR 10
taxprNm This is the customer’s name Taxpayer Name VARCHAR 60
taxprSttsCd This is the customer’s taxpayer status code Taxpayer Status Code VARCHAR 5
prvncNm This refers to the province where the customer has their registration. Province Name VARCHAR 100

dstrtNm This refers to the district where the customer has their registration. District Name VARCHAR 100
sctrNm This refers to the sector where the customer has their registration. Sector Name VARCHAR 100
resultCd This it the customer’s registered location Telephone Number VARCHAR 3

JSON RESPONSE SAMPLE

{"resultCd":"000","resultMsg":"It is succeeded","resultDt":"20240509173806","data":{"custList":[{"tpin":"9999999999","bhfId":"000","custNo":"09xxxxxxxx
","custTpin":"8888888888","custNm":"TAXPAYER 1","adrs":null,"telNo":"09xxxxxxxx","email":null,"faxNo":null,"useYn":"Y","remark":"Walk-in
Customer","regrId":null,"regrNm":null,"modrId":null,"modrNm":null}]}}

19
SAVE BRANCH CUSTOMER
• Endpoint: /branches/saveBrancheCustomers
• Request method: POST.
• Requirement: OPTIONAL
• Description: Saves customer details captured in third-party system to Smart Invoice.
• Request Parameters: Customer data including name, contact information, address, etc.
• Response: Returns confirmation of successful creation of customer.
Save Branch Customer Request
Object ID Object Name Attribute ID Attribute Description Attribute Name Required Data Type Data Length

BhfCustSaveReq Save Branch Tpin Taxpayer’s identification number as TPIN Y 10

Customer Request registered on core Tax Administration VARCHAR
System TaxOnline
bhfId Taxpayer branch (store) location Branch ID Y 3
VARCHAR
identifier
custNo This is the customer’s mobile number Customer Number Y VARCHAR 9
custTpin This is the customer’s TPIN Customer TPIN Y VARCHAR 10
custNm This is customer’s name Customer Name Y VARCHAR 60
Adrs This is the customer’s address Address N VARCHAR 300
Email This is the email of the customer Email N VARCHAR 50
faxNo This is the fax of the customer Fax Number N VARCHAR 20
useYn This is the active status of the customer Used (Y/N) Y VARCHAR 1
remark This is a remark on the registered user Remark N VARCHAR 1000
regrNm This is the username of the system user Registrant Name Y 60
VARCHAR
adding the customer
regrId This is the user id of the system user Registrant ID Y 20
VARCHAR
adding the customer
modrNm This is the username of the system user Modifier Name Y 60
VARCHAR
modifying the customer
modrId This is the user id of the user modifying Modifier ID Y 20
VARCHAR
the customer details
JSON REQUEST SAMPLE
{"tpin":"9999999999","bhfId":"000","custNo":"097xxxxxxx","custTpin":"88888888","custNm":"ZRA","adrs":null,"email":null,"faxNo":null,"useYn":"Y","remark":null,"regrNm":"Admin","regrId":"Admin","modr
Nm":"Admin","modrId":"Admin"}

20
Save Branch Customer Response
Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Data Length

BhfCustSaveRes Save Branch Customer Response resultCd This is the VSDC response code Result Code VARCHAR 3
resultMsg This is the VSDC response message Result Message VARCHAR 200
resultDt This is the VSDC response date-time Result Date VARCHAR 14

JSON RESPONSE SAMPLE

{"resultCd":"000","resultMsg":"It is succeeded","resultDt":”20231120193115","data”: null}

5.7. Item Information

The Item API enables the seamless integration of product or service information from third-party systems into Smart Invoice. An item refers to
any product or service offered or sold by a business. Developers can utilize the Item API endpoints to transmit details about each item, such as
product names, descriptions, pricing information, units of measure, and classification codes. This integration ensures that Smart Invoice maintains
an up-to-date and synchronized record of all items a business has available for sale, aligning with the data in the third-party system.
SAVE ITEMS

• Endpoints: /items/saveItem
• Request method: POST.
• Requirement: MANDATORY
• Description: Saves product items created in third-party system to Smart Invoice.
• Request Parameter: Item data including name, description, price quantity, category, etc.
• Response: Returns success for saved item.
• Dependency: This endpoint requires valid standard and classification codes. To ensure successful use, retrieve and store/update these
codes before calling the endpoint with its attributes.
• Note: This endpoint allows you to register the products/services your offer with ZRA. It is used solely for the purpose of recording these
items. Stock-in and stock adjustments will be invoked by other process such as purchase, import or sales.

21
 ERP VSDC API

Retrieves Constant Codes from Smart

Get Standard Codes POST /code/selectCodes
Invoice and stores it in ERP

Retrieves Class Codes from Smart

Get Classification Codes POST /itemClass/selectItemsClass
Invoice and stores it in ERP

Item created in ERP is saved to Smart

Save Item POST /items/saveItem
Invoice

Save Item Request

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length Format

ItemSaveReq Save Item tpin Taxpayer’s identification number as registered on core Tax VARCHAR Y 10
TPIN
Request Administration System TaxOnline
bhfId Taxpayer branch (store) location identifier Branch ID VARCHAR Y 3
itemCd This the item classification code Item Code VARCHAR Y 100 See ‘6.16. Item
code’
itemClsCd This is the USNPSC item class code Item Classification VARCHAR Y 10
Code
itemTyCd This is the item product type VARCHAR Y 5 See ‘6.2.
item Type Code
Product
type’
itemNm This is the name of the item being registered by the item Name VARCHAR Y 200
taxpayer
itemStdNm Item Standard Name VARCHAR N 200

orgnNatCd This is the country of origin of the registered item Origin Place Code (Origin VARCHAR Y 5 See ‘6.3.
country code) Country
Codes’
pkgUnitCd This is the item packaging unit code VARCHAR Y 5 See ‘6.4.
Packaging Unit Code
Packaging
Unit’

22
 qtyUnitCd This is the item quantity code VARCHAR Y 5 See ‘6.5.
Quantity Unit Code
Units of
Measure’
vatCatCd This is the VAT category code of a registered item VAT category Code VARCHAR Y 5 See ‘6.1. Tax
Type’
iplCatCd This is the IPL category code of the registered item IPL category code VARCHAR Y 5 See ‘6.1. Tax
Type’
tlCatCd This is the TL category code of the registered item IPL category code VARCHAR Y 5 See ‘6.1. Tax
Type’
This is the Excise category code of the registered item Excise tax category code VARCHAR Y 5 See ‘6.1. Tax
Type’
btchNo This is the item batch number Batch Number VARCHAR N 10
bcd This is the item barcode Barcode VARCHAR N 20

dftPrc This is the default unit price Default Unit Price NUMBER Y 18,4

addInfo This is any additional information about the registered item Additional VARCHAR N 100
Information
sftyQty Refers to the additional inventory or stock that a business Safety Quantity NUMBER N 13,2
maintains as a buffer to guard against unexpected
fluctuations in demand
isrcAplcbYn This is insurance applicable flag Insurance Appicable(Y/N) VARCHAR Y 1
useYn This is the usage status of the registered item Used / UnUsed VARCHAR Y 1
regrNm This is the username of the user registering the item Registrant Name VARCHAR Y 60

regrId This is the user id of the user registering the item Registrant ID VARCHAR Y 20

JSON REQUEST SAMPLE

{"tpin":"9999999999","bhfId":"000","itemCd":"P200005","itemClsCd":"46181901","itemTyCd":"2","itemNm":"Corn Flakes","itemStdNm":"Corn
Flakes","orgnNatCd":"SA","pkgUnitCd":"BOX","qtyUnitCd":"U","vatCatCd":"A","iplCatCd":"IPL1","tlCatCd":null,"exciseTxCatCd":null,"btchNo":null,"bcd":null,"dftPrc":15,"addInfo":null,"sftyQty":5,"isrcAplcb
Yn":"N","useYn":"Y","regrNm":"ADMIN","regrId":"ADMIN","modrNm":"ADMIN","modrId":"ADMIN"}

23
Save Item Response
Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Data Length

ItemSaveRes Save Item Response resultCd This is the VSDC response code Result Code VARCHAR 3
resultMsg This is the response message Result Message VARCHAR 200
resultDt This is the response date Result Date VARCHAR 14

JSON RESPONSE SAMPLE

{"resultCd":"000","resultMsg":"It is succeeded","resultDt":”20231120193115","data”: null}

UPDATE ITEMS

• Endpoint: /items/updateItem
• Request method: POST.
• Requirement: MANDATORY
• Description: Updates specific product item details.
• Request Parameter: Item data including name, description, price, category, etc.
• Response: Returns success for updated item details.
• Dependency Note: This endpoint requires valid standard and classification codes. To ensure successful use, retrieve and update these
codes before calling the endpoint with its attributes.

ERP VSDC API

Retrieves Constant Codes from Smart

Get Standard Codes POST /code/selectCodes
Invoice and stores it in ERP

Retrieves Class Codes from Smart

Get Classification Codes POST /itemClass/selectItemsClass
Invoice and stores it in ERP

Item details updated in ERP are

Update Item POST /items/updateItem synchronized and saved to Smart
Invoice

24
Update Item Request
Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length Format

ItemSaveReq Save Item tpin Taxpayer’s identification number as registered on core Tax VARCHAR Y 10
TPIN
Request Administration System TaxOnline
bhfId Taxpayer branch (store) location identifier Branch ID VARCHAR Y 3
itemCd This the item classification code Item Code VARCHAR Y 100 See ‘6.16. Item
code’
itemClsCd This is the USNPSC item class code Item Classification VARCHAR Y 10
Code
itemTyCd This is the item product type VARCHAR Y 5 See ‘6.2.
item Type Code
Product
type’
itemNm This is the name of the item being registered by the item Name VARCHAR Y 200
taxpayer
itemStdNm This refers to the standardized or commonly accepted name Item Standard Name VARCHAR N 200
used to identify a specific item or product within a system
orgnNatCd This is the country of origin of the registered item Origin Place Code (Origin VARCHAR Y 5 See ‘6.3.
country code) Country
Codes’
pkgUnitCd This is the item packaging unit code VARCHAR Y 5 See ‘6.4.
Packaging Unit Code
Packaging
Unit’
qtyUnitCd This is the item quantity code VARCHAR Y 5 See ‘6.5.
Quantity Unit Code
Units of
Measure’
vatCatCd This is the VAT category code of a registered item VAT category Code VARCHAR Y 5 See ‘6.1. Tax
Type’
iplCatCd This is the IPL category code of the registered item IPL category code VARCHAR Y 5 See ‘6.1. Tax
Type’
tlCatCd This is the TL category code of the registered item IPL category code VARCHAR Y 5 See ‘6.1. Tax
Type’
exciseTxCatCd This is the Excise category code of the registered item Excise tax category code VARCHAR Y 5 See ‘6.1. Tax
Type’
btchNo This is the item batch number Batch Number VARCHAR N 10
bcd This is the item barcode Barcode VARCHAR N 20
dftPrc This is the default unit price Default Unit Price NUMBER Y 18,4

25
 addInfo This is any additional information about the registered item Additional VARCHAR N 100
Information
sftyQty Refers to the additional inventory or stock that a business Safety Quantity NUMBER N 13,2
maintains as a buffer to guard against unexpected
fluctuations in demand
isrcAplcbYn Insurance Appicable(Y/N) VARCHAR Y 1
useYn This is the usage status of the registered item Used / UnUsed VARCHAR Y 1
regrNm This is the username of the user registering the item Registrant Name VARCHAR Y 60

regrId This is the user id of the user registering the item Registrant ID VARCHAR Y 20

JSON REQUEST SAMPLE

{"tpin":"9999999999","bhfId":"000","itemCd":"P200005","itemClsCd":"46181901","itemTyCd":"2","itemNm":"Corn Flakes","itemStdNm":"Corn
Flakes","orgnNatCd":"SA","pkgUnitCd":"BOX","qtyUnitCd":"U","vatCatCd":"A","iplCatCd":"IPL1","tlCatCd":null,"exciseTxCatCd":null,"btchNo":null,"bcd":null,"dftPrc":15,"addInfo":null,"sftyQty":5,"isrcAplcb
Yn":"N","useYn":"Y","regrNm":"ADMIN","regrId":"ADMIN","modrNm":"ADMIN","modrId":"ADMIN"}

Update Item Response

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Data Length

ItemUpdateRes Update Item Response resultCd This is the VSDC response code Result Code VARCHAR 3
resultMsg This is the response message Result Message VARCHAR 200
resultDt This is the response date Result Date VARCHAR 14

JSON RESPONSE SAMPLE

{"resultCd":"000","resultMsg":"It is succeeded","resultDt":”20231120193115","data”: null}

GET ITEMS

• Endpoint: /items/selectItems
• Request method: POST.
• Requirement: OPTIONAL
• Description: Retrieves a list of all product items saved in Smart Invoice.
• Request Parameters: TPIN, Branch id, Last Request Date

26
 • Response: Returns a list of items with their details including name, description, price, quantity, category, etc.

Select Items Request

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length

ItemReq Search Item tpin Taxpayer’s identification number as registered on core Tax TPIN VARCHAR Y 10
Request Administration System TaxOnline
bhfId Taxpayer branch (store) location identifier Branch ID VARCHAR Y 3

lastReqDt This is the date depicting the last time an endpoint was called. By Last Request Date VARCHAR Y 14
default, this defaults to 20160523000000
JSON REQUEST SAMPLE

Request Body {"tpin": "9999999999","bhfId": "000","lastReqDt":"20231215000000"}

Select Items Response

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Data Length Format

ItemRes Search Item Response resultCd This is the VSDC response code Result Code VARCHAR 3

resultMsg This is the VSDC response message Result Message VARCHAR

resultDt This is the VSDC response date-time Result Date VARCHAR 14

Tpin This is the taxpayer’s identification number as TPIN VARCHAR 10
registered on the core tax administration system
TaxOnline
itemCd This is the item identifier on the taxpayer’s Item Code VARCHAR 100 See ‘6.16. Item
system code’
itemClsCd This is the item identifier from the UNSPSC Item Classification Code VARCHAR 10
codes which maps to the registered item
itemTyCd This is the classifier used to categorize different item Type Code VARCHAR 5 See ‘6.2.
types of items Product type’
itemNm This is the name of the registered item item Name VARCHAR 200

itemStdNm This refers to the standardized or official Item Standard Name VARCHAR 200
name given to an item within a particular
system
orgnNatCd This refers to the country of origin of the Origin Place Code (Origin country code) VARCHAR 5
registered item/product See ‘6.3.

27
 Country
Codes’
pkgUnitCd This refers to a unique identifier or code Packaging Unit Code VARCHAR 5 See ‘6.4.
assigned to a specific packaging unit within Packaging
a system Unit’
qtyUnitCd This refers to an identifier used to Quantity Unit Code VARCHAR 5 See ‘6.5. Units
represent a specific unit of measurement of Measure’
for quantity
vatCatCd This is the VAT category code VAT category Code VARCHAR 5 See ‘6.1. Tax
Type’
iplCatCd This is the IPL category code IPL category code VARCHAR 5 See ‘6.1. Tax
Type’
tlCatCd This is the TL category code Tourism Levy category code VARCHAR 5 See ‘6.1. Tax
Type’
exciseTxCatCd This is the excise category code Excise tax category code VARCHAR 5 See ‘6.1. Tax
Type’
btchNo Refers to a unique identifier assigned to a group Batch Number VARCHAR 10
of items or products
bcd Refers to a visual representation of data Barcode VARCHAR N 20
that is readable by machines, typically
used for automatic identification and
tracking of products
dftPrc Refers to the standard or base price assigned to a Default Unit Price NUMBER Y 18,4
single unit of a product or item
addInfo Refers to any additional information about the Additional Information VARCHAR N 100
registered product or item
sftyQty Refers to the additional inventory or stock that a Safety Quantity NUMBER N 13,2
business maintains as a buffer to guard against
unexpected fluctuations in demand
regBhfId This is the branch ID where the item was Registered Branch ID VARCHAR 3
registered
isrcAplcbYn Insurance Appicable Y/N VARCHAR 1

ZRAModYn This is an identifier regarding modification of ZRA Modify Y/N (Item VARCHAR 1
the item classification code by ZRA Classification Code)
useYn This is the item utilization status Used / UnUsed VARCHAR 1

JSON RESPONSE SAMPLE

{"resultCd":"000","resultMsg":"It is
succeeded","resultDt":”20231120193501","data":{"itemList":[{"tpin":"9999999999","itemCd":"KR2AMXBLL0000001","itemClsCd":"1110160600","itemTyCd":"2","itemNm":"restitem#1","itemStdNm":null,"orgn

28
 NatCd":"KR","pkgUnitCd":"AM","qtyUnitCd":"BLL","vatCatCd":"A","vatCatCd":"A","iplCatCd":null,"tlCatCd":null,"exciseTxCatCd":null, null,
"btchNo":null,"regBhfId":"000","bcd":"8801234567061","dftPrc":21000,"addInfo":null,"sftyQty":0,"isrcAplcbYn":"N","ZRAModYn":"N","useYn":"Y"},{"tpin":"1234567890","itemCd":"KR2AMXBLL0000001","i
temClsCd":"1110160600","itemTyCd":"2","itemNm":"restitem#1","itemStdNm":null,"orgnNatCd":"KR","pkgUnitCd":"AM","qtyUnitCd":"BLL","vatCatCd":"A","vatCatCd": "A","iplCatCd": null,"tlCatCd":
null,"exciseTxCatCd": null, "btchNo":null,"regBhfId":"000","bcd":"8801234567061","dftPrc":21000,"addInfo":null,"sftyQty":0,"isrcAplcbYn":"N","ZRAModYn":"N","useYn":"Y"}]}}

GET ITEM

• Endpoint: /items/selectItem
• Request method: POST.
• Requirement: OPTIONAL
• Description: Retrieves details of a product item based on the provided item code.
• Request Parameters: TPIN, Branch Id, Item Code.
• Response: Returns details of product item including name, item code, package unit, etc.

Select Item Request

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length

ItemClsReq Search tpin Taxpayer’s identification number as registered on core Tax TPIN VARCHAR Y 10
Classification Administration System TaxOnline
Request bhfId Taxpayer branch (store) location identifier Branch ID VARCHAR Y 3

itemCd This is the product item code defined for a registered item Item Code VARCHAR Y 100

JSON REQUEST SAMPLE

Request Body {“tpin”: “9999999999”, “bhfId”: “000”, “itemCd”: “AT2BX0000013”}

Select Item Response

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length Format

GetItemReq Get item Tpin This is the taxpayer’s identification number as registered on VARCHAR Y 10
TPIN
details the core tax administration system TaxOnline
itemCd This is the item identifier on the taxpayer’s system Item Code VARCHAR Y 100
itemClsCd This is the item identifier from the UNSPSC codes Item Classification VARCHAR Y 10

29
 Code

itemTyCd This is the classifier used to categorize different types of VARCHAR Y 5 See ‘6.2.
item Type Code
items Product type’
itemNm This is the name of the registered item item Name VARCHAR Y 200
itemStdNm This refers to the standardized or official name given to an Item Standard Name VARCHAR N 200
item within a particular system
orgnNatCd This refers to the country of origin of the registered Origin Place Code (Origin VARCHAR Y 5 See ‘6.3.
item/product country code) Country
Codes’
pkgUnitCd This refers to a unique identifier or code assigned to a VARCHAR Y 5 See ‘6.4.
Packaging Unit Code
specific packaging unit within a system Packaging
Unit’
qtyUnitCd This refers to an identifier used to represent a specific unit VARCHAR Y 5 See ‘6.5.
Quantity Unit Code
of measurement for quantity Units of
Measure’
vatCatCd This is the VAT category code of the registered item VAT category Code VARCHAR Y 5 See ‘6.1. Tax
Type’
iplCatCd This is the IPL category code of the registered item IPL category code VARCHAR Y 5 See ‘6.1. Tax
Type’
tlCatCd This is the TL category code Tourism Levy category code VARCHAR Y 5 See ‘6.1. Tax
Type’
exciseTxCatCd This is the excise category code Excise tax category code VARCHAR Y 5 See ‘6.1. Tax
Type’
btchNo Refers to a unique identifier assigned to a group of items or Batch Number VARCHAR N 10
products
bcd Refers to a visual representation of data that is readable by Barcode VARCHAR N 20
machines, typically used for automatic identification and
tracking of products
dftPrc Refers to the standard or base price assigned to a single unit Default Unit Price NUMBER Y 18,4
of a product or item
addInfo Refers to any additional information about the registered Additional VARCHAR N 100
product or item Information
sftyQty Refers to the additional inventory or stock that a business Safety Quantity NUMBER N 13,2
maintains as a buffer to guard against unexpected
fluctuations in demand
regBhfId Registered Branch ID VARCHAR 3

JSON RESPONSE SAMPLE

30
{"resultCd": "000", "resultMsg": "It is succeeded", "resultDt": "20240327154703", "data": {"itemList": [{"tpin": "9999999999", "itemCd": "AT2BX0000013", "itemClsCd": "43191501", "itemTyCd": "2", "itemNm":
"Techno S30", "itemStdNm": "Techno S30", "orgnNatCd": "AT", "pkgUnitCd": "BG", "qtyUnitCd": "KG", "vatCatCd": "A", "iplCatCd": null, "tlCatCd": null, "exciseTxCatCd": null, "btchNo": null, "regBhfId":
"000", "bcd": null, "dftPrc": 5000, "addInfo": null, "sftyQty": 9}]}}"

SAVE ITEM COMPOSITION

• Endpoint: /items/saveItemComposition
• Request method: POST.
• Requirement: OPTIONAL
• Description: This endpoint is designed to manage the storage of items involved in processing or repackaging activities. It is particularly
useful for situations where multiple products are combined or transformed into a unique finished product.
• Request Parameters: Item data including item code, quantity, etc.
• Response: Returns success or failure of the save item composition operation.

Save Item Composition Request

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length Format

SaveItemComReq Save Item tpin This is the taxpayer’s identification number registered TPIN VARCHAR Y 10
Composition with ZRA
bhfId This is the branch (store) identifier. Supplied by ZRA Branch ID VARCHAR Y 3
itemCd This refers to an identifier used to categorize different Item Code VARCHAR Y 100
types of items or products within a system
cpstItemCd This refers to an identifier used to categorize the final Composition Item VARCHAR Y 20
product Code
cpstQty This refers to the quantity or amount of a specific Composition Quantity NUMBER Y 13,2
ingredient
regrId This refers to the ID of the user of the system adding the Registrant ID VARCHAR Y 60
item
regrNm This refers to the username of the user adding the item Registrant Name VARCHAR Y 20
JSON REQUEST SAMPLE

31
 {"tpin": "9999999999", "bhfId": "000", "itemCd": "ZM2NTBA0000051", "cpstItemCd": "ZM2NTBA0000051", "cpstQty": 3, "regrId": "ADMIN", "regrNm": "ADMIN"}

Save Item Composition Response

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Data Length

ISaveItemCompRes Save Item Composition Response resultCd This is the VSDC response code Result Code VARCHAR 3
resultMsg This is the VSDC response message Result Message VARCHAR 200
resultDt This is the VSDC response date Result Date VARCHAR 14

JSON RESPONSE SAMPLE

{"resultCd":"000","resultMsg":"It is succeeded","resultDt":”20231120193115","data”: null}

5.8. Import Information

The Imports API facilitates the exchange of all data associated with items imported by a business, as declared in the Automated System for Customs
Data (ASYCUDA). This integration ensures seamless transfer of import details, enabling businesses to efficiently manage and synchronize
imported item data in their third-party systems.
Through the Imports API, businesses can automatically fetch and integrate import details from ASYCUDA directly into their third-party system.
This includes information such as product descriptions, quantities, values, etc.
GET IMPORTS
• Endpoint: /imports/selectImportItems
• Request method: POST.
• Requirement: MANDATORY
• Description: Retrieves a list of imported items saved on Smart Invoice from ASYCUDA.
• Request Parameters: TPIN, Branch Id, Last Request Date.
• Response: Retrieves a list of imported items including detailed information such as product descriptions, quantities, values, etc.

32
 ERP VSDC API

Retrieves import data from Smart Invoice

Get Imports POST /imports/selectImportItems
and stores it in ERP

Get Imports Request

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length

ImptItemReq Search tpin Taxpayer’s identification number as registered on core Tax TPIN VARCHAR Y 10
Import Item Administration System TaxOnline
Request bhfId Taxpayer branch (store) location identifier Branch ID VARCHAR Y 3

lastReqDt This is the date depicting the last time an endpoint was called. By Last Request Date VARCHAR Y 14
default, this defaults to 20160523000000
JSON REQUEST SAMPLE

Request Body {"tpin": "9999999999","bhfId": "000","lastReqDt":"20231215000000"}

Get Imports Response

Object ID Object Name Attribute Attribute Description Attribute Name Data Type Data Length Format
ID
ImptItemRes Search resultCd This is the VSDC response code Result Code VARCHAR 3
Import Item Response
Response resultMsg This is the response message VARCHAR 200
Result Message
resultDt This is the response date VARCHAR 14
Result Date
taskCd Refers to a code for the specific declaration related to customs VARCHAR 50
Task Code
clearance
dclDe Refers to the date when the customs declaration for the goods was VARCHAR 8
Declaration Date
submitted
itemSeq This is the order of items in a particular declaration NUMBER 10
Item Sequence
dclNo This refers to the reference number assigned to a specific declaration VARCHAR 50
Declaration Number
on the Customs System
hsCd Refers to an internationally standardized system of names and VARCHAR 17
HS Code
numbers used to classify traded products for customs and tariff
purposes

33
 itemNm This is the product name of the imported item VARCHAR 500
Item Name
orgnNatCd Refers to the Country of origin of the imported item VARCHAR 5 See ‘6.3. Country
Origin Nation Code
Codes’
exptNatCd This refers to a code or identifier used to represent a specific country VARCHAR 5
Export Nation Code
or nation in the context of international trade
Pkg This refers to a container, box, or bundle in which items, products, or NUMBER 13,2
Package
goods are enclosed for storage
pkgUnitCd Refers to a unique identifier or code assigned to a specific packaging VARCHAR 5 See ‘6.4.
Packaging Unit Code
unit Packaging Unit’
Qty Refers to the quantity of the imported item NUMBER 13,2
Quantity
qtyUnitCd Refers to the quantity unit code of the imported item VARCHAR 5 See ‘6.5. Units of
Quantity Unit Code
Measure’
totWt Refers to the gross weight of the imported item NUMBER 13,2
Gross Weight
netWt Refers to the net weight of the imported item NUMBER 13,2
Net Weight
spplrNm Refers to the supplier’s name of the imported item VARCHAR 500
Supplier's name
agntNm Refers to the agent’s name of the importation VARCHAR 500
Agent name
invcFcurAmt Refers to the foreign currency amount for the imported item NUMBER 18,4
Invoice Foreign Currency
Amount
invcFcurCd Refers to the foreign currency used to import the item VARCHAR 5 See ‘6.6.
Invoice Foreign Currency
Currency’
invcFcurExcrt Refers to the exchange rate used when importing the item NUMBER 18,4
Invoice Foreign Currency
Exchange Rate
JSON RESPONSE SAMPLE

{"resultCd":"000","resultMsg":"It is succeeded","resultDt":”20231120194118","data":{"itemList":[{"taskCd":"2239078","dclDe":"-1","itemSeq":1,"dclNo":"C3460-2019-
TZDL","hsCd":"20055900000","itemNm":"BAKED
BEANS","imptItemsttsCd":"2","orgnNatCd":"BR","exptNatCd":"BR","pkg":2922,"pkgUnitCd":null,"qty":19946,"qtyUnitCd":"KGM","totWt":19945.57,"netWt":19945.57,"spplrNm":"ODERICH CONSERVA
QUALIDADE\nBRASIL","agntNm":"BN METRO Ltd","invcFcurAmt":296865.6,"invcFcurCd":"USD","invcFcurExcrt":929.79}]}}

UPDATE IMPORT ITEMS

• Endpoint: /imports/updateImportItems
• Request method: POST.

34
 • Requirement: MANDATORY
• Description: This endpoint is used to acknowledge, or disregard imported items received from Smart Invoice which were declared on
ASYCUDA. Acknowledged imported items will have to be saved in stock whereas disregarded imported items will not.
• Request Parameters: Import data including declaration date, item sequence, item classification code, import item status code, etc. (See
table for full parameter list)
• Response: Returns the successful confirmation of the updated status of an import item.
• Dependency: After your import is approved, call the “Save Stock Items” endpoint to add the approved imports as stock items.
Subsequently, call the “Stock Master” endpoint to update the existing stock quantities for any items that were already present in your
inventory reflecting the additional approved imports. This process ensures that approved imports are accurately reflected in the overall
stock inventory.
ERP VSDC API

Update Import POST /imports/updateImportItems Import Item status updated

Update Smart Invoice with the

Save Stock Item POST /stock/saveStockItems
approved Import Item

Updates stock item quantities within

Save Stock Master POST /stockMaster/saveStockMaster
Smart Invoice

Update Import Items Request

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length Format

ImptItemSaveRes Update Item Response tpin This is the VSDC response code TPIN VARCHAR Y 10
bhfId This is the response message Branch ID VARCHAR Y 3
taskCd Refers to a code for the specific Task Code VARCHAR Y 50
declaration related to customs
clearance

35
 dclDe Refers to the date when the customs Declaration Date VARCHAR Y 8
declaration for the goods was
submitted
itemSeq This is the order of items in a Item Sequence NUMBER Y 10
particular declaration
hsCd Refers to an internationally HS Code VARCHAR Y 17
standardized system of names and
numbers used to classify traded
products for customs and tariff
purposes
itemClCd This is the UNSPSC classification Item Classification Code VARCHAR Y 10
code used to classify the imported
item. Retrieved from the UNSPSC
codes previously saved on the third-
party system
itemCd This is the identification code of the Item Code VARCHAR Y 100
item used to classify products or
services in the third-party system
imptItemsttsCd This is the status code of the item to Import Item Status Code VARCHAR Y 5 See ‘6.17. Import
be approved or rejected by the Item status’
taxpayer
remark This is a general remark about the Remark VARCHAR N 400
approval or rejection of the item by
the taxpayer
modrNm This is the username of the system Modifier Name VARCHAR Y 60
user approving or rejecting the
imported item.
modrId This is the user ID of the system user Modifier ID VARCHAR Y 20
approving or rejecting the imported
item.
JSON REQUEST SAMPLE

{"tpin": "9999999999","bhfId": "000","taskCd": "4561614","dclDe": "20240426","importItemList": [{"itemSeq": 2,"hsCd": "72149900000","itemClsCd": "5022110801","itemCd": "RW1NTXU0000006",
"imptItemSttsCd": "3","remark": "remark","modrNm": "Admin","modrId": "Admin"}, {"itemSeq": 3,"hsCd": "04051000000","itemClsCd": "5022110802","itemCd": "RW1NTXU0000007","imptItemSttsCd": "4",
"remark": "another remark","modrNm": "Admin2","modrId": "Admin2"}]}

Update Import Items Response

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Data Length

ImptItemSaveRes Update Item Response resultCd This is the VSDC response code Result Code VARCHAR 3
resultMsg This is the VSDC response message Result Message VARCHAR 200
resultDt This is the response date Result Date VARCHAR 14

36
 JSON RESPONSE SAMPLE

{"resultCd":"000","resultMsg":"It is succeeded","resultDt":”20231120193115","data”: null}

5.9. Sales Information

The Sales API facilitates the transmission of detailed sales data from a third-party system to Smart Invoice. This data includes specific details
associated with each sale, such as customer information, sale type, invoice number, and the date/time of the transaction. Developers can use this
API to seamlessly transfer sales information, ensuring accurate invoicing and efficient management of customer transactions.
SAVE SALES

• Endpoint: /trnsSales/saveSales
• Request method: POST.
• Requirement: MANDATORY
• Description: This endpoint facilitates the submission of sales data from the third-party system into Smart Invoice.
• Request Parameters: Sales data including customer details, sale type, invoice number, and transaction timestamp.
• Response: Returns the success or failure of sales data submission.
• Dependency: After completing a sale, it's important to update the inventory to reflect the correct levels of the items sold. This involves
using the 'Save Stock Items' endpoint to show stock movements. Following this, the 'Stock Master' endpoint should be called to update the
stock quantities based on the sales recorded. This process ensures that inventory adjustments due to sales are accurately reflected in the
overall stock inventory, for further reporting to Smart Invoice.
• Note: All sales receipts must be printed with the ‘rcptNo’ which is returned in success response when sale is posted to VSDC. This is the
ZRA invoice number which must be referred to when taxpayer intends to issue a credit note or debit note.

37
 ERP VSDC API
Update Smart Invoice with the sales
Save Sales POST /trnsSales/saveSales
recorded by the ERP

Save Stock Items Update Smart Invoice with the item data
POST /stock/saveStockItems
for each sale

Updates stock quantities related to sales

Save Stock Master POST /stockMaster/saveStockMaster
within Smart Invoice

Save Sales Request – Normal Sale

Object ID Object Attribute ID Attribute Description Attribute Name Data Type Required Data Format
Name Length

TrnsSalesSaveWrReq Save Sales Request tpin Taxpayer’s identification TPIN VARCHAR Y 10

number as registered on core
Tax Administration System
TaxOnline
bhfId Taxpayer branch (store) Branch Id VARCHAR Y 3
location identifier
orgIncNo The invoice number being Original Invoice NUMBER N 38
referred to if you are issuing Number
a credit note or debit note
cisInvcNo Invoice number as generated CIS Invoice number VARCHAR Y 50
on Taxpayers Certified
invoicing solutions
custTpin Customers taxpayer’s Customer TPIN VARCHAR N 10
identification number as
registered on core Tax
Administration System
TaxOnline
custNm Customers name Customer Name VARCHAR N 60

salesTyCd Code associated with type of Sales Type Code VARCHAR Y 5 See ‘6.7.
sale (Pass N) Transaction Type’

38
rcptTyCd Type of receipt Receipt Type Code VARCHAR Y 5 See ‘6.8. Sale
Receipt Type’
pmtTyCd The mode of payment used Payment Type Code VARCHAR Y 5 See ‘6.9. Payment
for this transaction Method’
salesSttsCd Progress of transaction e.g. Invoice/Sale Status VARCHAR Y 5 See ‘6.10.
Approved, Refunded etc. Code Transaction
Progress’
cfmDt Date time when invoice was Confirmation Date VARCHAR Y 14 yyyyMMddhhmmss
issued
salesDt Date when sale was made Sales Date VARCHAR Y 8 yyyyMMdd

stockRlsDt Date when the item was Stock Released Date VARCHAR N 14 yyyyMMddhhmmss
released from the
warehouse/branch
cnclReqDt Date time when a Cancell Requested VARCHAR Y 14 yyyyMMddhhmmss
cancellation request was Date
made. This is used when one
needs to cancel an invoice
cnclDt Date when cancellation was Cancel Date VARCHAR Y 14 yyyyMMddhhmmss
approved
rfdDt Date when refund was made Refunded Date VARCHAR Y 14 yyyyMMddhhmmss
(null when not a refund)
rfdRsnCd Reason for issuing a refund Refunded Reason VARCHAR Y 5 See ‘6.15. Refund Reason
(empty string when not a Code Code’
refund)
totItemCnt Total number of items on the Total Item Count NUMBER Y 10
invoice
taxblAmtA Total tax exclusive amount Taxable Amount A NUMBER Y 18,4
for all line items classified as
Standard Rated for VAT
purposes (Pass 0.0 if not
applicable)
taxblAmtB Total tax exclusive Taxable Amount B NUMBER Y 18,4
amount for all line items
classified as MTV -
Minimum Taxable Value for
VAT purposes (pass 0.0 if
not applicable)
taxblAmtC1 Total tax exclusive amount Taxable Amount C1 NUMBER Y 18.4
for all line items classified as
C1 - Exports for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtC2 Total tax exclusive amount Taxable Amount C2 NUMBER Y 18.4
for all line items classified as
C2 – Zero rating LPO for

39
 VAT purposes (pass 0.0 if
not applicable)
taxblAmtC3 Total tax exclusive amount Taxable Amount C3 NUMBER Y 18.4
for all line items classified as
C3 Zero rated by nature for
VAT purposes (pass 0.0 if
not applicable)
taxblAmtD Total tax exclusive amount Taxable Amount D NUMBER Y 18,4
for all line items classified as
D Exempt for VAT purposes
(pass 0.0 if not applicable)
taxblAmtRvat Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items classified as RVAT
RVAT for VAT purposes
(pass 0.0 if not applicable)
taxblAmtE Total tax exclusive amount Taxable Amount E NUMBER Y 18,4
for all line items classified as
E - Disbursements for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtF Total tax exclusive amount Taxable Amount F NUMBER Y 18,4
for all line items classified as
F for VAT purposes (pass
0.0 if not applicable)
taxblAmtIpl1 Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting IPL
Insurance Premium Levy
(pass 0.0 if not applicable)
taxblAmtIpl2 Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting IPL2
Insurance Premium Levy 2
(pass 0.0 if not applicable)
taxblAmtTl Total tax exclusive amount Taxable Amount TL NUMBER Y 18,4
for all line items attracting
Tourism Levy (pass 0.0 if
not applicable)
taxblAmtEcm Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting ECM
Excise Coal (pass 0.0 if not
applicable)
taxblAmtExeeg Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting EXEEG
Excise Electricity (pass 0.0
if not applicable)
taxblAmtTot Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting TOT

40
 TOT (pass 0.0 if not
applicable)
taxRtA Tax rate VAT Standard rated Tax Rate A NUMBER Y 7,2
category A– As per standard
codes
taxRtB Tax rate for Minimum Tax Rate B NUMBER Y 7,2
Taxable Value – As per
standard codes
taxRtC1 Tax rate for C1- Exports – Tax Rate C1 NUMBER Y 7,2
As per standard codes
taxRtC2 Tax rate for C2 Zero rating Tax Rate C2 NUMBER Y 7,2
LPO – As per standard
codes
taxRtC3 Tax rate for C3 Zero rated Tax Rate C3 NUMBER Y 7,2
by nature – As per standard
codes
taxRtD Tax rate for D Exempt – As Tax Rate D NUMBER Y 7,2
per standard codes
taxRtRvat Tax rate for RVAT reverse Tax Rate RVAT NUMBER Y 7,2
VAT – As per standard
codes
taxRtE Tax rate E Disbursements – Tax Rate E NUMBER Y 7,2
As per standard codes
taxRtF Rate for F Service charge – Tax Rate F NUMBER Y 7,2
As per standard codes
taxRtIpl1 Tax rate for Insurance Tax Rate IPL NUMBER Y 7,2
premium levy – As per
standard codes
taxRtIpl2 Tax rate for Insurance Tax Rate IPL2 NUMBER Y 7,2
Premium Levy – As per
standard codes
taxRtTl Tax rate for Tourism Levy – Tax Rate TL NUMBER Y 7,2
As per standard codes
taxRtEcm Tax rate for Excise Coal Tax Rate ECM NUMBER Y 7,2
Mining – As per standard
codes
taxRtExeeg Tax rate Electricity and Tax Rate EXEEG NUMBER Y 7,2
Energy generation – As per
standard codes
taxRtTot Tax rate VAT – As per Tax Rate TOT NUMBER Y 7,2
standard codes
taxAmtA This is the total tax charged Tax Amount A NUMBER Y 18,4
on all VAT category A line
items on invoice (Pass 0.0
when not applicable)
taxAmtB This is the total tax charged Tax Amount B NUMBER Y 18,4
on all VAT category A line

41
 items on invoice (Pass 0.0
when not applicable)
taxAmtC1 This is the total tax charged Tax Amount C1 NUMBER Y 18,4
on all VAT category C1 line
items on invoice (Pass 0.0
when not applicable)
taxAmtC2 This is the total tax charged Tax Amount C2 NUMBER Y 18,4
on all VAT category C2 line
items on invoice (Pass 0.0
when not applicable)
taxAmtC3 This is the total tax charged Tax Amount C3 NUMBER Y 18,4
on all VAT category C3 line
items on invoice (Pass 0.0
when not applicable)
taxAmtD This is the total tax charged Tax Amount D NUMBER Y 18,4
on all VAT category D line
items on invoice (Pass 0.0
when not applicable)
taxAmtRvat This is the total tax charged Tax Amount RVAT NUMBER Y 18,4
on all VAT category RVAT
line items on invoice (Pass
0.0 when not applicable)
taxAmtE This is the total tax charged Tax Amount E NUMBER Y 18,4
on all VAT category E line
items on invoice (Pass 0.0
when not applicable)
taxAmtF This is the total tax charged Tax Amount F NUMBER Y 18,4
on all VAT category F
(Service Charge) line items
on invoice (Pass 0.0 when
not applicable)
taxAmtIpl1 This is the total Insurance Tax Amount IPL1 NUMBER Y 18,4
Premium Levy IPL on
invoice (Pass 0.0 when not
applicable)
taxAmtIpl2 This is the total Insurance Tax Amount IPL2 NUMBER Y 18,4
Premium Levy IPL2 (Re-
Insurance) on invoice (Pass
0.0 when not applicable)
taxAmtTl This is the total tax Tourism Tax Amount TL NUMBER Y 18,4
Levy charged on invoice
(Pass 0.0 when not
applicable)
taxAmtEcm This is the total tax charged Tax Amount ECM NUMBER Y 18,4
on all Excise Coal Mining
line items on invoice (Pass
0.0 when not applicable)

42
taxAmtExeeg This is the total tax charged Tax Amount NUMBER Y 18,4
on all Excise Electricity and EXEEG
Energy generating line items
on invoice (Pass 0.0 when
not applicable)
taxAmtTot [Pass 0.0 not applicable on Tax Amount TOT NUMBER Y 18,4
invoice]
totTaxblAmt This is the total Tax Total TaxlAmt NUMBER Y 18,2
Exclusive Amount for all
line items on invoice
totTaxAmt This is the total tax charged Tot Tax Amount NUMBER Y 18,2
on all line items on invoice
totAmt This is the total Tax Total Amount NUMBER Y 18,2
Inclusive Amount of all line
items on the invoice
prchrAcptcYn This specifies whether a Purchase Accepted VARCHAR Y 1
purchase has been accepted Yes or No
or not. (Pass Y)
remark This is any comment/remark Remark VARCHAR N 400
on the transaction
regrId This refers to the ID of the Registrant Id VARCHAR Y 20
user of the system adding the
item
regrNm This refers to the username Registrant Name VARCHAR Y 60
of the person making the
sale on the system.
modrId This refers to the ID of the Modifier Id VARCHAR Y 20
user of the system adding the
item
modrNm This refers to the username Modifier Name VARCHAR Y 60
of the person modifying the
sale on the system. (Default
to ADMIN when not
applicable)
saleCtyCd This is the sales category Sales Category Code VARCHAR Y 2
code.
(pass 1)
lpoNumber This is the Local Purchase LPO Number VARCHAR N 50
order number as presented
by the buyer. This will be
validated.
currencyTyCd This is the currency code Currency Type Code VARCHAR Y 5
used in the transaction – as
per standard codes
exchangeRt This is the exchange rate Exchange rate NUMBER Y 18,4
used in the transaction.

43
 destnCountryCd This is the destination Destination Country VARCHAR N 5
country of the item being Code
exported.
dbtRsnCd This is the reason code for Debit Reason Code VARCHAR N 5
issuing a debit.
invcAdjustReason This is the reason for Invoice Adjustment VARCHAR N
adjusting an invoice Reason
List<Trns itemSeq Item Sequence Number Item Sequence NUMBER Y 11
SalesSave Number
WrItem>
itemCd This is the item code as Item Code VARCHAR Y 100
defined on your system
itemClsCd This is the UNSCP code Item Classification VARCHAR Y 10
assigned to the item Code
itemNm This is the item name as Item Name VARCHAR Y 200
defined on your system
bcd This is the barcode assigned Barcode VARCHAR N 20
to the item
pkgUnitCd This is the packaging unit Packaging Unit VARCHAR Y 5 See ‘6.4 Packaging Unit’
code assigned to the item as Code
per standard codes.
Pkg This is the number of Package NUMBER Y 13,2
package items being sold.
qtyUnitCd This is the assigned single Quantity Unit Code VARCHAR Y 5 See ‘6.5. Unit of
item unit code assigned to Quantity’
the item as per standard
codes
qty This is the quantity of items Quantity NUMBER Y 13,2
being sold
prc This is the tax exclusive Unit Price NUMBER Y 18,4
price of the item
splyAmt This is the total amount of Supply Amount NUMBER Y 18,4
the supplied item (qty * prc)
dcRt This is the discount rate on Discount rate NUMBER Y 5,2
line item (Pass 0.0 if not
applicable)
dcAmt This is the discount amount Discount Amount NUMBER Y 18,2
on line item (Pass 0.0 if not
applicable)
isrccCd Insurance Company Code Insurance Company VARCHAR N 10
Code
isrccNm Insurance Company name Insurance Company VARCHAR N 100
name
isrcAmt This is the insurance amount Insurance Amount NUMBER N 18,4
on line item
vatCatCd This represents the tax Vat Category Code VARCHAR Y 5
category code for VAT

44
 purposes on line item. Pass
null where not applicable
exciseTxCatCd This represents the tax Excise Tax Category VARCHAR Y 5
category code for Excise on Code
line item. Pass null where
not applicable
vatTaxblAmt This is the Tax Exclusive VAT Taxable NUMBER Y 18,4
Amount for VAT at line- Amount
item level (Pass 0.0 when
not applicable)
exciseTaxblAmt This is the Tax Exclusive Excise Taxable NUMBER Y 18,4
Amount for Excise at line- Amount
item level (Pass 0.0 when
not applicable)
tlTaxblAmt This is the Tax Exclusive Tourism Levy NUMBER Y 18,4
Amount for Tourism Lecy Taxable Amount
at line-item level (Pass 0.0
when not applicable)
iplTaxblAmt This is the Tax Exclusive Insurance Premium NUMBER Y 18,4
Amount for IPL at line-item Levy Taxable
level (Pass 0.0 when not Amount
applicable)
iplAmt This is the insurance Insurance Premium NUMBER Y 18,4
premium levy tax amount Levy Amount
charged on the line item
tlAmt This is the Tourism Levy Tourism Levy NUMBER Y 18,4
amount charged on the line mount
item.
(Pass 0.0 when not
applicable)
vatAmt This is the VAT amount VAT Amount NUMBER Y 18,4
charged on the line item
exciseTxAmt This is the excise tax amount Excise Tax Amount NUMBER Y 18,4
charged on the line item
(Pass 0.0 when not
applicable)
totAmt This is the total Tax Total Amount NUMBER Y 18,2
Inclusive Amount of the
line item
JSON REQUEST SAMPLE

{"tpin":"9999999999","bhfId":"000","orgInvcNo":0,"cisInvcNo":"CIS001-1372","custTpin":"8888888888","custNm":"Smart
Customer","salesTyCd":"N","rcptTyCd":"S","pmtTyCd":"01","salesSttsCd":"02","cfmDt":"20240508102010","salesDt":"20240508","stockRlsDt":null,"cnclReqDt":null,"cnclDt":null,"rfdDt":null,"rfdRsnCd":nu
ll,"totItemCnt":2,"taxblAmtA":86.2069,"taxblAmtB":0.0,"taxblAmtC1":0.0,"taxblAmtC2":0.0,"taxblAmtC3":0.0,"taxblAmtD":0.0,"taxblAmtRvat":0.0,"taxblAmtE":0.0,"taxblAmtF":0.0,"taxblAmtIpl1":0.0,"tax
blAmtIpl2":100,"taxblAmtTl":0.0,"taxblAmtEcm":0,"taxblAmtExeeg":0.0,"taxblAmtTot":0.0,"taxRtA":16,"taxRtB":16,"taxRtC1":0,"taxRtC2":0,"taxRtC3":0,"taxRtD":0,"tlAmt":0.0,"taxRtRvat":16,"taxRtE":0,"
taxRtF":10,"taxRtIpl1":5,"taxRtIpl2":0,"taxRtTl":1.5,"taxRtEcm":5,"taxRtExeeg":3,"taxRtTot":0,"taxAmtA":13.7931,"taxAmtB":0.0,"taxAmtC1":0.0,"taxAmtC2":0.0,"taxAmtC3":0.0,"taxAmtD":0.0,"taxAmtR
vat":0.0,"taxAmtE":0.0,"taxAmtF":0.0,"taxAmtIpl1":0.0,"taxAmtIpl2":0.0,"taxAmtTl":0.0,"taxAmtEcm":0.0,"taxAmtExeeg":0.0,"taxAmtTot":0.0,"totTaxblAmt":186.2069,"totTaxAmt":13.7931,"totAmt":200,"p
rchrAcptcYn":"N","remark":"","regrId":"admin","regrNm":"admin","modrId":"admin","modrNm":"admin","saleCtyCd":"1",”lpoNumber”:null,"currencyTyCd":"ZMW","exchangeRt":"1","destnCountryCd":"","

45
dbtRsnCd":"","invcAdjustReason":"","itemList":[{"itemSeq":1,"itemCd":"20056","itemClsCd":"50102518","itemNm":"Bread","bcd":"","pkgUnitCd":"BA","pkg":0.0,"qtyUnitCd":"BE","qty":1.0,"prc":100,"sply
Amt":100,"dcRt":0.0,"dcAmt":0.0,"isrccCd":"","isrccNm":"","isrcRt":0.0,"isrcAmt":0.0,"vatCatCd":"A","exciseTxCatCd":null,"tlCatCd":null,"iplCatCd":null,"vatTaxblAmt":86.2069,"vatAmt":13.7931,"exciseT
axblAmt":0,"tlTaxblAmt":0.0,"iplTaxblAmt":0.0,"iplAmt":0.0,"tlAmt":0.0,"exciseTxAmt":0,"totAmt":100},{"itemSeq":2,"itemCd":"20056","itemClsCd":"50102518","itemNm":"Reinsurance","bcd":"","pkgUnit
Cd":"BA","pkg":0.0,"qtyUnitCd":"BE","qty":1.0,"prc":100,"splyAmt":100,"dcRt":0.0,"dcAmt":0.0,"isrccCd":"","isrccNm":"","isrcRt":0.0,"isrcAmt":0.0,"vatCatCd":null,"exciseTxCatCd":null,"vatTaxblAmt":0.
0,"exciseTaxblAmt":0,"tlTaxblAmt":0.0,"tlCatCd":null,"tlAmt":0.0,"iplCatCd":"IPL2","iplAmt":0.0,"iplTaxblAmt":100,"vatAmt":0.0,"exciseTxAmt":0,"totAmt":100}]}

46
Save Sales Request – Credit Note
Object ID Object Attribute ID Attribute Description Attribute Name Data Type Required Data Format
Name Length

TrnsSalesSaveWrReq Save Sales tpin Taxpayer’s identification TPIN VARCHAR Y 10

Request number as registered on
core Tax Administration
System TaxOnline
bhfId Taxpayer branch (store) Branch Id VARCHAR Y 3
location identifier
orgSdcId This is the SDC Id where Original Branch Id VARCHAR Y 13
the original invoice was
issued from
orgIncNo The invoice number being Original Invoice NUMBER Y 38
referred to if you are Number
issuing a credit note or
debit note
cisInvcNo Invoice number as CIS Invoice VARCHAR Y 50
generated on Taxpayers number
Certified invoicing
solutions
custTpin Customers taxpayer’s Customer TPIN VARCHAR N 10
identification number as
registered on core Tax
Administration System
TaxOnline
custNm Customers name Customer Name VARCHAR N 60

salesTyCd Code associated with type Sales Type Code VARCHAR Y 5 See ‘6.7.
of sale e.g. Normal sales, Transaction Type’
Copy sale
rcptTyCd Type of receipt (Pass R) Receipt Type Code VARCHAR Y 5 See ‘6.8. Sale
Receipt Type’
pmtTyCd The mode of payment Payment Type VARCHAR N 5 See ‘6.9. Payment
used for this transaction Code Method’
salesSttsCd Progress of transaction e.g. Invoice/Sale Status VARCHAR Y 5 See ‘6.10.
Approved, Refunded etc. Code Transaction
Progress’
cfmDt Date time when invoice Confirmation Date VARCHAR Y 14 yyyyMMddhhmmss
was issued
salesDt Date when sale was made Sales Date VARCHAR Y 8 yyyyMMdd

stockRlsDt Date when the item was Stock Released VARCHAR N 14 yyyyMMddhhmmss
released from the Date
warehouse/branch

47
cnclReqDt Date time when a Cancell Requested VARCHAR Y 14 yyyyMMddhhmmss
cancellation request was Date
made. This is used when
one needs to cancel an
invoice
cnclDt Date when cancellation Cancel Date VARCHAR Y 14 yyyyMMddhhmmss
was approved
rfdDt Date when refund was Refunded Date VARCHAR Y 14 yyyyMMddhhmmss
made (null when not a
refund)
rfdRsnCd Reason for issuing a Refunded Reason VARCHAR Y 5 See ‘6.15. Refund Reason
refund(empty string when Code Code’
not a refund)
totItemCnt Total number of items on Total Item Count NUMBER Y 10
the invoice
taxblAmtA Total tax exclusive Taxable Amount A NUMBER Y 18,4
amount for all line items
classified as Standard Rated
for VAT purposes (Pass 0.0
if not applicable)
taxblAmtB Total tax exclusive Taxable Amount B NUMBER Y 18,4
amount for all line items
classified as MTV -
Minimum Taxable Value
for VAT purposes (pass
0.0 if not applicable)
taxblAmtC1 Total tax exclusive amount Taxable Amount NUMBER Y 18.4
for all line items classified C1
as C1 - Exports for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtC2 Total tax exclusive amount Taxable Amount NUMBER Y 18.4
for all line items classified C2
as C2 – Zero rating LPO
for VAT purposes (pass
0.0 if not applicable)
taxblAmtC3 Total tax exclusive amount Taxable Amount NUMBER Y 18.4
for all line items classified C3
as C3 Zero rated by nature
for VAT purposes (pass
0.0 if not applicable)
taxblAmtD Total tax exclusive amount Taxable Amount D NUMBER Y 18,4
for all line items classified
as D Exempt for VAT
purposes (pass 0.0 if not
applicable)

48
taxblAmtRvat Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items classified RVAT
as RVAT for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtE Total tax exclusive amount Taxable Amount E NUMBER Y 18,4
for all line items classified
as E - Disbursements for
VAT purposes (pass 0.0 if
not applicable)
taxblAmtF Total tax exclusive amount Taxable Amount F NUMBER Y 18,4
for all line items classified
as F for VAT purposes
(pass 0.0 if not applicable)
taxblAmtIpl1 Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting IPL
Insurance Premium Levy
(pass 0.0 if not applicable)
taxblAmtIpl2 Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting IPL2
Insurance Premium Levy 2
(pass 0.0 if not applicable)
taxblAmtTl Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting TL
Tourism Levy (pass 0.0 if
not applicable)
taxblAmtEcm Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting ECM
Excise Coal (pass 0.0 if not
applicable)
taxblAmtExeeg Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting EXEEG
Excise Electricity (pass 0.0
if not applicable)
taxblAmtTot Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting TOT
TOT (pass 0.0 if not
applicable)
taxRtA Tax rate VAT Standard Tax Rate A NUMBER Y 7,2
rated category A– As per
standard codes
taxRtB Tax rate for Minimum Tax Rate B NUMBER Y 7,2
Taxable Value – As per
standard codes
taxRtC1 Tax rate for C1- Exports – Tax Rate C1 NUMBER Y 7,2
As per standard codes

49
taxRtC2 Tax rate for C2 Zero rating Tax Rate C2 NUMBER Y 7,2
LPO – As per standard
codes
taxRtC3 Tax rate for C3 Zero rated Tax Rate C3 NUMBER Y 7,2
by nature – As per standard
codes
taxRtD Tax rate for D Exempt – Tax Rate D NUMBER Y 7,2
As per standard codes
taxRtRvat Tax rate for RVAT reverse Tax Rate RVAT NUMBER Y 7,2
VAT – As per standard
codes
taxRtE Tax rate E Disbursements Tax Rate E NUMBER Y 7,2
– As per standard codes
taxRtF Rate for F Service charge – Tax Rate F NUMBER Y 7,2
As per standard codes
taxRtIpl1 Tax rate for Insurance Tax Rate IPL NUMBER Y 7,2
premium levy – As per
standard codes
taxRtIpl2 Tax rate for Insurance Tax Rate IPL2 NUMBER Y 7,2
Premium Levy – As per
standard codes
taxRtTl Tax rate for Tourism Levy Tax Rate TL NUMBER Y 7,2
– As per standard codes
taxRtEcm Tax rate for Excise Coal Tax Rate ECM NUMBER Y 7,2
Mining – As per standard
codes
taxRtExeeg Tax rate Electricity and Tax Rate EXEEG NUMBER Y 7,2
Energy generation – As per
standard codes
taxRtTot Tax rate VAT – As per Tax Rate TOT NUMBER Y 7,2
standard codes
taxAmtA This is the total tax Tax Amount A NUMBER Y 18,4
charged on all VAT
category A line items on
invoice (Pass 0.0 when not
applicable)
taxAmtB This is the total tax Tax Amount B NUMBER Y 18,4
charged on all VAT
category A line items on
invoice (Pass 0.0 when not
applicable)
taxAmtC1 This is the total tax Tax Amount C1 NUMBER Y 18,4
charged on all VAT
category C1 line items on
invoice (Pass 0.0 when not
applicable)

50
taxAmtC2 This is the total tax Tax Amount C2 NUMBER Y 18,4
charged on all VAT
category C2 line items on
invoice (Pass 0.0 when not
applicable)
taxAmtC3 This is the total tax Tax Amount C3 NUMBER Y 18,4
charged on all VAT
category C3 line items on
invoice (Pass 0.0 when not
applicable)
taxAmtD This is the total tax Tax Amount D NUMBER Y 18,4
charged on all VAT
category D line items on
invoice (Pass 0.0 when not
applicable)
taxAmtRvat This is the total tax Tax Amount NUMBER Y 18,4
charged on all VAT RVAT
category RVAT line items
on invoice (Pass 0.0 when
not applicable)
taxAmtE This is the total tax Tax Amount E NUMBER Y 18,4
charged on all VAT
category E line items on
invoice (Pass 0.0 when not
applicable)
taxAmtF This is the total tax Tax Amount F NUMBER Y 18,4
charged on all VAT
category F (Service
Charge) line items on
invoice (Pass 0.0 when not
applicable)
taxAmtIpl1 This is the total Insurance Tax Amount IPL1 NUMBER Y 18,4
Premium Levy IPL on
invoice (Pass 0.0 when not
applicable)
taxAmtIpl2 This is the total Insurance Tax Amount IPL2 NUMBER Y 18,4
Premium Levy IPL2 (Re-
Insurance) on invoice (Pass
0.0 when not applicable)
taxAmtTl This is the total Tax Amount TL NUMBER Y 18,4
tax Tourism Levy charged
on invoice (Pass 0.0 when
not applicable)
taxAmtEcm This is the total tax Tax Amount ECM NUMBER Y 18,4
charged on all Excise Coal
Mining line items on
invoice (Pass 0.0 when not
applicable)

51
taxAmtExeeg This is the total tax Tax Amount NUMBER Y 18,4
charged on all Excise EXEEG
Electricity and Energy
generating line items on
invoice (Pass 0.0 when not
applicable)
taxAmtTot [Pass 0.0 not applicable on Tax Amount TOT NUMBER Y 18,4
invoice]
totTaxblAmt This is the total Tax Total TaxlAmt NUMBER Y 18,2
Exclusive Amount for all
line items on invoice
totTaxAmt This is the total tax Tot Tax Amount NUMBER Y 18,2
charged on all line items
on invoice
totAmt This is the total Tax Total Amount NUMBER Y 18,2
Inclusive Amount of all
line items on the invoice
prchrAcptcYn This specifies whether a Purchase Accepted VARCHAR Y 1
purchase has been accepted Yes or No
or not.
remark This is any Remark VARCHAR N 400
comment/remark on the
transaction
regrId This refers to the ID of the Registrant Id VARCHAR Y 20
user of the system adding
the item
regrNm This refers to the username Registrant Name VARCHAR Y 60
of the person making the
sale on the system.
modrId This refers to the ID of the Modifier Id VARCHAR Y 20
user of the system adding
the item
modrNm This refers to the username Modifier Name VARCHAR Y 60
of the person modifying
the sale on the system.
(Default to ADMIN when
not applicable)
saleCtyCd This is the sales category Sales Category VARCHAR Y 2
code Code
(pass 1 )
lpoNumber This is the Local Purchase LPO Number VARCHAR N 50
order number as presented
by the buyer. This will be
validated.
currencyTyCd This is the currency code Currency Type VARCHAR Y 5
used in the transaction – as Code
per standard codes

52
 exchangeRt This is the exchange rate Exchange rate NUMBER Y 18,4
used in the transaction.
destnCountryCd This is the destination Destination Country VARCHAR N 5
country of the item being Code
exported.
dbtRsnCd This is the reason code for Debit Reason Code VARCHAR N 5
issuing a debit.
invcAdjustReason This is the reason for Invoice Adjustment VARCHAR N
adjusting an invoice Reason
List<Trns itemSeq Item Sequence Number Item Sequence NUMBER Y 11
SalesSave Number
WrItem>
itemCd This is the item code as Item Code VARCHAR Y 100
defined on your system
itemClsCd This is the UNSCP code Item Classification VARCHAR Y 10
assigned to the item Code
itemNm This is the item name as Item Name VARCHAR Y 200
defined on your system
bcd This is the barcode Barcode VARCHAR N 20
assigned to the item
pkgUnitCd This is the packaging unit Packaging Unit VARCHAR Y 5 See ‘6.4 Packaging Unit’
code assigned to the item Code
as per standard codes.
Pkg This is the number of Package NUMBER Y 13,2
package items being sold.
qtyUnitCd This is the assigned single Quantity Unit Code VARCHAR Y 5 See ‘6.5. Unit of
item unit code assigned to Quantity’
the item as per standard
codes
qty This is the quantity of Quantity NUMBER Y 13,2
items being sold
prc This is the tax exclusive Unit Price NUMBER Y 18,4
price of the item
splyAmt This is the total amount of Supply Amount NUMBER Y 18,4
the supplied item (qty *
prc)
dcRt This is the discount rate on Discount rate NUMBER Y 5,2
line item (Pass 0.0 if not
applicable)
dcAmt This is the discount amount Discount Amount NUMBER Y 18,2
on line item (Pass 0.0 if not
applicable)
isrccCd Insurance Company Code Insurance Company VARCHAR N 10
Code
isrccNm Insurance Company name Insurance Company VARCHAR N 100
name

53
 isrcAmt This is the insurance Insurance Amount NUMBER N 18,4
amount on line item
vatCatCd This represents the tax Vat Category Code VARCHAR Y 5
category code for VAT
purposes on line item
exciseTxCatCd This represents the tax Excise Tax VARCHAR Y 5
category code for Excise Category Code
on line item.
vatTaxblAmt This is the Tax Exclusive VAT Taxable NUMBER Y 18,4
Amount for VAT at line Amount
item level (Pass 0.0 when
not applicable)
exciseTaxblAmt This is the Tax Exclusive Excise Taxable NUMBER Y 18,4
Amount for Excise at line Amount
item level (Pass 0.0 when
not applicable)
tlTaxblAmt This is the Tax Exclusive Tourism Levy NUMBER Y 18,4
Amount for Tourism Lecy Taxable Amount
at line item level (Pass 0.0
when not applicable)
iplTaxblAmt This is the Tax Exclusive Insurance Premium NUMBER Y 18,4
Amount for IPL at line Levy Taxable
item level (Pass 0.0 when Amount
not applicable)
iplAmt This is the insurance Insurance Premium NUMBER Y 18,4
premium levy tax amount Levy Amount
charged on the line item
tlAmt This is the Tourism Levy Tourism Levy NUMBER Y 18,4
amount charged on the line mount
item
(Pass 0.0 when not
applicable)
vatAmt This is the VAT amount VAT Amount NUMBER Y 18,4
charged on the line item
exciseTxAmt This is the excise tax Excise Tax NUMBER Y 18,4
amount charged on the line Amount
item (Pass 0.0 when not
applicable)
totAmt This is the total Tax Total Amount NUMBER Y 18,2
Inclusive Amount of the
line item
JSON REQUEST SAMPLE

{"tpin":"999999999","bhfId":"001","orgSdcId ":"000","orgInvcNo":7,"cisInvcNo":"DBT000002","custTpin":"1000724543","custNm":"Customer Name

1","salesTyCd":"N","rcptTyCd":"R","pmtTyCd":"01","salesSttsCd":"02","cfmDt":"20240509172010","salesDt":"20240509","stockRlsDt":null,"cnclReqDt":null,"cnclDt":null,"rfdDt":null,"rfdRsnCd":null,"totIte
mCnt":1,"taxblAmtA":862.069,"taxblAmtB":0,"taxblAmtC1":0,"taxblAmtC2":0,"taxblAmtC3":0,"taxblAmtD":0,"taxblAmtRvat":0,"taxblAmtE":0,"taxblAmtF":0,"taxblAmtIpl1":0,"taxblAmtIpl2":0,"taxblAmtT
l":0,"taxblAmtEcm":0,"taxblAmtExeeg":0,"taxblAmtTot":0,"taxRtA":16,"taxRtB":16,"taxRtC1":0,"taxRtC2":0,"taxRtC3":0,"taxRtD":0,"taxRtRvat":16,"taxRtE":0,"taxRtF":10,"taxRtIpl1":5,"taxRtIpl2":0,"taxRt
Tl":1.5,"taxRtEcm":5,"taxRtExeeg":3,"taxRtTot":0,"taxAmtA":137.931,"taxAmtB":0

54
 ,"taxAmtC1":0,"taxAmtC2":0,"taxAmtC3":0,"taxAmtD":0,"taxAmtRvat":0,"taxAmtE":0,"taxAmtF":0,"taxAmtIpl1":0,"taxAmtIpl2":0,"taxAmtTl":0,"taxAmtEcm":0,"taxAmtExeeg":0,"taxAmtTot":0,"totTaxblA
mt":862.069,"totTaxAmt":137.931,"totAmt":1000,"prchrAcptcYn":"N","remark":"","regrId":"ADMIN","regrNm":"ADMIN","modrId":"ADMIN","modrNm":"ADMIN","saleCtyCd":"1",”lpoNumber”:null,"curr
encyTyCd":"ZMW","exchangeRt":"1","destnCountryCd":"","dbtRsnCd":"03","invcAdjustReason":"Omitted Item","itemList":[{"itemSeq":1,"itemCd":"P200007","itemClsCd":"46181901","itemNm":"ITEM
1234","bcd":"","pkgUnitCd":"P/KG","pkg":0,"qtyUnitCd":"U","qty":10,"prc":100,"splyAmt":1000,"dcRt":0,"dcAmt":0,"isrccCd":"","isrccNm":"","isrcRt":0,"isrcAmt":0,"vatCatCd":"A","exciseTxCatCd":null,"
vatTaxblAmt":862.069,"exciseTaxblAmt":0,"vatAmt":137.931,"exciseTxAmt":0,"totAmt":1000}]}

Save Sales Request – Debit Note

Object ID Object Attribute ID Attribute Description Attribute Name Data Type Required Data Format
Name Length

TrnsSalesSaveWrReq Save Sales tpin Taxpayer’s identification TPIN VARCHAR Y 10

Request number as registered on
core Tax Administration
System TaxOnline
bhfId Taxpayer branch (store) Branch Id VARCHAR Y 3
location identifier
orgIncNo The invoice number being Original Invoice NUMBER Y 38
refered to in the event that Number
you are issueing a credit
note or debit note
cisInvcNo Invoice number as CIS Invoice VARCHAR Y 50
generated on Taxpayers number
Certified invoicing
solutions
custTpin Customers taxpayer’s Customer TPIN VARCHAR N 10
identification number as
registered on core Tax
Administration System
TaxOnline
custNm Customers name Customer Name VARCHAR N 60

salesTyCd Code associated with type of Sales Type Code VARCHAR Y 5 See ‘6.7.
sale e.g Normal sales, Copy Transaction Type’
sale
rcptTyCd Type of receipt Receipt Type Code VARCHAR Y 5 See ‘6.8. Sale
Receipt Type’
pmtTyCd The mode of payment used Payment Type VARCHAR N 5 See ‘6.9. Payment
for this transaction Code Method’
salesSttsCd Progress of transaction e.g Invoice/Sale Status VARCHAR Y 5 See ‘6.10.
Approved, Refunded etc Code Transaction
Progress’
cfmDt Date time when invoice was Confirmation Date VARCHAR Y 14 yyyyMMddhhmmss
issued

55
salesDt Date when sale was made Sales Date VARCHAR Y 8 yyyyMMdd

stockRlsDt Date when the item was Stock Released VARCHAR N 14 yyyyMMddhhmmss
released from the Date
warehouse/branch
cnclReqDt Date time when a Cancell Requested VARCHAR N 14 yyyyMMddhhmmss
cancellation request was Date
made. This is used when
one needs to cancel an
invoice
cnclDt Date when cancellation was Cancel Date VARCHAR N 14 yyyyMMddhhmmss
approved
rfdDt Date when refund was made Refunded Date VARCHAR N 14 yyyyMMddhhmmss
(null when not a refund)
rfdRsnCd Reason for issuing a Refunded Reason VARCHAR N 5 See ‘6.15. Refund Reason
refund(empty string when Code Code’
not a refund)
totItemCnt Total number of items on Total Item Count NUMBER Y 10
the invoice
taxblAmtA Total tax exclusive amount Taxable Amount A NUMBER Y 18,4
for all line items classified as
Standard Rated for VAT
purposes (Pass 0.0 if not
applicable)
taxblAmtB Total tax exclusive Taxable Amount B NUMBER Y 18,4
amount for all line items
classified as MTV -
Minimum Taxable Value
for VAT purposes (pass 0.0
if not applicable)
taxblAmtC1 Total tax exclusive amount Taxable Amount NUMBER Y 18.4
for all line items classified C1
as C1 - Exports for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtC2 Total tax exclusive amount Taxable Amount NUMBER Y 18.4
for all line items classified C2
as C2 – Zero rating LPO for
VAT purposes (pass 0.0 if
not applicable)
taxblAmtC3 Total tax exclusive amount Taxable Amount NUMBER Y 18.4
for all line items classified C3
as C3 Zero rated by nature
for VAT purposes (pass 0.0
if not applicable)
taxblAmtD Total tax exclusive amount Taxable Amount D NUMBER Y 18,4
for all line items classified

56
 as D Exempt for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtRvat Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items classified RVAT
as RVAT for VAT purposes
(pass 0.0 if not applicable)
taxblAmtE Total tax exclusive amount Taxable Amount E NUMBER Y 18,4
for all line items classified
as E - Disbursements for
VAT purposes (pass 0.0 if
not applicable)
taxblAmtF Total tax exclusive amount Taxable Amount F NUMBER Y 18,4
for all line items classified
as F for VAT purposes
(pass 0.0 if not applicable)
taxblAmtIpl1 Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting IPL
Insurance Premium Levy
(pass 0.0 if not applicable)
taxblAmtIpl2 Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting IPL2
Insurance Premium Levy 2
(pass 0.0 if not applicable)
taxblAmtTl Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting TL
Tourism Levy (pass 0.0 if
not applicable)
taxblAmtEcm Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting ECM
Excise Coal (pass 0.0 if not
applicable)
taxblAmtExeeg Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting EXEEG
Excise Electricity (pass 0.0
if not applicable)
taxblAmtTot Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting TOT
TOT (pass 0.0 if not
applicable)
taxRtA Tax rate VAT Standard Tax Rate A NUMBER Y 7,2
rated category A– As per
standard codes
taxRtB Tax rate for Minimum Tax Rate B NUMBER Y 7,2
Taxable Value – As per
standard codes

57
taxRtC1 Tax rate for C1- Exports – Tax Rate C1 NUMBER Y 7,2
As per standard codes
taxRtC2 Tax rate for C2 Zero rating Tax Rate C2 NUMBER Y 7,2
LPO – As per standard
codes
taxRtC3 Tax rate for C3 Zero rated Tax Rate C3 NUMBER Y 7,2
by nature – As per standard
codes
taxRtD Tax rate for D Exempt – As Tax Rate D NUMBER Y 7,2
per standard codes
taxRtRvat Tax rate for RVAT reverse Tax Rate RVAT NUMBER Y 7,2
VAT – As per standard
codes
taxRtE Tax rate E Disbursements – Tax Rate E NUMBER Y 7,2
As per standard codes
taxRtF Rate for F Service charge – Tax Rate F NUMBER Y 7,2
As per standard codes
taxRtIpl1 Tax rate for Insurance Tax Rate IPL NUMBER Y 7,2
premium levy – As per
standard codes
taxRtIpl2 Tax rate for Insurance Tax Rate IPL2 NUMBER Y 7,2
Premium Levy – As per
standard codes
taxRtTl Tax rate for Tourism Levy – Tax Rate TL NUMBER Y 7,2
As per standard codes
taxRtEcm Tax rate for Excise Coal Tax Rate ECM NUMBER Y 7,2
Mining – As per standard
codes
taxRtExeeg Tax rate Electricity and Tax Rate EXEEG NUMBER Y 7,2
Energy generation – As per
standard codes
taxRtTot Tax rate VAT – As per Tax Rate TOT NUMBER Y 7,2
standard codes
taxAmtA This is the total tax charged Tax Amount A NUMBER Y 18,4
on all VAT category A line
items on invoice (Pass 0.0
when not applicable)
taxAmtB This is the total tax charged Tax Amount B NUMBER Y 18,4
on all VAT category A line
items on invoice (Pass 0.0
when not applicable)
taxAmtC1 This is the total tax charged Tax Amount C1 NUMBER Y 18,4
on all VAT category C1 line
items on invoice (Pass 0.0
when not applicable)
taxAmtC2 This is the total tax charged Tax Amount C2 NUMBER Y 18,4
on all VAT category C2 line

58
 items on invoice (Pass 0.0
when not applicable)
taxAmtC3 This is the total tax charged Tax Amount C3 NUMBER Y 18,4
on all VAT category C3 line
items on invoice (Pass 0.0
when not applicable)
taxAmtD This is the total tax charged Tax Amount D NUMBER Y 18,4
on all VAT category D line
items on invoice (Pass 0.0
when not applicable)
taxAmtRvat This is the total tax charged Tax Amount NUMBER Y 18,4
on all VAT category RVAT RVAT
line items on invoice (Pass
0.0 when not applicable)
taxAmtE This is the total tax charged Tax Amount E NUMBER Y 18,4
on all VAT category E line
items on invoice (Pass 0.0
when not applicable)
taxAmtF This is the total tax charged Tax Amount F NUMBER Y 18,4
on all VAT category F
(Service Charge) line items
on invoice (Pass 0.0 when
not applicable)
taxAmtIpl1 This is the total Insurance Tax Amount IPL1 NUMBER Y 18,4
Premium Levy IPL on
invoice (Pass 0.0 when not
applicable)
taxAmtIpl2 This is the total Insurance Tax Amount IPL2 NUMBER Y 18,4
Premium Levy IPL2
(ReInsurance) on invoice
(Pass 0.0 when not
applicable)
taxAmtTl This is the total tax Tourism Tax Amount TL NUMBER Y 18,4
Levy charged on invoice
(Pass 0.0 when not
applicable)
taxAmtEcm This is the total tax charged Tax Amount ECM NUMBER Y 18,4
on all Excise Coal Mining
line items on invoice (Pass
0.0 when not applicable)
taxAmtExeeg This is the total tax charged Tax Amount NUMBER Y 18,4
on all Excise Electricity and EXEEG
Energy generating line
items on invoice (Pass 0.0
when not applicable)
taxAmtTot [Pass 0.0 not applicable on Tax Amount TOT NUMBER Y 18,4
invoice]

59
totTaxblAmt This is the total Tax Total TaxlAmt NUMBER Y 18,2
Exclusive Amount for all
line items on invoice
totTaxAmt This is the total tax charged Tot Tax Amount NUMBER Y 18,2
on all line items on invoice
totAmt This is the total Tax Total Amount NUMBER Y 18,2
Inclusive Amount of all
line items on the invoice
prchrAcptcYn This specifies whether a Purchase Accepted VARCHAR Y 1
purchase has been accepted Yes or No
or not.
remark This is any Remark VARCHAR N 400
comment/remark on the
transaction
regrId This refers to the ID of the Registrant Id VARCHAR Y 20
user of the system adding
the item
regrNm This refers to the username Registrant Name VARCHAR Y 60
of the person making the
sale on the system.
modrId This refers to the ID of the Modifier Id VARCHAR Y 20
user of the system adding
the item
modrNm This refers to the username Modifier Name VARCHAR Y 60
of the person modifying the
sale on the system. (Default
to ADMIN when not
applicable)
saleCtyCd This is the sales category Sales Category VARCHAR Y 2
code Code
(pass 1 )
lpoNumber This is the Local Purchase LPO Number VARCHAR N 50
order number as presented
by the buyer. This will be
validated.
currencyTyCd This is the currency code Currency Type VARCHAR Y 5
used in the transaction – as Code
per standard codes
exchangeRt This is the exchange rate Exchange rate NUMBER Y 18,4
used in the transaction.
destnCountryCd This is the destination Destination Country VARCHAR N 5
country of the item being Code
exported.
dbtRsnCd This is the reason code for Debit Reason Code VARCHAR Y 5
issuing a debit.
invcAdjustReason This is the reason for Invoice Adjustment VARCHAR Y
adjusting an invoice Reason

60
List<Trns itemSeq Item Sequence Number Item Sequence NUMBER Y 11
SalesSave Number
WrItem>
itemCd This is the item code as Item Code VARCHAR Y 20
defined on your system
itemClsCd This is the UNSCP code Item Classification VARCHAR Y 10
assigned to the item Code
itemNm This is the item name as Item Name VARCHAR Y 200
defined on your system
bcd This is the barcode assigned Barcode VARCHAR N 20
to the item
pkgUnitCd This is the packaging unit Packaging Unit VARCHAR Y 5 See ‘6.4. Packaging Unit’
code assigned to the item as Code
per standard codes.
Pkg This is the number of Package NUMBER Y 13,2
package items being sold.
qtyUnitCd This is the assigned single Quantity Unit Code VARCHAR Y 5 See ‘6.5. Unit of
item unit code assigned to Quantity’
the item as per standard
codes
qty This is the quantity of items Quantity NUMBER Y 13,2
being sold
prc This is the tax exclusive Unit Price NUMBER Y 18,4
price of the item
splyAmt This is the total amount of Supply Amount NUMBER Y 18,4
the supplied item (qty *
prc)
dcRt This is the discount rate on Discount rate NUMBER Y 5,2
line item (Pass 0.0 if not
applicable)
dcAmt This is the discount amount Discount Amount NUMBER Y 18,2
on line item (Pass 0.0 if not
applicable)
isrccCd Insurance Company Code Insurance Company VARCHAR N 10
Code
isrccNm Insurance Company name Insurance Company VARCHAR N 100
name
isrcAmt This is the insurance Insurance Amount NUMBER N 18,4
amount on line item
vatCatCd This represents the tax Vat Category Code VARCHAR Y 5
category code for VAT
purposes on line-item
exciseTxCatCd This represents the tax Excise Tax VARCHAR Y 5
category code for Excise on Category Code
line-item.
vatTaxblAmt This is the Tax Exclusive VAT Taxable NUMBER Y 18,4
Amount for VAT at line- Amount

61
 item level (Pass 0.0 when
not applicable)
exciseTaxblAmt This is the Tax Exclusive Excise Taxable NUMBER Y 18,4
Amount for Excise at line Amount
item level (Pass 0.0 when
not applicable)
tlTaxblAmt This is the Tax Exclusive Tourism Levy NUMBER Y 18,4
Amount for Tourism Lecy Taxable Amount
at line-item level (Pass 0.0
when not applicable)
iplTaxblAmt This is the Tax Exclusive Insurance Premium NUMBER Y 18,4
Amount for IPL at line- Levy Taxable
item level (Pass 0.0 when Amount
not applicable)
iplAmt This is the insurance Insurance Premium NUMBER Y 18,4
premium levy tax amount Levy Amount
charged on the line item
tlAmt This is the Tourism Levy Tourism Levy NUMBER Y 18,4
amount charged on the line- mount
item
(Pass 0.0 when not
applicable)
vatAmt This is the VAT amount VAT Amount NUMBER Y 18,4
charged on the line item
exciseTxAmt This is the excise tax Excise Tax Amount NUMBER Y 18,4
amount charged on the line
item (Pass 0.0 when not
applicable)
totAmt This is the total Tax Total Amount NUMBER Y 18,2
Inclusive Amount of the
line item
JSON REQUEST SAMPLE

{"tpin":"999999999","bhfId":"000","orgInvcNo":7,"cisInvcNo":"DBT000002","custTpin":"1000724543","custNm":"Customer Name
1","salesTyCd":"N","rcptTyCd":"D","pmtTyCd":"01","salesSttsCd":"02","cfmDt":"20240509172010","salesDt":"20240509","stockRlsDt":null,"cnclReqDt":null,"cnclDt":null,"rfdDt":null,"rfdRsnCd":null,"totIt
emCnt":1,"taxblAmtA":862.069,"taxblAmtB":0,"taxblAmtC1":0,"taxblAmtC2":0,"taxblAmtC3":0,"taxblAmtD":0,"taxblAmtRvat":0,"taxblAmtE":0,"taxblAmtF":0,"taxblAmtIpl1":0,"taxblAmtIpl2":0,"taxblAmt
Tl":0,"taxblAmtEcm":0,"taxblAmtExeeg":0,"taxblAmtTot":0,"taxRtA":16,"taxRtB":16,"taxRtC1":0,"taxRtC2":0,"taxRtC3":0,"taxRtD":0,"taxRtRvat":16,"taxRtE":0,"taxRtF":10,"taxRtIpl1":5,"taxRtIpl2":0,"tax
RtTl":1.5,"taxRtEcm":5,"taxRtExeeg":3,"taxRtTot":0,"taxAmtA":137.931,"taxAmtB":0,
"taxAmtC1":0,"taxAmtC2":0,"taxAmtC3":0,"taxAmtD":0,"taxAmtRvat":0,"taxAmtE":0,"taxAmtF":0,"taxAmtIpl1":0,"taxAmtIpl2":0,"taxAmtTl":0,"taxAmtEcm":0,"taxAmtExeeg":0,"taxAmtTot":0,"totTaxblA
mt":862.069,"totTaxAmt":137.931,"totAmt":1000,"prchrAcptcYn":"N","remark":"","regrId":"ADMIN","regrNm":"ADMIN","modrId":"ADMIN","modrNm":"ADMIN","saleCtyCd":"1",”lpoNumber”:null,"curr
encyTyCd":"ZMW","exchangeRt":"1","destnCountryCd":"","dbtRsnCd":"03","invcAdjustReason":"Omitted Item","itemList":[{"itemSeq":1,"itemCd":"P200007","itemClsCd":"46181901","itemNm":"ITEM
1234","bcd":"","pkgUnitCd":"P/KG","pkg":0,"qtyUnitCd":"U","qty":10,"prc":100,"splyAmt":1000,"dcRt":0,"dcAmt":0,"isrccCd":"","isrccNm":"","isrcRt":0,"isrcAmt":0,"vatCatCd":"A","exciseTxCatCd":null,"
vatTaxblAmt":862.069,"exciseTaxblAmt":0,"vatAmt":137.931,"exciseTxAmt":0,"totAmt":1000}]}

62
63
Save Sales Request – LPO Transactions
Object ID Object Attribute ID Attribute Description Attribute Name Data Type Required Data Format
Name Length

TrnsSalesSaveWrReq Save Sales Request tpin Taxpayer’s identification number as TPIN VARCHAR Y 10
registered on core Tax
Administration System
TaxOnline
bhfId Taxpayer branch (store) location Branch ID VARCHAR Y 3
identifier
orgInvcNo This is the original invoice number Original Invoice NUMBER N 38
referred to in the event of a reversal Number
or debit note
cisInvcNo Invoice number as generated on CIS Invoice number VARCHAR Y 50
Taxpayers Certified invoicing
solutions
custTpin Customers taxpayer’s identification Customer TPIN VARCHAR N 10
number as registered on core Tax
Administration System
TaxOnline
custNm Customers name Customer Name VARCHAR N 60

salesTyCd Type of sale e.g Normal sales, Copy Sales Type Code VARCHAR Y 5 See ‘6.7.
sale Transaction Type’
rcptTyCd Type of receipt Receipt Type Code VARCHAR Y 5 See ‘6.8. Sale
Receipt Type’
pmtTyCd The mode of payment used for this Payment Type Code VARCHAR N 5 See ‘6.9. Payment
transaction Method’
salesSttsCd Progress of transaction e.g Invoice/Sale Status VARCHAR Y 5 See ‘6.10.
Approved, Refunded etc Code Transaction
Progress’
cfmDt Date time when invoice was Confirmation Date VARCHAR Y 14 yyyyMMddhhmmss
issued
salesDt Date when sale was made Sales Date VARCHAR Y 8 yyyyMMdd

stockRlsDt Date when the item was released Stock Released Date VARCHAR N 14 yyyyMMddhhmmss
from the warehouse/branch
cnclReqDt Date time when a cancellation Cancel Reqeuested Date VARCHAR N 14 yyyyMMddhhmmss
request was made. This is used
when one needs to cancel an
invoice
cnclDt Date when cancellation was Cancel Date VARCHAR N 14 yyyyMMddhhmmss
approved
rfdDt Date when refund was made (null Refunded Date VARCHAR N 14 yyyyMMddhhmmss
when not a refund)

64
rfdRsnCd Reason for issuing a refund( empty Refunded Reason Code VARCHAR N 5 See ‘6.15. Refund
string when not a refund) Reason Code’
totItemCnt Total number of items on Total Item Count NUMBER Y 10
the invoice
taxblAmtA Total amount taxable for all line Taxable Amount A NUMBER Y 18,4
items attracting VAT -Standard
Rated A (pass 0.0 if not applicable)
taxblAmtB Total amount taxable for all line Taxable Amount B NUMBER Y 18,4
items attracting MTV -Minimum
Taxable Value B (pass 0.0 if not
applicable)
taxblAmtC1 Total amount taxable for all line Taxable Amount C1 NUMBER Y 18.4
items attracting VAT category C1 -
exports (pass 0.0 if not applicable)
taxblAmtC2 Total amount taxable for all line Taxable Amount C2 NUMBER Y 18.4
items attracting VAT category C2 -
Zero rating LPO (pass 0.0 if not
applicable)
taxblAmtC3 Total amount taxable for all line Taxable Amount C3 NUMBER Y 18.4
items attracting C3 Zero rated by
nature (pass 0.0 if not applicable)
taxblAmtD Total amount taxable for all line Taxable Amount D NUMBER Y 18,4
items attracting VAT category D
Exempt (pass 0.0 if not
applicable)
taxblAmtRvat Total amount taxable for all line Taxable Amount RVAT NUMBER Y 18,4
items attracting RVAT reverse
VAT (pass 0.0 if not applicable)
taxblAmtE Total amount taxable for all line Taxable Amount E NUMBER Y 18,4
items attracting VAT category
E Disbursements (pass 0.0 if not
applicable)
taxblAmtF Total amount taxable for all line Taxable Amount F NUMBER Y 18,4
items attracting VAT category F
Service charge (pass 0.0 if not
applicable)
taxblAmtIpl1 Total amount taxable for all line Taxable Amount IPL NUMBER Y 18,4
items attracting Insurance Premium
Levy (pass 0.0 if not applicable)
taxblAmtIpl2 Total amount taxable for all line Taxable Amount IPL2 NUMBER Y 18,4
items attracting Insurance Premium
Levy 2 (pass 0.0 if not applicable)
taxblAmtTl Total amount taxable for all line Taxable Amount TL NUMBER Y 18,4
items attracting Tourism Levy (pass
0.0 if not applicable)

65
taxblAmtEcm Total amount taxable for all line Taxable Amount ECM NUMBER Y 18,4
items attracting Excise Coal (pass
0.0 if not applicable)
taxblAmtExeeg Total amount taxable for all line Taxable Amount NUMBER Y 18,4
items attracting Excise Electricity EXEEG
(pass 0.0 if not applicable)
taxblAmtTot Total amount taxable for all line Taxable Amount TOT NUMBER Y 18,4
items attracting TOT (pass 0.0 if
not applicable)
taxRtA Tax rate VAT category A– As per Tax Rate A NUMBER Y 7,2
standard codes
taxRtB Tax rate for Minimum Taxable Tax Rate B NUMBER Y 7,2
Value – As per standard codes
taxRtC1 Tax rate for C1- Exports – As per Tax Rate C1 NUMBER Y 7,2
standard codes
taxRtC2 Tax rate for C2 Zero rating LPO – Tax Rate C2 NUMBER Y 7,2
As per standard codes
taxRtC3 Tax rate for C3 Zero rated by Tax Rate C3 NUMBER Y 7,2
nature – As per standard codes
taxRtD Tax rate for D Exempt – As per Tax Rate D NUMBER Y 7,2
standard codes
taxRtRvat Tax rate for RVAT reverse VAT – Tax Rate RVAT NUMBER Y 7,2
As per standard codes
taxRtE Tax rate E Disbursements – As per Tax Rate E NUMBER Y 7,2
standard codes
taxRtF Rate for F Service charge – As per Tax Rate F NUMBER Y 7,2
standard codes
taxRtIpl1 Tax rate for Insurance premium Tax Rate IPL NUMBER Y 7,2
levy – As per standard codes
taxRtIpl2 Tax rate for Insurance Premium Tax Rate IPL2 NUMBER Y 7,2
Levy – As per standard codes
taxRtTl Tax rate for Tourism Levy – As per Tax Rate TL NUMBER Y 7,2
standard codes
taxRtEcm Tax rate for Excise Coal Mining – Tax Rate ECM NUMBER Y 7,2
As per standard codes
taxRtExeeg Tax rate Electricity and Energy Tax Rate EXEEG NUMBER Y 7,2
generation – As per standard
codes
taxRtTot Tax rate VAT – As per standard Tax Rate TOT NUMBER Y 7,2
codes
taxAmtA This is the total tax charged on all Tax Amount A NUMBER Y 18,4
VAT category A line items on
invoice (Pass 0.0 when not
applicable)
taxAmtB This is the total tax charged on all Tax Amount B NUMBER Y 18,4
VAT category A line items on

66
 invoice (Pass 0.0 when not
applicable)
taxAmtC1 This is the total tax charged on all Tax Amount C1 NUMBER Y 18,4
VAT category C1 line items on
invoice (Pass 0.0 when not
applicable)
taxAmtC2 This is the total tax charged on all Tax Amount C2 NUMBER Y 18,4
VAT category C2 line items on
invoice (Pass 0.0 when not
applicable)
taxAmtC3 This is the total tax charged on all Tax Amount C3 NUMBER Y 18,4
VAT category C3 line items on
invoice (Pass 0.0 when not
applicable)
taxAmtD This is the total tax charged on all Tax Amount D NUMBER Y 18,4
VAT category D line items on
invoice (Pass 0.0 when not
applicable)
taxAmtRvat This is the total tax charged on all Tax Amount RVAT NUMBER Y 18,4
VAT category RVAT line items on
invoice (Pass 0.0 when not
applicable)
taxAmtE This is the total tax charged on all Tax Amount E NUMBER Y 18,4
VAT category E line items on
invoice (Pass 0.0 when not
applicable)
taxAmtF This is the total tax charged on all Tax Amount F NUMBER Y 18,4
VAT category F (Service
Charge) line items on invoice (Pass
0.0 when not applicable)
taxAmtIpl1 This is the total Insurance Premium Tax Amount IPL1 NUMBER Y 18,4
Levy IPL on invoice (Pass 0.0
when not applicable)
taxAmtIpl2 This is the total Insurance Premium Tax Amount IPL2 NUMBER Y 18,4
Levy IPL2 (ReInsurance) on
invoice (Pass 0.0 when not
applicable)
taxAmtTl This is the total tax Tourism Tax Amount TL NUMBER Y 18,4
Levy charged on invoice (Pass 0.0
when not applicable)
taxAmtEcm This is the total tax charged on all Tax Amount ECM NUMBER Y 18,4
Excise Coal Mining line items on
invoice (Pass 0.0 when not
applicable)
taxAmtExeeg This is the total tax charged on all Tax Amount EXEEG NUMBER Y 18,4
Excise Electricity and Energy

67
 generating line items on invoice
(Pass 0.0 when not applicable)
taxAmtTot [Pass 0.0 not applicable on invoice] Tax Amount TOT NUMBER Y 18,4

totTaxblAmt This is the total Tax Exclusive Total TaxlAmt NUMBER Y 18,2
Amount for all line items on
invoice
totTaxAmt This is the total tax charged on all Tot Tax Amount NUMBER Y 18,2
line items on invoice
totAmt This is the total Tax Inclusive Total Amount NUMBER Y 18,2
Amount of all line items on the
invoice
prchrAcptcYn This specifies whether a purchase Purchase Accepted Yes VARCHAR Y 1
has been accepted or not. or No
remark This is any comment/remark on the Remark VARCHAR N 400
transaction
regrId This refers to the ID of the user of Registrant Id VARCHAR Y 20
the system adding the item
regrNm This refers to the username of the Registrant Name VARCHAR Y 60
person making the sale on the
system.
modrId This refers to the ID of the user of Modifier Id VARCHAR Y 20
the system adding the item
modrNm This refers to the username of the Modifier Name VARCHAR Y 60
person modifying the sale on the
system.
saleCtyCd This is the sales category code Sales Category Code VARCHAR Y 2
(pass 1 )
lpoNumber This is the Local Purchase order LPO Number VARCHAR N 50
number as presented by the buyer.
This will be validated.
currencyTyCd This is the currency code used in Currency Type Code VARCHAR Y 5
the transaction – as per standard
codes
exchangeRt This is the exchange rate used in Exchange rate NUMBER Y 18,4
the transaction.
destnCountryCd This is the destination country of Destination Country VARCHAR N 5
the item being exported. Code
dbtRsnCd This is the reason for issuing a Debit Reason Code VARCHAR N 5
debit sale.
invcAdjustReason This is the reason for adjusting an Invoice Adjustment VARCHAR N
invoice Reason
itemSeq Item Sequence Number Item Sequence Number NUMBER Y 11

itemCd This is the item code as defined on Item Code VARCHAR Y 100
your system

68
itemClsCd This is the UNSCP code assigned Item Classification Code VARCHAR Y 10
to the item
itemNm This is the item name as defined on Item Name VARCHAR Y 200
your system
bcd This is the barcode assigned to the Barcode VARCHAR N 20
item
pkgUnitCd This is the packaging unit code Packaging Unit Code VARCHAR Y 5 See ‘6.4. Packaging
assigned to the item as per standard Unit’
codes.
pkg This is the number of package Package NUMBER Y 13,2
items being sold.
qtyUnitCd This is the assigned single item unit Quantity Unit Code VARCHAR Y 5 See ‘6.5. Unit of
code assigned to the item as per Quantity’
standard codes
qty This is the quantity of items being Quantity NUMBER Y 13,2
sold
prc This is the tax exclusive price of the Unit Price NUMBER Y 18,4
item
splyAmt This is the total amount of the Supply Amount NUMBER Y 18,4
supplied item (qty * prc)
dcRt This is the discount rate on line Discount rate NUMBER Y 5,2
item (Pass 0.0 if not applicable)
dcAmt This is the discount amount on line Discount Amount NUMBER Y 18,2
item (Pass 0.0 if not applicable)
isrccCd Insurance Company Code Insurance Company VARCHAR N 10
Code
isrccNm Insurance Company name Insurance Company VARCHAR N 100
name
isrcAmt This is the insurance amount on Insurance Amount NUMBER N 18,4
line item
vatCatCd This represents the tax category Vat Category Code VARCHAR Y 5
code for VAT purposes
exciseTxCatCd This represents the tax category Excise Tax Category VARCHAR Y 5
code for Excise on line item Code
vatTaxblAmt This is the Tax Exclusive Amount VAT Taxable Amount NUMBER Y 18,4
for VAT at line-item level (Pass 0.0
when not applicable)
exciseTaxblAmt This is the Tax Exclusive Amount Excise Taxable Amount NUMBER Y 18,4
for Excise at line-item level (Pass
0.0 when not applicable)
vatAmt This is the VAT amount charged on VAT Amount NUMBER Y 18,4
the line item
exciseTxAmt This is the excise tax amount Excise Tax Amount NUMBER Y 18,4
charged on the line item (Pass 0.0
when not applicable)
totAmt This is the total Tax Inclusive Total Amount NUMBER Y 18,2
Amount of the line item

69
 JSON REQUEST SAMPLE
{
"tpin": "9999999999","bhfId": "000","orgInvcNo": 0,"cisInvcNo":"CIS001-19","custTpin": "8888888888","custNm": "Cumstomer Name One", "salesTyCd": "N", "rcptTyCd": "S", "pmtTyCd": "01", "salesSttsCd":
"02", "cfmDt": "20240508102010", "salesDt": "20240508", "stockRlsDt": null, "cnclReqDt": null, "cnclDt": null,"rfdDt": null,"rfdRsnCd": null,"totItemCnt": 1,"taxblAmtA": 85.1064,"taxblAmtB":
0.0,"taxblAmtC1": 0.0,"taxblAmtC2": 0.0,"taxblAmtC3": 0.0, "taxblAmtD": 0.0,"taxblAmtRvat": 0.0,"taxblAmtE": 0.0,"taxblAmtF": 0.0,"taxblAmtIpl1": 0,"taxblAmtIpl2": 0,"taxblAmtTl":
85.1064,"taxblAmtEcm": 0, "taxblAmtExeeg": 0.0,"taxblAmtTot": 0.0,"taxRtA": 16,"taxRtB": 16,"taxRtC1": 0,"taxRtC2": 0,"taxRtC3": 0,"taxRtD": 0,"tlAmt":0.0,"taxRtRvat": 16, "taxRtE": 0,"taxRtF":
10,"taxRtIpl1": 5,"taxRtIpl2": 0,"taxRtTl": 1.5,"taxRtEcm": 5,"taxRtExeeg": 3,"taxRtTot": 0,"taxAmtA": 13.6170,"taxAmtB": 0.0, "taxAmtC1": 0.0,"taxAmtC2": 0.0,"taxAmtC3": 0.0,"taxAmtD":
0.0,"taxAmtRvat":0.0,"taxAmtE": 0.0,"taxAmtF": 0.0,"taxAmtIpl1": 0.0,"taxAmtIpl2": 0.0, "taxAmtTl": 1.1489,"taxAmtEcm": 0.0,"taxAmtExeeg": 0.0,"taxAmtTot": 0.0,"totTaxblAmt":
85.1064,"totTaxAmt":14.8936,"totAmt": 100.00,"prchrAcptcYn": "N", "remark": "","regrId": "admin","regrNm": "admin","modrId": "admin","modrNm": "admin","saleCtyCd": "1","lpoNumber":
"12345678999","currencyTyCd": "ZMW","exchangeRt": "1",
"destnCountryCd": "","dbtRsnCd": "","invcAdjustReason":"","itemList": [{"itemSeq": 1,"itemCd": "20056","itemClsCd": "50102518","itemNm": "Item One", "bcd": "","pkgUnitCd": "BA","pkg":
0.0,"qtyUnitCd": "BE","qty": 1.0,"prc": 100,"splyAmt": 100,"dcRt": 0,"dcAmt": 0.0,"vatCatCd": "A","vatTaxblAmt": 85.1064, "tlTaxblAmt":85.1064,"tlCatCd": "TL","tlAmt":1.2766,"vatAmt": 13.6170,"totAmt":
100}]
}

70
Save Sales Request – Exports
Object ID Object Attribute ID Attribute Description Attribute Name Data Type Required Data Format
Name Length

TrnsSalesSaveWrReq Save Sales tpin Taxpayer’s identification TPIN VARCHAR Y 10

Request number as registered on core
Tax Administration System
TaxOnline
bhfId Taxpayer branch (store) Branch Id VARCHAR Y 3
location identifier
orgIncNo The invoice number being Original Invoice NUMBER Y 38
refered to in the event that Number
you are issueing a credit
note or debit note
cisInvcNo Invoice number as generated CIS Invoice number VARCHAR Y 50
on Taxpayers Certified
invoicing solutions
custTpin Customers taxpayer’s Customer TPIN VARCHAR N 10
identification number as
registered on core Tax
Administration System
TaxOnline
custNm Customers name Customer Name VARCHAR N 60

salesTyCd Code associated with type of Sales Type Code VARCHAR Y 5 See ‘6.7.
sale e.g Normal sales, Copy Transaction Type’
sale
rcptTyCd Type of receipt Receipt Type Code VARCHAR Y 5 See ‘6.8. Sale
Receipt Type’
pmtTyCd The mode of payment used Payment Type VARCHAR N 5 See ‘6.9. Payment
for this transaction Code Method’
salesSttsCd Progress of transaction e.g Invoice/Sale Status VARCHAR Y 5 See ‘6.10.
Approved, Refunded etc Code Transaction
Progress’
cfmDt Date time when invoice was Confirmation Date VARCHAR Y 14 yyyyMMddhhmmss
issued
salesDt Date when sale was made Sales Date VARCHAR Y 8 yyyyMMdd

stockRlsDt Date when the item was Stock Released VARCHAR N 14 yyyyMMddhhmmss
released from the Date
warehouse/branch
cnclReqDt Date time when a Cancell Requested VARCHAR N 14 yyyyMMddhhmmss
cancellation request was Date
made. This is used when one
needs to cancel an invoice

71
cnclDt Date when cancellation was Cancel Date VARCHAR N 14 yyyyMMddhhmmss
approved
rfdDt Date when refund was made Refunded Date VARCHAR N 14 yyyyMMddhhmmss
(null when not a refund)
rfdRsnCd Reason for issuing a Refunded Reason VARCHAR N 5 See ‘6.15. Refund Reason
refund(empty string when Code Code’
not a refund)
totItemCnt Total number of items on Total Item Count NUMBER Y 10
the invoice
taxblAmtA Total tax exclusive amount Taxable Amount A NUMBER Y 18,4
for all line items classified as
Standard Rated for VAT
purposes (Pass 0.0 if not
applicable)
taxblAmtB Total tax exclusive Taxable Amount B NUMBER Y 18,4
amount for all line items
classified as MTV -
Minimum Taxable Value for
VAT purposes (pass 0.0 if
not applicable)
taxblAmtC1 Total tax exclusive amount Taxable Amount NUMBER Y 18.4
for all line items classified C1
as C1 - Exports for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtC2 Total tax exclusive amount Taxable Amount NUMBER Y 18.4
for all line items classified C2
as C2 – Zero rating LPO for
VAT purposes (pass 0.0 if
not applicable)
taxblAmtC3 Total tax exclusive amount Taxable Amount NUMBER Y 18.4
for all line items classified C3
as C3 Zero rated by nature
for VAT purposes (pass 0.0
if not applicable)
taxblAmtD Total tax exclusive amount Taxable Amount D NUMBER Y 18,4
for all line items classified
as D Exempt for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtRvat Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items classified RVAT
as RVAT for VAT purposes
(pass 0.0 if not applicable)
taxblAmtE Total tax exclusive amount Taxable Amount E NUMBER Y 18,4
for all line items classified
as E - Disbursements for

72
 VAT purposes (pass 0.0 if
not applicable)
taxblAmtF Total tax exclusive amount Taxable Amount F NUMBER Y 18,4
for all line items classified
as F for VAT purposes (pass
0.0 if not applicable)
taxblAmtIpl1 Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting IPL
Insurance Premium Levy
(pass 0.0 if not applicable)
taxblAmtIpl2 Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting IPL2
Insurance Premium Levy 2
(pass 0.0 if not applicable)
taxblAmtTl Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting TL
Tourism Levy (pass 0.0 if
not applicable)
taxblAmtEcm Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting ECM
Excise Coal (pass 0.0 if not
applicable)
taxblAmtExeeg Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting EXEEG
Excise Electricity (pass 0.0
if not applicable)
taxblAmtTot Total tax exclusive amount Taxable Amount NUMBER Y 18,4
for all line items attracting TOT
TOT (pass 0.0 if not
applicable)
taxRtA Tax rate VAT Standard Tax Rate A NUMBER Y 7,2
rated category A– As per
standard codes
taxRtB Tax rate for Minimum Tax Rate B NUMBER Y 7,2
Taxable Value – As per
standard codes
taxRtC1 Tax rate for C1- Exports – Tax Rate C1 NUMBER Y 7,2
As per standard codes
taxRtC2 Tax rate for C2 Zero rating Tax Rate C2 NUMBER Y 7,2
LPO – As per standard
codes
taxRtC3 Tax rate for C3 Zero rated Tax Rate C3 NUMBER Y 7,2
by nature – As per standard
codes
taxRtD Tax rate for D Exempt – As Tax Rate D NUMBER Y 7,2
per standard codes

73
taxRtRvat Tax rate for RVAT reverse Tax Rate RVAT NUMBER Y 7,2
VAT – As per standard
codes
taxRtE Tax rate E Disbursements – Tax Rate E NUMBER Y 7,2
As per standard codes
taxRtF Rate for F Service charge – Tax Rate F NUMBER Y 7,2
As per standard codes
taxRtIpl1 Tax rate for Insurance Tax Rate IPL NUMBER Y 7,2
premium levy – As per
standard codes
taxRtIpl2 Tax rate for Insurance Tax Rate IPL2 NUMBER Y 7,2
Premium Levy – As per
standard codes
taxRtTl Tax rate for Tourism Levy – Tax Rate TL NUMBER Y 7,2
As per standard codes
taxRtEcm Tax rate for Excise Coal Tax Rate ECM NUMBER Y 7,2
Mining – As per standard
codes
taxRtExeeg Tax rate Electricity and Tax Rate EXEEG NUMBER Y 7,2
Energy generation – As per
standard codes
taxRtTot Tax rate VAT – As per Tax Rate TOT NUMBER Y 7,2
standard codes
taxAmtA This is the total tax charged Tax Amount A NUMBER Y 18,4
on all VAT category A line
items on invoice (Pass 0.0
when not applicable)
taxAmtB This is the total tax charged Tax Amount B NUMBER Y 18,4
on all VAT category A line
items on invoice (Pass 0.0
when not applicable)
taxAmtC1 This is the total tax charged Tax Amount C1 NUMBER Y 18,4
on all VAT category C1 line
items on invoice (Pass 0.0
when not applicable)
taxAmtC2 This is the total tax charged Tax Amount C2 NUMBER Y 18,4
on all VAT category C2 line
items on invoice (Pass 0.0
when not applicable)
taxAmtC3 This is the total tax charged Tax Amount C3 NUMBER Y 18,4
on all VAT category C3 line
items on invoice (Pass 0.0
when not applicable)
taxAmtD This is the total tax charged Tax Amount D NUMBER Y 18,4
on all VAT category D line
items on invoice (Pass 0.0
when not applicable)

74
taxAmtRvat This is the total tax charged Tax Amount RVAT NUMBER Y 18,4
on all VAT category RVAT
line items on invoice (Pass
0.0 when not applicable)
taxAmtE This is the total tax charged Tax Amount E NUMBER Y 18,4
on all VAT category E line
items on invoice (Pass 0.0
when not applicable)
taxAmtF This is the total tax charged Tax Amount F NUMBER Y 18,4
on all VAT category F
(Service Charge) line items
on invoice (Pass 0.0 when
not applicable)
taxAmtIpl1 This is the total Insurance Tax Amount IPL1 NUMBER Y 18,4
Premium Levy IPL on
invoice (Pass 0.0 when not
applicable)
taxAmtIpl2 This is the total Insurance Tax Amount IPL2 NUMBER Y 18,4
Premium Levy IPL2 (Re-
Insurance) on invoice (Pass
0.0 when not applicable)
taxAmtTl This is the total tax Tourism Tax Amount TL NUMBER Y 18,4
Levy charged on invoice
(Pass 0.0 when not
applicable)
taxAmtEcm This is the total tax charged Tax Amount ECM NUMBER Y 18,4
on all Excise Coal Mining
line items on invoice (Pass
0.0 when not applicable)
taxAmtExeeg This is the total tax charged Tax Amount NUMBER Y 18,4
on all Excise Electricity and EXEEG
Energy generating line items
on invoice (Pass 0.0 when
not applicable)
taxAmtTot This is the total tax charged Tax Amount TOT NUMBER Y 18,4
on all TOT line items on
invoice (Pass 0.0 when not
applicable)
totTaxblAmt This is the total Tax Total TaxlAmt NUMBER Y 18,2
Exclusive Amount for all
line items on invoice
totTaxAmt This is the total tax charged Tot Tax Amount NUMBER Y 18,2
on all line items on invoice
totAmt This is the total Tax Total Amount NUMBER Y 18,2
Inclusive Amount of all
line items on the invoice

75
prchrAcptcYn This specifies whether a Purchase Accepted VARCHAR Y 1
purchase has been accepted Yes or No
or not.
remark This is any comment/remark Remark VARCHAR N 400
on the transaction
regrId This refers to the ID of the Registrant Id VARCHAR Y 20
user of the system adding
the item
regrNm This refers to the username Registrant Name VARCHAR Y 60
of the person making the
sale on the system.
modrId This refers to the ID of the Modifier Id VARCHAR Y 20
user of the system adding
the item
modrNm This refers to the username Modifier Name VARCHAR Y 60
of the person modifying the
sale on the system. (Default
to ADMIN when not
applicable)
saleCtyCd This is the sales category Sales Category VARCHAR Y 2
code. Code
(pass 1)
lpoNumber This is the Local Purchase LPO Number VARCHAR N 50
order number as presented
by the buyer. This will be
validated.
currencyTyCd This is the currency code Currency Type VARCHAR Y 5
used in the transaction – as Code
per standard codes
exchangeRt This is the exchange rate Exchange rate NUMBER Y 18,4
used in the transaction.
destnCountryCd This is the destination Destination Country VARCHAR N 5
country of the item being Code
exported.
dbtRsnCd This is the reason code for Debit Reason Code VARCHAR N 5
issuing a debit.
invcAdjustReason This is the reason for Invoice Adjustment VARCHAR N
adjusting an invoice Reason
itemSeq Item Sequence Number Item Sequence NUMBER Y 11
Number
itemCd This is the item code as Item Code VARCHAR Y 100
defined on your system
itemClsCd This is the UNSCP code Item Classification VARCHAR Y 10
assigned to the item Code
itemNm This is the item name as Item Name VARCHAR Y 200
defined on your system

76
bcd This is the barcode assigned Barcode VARCHAR N 20
to the item
pkgUnitCd This is the packaging unit PackagUnit Code VARCHAR Y 5 See ‘6.4. Packaging Unit’
code assigned to the item as
per standard codes.
pkg This is the number of Package NUMBER Y 13,2
package items being sold.
qtyUnitCd This is the assigned single Quantity Unit Code VARCHAR Y 5 See ‘6.5. Unit of
item unit code assigned to Quantity’
the item as per standard
codes
qty This is the quantity of items Quantity NUMBER Y 13,2
being sold
prc This is the tax exclusive Unit Price NUMBER Y 18,4
price of the item
splyAmt This is the total amount of Supply Amount NUMBER Y 18,4
the supplied item (qty *
prc)
dcRt This is the discount rate on Discount rate NUMBER Y 5,2
line item (Pass 0.0 if not
applicable)
dcAmt This is the discount amount Discount Amount NUMBER Y 18,2
on line item (Pass 0.0 if not
applicable)
isrccCd Insurance Company Code Insurance Company VARCHAR N 10
Code
isrccNm Insurance Company name Insurance Company VARCHAR N 100
name
isrcAmt This is the insurance amount Insurance Amount NUMBER N 18,4
on line item
vatCatCd This represents the tax Vat Category Code VARCHAR Y 5
category code for VAT
purposes on line item
exciseTxCatCd This represents the tax Excise Tax VARCHAR Y 5
category code for Excise on Category Code
line item.
vatTaxblAmt This is the Tax Exclusive VAT Taxable NUMBER Y 18,4
Amount for VAT at line- Amount
item level (Pass 0.0 when
not applicable)
exciseTaxblAmt This is the Tax Exclusive Excise Taxable NUMBER Y 18,4
Amount for Excise at line Amount
item level (Pass 0.0 when
not applicable)
tlTaxblAmt This is the Tax Exclusive Tourism Levy NUMBER Y 18,4
Amount for Tourism Lecy Taxable Amount

77
 at line-item level (Pass 0.0
when not applicable)
iplTaxblAmt This is the Tax Exclusive Insurance Premium NUMBER Y 18,4
Amount for IPL at line-item Levy Taxable
level (Pass 0.0 when not Amount
applicable)
iplAmt This is the insurance Insurance Premium NUMBER Y 18,4
premium levy tax amount Levy Amount
charged on the line item
tlAmt This is the Tourism Levy Tourism Levy NUMBER Y 18,4
amount charged on the line mount
item
(Pass 0.0 when not
applicable)
vatAmt This is the VAT amount VAT Amount NUMBER Y 18,4
charged on the line item
exciseTxAmt This is the excise tax Excise Tax Amount NUMBER Y 18,4
amount charged on the line
item (Pass 0.0 when not
applicable)
totAmt This is the total Tax Total Amount NUMBER Y 18,2
Inclusive Amount of the
line item
JSON REQUEST SAMPLE
{"tpin":"9999999999","bhfId":"000","orgInvcNo":0,"cisInvcNo":"INV001","custTpin":"8888888888","custNm":"SMART
CUSTOMER","salesTyCd":"N","rcptTyCd":"S","pmtTyCd":"01","salesSttsCd":"02","cfmDt":"20240508102010","salesDt":"20240508","stockRlsDt":null,"cnclReqDt":null,"cnclDt":null,"rfdDt":null,"rfdRsnCd":
null,"totItemCnt":4,"taxblAmtA":0,"taxblAmtB":0,"taxblAmtC1":400,"taxblAmtC2":0,"taxblAmtC3":0,"taxblAmtD":0,"taxblAmtRvat":0,"taxblAmtE":0,"taxblAmtF":0,"taxblAmtIpl1":0,"taxblAmtIpl2":0,"taxbl
AmtTl":0,"taxblAmtEcm":0,"taxblAmtExeeg":0,"taxblAmtTot":0,"taxRtA":16,"taxRtB":16,"taxRtC1":0,"taxRtC2":0,"taxRtC3":0,"taxRtD":0,"taxRtRvat":16,"taxRtE":0,"taxRtF":10,"taxRtIpl1":5,"taxRtIpl2":0,"ta
xRtTl":1.5,"taxRtEcm":5,"taxRtExeeg":3,"taxRtTot":0,"taxAmtA":0,"taxAmtB":0,
"taxAmtC1":0,"taxAmtC2":0,"taxAmtC3":0,"taxAmtD":0,"taxAmtRvat":0,"taxAmtE":0,"taxAmtF":0,"taxAmtIpl1":0,"taxAmtIpl2":0,"taxAmtTl":0,"taxAmtEcm":0,"taxAmtExeeg":0,"taxAmtTot":0,"totTaxblAmt
":400,"totTaxAmt":0,"totAmt":400,"prchrAcptcYn":"N","remark":"","regrId":"admin","regrNm":"admin","modrId":"admin","modrNm":"admin","saleCtyCd":"1",”lpoNumber”:null,"currencyTyCd":"ZMW","exch
angeRt":"1","destnCountryCd":"ZM","dbtRsnCd":"","invcAdjustReason":"","itemList":[{"itemSeq":1,"itemCd":"20044","itemClsCd":"50102517","itemNm":"Chicken
nuggets","bcd":"","pkgUnitCd":"BA","pkg":0,"qtyUnitCd":"BE","qty":1,"prc":100,"splyAmt":100,"dcRt":0,"dcAmt":0,"isrccCd":"","isrccNm":"","isrcRt":0,"isrcAmt":0,"vatCatCd":"C1","exciseTxCatCd":null,"va
tTaxblAmt":100,"exciseTaxblAmt":0,"vatAmt":0,"exciseTxAmt":0,"totAmt":100}]}

78
Save Sales Response (All sale types)
Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length Format

TrnsSalesSaveWrRes Save resultCd This is the VSDC response code Result Code VARCHAR 3
Sales
resultMsg This is the VSDC response message Result Message VARCHAR 200
Response
resultDt This is the VSDC response date-time Result DateTime VARCHAR 14
data Response data OBJECT

JSON RESPONSE SAMPLE

{"resultCd": "000","resultMsg": "It is succeeded","resultDt": "20240508194441","data": {"rcptNo": 7,"intrlData": "EDRNWVYKTVBCTS3U2236YMYWNQ","rcptSign":
"KEKNILL3BK6CAH3H","vsdcRcptPbctDate": "20240508194441","sdcId": "SDC0010000553","mrcNo": "WIS00001092","qrCodeUrl":
"https://sandboxportal.zra.org.zm/common/link/ebm/receipt/indexEbmReceiptData?Data=2002572458000KEKNILL3BK6CAH3H"}}

SAVE SALES
• Endpoint: /trnsSales/saveSales
• Request method: POST.
• Requirement: OPTIONAL
• Description: This endpoint facilitates the retrieval of invoice transactions already posted to ZRA.
• Request Parameters: TPIN, Branch ID and CIS Invoice number.
• Response: Returns details of the already uploaded invoice.
• Dependency: success response from the trnsSales/saveSales endpoint and successful upload of invoice to ZRA.
• Note: This request will only return details if an invoice was successfully posted to ZRA. More information about the uploaded invoices is
available on the Portal under Transaction Management.

79
Select Invoice Request
Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length Format

TrnsSalesSaveWrRes Save tpin This is the taxpayer identification number Result Code VARCHAR Y 3
Sales
bhfId This is the branch/store locator of the Result Message VARCHAR Y 3
Response
registered VSDC
cisInvcNo This is the CIS Invoice number previously Result DateTime VARCHAR Y 50
posted
JSON REQUEST SAMPLE

{"resultCd": "000","resultMsg": "It is succeeded","resultDt": "20240508194441","data": {"rcptNo": 7,"intrlData": "EDRNWVYKTVBCTS3U2236YMYWNQ","rcptSign":

"KEKNILL3BK6CAH3H","vsdcRcptPbctDate": "20240508194441","sdcId": "SDC0010000553","mrcNo": "WIS00001092","qrCodeUrl":
"https://sandboxportal.zra.org.zm/common/link/ebm/receipt/indexEbmReceiptData?Data=2002572458000KEKNILL3BK6CAH3H"}}

Select Invoice Response

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length Format

TrnsSalesSelect Select resultCd This is the VSDC response code Result Code VARCHAR 3
Invoice
resultMsg This is the VSDC response message Result Message VARCHAR 200
Response
resultDt This is the VSDC response date-time Result DateTime VARCHAR 14
data Response data OBJECT
JSON RESPONSE SAMPLE

{"resultCd":"000","resultMsg":"It is
succeeded","resultDt":"20240603074526","data":{"cisInvcNo":"5589","rcptNo":27,"intrlData":"QWYJKVB5J2RXUMQPXIJG2RQJYE","rcptSign":"IKD6GWL3FHB7OMSH","vsdcRcptPbctDate":"2024-06-03
07:34:17","sdcId":"SDC0010000489","mrcNo":"WIS00001031","qrCodeUrl":"https://sandboxportal.zra.org.zm/common/link/ebm/receipt/indexEbmReceiptData?Data=1000000668000IKD6GWL3FHB7OMSH"}}

80
 5.10. Purchase Information
The Purchases API facilitates the transmission of detailed purchase data from a third-party system to Smart Invoice. This data includes specific
details associated with each purchase, such as supplier information, invoice number, item information and the date/time of the transaction.
Developers can use this API to seamlessly transfer purchase information, ensuring accurate invoicing and efficient management of supplier
transactions.
GET PURCHASES

• Endpoint: /trnsPurchase/selectTrnsPurchaseSales
• Request method: POST.
• Requirement: MANDATORY
• Description: Retrieve all purchases made by a business when they are supplied by another business using Smart Invoice.
• Request Parameters: TPIN, Branch ID, and Last Request Date
• Response: Returns a list of purchases with their details including item names, description, price recorded in Smart Invoice.

ERP VSDC API

Retrieves purchase data from Smart

Get Purchases POST /trnsPurchase/selectTrnsPurchaseSales
Invoice and stores it in ERP

Select Purchases Request

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length

TrnsPurchaseSalesReq Search tpin Taxpayer’s identification number as registered on core Tax TPIN VARCHAR Y 10
Purchase/Sales Administration System TaxOnline
Request bhfId Taxpayer branch (store) location identifier Branch ID VARCHAR Y 3

lastReqDt This is the date depicting the last time an endpoint was called. Last Request Date VARCHAR Y 14
By default, this defaults to 20160523000000
JSON REQUEST SAMPLE

Request Body {"tpin": "9999999999","bhfId": "000","lastReqDt":"20231215000000"}

81
Select Purchases Response
Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Data Length Format

TrnsPurchaseSalesRes Search resultCd This is the VSDC response code Result Code VARCHAR 3
Purchase/Sales
Response resultMsg This is the VSDC response Result Message VARCHAR 200
message
resultDt This is the VSDC response date- Result Date Time VARCHAR 14 yyyyMMddhhmmss
time
spplrTpin This is the TPIN of the supplier Supplier TPIN VARCHAR 10

spplrNm This is the name of the supplier Supplier Name VARCHAR 60

spplrBhfId This is the registered branch of the Supplier Branch Id VARCHAR 3

supplier, as recorded on Smart
Invoice. (Note: This is provided by
supplier if they are Smart Invoice
registered, otherwise can be left
blank)
spplrInvcNo This represents the invoice number Supplier Invoice Number NUMBER 38
provided by the supplier
rcptTyCd This represents the type of sale of Receipt Type Code VARCHAR 5 See ‘6.8. Sale
the transaction i.e. Sale or Refund Receipt Type’
after Sale
pmtTyCd This is the mode/method of Payment Type Code VARCHAR 5 See 6.9. Payment
payment used in the transaction Method
cfmDt This is the date on which the Confirmed Date VARCHAR 14 yyyyMMddhhmmss
purchase was approved/confirmed
salesDt This is the date on which the sale Sales Date VARCHAR 8 yyyyMMdd
was made
stockRlsDt This is the date on which items Stock Release Date VARCHAR 14 yyyyMMddhhmmss
were released from
warehouse/branch for sale
totItemCnt This is the total number of line Total Item Count NUMBER 10
items on invoice
totTaxblAmt This is the total Tax Exclusive Total Taxable Amount NUMBER 18,4
Amount for all line items on
invoice
totTaxAmt This is the total tax charged on all Total Tax Amount NUMBER 18,2
line items on invoice
totAmt This is the total Tax Inclusive Total Amount NUMBER 18,2
Amount of all line items on the
invoice
remark This is an additional comment Remark VARCHAR 400
section/field for remarks

82
itemSeq This is the line item sequence Item Sequence NUMBER 4
number
itemCd This is the item code identifier of Item Code VARCHAR 100
the item
itemClsCd This is the classification code of Item Classification Code 10
the item
itemNm This is the name of the item being Item Name VARCHAR 200
supplied
bcd This is the Barcode assigned to line Barcode VARCHAR 20
item
pkgUnitCd This is the packaging unit code Package Unit Code VARCHAR 5 See ‘6.4. Packaging Unit’
assigned to the item as per standard
codes.
pkg This is the number of package Package NUMBER 13,2
items being sold.
qtyUnitCd This is the assigned single item Quantity Unit Code VARCHAR 5 See ‘6.5. Unit of
unit of measure code assigned to Quantity’
the item as per standard codes
qty This is the quantity of the line Quantity NUMBER 13,2
items
prc This is the unit price of the item Price NUMBER 18,4

splyAmt This is the total amount of the Supply Amount NUMBER 18,4
items or services provided by the
seller to the buyer (qty * prc)
dcRt This is the discount rate Discount Rate NUMBER 5,2

dcAmt This is the total discount amount Discount Amount NUMBER 18,2
applied on the invoice if
applicable
vatCatCd This represents the tax category VAT Category Code VARCHAR 5 See ‘6.1. Tax Type’
code for VAT purposes.
iplCatCd This represents the tax category for IPL Category Code VARCHAR 5 See ‘6.1. Tax Type’
IPL purposes e.g. “IPL”
tlCatCd This represents the tax category for TL Category Code VARCHAR 5 See ‘6.1. Tax Type’
TL purposes e.g.”TL”
exciseTxCatC This represents the tax category for Excise Tax Category Code VARCHAR 5 See ‘6.1. Tax Type’
Excise purposes e.g. “ECM” or
“EXEEG”
vatTaxblAmt This is the tax exclusive amount for VAT Taxable Amount NUMBER 18,4
a line item classified as VAT
exciseTaxblAmt This is the tax exclusive amount for Excise Table Amount NUMBER 18,4
a line item classified as Excise
iplTaxblAmt This is the tax exclusive amount IPL Taxable Amount NUMBER 18,4
for a line item classified as IPL
tlTaxblAmt This is the tax exclusive amount TL Taxable Amount NUMBER 18,4
for a line item classified as TL

83
 taxblAmt This is the Total tax exclusive Taxable Amount NUMBER 18,4
amount for the line item
vatAmt This represents the tax charged VAT Amount NUMBER 18,4
specifically to VAT line items
iplAmt This represents the tax charged IPL Amount NUMBER 18,4
specifically to IPL line items
tlAmt This represents the tax charged TL Amount NUMBER 18,4
specifically to TL line items
exciseTxAmt This represents the tax charged Excise Tax Amount NUMBER 18,4
specifically to Excise line items
totAmt This is the total Tax Inclusive Total Amount NUMBER 18,2
Amount of the line item
JSON RESPONSE SAMPLE

{"resultCd":"000","resultMsg":"It is succeeded","resultDt":"20240510103403","data":{"saleList":[{"spplrTpin":"9999999999","spplrNm":"SMART
SUPPLIER","spplrBhfId":"000","spplrInvcNo":45,"rcptTyCd":"S","pmtTyCd":"01","cfmDt":"2024-05-08
10:20:10","salesDt":"20240502","stockRlsDt":null,"totItemCnt":1,"totTaxblAmt":86.2069,"totTaxAmt":13.7931,"totAmt":100,"remark":null,"itemList":[{"itemSeq":1,"itemCd":"20044","itemClsCd":"50102517","ite
mNm":"ChickenWings","bcd":null,"pkgUnitCd":"BA","pkg":0,"qtyUnitCd":"BE","qty":1,"prc":100,"splyAmt":100,"dcRt":0,"dcAmt":0,"vatCatCd":"A","iplCatCd":null,"tlCatCd":null,"exciseTxCatCd":null,"vatTax
blAmt":86.21,"exciseTaxblAmt":0,"iplTaxblAmt":0,"tlTaxblAmt":0,"taxblAmt":86.21,"vatAmt":13.79,"iplAmt":0,"tlAmt":0,"exciseTxAmt":0,"totAmt":100}]}]}}

SAVE PURCHASES

• Endpoints: /trnsPurchase/savePurchase
• Request method: POST.
• Requirement: MANDATORY
• Description: This endpoint is utilized to approve or reject all purchases made by a business from suppliers.
• Request Parameters: Purchase data including supplier information, purchase type code, purchase status code, item information, etc.
• Response: Returns the success or failure of the purchase data submission.
• Dependency: Upon approval of a purchase, you must call the "Save Stock Items" endpoint to add the approved purchases as stock items.
Subsequently, call the “Stock Master” endpoint to update the existing stock quantities for any items that were already present in your
inventory reflecting the additional approved purchases. This process ensures that approved purchases are accurately reflected in the
overall stock inventory.

84
 ERP VSDC API

Retrieves purchase data from Smart

Get Purchases POST /trnsPurchase/selectTrnsPurchaseSales
Invoice and stores it in ERP

Save Purchase POST /trnsPurchase/savePurchase Purchase item status updated

Update Smart Invoice with the approved

Save Stock Items POST /stock/saveStockItems
purchase item.

Updates stock quantities related to

Save Stock Master POST /stockMaster/saveStockMaster
purchased items within Smart Invoice

Save Purchase Request

Object ID Object Attribute ID Attribute Description Attribute Name Data Type Required Data Format
Name Length

TrnsPurchaseSalesReq Save Purchase tpin Taxpayer’s identification VARCHAR Y 10

Request number as registered on core
TPIN
Tax Administration System
TaxOnline
bhfId Taxpayer branch (store) VARCHAR Y 3
Branch ID
location identifier
invcNo Invoice number as generated NUMBER Y 38
Invoice Number
on the VSDC
orgInvcNo The invoice number being Original Invoice NUMBER N 38
referred to. Number
spplrTpin Taxpayer’s identification Supplier TPIN VARCHAR N 10
number as registered on core
Tax Administration System
TaxOnline

85
spplrBhfId Supplier branch (store) VARCHAR N 2
Supplier Branch ID
location identifier
spplrNm Supplier Trading Name VARCHAR N 60
Supplier Name
spplrInvcNo Invoice number as generated NUMBER N 38
Supplier Invoice
on suppliers Certified
Number
invoicing solutions
regTyCd Type of registration Registration Type VARCHAR Y 5 See ‘6.11. Registration
Code Type’
pchsTyCd Type of purchase VARCHAR Y 5 See ‘6.7. Transaction
Purchase Type Code
Type’
rcptTyCd Type of receipt VARCHAR Y 5 See ‘6.12. Purchase
Receipt Type Code
Receipt Type’
pmtTyCd The mode of payment used for VARCHAR Y 5 See ‘6.9. Payment
Payment Type Code
this transaction Method’
pchsSttsCd Purchase status code VARCHAR Y 5 See ‘6.10. Transaction
Purchase Status Code
Progress’
pchsDt Date of purchase VARCHAR Y 8 yyyyMMdd
Purchase Date
cnclReqDt Cancelation request date VARCHAR N 14 yyyyMMddhhmmss
Cancel Requested Date
cnclDt Cancel date VARCHAR N 14 yyyyMMddhhmmss
Canceled Date
totItemCnt Total number of items on the NUMBER Y 10
Total Item Count
invoice
totTaxblAmt Total taxable amount NUMBER Y 18,2
Total Taxable Amount
totTaxAmt Total tax amount NUMBER Y 18,2
Total Tax Amount
totAmt Total amount NUMBER Y 18,2
Total tax amount
itemSeq Item Sequence Number Item Sequence Number NUMBER Y 3

itemCd This is the item code as Item Code VARCHAR N 100

defined on your system
itemClsCd This is the UNSCP code Item Classification VARCHAR Y 10
assigned to the item Code
itemNm This is the item name as Item Name VARCHAR Y 200
defined on your system
bcd This is the barcode assigned to Barcode VARCHAR N 20
the item
spplrItemClsCd This is the supplier UNSCP Supplier Item VARCHAR N 10
code assigned to the item Classification Code
spplrItemCd This is the supplier item code Supplier Item Code VARCHAR N 20
as defined on your system
spplrItemNm This is the supplier item name Supplier Item Name VARCHAR N 200
as defined on your system

86
pkgUnitCd This is the packaging unit Packaging Unit Code VARCHAR N 5 See ‘6.4. Packaging
code assigned to the item as Unit’
per standard codes.
pkg This is the number of package Package NUMBER Y 13,2
items being sold.
qtyUnitCd This is the assigned single Quantity Unit Code VARCHAR Y 5 See ‘6.5. Unit of
item unit code assigned to the Quantity’
item as per standard codes
qty This is the quantity of items Quantity NUMBER Y 13,2
being sold
prc This is the tax exclusive price Unit Price NUMBER Y 18,2
of the item
splyAmt This is the total amount of the Supply Price NUMBER Y 18,2
supplied item (qty * prc)
dcRt This is the discount rate on the Discount Rate NUMBER Y 5,2
line item (Pass 0.0 if not
applicable)
dcAmt This is the discount amount on Discount Amount NUMBER Y 18,2
the line item (Pass 0.0 if not
applicable)
iplCatCd This represents the tax category IPL Category Code VARCHAR Y 5
code for IPL purposes on the
line item
tlCatCd This represents the tax category TL Category Code VARCHAR Y 5
code for TL purposes on the
line item
exciseCatCd This represents the tax category EXCISE Category VARCHAR Y 5
code for EXCISE purposes on Code
line item
taxblAmt This is the Tax Exclusive VAT Taxable Amount NUMBER Y 18,2
Amount for VAT at line item
level (Pass 0.0 when not
applicable)
vatCatCd This represents the tax category VAT Category Code VARCHAR Y 5
code for VAT purposes on line
item
iplTaxblAmt This is the Tax Exclusive IPL Taxable Amount NUMBER Y 18,2
Amount for IPL at line item
level (Pass 0.0 when not
applicable)
tlTaxblAmt This is the Tax Exclusive TL Taxable Amount NUMBER Y 18,2
Amount for TL at line item
level (Pass 0.0 when not
applicable)
exciseTaxblAmt This is the Tax Exclusive EXCISE Taxable NUMBER Y 18,2
Amount for EXCISE at line Amount

87
 item level (Pass 0.0 when not
applicable)
taxAmt This is the VAT amount VAT Tax Amount NUMBER Y 18,2
charged on the line item
iplAmt This is the IPL amount charged IPL Tax Amount NUMBER Y 18,2
on the line item
tlAmt This is the TL amount charged TL Tax Amount NUMBER Y 18,2
on the line item
exciseTxAmt This is the EXCISE amount EXCISE Tax Amount NUMBER Y 18,2
charged on the line item
totAmt This is the total Tax Inclusive Total Amount NUMBER Y 18,2
Amount of the line item

JSON REQUEST SAMPLE

{"tpin":"9999999999","bhfId":"000","invcNo":1,"orgInvcNo": 0,"spplrTpin":"9999999990","spplrBhfId":"000","spplrNm":"Supplier Name
1","spplrInvcNo":"INV0001","regTyCd":"M","pchsTyCd":"N","rcptTyCd":"P","pmtTyCd":"01","pchsSttsCd":"02","cfmDt":"20240509210300","pchsDt":"20240509","cnclReqDt":"","cnclDt":"","totItemCnt":1,"t
otTaxblAmt":86.2069,"totTaxAmt":13.7931,"totAmt":100,"remark":"remarks","regrNm":"ADMIN","regrId":"ADMIN","modrNm":"ADMIN","modrId":"ADMIN","itemList":[{"itemSeq":1,"itemCd":"ZM2BGK
G0000001","itemClsCd":"50102517","itemNm":"Item Name
1","bcd":null,"pkgUnitCd":"BG","pkg":0,"qtyUnitCd":"KG","qty":1,"prc":100,"splyAmt":100,"dcRt":0,"dcAmt":0,"taxTyCd":"A","iplCatCd":null,"tlCatCd":null,"exciseCatCd":null,"taxblAmt":86.21,"vatCatCd":
"A","iplTaxblAmt":null,"tlTaxblAmt":null,"exciseTaxblAmt":null,"taxAmt":13.79,"iplAmt":null,"tlAmt":null,"exciseTxAmt":null,"totAmt":100}]}

Save Purchase Response

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Data Length

TrnsPurchaseSaveRes Save Purchase Response resultCd This is the VSDC response code Result Code VARCHAR 3
resultMsg This is the VSDC response message Result Message VARCHAR 200
resultDt This is the response date Result Date VARCHAR 14

JSON RESPONSE SAMPLE

{"resultCd":"000","resultMsg":"It is succeeded","resultDt":”20231120193115","data”: null}

88
 5.11. Stock Information
The Stock API allows businesses to manage and maintain accurate inventory levels within the Smart Invoice system. It provides endpoints to
perform various stock-related operations, ensuring seamless integration and synchronization of stock data between third-party systems and Smart
Invoice.
Through this API, businesses can retrieve comprehensive stock information, including item details, quantities, and associated metadata. Developers
can leverage the Stock API to retrieve stock levels, update stock quantities, and manage stock movements across multiple branches or locations.
GET STOCK ITEMS

• Endpoint: /stock/selectStockItems
• Request method: POST.
• Requirement: OPTIONAL
• Description: Retrieves stock information for all items, including quantities, item details, branch-level stock, etc.
• Request Parameters: TPIN, Branch Id, Last Request Date.
• Response: Returns a list of stock items recorded on Smart Invoice.

89
Select Stock Items Request
Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length

StockMoveReq Select Stock tpin Taxpayer’s identification number as registered on core Tax TPIN VARCHAR Y 10
Items Administration System TaxOnline
Request bhfId Taxpayer branch (store) location identifier Branch ID VARCHAR Y 3

lastReqDt This is the date depicting the last time an endpoint was called. By Last Request Date VARCHAR Y 14
default, this defaults to 20160523000000
JSON REQUEST SAMPLE

Request Body {"tpin": "9999999999","bhfId": "000","lastReqDt":"20231215000000"}

Select Stock Items Response

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Data Length Format

ImptItemSaveRes Update Item Response resultCd This is the VSDC response code Recult code VARCHAR 10
resultMsg This is the response message Result message VARCHAR 200
resultDt This is the VSDC response date Result date VARCHAR 14

custTpin This is the taxpayer TPIN Taxpayer TPIN VARCHAR 10

custBhfId This is the taxpayer branch Taxpayer branch id VARCHAR 3

sarNo Stock Accounting Record Number, Stored and released Number NUMBER 38
for the stock transaction or record.
ocrnDt This is the occurrence date Occurrence date VARCHAR 14

totItemCnt The total number of items included Total Item Count

NUMBER 10
in the stock transaction or record.
totTaxbltAmt This is the total taxable amount Taxable amount VARCHAR (18,4) See ‘6.17. Import
Item status’
totTaxAmt This is the total tax amount Total tax amount VARCHAR (18,4)

totAmt This is the total amount Total amount NUMBER (18,2)

remark This is the comment on the item Remark VARCHAR 20

itemSeq This is the item sequence Item sequence NUMBER 10

90
 itemCd This is the item code Item code VARCHAR 100

itemClsCd This is the item classification code Item class code VARCHAR 10

itemNm This is the item name Item name VARCHAR 100

pkgUnitCd This is the packaging unit code Package unit code VARCHAR 5

qty This is the quantity Quantity NUMBER (18,2)

prc This is the price Price NUMBER (18,2)

splyAmt This is the supply amount Supply amount NUMBER (18,2)

taxblAmt This is the taxable amount Taxable amount NUMBER (18,4)

vatCatCd This is the VAT category code Vat category code VARCHAR 5

vatAmt This is the VAT amount Vat amount NUMBER (18,4)

totAmt This is the total amount Total amount NUMBER (18,2)

JSON REQUEST SAMPLE

{"tpin": "9999999999","bhfId": "000","taskCd": "4561614","dclDe": "20240426","importItemList": [{"itemSeq": 2,"hsCd": "72149900000","itemClsCd": "5022110801","itemCd":

"RW1NTXU0000006","imptItemSttsCd": "3","remark": "remark","modrNm": "Admin","modrId": "Admin"}, {"itemSeq": 3,"hsCd": "04051000000","itemClsCd": "5022110802","itemCd":
"RW1NTXU0000007","imptItemSttsCd": "4","remark": "another remark","modrNm": "Admin2","modrId": "Admin2"}]}

SAVE STOCK ITEM

• Endpoint: /stock/saveStockItems
• Request method: POST.
• Requirement: MANDATORY
• Description: This endpoint is used to add stock items that have been recorded from approved purchases, imports, sales, and different
types of stock movement adjustments, such as interbranch transfers, to Smart Invoice.
• Request Parameters: Stock Item data including item details such as quantities, adjustment reasons, total stock amount, etc.
• Response: Returns the success or failure of the save stock item operation.
• Dependency: subsequent call to saveStockMaster should be made after this endpoint is called.

91
 Save Stock Items Update Smart Invoice with the stock item
POST /stock/saveStockItems
data

Save Stock Items Request

Object ID Object Name Attribute ID Attribute Attribute Name Data Type Required Data Length Format
Description

StockIOSaveRes Save Stock In/Out tpin Taxpayer TPIN

Req Identification
Number, identifying
VARCHAR Y 10
the taxpayer or entity
associated with the
stock.
bhfId This is the branch Branch ID
(store) location
VARCHAR Y 3
identifier. Supplied by
ZRA
sarNo Stock Accounting Stored and released
Record Number, for Number
NUMBER Y 38
the stock transaction
or record.
orgSarNo Original Stock Original Stored and
Accounting Record released Number
Number, indicating NUMBER Y 38
changes or updates to
the stock record.
regTyCd Registration Type Registration Type
Code, specifying the Code
VARCHAR Y 5
type of registration
related to the stock.
custTpin The taxpayer Customer TPIN
associated with the VARCHAR N 10
transaction
custNm The taxpayer sname Customer Name
of the recipient of the VARCHAR N 100
stock.

92
custBhfId The branch (store) Customer BHF ID See ‘6.14. Stock In/Out Type’
identifier of the VARCHAR N 2
location
sarTyCd Stock Accounting Stored and released
Record Type Code, Type Code
specifying the type or VARCHAR Y 5
category of the stock
record.
ocrnDt The date when the Occurred Date time
stock transaction or VARCHAR Y 8
record occurred.
totItemCnt The total number of Total Item Count
items included in the
NUMBER Y 10
stock transaction or
record.
totTaxblAmt The total amount of Total Supply Price
the stock transaction
NUMBER Y 18,4
or record subject to
taxation.
totTaxAmt The total amount of Total VAT
tax associated with
NUMBER Y 18,4
the stock transaction
or record.
totAmt The overall total Total Amount
amount of the stock
transaction or record, NUMBER Y 18,4
including taxes and
charges.
remark Remarks or notes Remark
associated with the
VARCHAR N 400
stock transaction or
record.
regrId The identifier of the Registrant Name
individual who
VARCHAR Y 60
registered or recorded
the stock transaction.
regrNm The name of the Registrant ID
individual who
VARCHAR Y 20
registered or recorded
the stock transaction.
modrNm The name of the Modifier Name
individual who
VARCHAR Y 60
modified or updated
the stock transaction.
modrId The identifier of the Modifier ID
VARCHAR Y 20
individual who

93
 modified or updated
the stock transaction.
itemSeq Item Sequence Item Sequence
NUMBER Y 3
Number
itemCd This is the item code Item Code
as defined on your VARCHAR N 100
system
itemClsCd This is the UNSCP Item Class Code
code assigned to the VARCHAR Y 10
item
itemNm This is the item name Item Name
as defined on your VARCHAR Y 200
system
This is the Barcode Barcode
bcd VARCHAR N 20
assigned to line item
This is the packaging Package unit code See ‘6.4. Packaging Unit Code’
unit code assigned to
pkgUnitCd VARCHAR Y 5
the item as per
standard codes.
This is the number of Package Quantity
pkg package items being NUMBER Y 13,2
sold.
This is the assigned Unit Quantity Code See ‘6.5. Unit of Measure
single item unit of
qtyUnitCd measure code VARCHAR Y 5
assigned to the item
as per standard codes
This is the quantity of Unit Quantity
qty
the line items
itemExprDt This is the expiry date Item Expired Date yyyyMMdd
NUMBER Y 13,2
of the item
This is the unit price Unit Price
prc VARCHAR N 8
of the item
splyAmt This is the total Supply Amount
amount of the items
or services provided NUMBER Y 15,2
by the seller to the
buyer (qty * prc)
totDcAmt This is the total Discount Amount
discount amount NUMBER Y 18,4
applied on an invoice
iplCatCd This represents the tax IPL Category Code
category for IPL VARCHAR Y 5
purposes e.g. “IPL”
tlCatCd This represents the tax TL Category Code
category for TL VARCHAR Y 5
purposes e.g.”TL”

94
 exciseTxCatC This represents the tax Excise Category
category for Excise Code
VARCHAR Y 5
purposes e.g. “ECM”
or “EXEEG”
taxblAmt This is the Total tax Taxable Amount
exclusive amount for NUMBER Y 18,4
the line item
This represents the tax VAT Category
vatCatCd category code for VAT Code VARCHAR Y 5
purposes.
taxAmt This is the VAT tax Total Tax Amount
NUMBER Y 18,4
amount of the item
iplAmt This is the IPL tax IPL Amount
NUMBER Y 18,4
amount
tlAmt This is the TL tax TL Amount
NUMBER Y 18,4
amount
exciseTxAmt This is the excise tax Excise Amount
NUMBER Y 18,4
amount
totAmt This is the total amount Total Amount
NUMBER Y 18,4
JSON REQUEST SAMPLE
{
"tpin": "9999999999", "bhfId": "000", "sarNo": 1, "orgSarNo": 0, "regTyCd": "M", "custTpin": null, "custNm": null, "custBhfId": null, "sarTyCd": "02", "ocrnDt": "20240509",
"totItemCnt": 1, "totTaxblAmt": 86.2069, "totTaxAmt": 13.7931, "totAmt": 100, "remark": null, "regrId": "Admin", "regrNm": "Admin", "modrNm": "Admin", "modrId": "Admin",
"itemList": [
{"itemSeq": 1, "itemCd": "20044", "itemClsCd": "50102517", "itemNm": "Soupu dedede", "pkgUnitCd": "BA", "qtyUnitCd": "BE", "qty": 1, "prc": 100, "splyAmt": 100, "taxblAmt": 86.21,
"vatCatCd": "A", "taxAmt": 13.79, "totAmt": 100}
]
}

Save Stock Items Response

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Data Length

StockIOSaveRes Save Stock In/Out Response resultCd This is the VSDC response code Result Code VARCHAR 3
resultMsg This is the response message Result Message VARCHAR 200
resultDt This is the response date Result Date VARCHAR 14

JSON RESPONSE SAMPLE

95
 {"resultCd":"000","resultMsg":"It is succeeded","resultDt":”20231120193115","data”: null}

SAVE STOCK MASTER

• Endpoint: /stockMaster/saveStockMaster
• Requirement: MANDATORY
• Description: This endpoint is used to update stock quantities for items that have been recorded from approved purchases, imports, sales,
and different types of stock movement adjustments.
• Request Parameters: Stock Item data including branch code, item code, remaining stock quantity after adjustment, etc.
• Response: Returns the success or failure of the stock adjustment operation.

Updates stock quantities related to sales

Save Stock Master POST /stockMaster/saveStockMaster
within Smart Invoice
Save Stock Master Request
Attribute Description
Object ID Object Name Attribute ID Attribute Name Data Type Required Data Length Format

This is the taxpayer’s identification

tpin TPIN VARCHAR Y 10
number
This is the branch/store identifier.
bhfId It is supplied by ZRA at Branch ID VARCHAR Y 3
registration of device
This is the username of the system
regrNm Registrant Name VARCHAR Y 60
user saving to stock master
This is the user ID of the system
regrId Registrant ID VARCHAR Y 20
Save Stock user saving to stock master
StockMstSaveReq
Master Request This is the username of the system
modrNm Modifier Name VARCHAR Y 60
user modifying stock master
This is the user ID of the system
modrId Modifier ID VARCHAR Y 20
user modifying stock master
This is the item code of the stock
itemCd Item Code VARCHAR Y 100
item being saved/modified
This is the remaining quantity of
rsdQty the stock item being Remain Quantity NUMBER Y 13,4
saved/modified
JSON REQUEST SAMPLE

96
 {"tpin":"9999999999","bhfId":"000","regrId":"Admin","regrNm":"Admin","modrNm":"Admin","modrId":"Admin","stockItemList":[{"itemCd":"P10007","rsdQty":34},{"itemCd":"P10005","rsdQty":34},{"itemC
d":"P10006","rsdQty":34}]}

Save Stock Master Response

Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Data Length

StockMstSaveRes Save Stock Master Response resultCd This is the VSDC response code Result Code VARCHAR 3
resultMsg This is the response message Result Message VARCHAR 200
resultDt This is the response date Result Date VARCHAR 14

JSON RESPONSE SAMPLE

{"resultCd":"000","resultMsg":"It is succeeded","resultDt":”20231120193115","data”: null}

97
6. Code Definition
6.1. Tax Type
Code Classification Code Classification Name
04 Tax Type
Code Sort Code Name Code Description remark
Order
Category applies to products and services which attract VAT at
VAT A 1 Standard Rated 16%
16% by nature
Minimum Taxable Value (MTV) 16% is charged on the Retail Price recommended by manufacturer
B 2
of MTV goods.
C1 3 Exports 0% Applies to exports
Zero-rating Local
Applies to transactions involving customers or projects granted
C2 4 Purchases Order
exemption from paying taxes
transactions 0%
Category applies to products and services which do not attract
C3 5 Zero-rated by nature 0%
VAT at 16% by nature.
The category applies to specific class of products and services
D 6 Exempt No tax charge
exempted from VAT
Applies to transactions involving imported services. (For both
E 7 Reverse VAT
Appointed Tax Agent and Self-invoicing).
Applies to expenses incurred by suppliers on behalf of customers
RVAT 8 Disbursement
while supplying a product or service.
Applies to the hospitality industry and computed on a total net
Insurance IPL1 9 Insurance Premium Levy
transaction amount. Applies to all classes of insurance except re-
Premium Levy
insurance.
IPL2 10 Re-Insurance
Applies only to re-insurance.
Tourism levy TL 11 Tourism Levy
Applies to accommodation and conference facilities.
F 15 Service Charge 10%
Applies to services rendered
Excise ECM 12 Excise on Coal
The tax rate is charged per ton
EXEEG 13 Excise Electricity
The tax rate is charged per 100kwh
Direct tax – tax amount does not reflect on an invoice. For
Turnover Tax TOT 14 No tax charge
purposes of accounting for turnover relating to taxpayers not
registered for VAT.

6.2. Product Type

Code Classification Code Classification Name
24 Product Type
Code Sort Order Code Name Code Description remark

1 1 Raw Material Raw Material

2 2 Finished Product Finished Product
3 3 Service Service without stock

6.3. Countries code

Code Classification Code Classification Name

05 Nation
Code Sort Order Code Name Code Description remark

AC 1 ASCENSION ISLAND ASCENSION ISLAND

AD 2 ANDOZRA ANDOZRA
UNITED ARAB
AE 3 UNITED ARAB EMIRATES
EMIRATES
ANTIGUA AND
AG 4 ANTIGUA AND BARBUDA
BARBUDA
AI 5 ANGUILLA ANGUILLA
AL 6 ALBANIA ALBANIA

98
AM 7 ARMENIA ARMENIA
NETHERLANDS
AN 8 NETHERLANDS ANTILLES
ANTILLES
AO 9 ANGOLA ANGOLA
AQ 10 ANTARCTICA ANTARCTICA
AR 11 ARGENTINA ARGENTINA
AS 12 AMERICAN SAMOA AMERICAN SAMOA

99
Code Classification Code Classification Name

05 Nation
Code Sort Order Code Name Code Description remark

AT 13 AUSTRIA AUSTRIA
AU 14 AUSTRALIA AUSTRALIA
AW 15 ARUBA ARUBA
AX 16 ALAND ISLANDS ALAND ISLANDS
AZ 17 AZERBAIJAN AZERBAIJAN
BOSNIA AND
BA 18 BOSNIA AND HERZEGOVINA
HERZEGOVINA
BB 19 BARBADOS BARBADOS
BD 20 BANGLADESH BANGLADESH
BE 21 BELGIUM BELGIUM
BF 22 BURKINA FASO BURKINA FASO
BG 23 BULGARIA BULGARIA
BH 24 BAHRAIN BAHRAIN
BI 25 BURUNDI BURUNDI
BJ 26 BENIN BENIN
BM 27 BERMUDA BERMUDA
BRUNEI
BN 28 BRUNEI DARUSSALAM
DARUSSALAM
BO 29 BOLIVIA BOLIVIA
BR 30 BRAZIL BRAZIL
BS 31 BAHAMAS BAHAMAS
BT 32 BHUTAN BHUTAN
BV 33 BOUVET ISLAND BOUVET ISLAND
BW 34 BOTSWANA BOTSWANA
BY 35 BELARUS BELARUS
BZ 36 BELIZE BELIZE
CA 37 CANADA CANADA
COCOS (KEELING)
CC 38 COCOS (KEELING) ISLANDS
ISLANDS
CONGO,
CD 39 DEMOCRATIC CONGO, DEMOCRATIC REPUBLIC
REPUBLIC
CENTRAL AFRICAN
CF 40 CENTRAL AFRICAN REPUBLIC
REPUBLIC
CG 41 CONGO CONGO
CH 42 SWITZERLAND SWITZERLAND
COTE D'IVOIRE
CI 43 COTE D'IVOIRE (IVORY COAST)
(IVORY COAST)
CK 44 COOK ISLANDS COOK ISLANDS
CL 45 CHILE CHILE
CM 46 CAMEROON CAMEROON
CN 47 CHINA CHINA
CO 48 COLOMBIA COLOMBIA
CR 49 COSTA RICA COSTA RICA
CZECHOSLOVAKIA
CS 50 CZECHOSLOVAKIA (FORMER)
(FORMER)
CU 51 CUBA CUBA
CV 52 CAPE VERDE CAPE VERDE
CX 53 CHRISTMAS ISLAND CHRISTMAS ISLAND

100
CY 54 CYPRUS CYPRUS
CZ 55 CZECH REPUBLIC CZECH REPUBLIC

Code Classification Code Classification Name

05 Nation
Code Sort Order Code Name Code Description remark

DE 56 GERMANY GERMANY
DJ 57 DJIBOUTI DJIBOUTI
DK 58 DENMARK DENMARK
DM 59 DOMINICA DOMINICA
DOMINICAN
DO 60 DOMINICAN REPUBLIC
REPUBLIC
DZ 61 ALGERIA ALGERIA
EC 62 ECUADOR ECUADOR
EE 63 ESTONIA ESTONIA
EG 64 EGYPT EGYPT
EH 65 WESTERN SAHARA WESTERN SAHARA
ER 66 ERITREA ERITREA
ES 67 SPAIN SPAIN
ET 68 ETHIOPIA ETHIOPIA
EU 69 EUROPEAN UNION EUROPEAN UNION
FI 70 FINLAND FINLAND
FJ 71 FIJI FIJI
FALKLAND ISLANDS
FK 72 FALKLAND ISLANDS (MALVINAS)
(MALVINAS)
FM 73 MICRONESIA MICRONESIA
FO 74 FAROE ISLANDS FAROE ISLANDS
FR 75 FRANCE FRANCE
FRANCE,
FX 76 FRANCE, METROPOLITAN
METROPOLITAN
GA 77 GABON GABON
GB 78 GREAT BRITAIN (UK) GREAT BRITAIN (UK)
GD 79 GRENADA GRENADA
GE 80 GEORGIA GEORGIA
GF 81 FRENCH GUIANA FRENCH GUIANA
GG 82 GUERNSEY GUERNSEY
GH 83 GHANA GHANA
GI 84 GIBRALTAR GIBRALTAR
GL 85 GREENLAND GREENLAND
GM 86 GAMBIA GAMBIA
GN 87 GUINEA GUINEA
GP 88 GUADELOUPE GUADELOUPE
GQ 89 EQUATORIAL GUINEA EQUATORIAL GUINEA
GR 90 GREECE GREECE
S. GEORGIA AND S.
GS 91 S. GEORGIA AND S. SANDWICH ISLS.
SANDWICH ISLS.
GT 92 GUATEMALA GUATEMALA
GU 93 GUAM GUAM
GW 94 GUINEA BISSAU GUINEA BISSAU

101
GY 95 GUYANA GUYANA
HK 96 HONG KONG HONG KONG
HEARD AND
HM 97 HEARD AND MCDONALD ISLANDS
MCDONALD ISLANDS
HN 98 HONDURAS HONDURAS
HR 99 CROATIA (HRVATSKA) CROATIA (HRVATSKA)

Code Classification Code Classification Name

05 Nation
Code Sort Order Code Name Code Description remark

HT 100 HAITI HAITI

HU 101 HUNGARY HUNGARY
ID 102 INDONESIA INDONESIA
IE 103 IRELAND IRELAND
IL 104 ISRAEL ISRAEL
IM 105 ISLE OF MAN ISLE OF MAN
IN 106 INDIA INDIA
BRITISH INDIAN
IO 107 BRITISH INDIAN OCEAN TERRITORY
OCEAN TERRITORY
IQ 108 IRAQ IRAQ
IR 109 IRAN IRAN
IS 110 ICELAND ICELAND
IT 111 ITALY ITALY
JE 112 JERSEY JERSEY
JM 113 JAMAICA JAMAICA
JO 114 JORDAN JORDAN
JP 115 JAPAN JAPAN
KE 116 KENYA KENYA
KG 117 KYRGYZSTAN KYRGYZSTAN
KH 118 CAMBODIA CAMBODIA
KI 119 KIRIBATI KIRIBATI
KM 120 COMOROS COMOROS
SAINT KITTS AND
KN 121 SAINT KITTS AND NEVIS
NEVIS
KP 122 NORTH KOREA NORTH KOREA
KR 123 SOUTH KOREA SOUTH KOREA
KW 124 KUWAIT KUWAIT
KY 125 CAYMAN ISLANDS CAYMAN ISLANDS
KZ 126 KAZAKHSTAN KAZAKHSTAN
LA 127 LAOS LAOS
LB 128 LEBANON LEBANON
LC 129 SAINT LUCIA SAINT LUCIA
LI 130 LIECHTENSTEIN LIECHTENSTEIN
LK 131 SRI LANKA SRI LANKA
LR 132 LIBERIA LIBERIA
LS 133 LESOTHO LESOTHO
LT 134 LITHUANIA LITHUANIA

102
LU 135 LUXEMBOURG LUXEMBOURG
LV 136 LATVIA LATVIA
LY 137 LIBYA LIBYA
MA 138 MOROCCO MOROCCO
MC 139 MONACO MONACO
MD 140 MOLDOVA MOLDOVA
ME 141 MONTENEGRO MONTENEGRO
MG 142 MADAGASCAR MADAGASCAR
MH 143 MARSHALL ISLANDS MARSHALL ISLANDS
F.Y.R.O.M.
MK 144 F.Y.R.O.M. (MACEDONIA)
(MACEDONIA)

Code Classification Code Classification Name

05 Nation
Code Sort Order Code Name Code Description remark

ML 145 MALI MALI

MM 146 MYANMAR MYANMAR
MN 147 MONGOLIA MONGOLIA
MO 148 MACAU MACAU
NORTHERN MARIANA
MP 149 NORTHERN MARIANA ISLANDS
ISLANDS
MQ 150 MARTINIQUE MARTINIQUE
MR 151 MAURITANIA MAURITANIA
MS 152 MONTSEZRAT MONTSEZRAT
MT 153 MALTA MALTA
MU 154 MAURITIUS MAURITIUS
MV 155 MALDIVES MALDIVES
MW 156 MALAWI MALAWI
MX 157 MEXICO MEXICO
MY 158 MALAYSIA MALAYSIA
MZ 159 MOZAMBIQUE MOZAMBIQUE
NA 160 NAMIBIA NAMIBIA
NC 161 NEW CALEDONIA NEW CALEDONIA
NE 162 NIGER NIGER
NF 163 NORFOLK ISLAND NORFOLK ISLAND
NG 164 NIGERIA NIGERIA
NI 165 NICARAGUA NICARAGUA
NL 166 NETHERLANDS NETHERLANDS
NO 167 NORWAY NORWAY
NP 168 NEPAL NEPAL
NR 169 NAURU NAURU
NT 170 NEUTRAL ZONE NEUTRAL ZONE
NU 171 NIUE NIUE
NEW ZEALAND
NZ 172 NEW ZEALAND (AOTEAROA)
(AOTEAROA)
OM 173 OMAN OMAN
PA 174 PANAMA PANAMA

103
PE 175 PERU PERU
PF 176 FRENCH POLYNESIA FRENCH POLYNESIA
PG 177 PAPUA NEW GUINEA PAPUA NEW GUINEA
PH 178 PHILIPPINES PHILIPPINES
PK 179 PAKISTAN PAKISTAN
PL 180 POLAND POLAND
ST. PIERRE AND
PM 181 ST. PIERRE AND MIQUELON
MIQUELON
PN 182 PITCAIRN PITCAIRN
PR 183 PUERTO RICO PUERTO RICO
PALESTINIAN
PS 184 TERRITORY, PALESTINIAN TERRITORY, OCCUPIED
OCCUPIED
PT 185 PORTUGAL PORTUGAL
PW 186 PALAU PALAU
PY 187 PARAGUAY PARAGUAY
QA 188 QATAR QATAR

Code Classification Code Classification Name

05 Nation
Code Sort Order Code Name Code Description remark

RE 189 REUNION REUNION

RO 190 ROMANIA ROMANIA
RS 191 SERBIA SERBIA
RUSSIAN
RU 192 RUSSIAN FEDERATION
FEDERATION
RW 193 RWANDA RWANDA
SA 194 SAUDI ARABIA SAUDI ARABIA
SB 195 SOLOMON ISLANDS SOLOMON ISLANDS
SC 196 SEYCHELLES SEYCHELLES
SD 197 SUDAN SUDAN
SE 198 SWEDEN SWEDEN
SG 199 SINGAPORE SINGAPORE
SH 200 ST. HELENA ST. HELENA
SI 201 SLOVENIA SLOVENIA
SVALBARD & JAN
SJ 202 SVALBARD & JAN MAYEN ISLANDS
MAYEN ISLANDS
SK 203 SLOVAK REPUBLIC SLOVAK REPUBLIC
SL 204 SIEZRA LEONE SIEZRA LEONE
SM 205 SAN MARINO SAN MARINO
SN 206 SENEGAL SENEGAL
SO 207 SOMALIA SOMALIA
SR 208 SURINAME SURINAME
SAO TOME AND
ST 209 SAO TOME AND PRINCIPE
PRINCIPE
SU 210 USSR (FORMER) USSR (FORMER)
SV 211 EL SALVADOR EL SALVADOR
SY 212 SYRIA SYRIA
SZ 213 SWAZILAND SWAZILAND
TURKS AND CAICOS
TC 214 TURKS AND CAICOS ISLANDS
ISLANDS

104
TD 215 CHAD CHAD
FRENCH SOUTHERN
TF 216 FRENCH SOUTHERN TERRITORIES
TERRITORIES
TG 217 TOGO TOGO
TH 218 THAILAND THAILAND
TJ 219 TAJIKISTAN TAJIKISTAN
TK 220 TOKELAU TOKELAU
TM 221 TURKMENISTAN TURKMENISTAN
TN 222 TUNISIA TUNISIA
TO 223 TONGA TONGA
TP 224 EAST TIMOR EAST TIMOR
TR 225 TURKEY TURKEY
TRINIDAD AND
TT 226 TRINIDAD AND TOBAGO
TOBAGO
TV 227 TUVALU TUVALU
TW 228 TAIWAN TAIWAN
TZ 229 TANZANIA TANZANIA
UA 230 UKRAINE UKRAINE
UG 231 UGANDA UGANDA
UK 232 UNITED KINGDOM UNITED KINGDOM

Code Classification Code Classification Name

05 Nation
Code Sort Order Code Name Code Description remark
US MINOR OUTLYING
UM 233 US MINOR OUTLYING ISLANDS
ISLANDS
US 234 UNITED STATES UNITED STATES
UY 235 URUGUAY URUGUAY
UZ 236 UZBEKISTAN UZBEKISTAN
VATICAN CITY STATE
VA 237 VATICAN CITY STATE (HOLY SEE)
(HOLY SEE)
SAINT VINCENT &
VC 238 SAINT VINCENT & THE GRENADINES
THE GRENADINES
VE 239 VENEZUELA VENEZUELA
BRITISH VIRGIN
VG 240 BRITISH VIRGIN ISLANDS
ISLANDS
VIRGIN ISLANDS
VI 241 VIRGIN ISLANDS (U.S.)
(U.S.)
VN 242 VIET NAM VIET NAM
VU 243 VANUATU VANUATU
WALLIS AND FUTUNA
WF 244 WALLIS AND FUTUNA ISLANDS
ISLANDS
WS 245 SAMOA SAMOA
YE 246 YEMEN YEMEN
YT 247 MAYOTTE MAYOTTE
SERBIA AND
YU 248 MONTENEGRO SERBIA AND MONTENEGRO (FORMER)
(FORMER)
ZA 249 SOUTH AFRICA SOUTH AFRICA
ZM 250 ZAMBIA ZAMBIA
(ZAIRE) SEE CD
CONGO, (ZAIRE) SEE CD CONGO, DEMOCRATIC
ZR 251
DEMOCRATIC REPUBLIC
REPUBLIC
ZW 252 ZIMBABWE ZIMBABWE

105
 6.4. Packaging Unit
Code Classification Code Classification Name

17 Packaging Unit
Code Sort Order Code Name Code Description remark

AM 1 Ampoule Ampoule
BA 2 Barrel Barrel
BC 3 Bottle crate Bottle crate
BE 4 Bundle Bundle
BF 5 Balloon, non-protected Balloon, non-protected
BG 6 Bag Bag
BJ 7 Bucket Bucket
BK 8 Basket Basket
BL 9 Bale Bale
Bottle, protected
BQ 10 Bottle, protected cylindrical
cylindrical
BR 11 Bar Bar
BV 12 Bottle, bulbous Bottle, bulbous
BZ 13 Bag Bag
CA 14 Can Can
CH 15 Chest Chest

Code Classification Code Classification Name

17 Packaging Unit
Code Sort Order Code Name Code Description remark

CJ 16 Coffin Coffin
CL 17 Coil Coil
Wooden Box, Wooden
CR 18 Wooden Box, Wooden Case
Case
CS 19 Cassette Cassette
CT 20 Carton Carton
CTN 21 Container Container
CY 22 Cylinder Cylinder
DR 23 Drum Drum
GT 24 Extra Countable Item Extra Countable Item
HH 25 Hand Baggage Hand Baggage
IZ 26 Ingots Ingots
JR 27 Jar Jar
JU 28 Jug Jug
JY 29 Jerry CAN Cylindrical Jerry CAN Cylindrical
KZ 30 Canester Canester
Logs, in
LZ 31 Logs, in bundle/bunch/truss
bundle/bunch/truss
NT 32 Net Net
Non-Exterior Packaging
OU 33 Non-Exterior Packaging Unit
Unit
PD 34 Poddon Poddon
PG 35 Plate Plate
PI 36 Pipe Pipe
PO 37 Pilot Pilot

106
PU 38 Traypack Traypack
RL 39 Reel Reel
RO 40 Roll Roll
Rods, in
RZ 41 Rods, in bundle/bunch/truss
bundle/bunch/truss
SK 42 Skeletoncase Skeletoncase
TY 43 Tank, cylindrical Tank, cylindrical
Bulk,gas(at 1031 mbar 15
VG 44 Bulk,gas(at 1031 mbar 15 oC)
oC)
Bulk,liquid(at normal
VL 45 Bulk,liquid(at normal temperature/pressure)
temperature/pressure)
Bulk, solid, large
VO 46 Bulk, solid, large particles("nodules")
particles(nodules)
Bulk, gas (liquefied at
VQ 47 abnormal Bulk, gas(liquefied at abnormal temperature/pressure)
temperature/pressure)
Bulk, solid, granular
VR 48 Bulk, solid, granular particles("grains")
particles(grains)
VT 49 Extra Bulk Item Extra Bulk Item
Bulk, fine
VY 50 Bulk, fine particles("powder")
particles(powder)
ML 51 Mills cigarette Mills
TN 52 TAN 1TAN REFER TO 20BAGS
Code Classification Code Classification Name

17 Packaging Unit
Code Sort Order Code Name Code Description remark

B/L 53 Black Lug Refers to a lug or container that is black in color.

BIN 54 Bin A container for storing or transporting goods
Bottle
BOTT 55 A container typically used for liquids

BOUQ 56 Bouquet A collection of flowers or other items bundled together

BOWL 57 Bowl A round or oval container used for holding food or other
items.
BOX 58 Box A rectangular container typically used for packaging and
storage.
BUBG 59 Budget Bag A bag designed for economical or budget-conscious
purposes.
BULK 60 Bulk Pack Packaging designed for large quantities of items.
BUNC 61 Bunch A grouping or collection of items, often tied together.
BUND 62 Bundle A group of items bound or packaged together.
CLEA 63 Clear Lid A lid or covering that is transparent or see-through.
EA 64 Each Indicates individual units or items.
EACH 65 Each Similar to "EA," denotes individual units or items.
ECON 66 Economy Bag A bag designed for cost-effective or budget-friendly use.
ECPO 67 Econo Poc Sell Refers to an economical or budget-friendly pocket for
selling items.
Green Lugs
G/L 68 Lugs or containers that are green in color.

KARR 69 Karripoc Specific packaging or container type.

Labels
LABE 70 Refers to adhesive labels used for marking or identifying
items.
MESH 71 Mesh Packaging material made of interconnected strands or
fibers.
NETL 72 Netlon Refers to a type of net or netting used in packaging.
P/KG 73 Per Kilogram Indicates pricing or packaging based on weight in
kilograms.
PACK 74 PACK General term for packaging or packaging units.

107
PCRT 75 PCRT Specific type of packaging or container.
PILP 76 Pilpac Specific type of packaging or container.
POC 77 Pocket A small container or compartment.
Poc Sell
POCS 78 Refers to a pocket or small container used for selling
items.
POLY 79 Poly Bags Bags made of polyethylene or similar materials.
POT 80 Pots Containers typically used for planting or holding plants.
Prepack
PREP 81 Items or units that are prepackaged or prepared.
Pun DTray
PUND 82 Refers to a tray or container for specific items.
Punnet - Packaging
PUNN 83 A specific type of packaging often used for fruits or
vegetables.
SLEE 84 Sleeve A covering or protective layer.

Sock
SOCK 85 A fabric covering often used for protection or packaging.

TRAY 86 Tray A flat, shallow container used for holding or displaying

items.
Tray Sell
TRSE 87 Refers to a tray or container specifically designed for
selling items.
TUB 88 TUB A container typically with a round shape and open top.
UNWR 89 Unwrap Indicates items that are not wrapped or packaged.
WRAP 90 Wraped Indicates items that are wrapped or packaged.

6.5. Units of measure

Code Classification Code Classification Name

10 Unit of measures
Code Sort Order Code Name Code Description remark

4B 1 Pair Pair
AV 2 Cap Cap
BA 3 Barrel Barrel
BE 4 bundle bundle
BG 5 bag bag
BL 6 block block
BLL 7 BLL Barrel BLL Barrel (petroleum) (158,987 dm3)
BX 8 box box
CA 9 Can Can
CEL 10 Cell Cell
CMT 11 centimetre centimetre
CR 12 CARAT CARAT
DR 13 Drum Drum
DZ 14 Dozen Dozen
GLL 15 Gallon Gallon
GRM 16 Gram Gram
GRO 17 Gross Gross
KG 18 Kilo-Gramme Kilo-Gramme
KTM 19 kilometre kilometre
KWT 20 kilowatt kilowatt
L 21 Litre Litre
LBR 22 pound pound

108
LK 23 link link
LTR 24 Litre Litre
M 25 Metre Metre
M2 26 Square Metre Square Metre
M3 27 Cubic Metre Cubic Metre
MGM 28 milligram milligram
MTR 29 metre metre
megawatt hour (1000
MWT 30 megawatt hour (1000 kW.h)
kW.h)
NO 31 Number Number
NX 32 part per thousand part per thousand
PA 33 packet packet
PG 34 plate plate
PR 35 pair pair
RL 36 reel reel
RO 37 roll roll
SET 38 set set
ST 39 sheet sheet
TNE 40 tonne (metric ton) tonne (metric ton)
TU 41 tube tube
U 42 Pieces/item [Number] Pieces/item [Number]
YRD 43 yard yard

6.6. Currency
Code Classification Code Classification Name

33 Currency
Code Code Name Code Description remark

ZMW Zambian kwacha Zambian kwacha

USD United States Dollar United States Dollar
ZAR South African Rand South African Rand
GBP Pound Sterling Pound Sterling
CNY Chinese Yuan Chinese Yuan
EUR Euro Euro

6.7. Transaction Type

Code Classification Code Classification Name

14 Transaction Type
Code Sort Order Code Name Code Description remark

C 1 Copy Sales and purchase type: Copy

N 2 Normal Sales and purchase type: Normal

109
 6.8. Sales Receipt Type
Code Classification Code Classification Name

37 Sales Receipt Type

Code Sort Order Code Name Code Description remark

S 10 Sale Sale
R 11 Reversal after Sale Refund after Sale Credit Note

D 12 Adjustment upwards after Adjustment upwards after Sale Debit Note

Sale

6.9. Payment Method

Code Classification Code Classification Name

07 Payment Method
Code Sort Order Code Name Code Description remark

01 1 CASH CASH
02 2 CREDIT CREDIT
03 3 CASH/CREDIT CASH/CREDIT
04 4 BANK CHECK BANK CHECK PAYMENT
05 5 DEBIT&CREDIT CARD PAYMENT USING CARD
ANY TRANSACTION USING MOBILE MONEY
06 6 MOBILE MONEY
SYSTEM
08 7 Bank transfer

07 8 OTHER OTHER MEANS OF PAYMENT

6.10. Transaction Progress

Code Classification Code Classification Name

11 Transaction progress
Code Sort Order Code Name Code Description remark

02 2 Approved Approved
05 5 Refunded Refunded
06 6 Transferred Transferred

6.11. Registration Type

Code Classification Code Classification Name

31 Registration Type
Code Sort Order Code Name Code Description remark

A 1 Automatic Automatic – Purchases from another Smart Invoice user.

These purchases will be identifiable from the select
purchase endpoint (i.e. if the endpoint returns anything, it
means these were sold to your TPIN by another Smart
Invoice user.)
M 2 Manual Manual – Purchases from a non-Smart Invoice user
These are purchases manually registered onto the system
by the taxpayer.

110
 6.12. Purchase Receipt Type
Code Classification Code Classification Name

38 Purchase Receipt Type

Code Sort Order Code Name Code Description remark

P 1 Purchase Purchase
R 2 Refund after Purchase Refund after Purchase

6.13. API Response Code

Code System Description

000 Server It is succeeded

001 Server There is no search result
884 Client Invalid customer TPIN was provided
891 Client An error occurred while Request URL is created.
892 Client An error occurred while Request Header data is created.
893 Client An error occurred while Request Body data is created.
894 Client An error regarding server communication occurred.
895 Client An error regarding unallowed Request Method occurred.
896 Client An error regarding Request Status occurred.
899 Client An error regarding Client occurred.
900 Server There is no Header information
901 Server It is not valid device
902 Server This device is installed
903 Server Only VSDC device can be verified.
910 Server Request parameter error
911 Server There is no request full text
912 Server There is a request Method error.
921 Server Sales or sales invoice data which is declared cannot be received.
922 Server Sales invoice data can be received after receiving the sales data.
930 Server The specified invoice could not be found. Please verify [orgInvcNo] and try again
931 Server The credit note amount exceeds the original invoice amount for item:
932 Server The item specified in the credit note does not exist on the original invoice. [itemCd]
934 Server The quantity specified in the credit note exceeds the quantity in the original invoice.
935 Server The credit note contains information that does not match the original invoice data
990 Server The maximum number of views are exceeded
991 Server There is an error during registration
992 Server There is an error during modification
993 Server There is an error during deletion
994 Server There is an overlapped Data
995 Server There is no downloaded file
999 Server There is an unknown error. Please ask it administrator

111
 6.14. Stock In/Out Type
Code Classification Code Classification Name

12 Stock In/Out Type

Code Sort Order Code Name Code Description remark

01 1 Import Incoming-Import
02 2 Purchase Incoming- Purchase
03 3 Return Incoming- Return
04 4 Stock Movement Incoming- Stock Movement
05 5 Processing Incoming- Processing
06 6 Adjustment Incoming- Adjustment
11 11 Sale Outgoing- Sale
12 12 Return Outgoing- Return

Code Classification Code Classification Name

12 Stock In/Out Type

Code Sort Order Code Name Code Description remark

13 13 Stock Movement Outgoing- Stock Movement

14 14 Processing Outgoing- Processing
15 15 Discarding Outgoing- Discarding
16 16 Adjustment Outgoing- Adjustment

6.15. Refund Reason Code

32 Refund reason code
Code Sort Order Code Name Code Description remark

01 1 Missing Quantity Missing Quantity

02 2 Missing Item Missing Item
03 3 Damaged Damaged
04 4 Wasted Wasted
05 5 Raw Material Shortage Raw Material Shortage
06 6 Refund Refund
07 7 Wrong Customer TPIN Wrong Customer TPIN
08 8 Wrong Customer name Wrong Customer name
09 9 Wrong Amount/price Wrong Amount/price
10 10 Wrong Quantity Wrong Quantity
11 11 Wrong Item(s) Wrong Item(s)
12 12 Wrong tax type Wrong tax type
13 13 Other reason Other reason

6.16. Item code Generation

The item code field is required and must have a unique value. This means that each item registered in the CIS
should be identified by its own unique item code.

Where the CIS has no unique identifiers for a registered item, the below formula should be used to generate item
code.

112
For example: itemCd: ZM2NTBA0000012

ZM: Country of Origin (Zambia)

2: Product Type (Finished Product)
NT: Packaging Unit (NET)
BA: Quantity Unity (Barrel)
0000012: increments from 0000001 to N value

6.17. Import Item status.

Code Classification Code Classification Name

26 Import item Status

Code Sort Order Code Name Code Description remark

3 3 Approved These are imported items approved to be

stocked-in
4 4 Cancelled These are imported items discarded for stock-in

6.18. Debit note reason.

Code Classification Code Classification Name

67 Reason for debit note

Code Sort Order Code Name Code Description remark

01 1 Wrong quantity invoiced

02 2 Wrong invoice amount
03 3 Omitted item
04 4 Other [specify]

113