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 ........................................................................................................ 4
4. Getting Started .............................................................................................................................. 5
4.1. Signup and Registration.......................................................................................... 5
4.2. VSDC Setup and Initialization ............................................................................... 5
4.3. VSDC Services ......................................................................................................... 6
4.4. VSDC API Versions ................................................................................................ 7
4.5. Interacting with the VSDC API ............................................................................. 7
4.6. Sample Request Illustration using Postman API Client ...................................... 7
5. VSDC API Services ....................................................................................................................... 9
5.1. Device Initialization ................................................................................................. 9
5.2. Standard Codes (Constants) ................................................................................. 12
5.3. Notices ..................................................................................................................... 16
5.4. Branch Information............................................................................................... 17
5.5. Customer Information .......................................................................................... 20
5.6. Item Information ................................................................................................... 23
5.7. Import Information ............................................................................................... 40
5.8. Sales Information................................................................................................... 44
Save Sales Response ....................................................................................................................... 122
5.9. Commercial invoice information ........................................................................ 124
5.10. Provisional and Final invoice Information ........................................................ 135
5.11. Purchase Information.......................................................................................... 159
5.12. Stock Information ................................................................................................ 167
6. Code Definition.............................................................................................................................. 175
6.1. Tax Type ............................................................................................................................. 175
6.2. Product Type ...................................................................................................................... 175
6.3. Countries code .................................................................................................................... 176
6.4. Packaging Unit ................................................................................................................... 183
6.5. Units of measure ................................................................................................................. 185
6.6. Currency ............................................................................................................................. 187
6.7. Transaction Type ............................................................................................................... 188
6.8. Sales Receipt Type ............................................................................................................. 188
6.9. Payment Method ................................................................................................................ 188
6.10. Transaction Progress ....................................................................................................... 188
6.11. Registration Type ............................................................................................................. 189
6.12. Purchase Receipt Type .................................................................................................... 189
6.13. API Response Code .......................................................................................................... 189
6.14. Stock In/Out Type ............................................................................................................ 190
6.15. Credit Note Reason Code ................................................................................................ 191
6.16. Item code Generation....................................................................................................... 191
6.17. Import Item status. .......................................................................................................... 191
6.18. Debit note reason.............................................................................................................. 191
6.19. Zambia ports .................................................................................................................... 192
6.20. Destination Incortem ....................................................................................................... 193
6.21. Departure Incoterm ......................................................................................................... 193
6.22. Commercial Invoice status .............................................................................................. 193
6.23. Banks ................................................................................................................................. 194
1. Document revision.

VSDC Service What’s New Affected Endpoint

Device Initialization No changes
Standard Codes Added
Classification Codes No changes
Branch Information No changes
Notices No changes
Item Information No changes
Import Information No changes
Sales Information 1. Refer to: Commercial,
Provisional and Final Invoice
information sections
2. Enhanced validations on /trnsSales/saveSales
currency type management.
3. Introduced value credit note
/trnsSales/saveSales
Purchase Information No changes
Stock Information No changes
Commercial invoice 1. Added new API response codes. /trnsSales/saveCommer
information 2. Added new endpoint to process cialInvoice
commercial invoice information
Provisional and final 1. Added new API response codes. /trnsSales/saveProvisio
invoice information 2. Added 4 new endpoints to nalInvoice
process provisional invoice, /trnsSales/saveFinaInvo
Final invoice, Final credit note ice
and final combined invoice /trnsSales/saveFinalCre
information ditNote
/trnsSales/saveFinalCo
mbinedInvoice
Other 1. Added monitoring feature for
pending uploads on the VSDC
home page.
2. Added watermark on scanned
sandbox invoices.
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
Version: ≥ 9.0 and < 10.0, 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/zrasandboxvsdc
VSDC Postman Collection https://www.postman.com/warped-
astronaut-6832/virtual-sales-data-controller-
api/overview

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
 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.

4
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 Approval Download

Smart VSDC by and deploy
Invoice Service ZRA 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.

5
 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.

6
 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, acquired after completing the registration process,
onto your server and run the application.
b. When deployed, run the URL in your browser. You should have a landing page
like below.

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

7
Response

8
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. A
response of “Device already installed indicates that the request data was already utilized to call this endpoint.”

ERP VSDC API

Device Initialized, API keys
Integration POST /initializer/selectInitInfo
are generated and stored.

9
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. TPIN VARCHAR Y 10

Request
bhfId Taxpayer branch identifier. Available Branch ID VARCHAR Y 3
under device management in the
Taxpayer Portal.
dvcSrlNo VSDC identifier. Available under Device Serial Number VARCHAR Y 100
device management in the Taxpayer
Portal.
JSON REQUEST SAMPLE
Request Body {"tpin":"1000000000","bhfId":"000","dvcSrlNo":"20180520000000"}

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

10
 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.
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": "1000000000", "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 } }}

11
 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

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 20231215000000
JSON REQUEST SAMPLE

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

Standard Codes Response

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

12
 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"}]}]}}

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 is readily
available for access by the developers of smart invoice solutions, for classification of their products. It can be accessed on the ZRA website under
the Smart Invoice tab. All classifications of products must be done at commodity level. Where a commodity level does not apply, the closest must
be utilized in classifying products or services.
● 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

13
● 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

14
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": "1000000000","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"}]}}

15
 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": "1000000000","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
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

16
 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.

17
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":"1000000000","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}

18
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, 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": "1000000000","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
identifier
bhfNm This is the branch name Branch Office Name VARCHAR 60

19
 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":"1000000000","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":"1000000000","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

20
 ● 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":"1000000000","bhfId": "000","custmTpin": "2000000000"}

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":"1000000000","bhfId":"000","custNo":"09xxxxxxxx
","custTpin":"2000000000","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}]}}

21
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":"1000000000","bhfId":"000","custNo":"097xxxxxxx","custTpin":"2000000000","custNm":"ZRA","adrs":null,"email":null,"faxNo":null,"useYn":"Y","remark":null,"regrNm":"Admin","regrId":"Admin","mo
drNm":"Admin","modrId":"Admin"}

22
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 ITEM
● Endpoints: /items/saveItem
● Request method: POST.
● Requirement: MANDATORY
● Description: Saves product or services created in third-party system to Smart Invoice.
● Request Parameter: Item data including name, description, price quantity, category, etc.
● Response: Returns success for the saved product of service.
● 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. All items registered must align
with level 4 of the UNSPSC codes list. Where not found, businesses must align to the closest codes at that level.

23
 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 tpin Taxpayer’s identification number as VARCHAR Y 10

TPIN
Item registered on core Tax Administration System
Request TaxOnline
bhfId Taxpayer branch (store) location identifier Branch ID VARCHAR Y 3
itemCd This is the item identifier on the taxpayer’s Item Code VARCHAR Y 100 See ‘6.16. Item code’
system
itemClsCd This is the USNPSC item classification code. Item Classification Code VARCHAR Y 10
Retrieve this from the Item
classification code dictionary
under the Smart Invoice Tab on
the ZRA website
itemTyCd This is the item product type VARCHAR Y 5 See ‘6.2. Product type’
Item Type Code
itemNm This is the name of the item being registered Item× Name VARCHAR Y 200
by the taxpayer
itemStdNm Item Standard Name VARCHAR N 200
orgnNatCd This is the country of origin of the registered Origin Place Code (Origin VARCHAR Y 5 See ‘6.3. Country Codes’
item country code)
pkgUnitCd This is the item packaging unit code VARCHAR Y 5 See ‘6.4. Packaging Unit’
Packaging Unit Code

24
qtyUnitCd This is the item quantity code VARCHAR Y 5 See ‘6.5. Units of Measure’
Quantity Unit Code
vatCatCd This is the VAT category code of a registered VAT category Code VARCHAR Y 5 See ‘6.1. Tax Type’
item. Where not applicable, pass null
iplCatCd This is the IPL category code of the registered IPL category code VARCHAR Y 5 See ‘6.1. Tax Type’
item. Where not applicable, pass null
tlCatCd This is the TL category code of the registered TL category code VARCHAR Y 5 See ‘6.1. Tax Type’
item. Where not applicable, pass null
exciseTxCatCd This is the Excise category code of the Excise tax category code VARCHAR Y 5 See ‘6.1. Tax Type’
registered item
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 Additional Information VARCHAR N 100
registered item
sftyQty Refers to the additional inventory or stock Safety Quantity NUMBER N 13,2
that a business maintains as a buffer to guard
against unexpected fluctuations in demand
manufactuterTpin Manufacturer TPIN for MTV product Manufacture TPIN VARCHAR N 10
manufacturerItemCd Manufacturer item code for MTV product Manufacturer item code VARCHAR N 100
rrp Recommended Retailed Price as set by the RRP NUMBER N 18,4
manufacturer
svcChargeYn Indication of whether item being registered Service charge flag CHAR N 1
has a service charge
rentalYn Indication of whether item being registered Rental Flag CHAR N 1
has rental charge
useYn This is the usage status of the registered item Used / Unused VARCHAR Y 1
regrNm This is the username of the user registering Registrant Name VARCHAR Y 60
the item
regrId This is the user id of the user registering the Registrant ID VARCHAR Y 20
item
modrNm This is the username of the user modifying Modifier name VARCHAR Y 60
the item
modrId This is the user id of the user modifying the Modifier id VARCHAR Y 20
item
JSON REQUEST SAMPLE

25
{"tpin":"1000000000","bhfId":"000","itemCd":"P200005","itemClsCd":"43322555","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,”manufacturerTpin”:”1000000000”,”m
anufacturerItemCd”:ZM2EA1234”,”rrp”:”1000”,”svcChargeYn”:”Y”,”rentalYn”:”N”,"addInfo":null,"sftyQty":5,"isrcAplcbYn":"N","useYn":"Y","regrNm":"ADMIN","regrId":"ADMIN","modrNm":"ADMIN","modr
Id":"ADMIN"}
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.
● Note: Tax categories (VAT category code, IPL category code, TL category code, and excise tax category code) are only required if the
item falls under that specific tax category. For instance, the TL category code is always required for accommodation for taxpayers registered
under TL, but it is not mandatory for other items that do not pertain to tourism.

26
 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

27
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 is the item identifier on the taxpayer’s system Item Code VARCHAR Y 100 See ‘6.16. Item
code’
itemClsCd This is the USNPSC item classification 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 Item Standard Name VARCHAR N 200
name 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 N 5 See ‘6.1. Tax
Type’
iplCatCd This is the IPL category code of the registered item IPL category code VARCHAR N 5 See ‘6.1. Tax
Type’
tlCatCd This is the TL category code of the registered item TL category code VARCHAR N 5 See ‘6.1. Tax
Type’
exciseTxCatCd This is the Excise category code of the registered item Excise tax category code VARCHAR N 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

28
 manufactuterTpin Manufacturer TPIN for MTV product Manufacture TPIN VARCHAR N 10

manufacturerItemCd Manufacturer item code for MTV product Manifacture item code VARCHAR N 100
rrp Recommended Retailed Price as set by the manufacturer RRP NUMBER N 18,4

svcChargeYn Indication of whether item being registered has a service Service charge flag CHAR N 1
charge
rentalYn Indication of whether item being registered has rental Rental Flag CHAR N 1
charge
addInfo This is any additional information about the registered Additional VARCHAR N 100
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
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

modrNm This is the username of the system user approving or Modifier name VARCHAR Y 60
rejecting the imported item.

modrId This is the user ID of the system user approving or Modifier ID VARCHAR Y 20
rejecting the imported item.

JSON REQUEST SAMPLE

{"tpin":"1000000000","bhfId":"000","itemCd":"P200005","itemClsCd":"50425610","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,”manufacturerTpin”:”1000000000”,”
manufacturerItemCd”:1234”,”rrp”:”1000”,”svcChargeYn”:”Y”,”rentalYn”:”N”,"addInfo":null,"sftyQty":5,"isrcAplcbYn":"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

29
 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
● 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": "1000000000","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’

30
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.
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 TL 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
manufactuterTpin Manufacturer TPIN for MTV product Manufacture TPIN VARCHAR N 10
manufacturerItemCd Manufacturer item code for MTV product Manufacturer item code VARCHAR N 100
rrp Recommended Retailed Price RRP NUMBER N 18,4

svcChargeYn Indication of whether an item has service charge Service charge flag CHAR N 1

31
 to it
rentalYn Indication of whether an item has rental or not Rental Flag CHAR N 1

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":"1000000000","itemCd":"KR2AMXBLL0000001","itemClsCd":"43322555","itemTyCd":"2","itemNm":"restitem#1","itemStdNm":null,"orgnNa
tCd":"KR","pkgUnitCd":"AM","qtyUnitCd":"BLL","vatCatCd":"A","vatCatCd":"A","iplCatCd":null,"tlCatCd":null,"exciseTxCatCd":null, null,
"btchNo":null,"regBhfId":"000","bcd":"8801234567061","dftPrc":21000,”manufacturerTpin”:”1000000000”,”manufacturerItemCd”:”
KR2AMXBLL1234”,”rrp”:”1000”,”svcChargeYn”:”Y”,”rentalYn”:”N”,"addInfo":null,"sftyQty":0,"isrcAplcbYn":"N","ZRAModYn":"N","useYn":"Y"},{"tpin":"1234567890","itemCd":"KR2AMXBLL0000001","it
emClsCd":"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 that would have been registered by the business
onto Smart Invoice.

32
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 item identifier on the taxpayer’s system Item Code VARCHAR Y 100

JSON REQUEST SAMPLE

Request Body {“tpin”: “1000000000”, “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
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 Value Added Tax category VARCHAR Y 5 See ‘6.1. Tax
Code Type’
iplCatCd This is the IPL category code of the registered item Insurance Premium Levy VARCHAR Y 5 See ‘6.1. Tax

33
 category code Type’
tlCatCd This is the TL category code Tourism Levy category VARCHAR Y 5 See ‘6.1. Tax
code 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
manufactuterTpin Manufacturer TPIN for MTV Transactions Manufacture TPIN VARCHAR N 10
manufacturerItemCd Manufacturer item code for MTV transaction Manufacturer item code VARCHAR N 100

rrp Recommended Retailed Price RRP NUMBER N 18,4

svcChargeYn Indication of whether an item has service charge Service charge flag CHAR N 1

rentalYn Indication of whether an item is rental or not Rental Flag CHAR N 1

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

{"resultCd": "000", "resultMsg": "It is succeeded", "resultDt": "20240327154703", "data": {"itemList": [{"tpin": "1000000000", "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 ,”manufacturerTpin”:”1000000000”,”manufacturerItemCd”:1234”,”rrp”:”1000”,”svcChargeYn”:”Y”,”rentalYn”:”N”,"addInfo": null, "sftyQty": 9}]}}"

34
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 is the item identifier on the taxpayer’s system Item Code VARCHAR Y 100
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

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

35
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}

SAVE RRP ITEMS

● Endpoint: /items/saveRrpItems
● Request method: POST
● Requirement: OPTIONAL
● Description: This endpoint is designed to store recommended retailed price items by manufactures
● Request Parameters: Item data including item code, quantity, etc.
● Response: Returns success or failure of the save RRP.
● Note: This endpoint should only be consumed by manufacturers with RRP
Save MTV Product Request
Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length Format

saveRrpItems Save RRP tpin Taxpayer’s identification number as registered on core VARCHAR Y 10
TPIN
Item Tax Administration System TaxOnline
bhfId Taxpayer branch (store) location identifier Branch ID VARCHAR Y 3
itemCd This is the item identifier on the taxpayer’s system Item Code VARCHAR Y 100 See ‘6.16. Item
code’
itemClsCd This is the USNPSC item classification 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
orgnNatCd This is the country of origin of the registered item Origin Place Code (Origin VARCHAR Y 5 See ‘6.3.
country code) Country

36
 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’
rrp This is the recommended retail price set by the RRP NUMBER Y 18,4
manufacturer
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

modrNm This is the username of the system user approving or Modifier name VARCHAR Y 60
rejecting the imported item.

modrId This is the user ID of the system user approving or Modifier ID VARCHAR Y 20
rejecting the imported item.

JSON REQUEST SAMPLE

{"tpin":"1000000000","bhfId":"000","itemList": [{"itemCd":"itemCode1","itemClsCd":"50102515","itemTyCd":"3","itemNm":"Item Name Example","itemDesc":"This is
fanta","orgnNatCd":"ZM","pkgUnitCd":"BG","qtyUnitCd":"BX","rrp":123.6789,"useYn":"Y","regrId":
"admin","regrNm":"Admin","modrNm":"Admin","modrId":"1231"},{"itemCd":"itemCode2","itemClsCd":"50102515","itemTyCd":"3","itemNm":
"Item Name Example","itemDesc":"This is fanta","orgnNatCd":"ZM","pkgUnitCd":"BG","qtyUnitCd":"BX","rrp":123.6789,"useYn":"Y",
"regrId":"admin","regrNm":"Admin","modrNm":"Admin","modrId":"1231"}]}

Save MTV Product 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":"20240728202141","data”: null}

37
SELECT RRP ITEMS
● Endpoint: /items/selectRrpItems
● Request method: POST.
● Requirement: OPTIONAL
● Description: This endpoint is designed to select recommended retailed price items from manufacturers data
● Request Parameters: Item data including Tpin, branch ID, and last request date.
● Response: Returns success or failure of the select RRP.
● Note: This endpoint should only be consumed by sellers of MTV products. It is used to get Recommended Retail Prices set by
manufacturers which will be used when processing sales with MTV products.

Select RRP request

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

rrpItemReq Search RRP tpin Taxpayer’s identification number as registered on core Tax TPIN VARCHAR Y 10
Item 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. Last Request Date VARCHAR Y 14

JSON REQUEST SAMPLE

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

Select RRP response

Object ID Object Name Sub ojbect Attribute ID Attribute Description Attribute Name Data Type Required Data Format
Length
rrpItemsRes RRP tpin Taxpayer’s identification number as registered on VARCHAR Y 10
TPIN
Item core Tax Administration System TaxOnline
List bhfId Taxpayer branch (store) location identifier Branch ID VARCHAR Y 3
respons
rrpItemList itemCd This is the item identifier on the taxpayer’s system Item Code VARCHAR Y 100 See ‘6.16.
e
Item code’
itemClsCd This is the USNPSC item classification code Item Classification VARCHAR Y 10
Code
itemTyCd This is the item product type VARCHAR Y 5 See ‘6.2.
Item Type Code

38
 Product
type’
itemNm This is the name of the item being registered by the Item Name VARCHAR Y 200
taxpayer
orgnNatCd This is the country of origin of the registered item Origin Place Code VARCHAR Y 5 See ‘6.3.
(Origin 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’
rrp This is the recommended retail price of an item RRP NUMBER Y 18,4

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

modrNm This is the username of the system user approving or Modifier name VARCHAR Y 60
rejecting the imported item.

modrId This is the user ID of the system user approving or Modifier ID VARCHAR Y 20
rejecting the imported item.

JSON REQUEST SAMPLE

{"tpin":"1000000000","bhfId":"000","itemList": [{"itemCd":"itemCode1","itemClsCd":"50102515","itemTyCd":"3","itemNm":"Item Name Example","itemDesc":"This is
fanta","orgnNatCd":"ZM","pkgUnitCd":"BG","qtyUnitCd":"BX","rrp":123.6789,"useYn":"Y","regrId":
"admin","regrNm":"Admin","modrNm":"Admin","modrId":"1231"},{"itemCd":"itemCode2","itemClsCd":"50102515","itemTyCd":"3","itemNm":
"Item Name Example","itemDesc":"This is fanta","orgnNatCd":"ZM","pkgUnitCd":"BG","qtyUnitCd":"BX","rrp":123.6789,"useYn":"Y",
"regrId":"admin","regrNm":"Admin","modrNm":"Admin","modrId":"1231"}]}

39
 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.

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
dclRefNum This is the declaration reference number captured on ASYCUDA Declaration VARCHAR N 100
reference number
JSON REQUEST SAMPLE

Request Body {"tpin": "1000000000","bhfId": "000","lastReqDt":"20231215000000", "dclRefNum":"CX1100096839"}

40
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 VARCHAR 50
Declaration Number
declaration 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
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 VARCHAR 5
Export Nation Code
country or nation in the context of international trade
pkg This refers to a container, box, or bundle in which items, products, NUMBER 13,2
Package
or goods are enclosed for storage
pkgUnitCd Refers to a unique identifier or code assigned to a specific VARCHAR 5 See ‘6.4.
Packaging Unit Code
packaging 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

41
 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
dclRefNum This is the declaration reference number captured on ASYCUDA VARCHAR 100
Declaration reference
number
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.
● 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

42

Update Smart Invoice with the

Save Stock Item POST /stock/saveStockItems
approved Import Item
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
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 item identifier on the Item Code VARCHAR Y 100
taxpayer’s system
imptItemsttsCd This is the status code of the item to Import Item Status Code VARCHAR Y 5 See ‘6.17.
be approved or rejected by the Import Item
taxpayer status’
remark This is a general remark about the Remark VARCHAR N 400
approval or rejection of the item by
the taxpayer

43
 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": "1000000000","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": "This is a non-stock item","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

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.

44
 ● 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.

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 Data Type Required Data Format
Name Name Length
TrnsSalesSaveWrReq Save Sales tpin Taxpayer’s TPIN VARCHAR Y 10
Request identification number as
registered on core Tax
Administration System
TaxOnline
bhfId Taxpayer branch (store) Branch Id VARCHAR Y 3
location identifier
orgIncNo The invoice number Original Invoice NUMBER N 38
being referred to if you Number
are issuing a credit note
or debit note
cisInvcNo Invoice number as CIS Invoice VARCHAR Y 50
generated on Taxpayers number

45
 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 Sales Type VARCHAR Y 5 See 6..7.

type of sale (Pass N) Code Transaction Type’
rcptTyCd Type of receipt Receipt Type VARCHAR Y 5 See ‘6.8. Sale
Code Receipt Type’
pmtTyCd The mode of payment Payment Type VARCHAR Y 5 See ‘6.9. Payment
used for this Code Method’
transaction
salesSttsCd Progress of transaction Invoice/Sale VARCHAR Y 5 See ‘6.10.
e.g. Approved, Refunded Status Code Transaction
etc. Progress’
cfmDt Date time when invoice Confirmation VARCHAR Y 14 yyyyMMddhhmmss
was issued Date
salesDt Date when sale was Sales Date VARCHAR Y 8 yyyyMMdd
made
stockRlsDt Date when the item was Stock Released VARCHAR N 14 yyyyMMddhhmmss
released from the Date
warehouse/branch
cnclReqDt Date time when a Cancell VARCHAR Y 14 yyyyMMddhhmmss
cancellation request Requested Date
was 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 VARCHAR Y 5 See ‘6.15. Refund
refund (empty string Reason Code Reason Code’
when not a refund)
totItemCnt Total number of items Total Item NUMBER Y 10
on the invoice Count
taxblAmtA Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items A
classified as Standard
Rated for VAT purposes
(Pass 0.0 if not
applicable)

46
taxblAmtB Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line B
items classified as MTV
-Minimum Taxable
Value for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtC1 Total tax exclusive Taxable Amount NUMBER Y 18.4
amount for all line C1
items classified as C1 -
Exports for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtC2 Total tax exclusive Taxable Amount NUMBER Y 18.4
amount for all line C2
items classified as C2 –
Zero rating LPO for
VAT purposes (pass 0.0
if not applicable)
taxblAmtC3 Total tax exclusive Taxable Amount NUMBER Y 18.4
amount for all line C3
items classified as C3
Zero rated by nature for
VAT purposes (pass 0.0
if not applicable)
taxblAmtD Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line D
items classified as D
Exempt for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtRvat Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line RVAT
items classified as
RVAT for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtE Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line E
items classified as E -
Disbursements for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtF Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line F
items classified as F for

47
 VAT purposes (pass 0.0
if not applicable)
taxblAmtIpl1 Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line IPL
items attracting
Insurance Premium
Levy (pass 0.0 if not
applicable)
taxblAmtIpl2 Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line IPL2
items attracting
Insurance Premium
Levy 2 (pass 0.0 if not
applicable)
taxblAmtTl Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line TL
items attracting
Tourism Levy (pass 0.0
if not applicable)
taxblAmtEcm Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line ECM
items attracting Excise
Coal (pass 0.0 if not
applicable)
taxblAmtExeeg Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line EXEEG
items attracting Excise
Electricity (pass 0.0 if
not applicable)
taxblAmtTot Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line TOT
items attracting 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- Tax Rate C1 NUMBER Y 7,2
Exports – As per
standard codes
taxRtC2 Tax rate for C2 Zero Tax Rate C2 NUMBER Y 7,2
rating LPO – As per
standard codes

48
taxRtC3 Tax rate for C3 Zero Tax Rate C3 NUMBER Y 7,2
rated 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 Tax Rate NUMBER Y 7,2
reverse VAT – As per RVAT
standard codes
taxRtE Tax rate E Tax Rate E NUMBER Y 7,2
Disbursements – As per
standard codes
taxRtF Rate for F Service Tax Rate F NUMBER Y 7,2
charge – 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 Tax Rate TL NUMBER Y 7,2
Levy – As per standard
codes
taxRtEcm Tax rate for Excise Tax Rate ECM NUMBER Y 7,2
Coal Mining – As per
standard codes
taxRtExeeg Tax rate Electricity and Tax Rate NUMBER Y 7,2
Energy generation – As EXEEG
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)

49
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 Tax Amount NUMBER Y 18,4
Insurance Premium IPL1
Levy IPL on invoice
(Pass 0.0 when not
applicable)
taxAmtIpl2 This is the total Tax Amount NUMBER Y 18,4
Insurance Premium IPL2
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

50
 (Pass 0.0 when not
applicable)
taxAmtEcm This is the total tax Tax Amount NUMBER Y 18,4
charged on all Excise ECM
Coal Mining line items
on invoice (Pass 0.0
when not applicable)
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 Tax Amount NUMBER Y 18,4
on invoice] TOT
totTaxblAmt This is the total Tax Total TaxlAmt NUMBER Y 18,4
Exclusive Amount for
all line items on
invoice
totTaxAmt This is the total tax Tot Tax NUMBER Y 18,4
charged on all line Amount
items on invoice
commInvcNo Commercial Invoice Number N 38
Number
custTyCd Customer category Varchar N 5 see ‘6.24’. Customer
type code’
travelPurposeCd Travel purpose code Varchar N 5 see ‘6.25’ Travelpurpose
code
nonResidenTyCd customer Non-residence Varchar N 5 see ‘6.25’ travel purpose
type or category code’
permenentRsdncAdr Customer Permanent Varchar N 100
s residence address
permanentRsncCoun Customer Permanent Varchar N 5
tryCd residence country code See ‘6.3. Country Codes’

originCountryCd Origin country code Varchar N 5

See ‘6.3. Country Codes’

countriesVisited List of countries visited List<String> N 5

See ‘6.3. Country Codes’

51
countriesToBeVisited List of countries to be List<String> N 5
visited See ‘6.3. Country Codes’

tourPkgNmDtl List of tour package List<String> N 100

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

52
 exchangeRt This is the exchange Exchange rate NUMBER Y 18,4
rate used in the
transaction.
destnCountryCd This is the destination Destination VARCHAR N 5
country of the item Country Code
being exported.
dbtRsnCd This is the reason code Debit Reason VARCHAR N 5
for issuing a debit. Code
invcAdjustReason This is the reason for Invoice VARCHAR N
adjusting an invoice Adjustment
Reason
cashDcRt This is the cash Cash Discount NUMBER N 18,4
discount rate applied on Rate
the summed total for the
line items
cashDcAmt Cash /value discount Cash discount NUMBER N 18,4
amount amount
List<Trns itemSeq Item Sequence Number Item Sequence NUMBER Y 11
SalesSave Number
WrItem>
itemCd This is the item Item Code VARCHAR Y 100
identifier on the
taxpayer’s system
itemClsCd This is the UNSCP Item VARCHAR Y 10
code assigned to the Classification
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 Packaging Unit VARCHAR Y 5 See ‘6.4 Packaging Unit’
unit code assigned to Code
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 Quantity Unit VARCHAR Y 5 See ‘6.5. Unit of
single item unit code Code Quantity’
assigned to 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 inclusive Unit Price NUMBER Y 18,4
price of the item

53
splyAmt This is the total amount Supply Amount NUMBER Y 18,4
of the supplied item
(qty * prc)
dcRt This is the discount rate Discount rate NUMBER Y 5,2
on line item (Pass 0.0 if
not applicable)
dcAmt This is the discount Discount NUMBER Y 18,4
amount on line item Amount
(Pass 0.0 if not
applicable)
isrccCd Insurance Company Insurance VARCHAR N 10
Code Company Code
isrccNm Insurance Company Insurance VARCHAR N 100
name Company name
isrcAmt This is the insurance Insurance NUMBER N 18,4
amount on line item Amount
vatCatCd This represents the tax Vat Category VARCHAR Y 5
category code for VAT Code
purposes on line item.
Pass null where not
applicable
exciseTxCatCd This represents the tax Excise Tax VARCHAR Y 5
category code for Category Code
Excise on line
item. Pass null where
not applicable
vatTaxblAmt This is the Tax VAT Taxable NUMBER Y 18,4
Exclusive Amount for Amount
VAT at line-item level
(Pass 0.0 when not
applicable)
exciseTaxblAmt This is the Tax Excise Taxable NUMBER Y 18,4
Exclusive Amount for Amount
Excise at line-item level
(Pass 0.0 when not
applicable)
tlTaxblAmt This is the Tax Tourism Levy NUMBER Y 18,4
Exclusive Amount for Taxable
Tourism Lecy at line- Amount
item level (Pass 0.0
when not applicable)
iplTaxblAmt This is the Tax Insurance NUMBER Y 18,4
Exclusive Amount for Premium Levy
IPL at line-item level Taxable
(Pass 0.0 when not Amount
applicable)

54
 iplAmt This is the insurance Insurance NUMBER Y 18,4
premium levy tax Premium Levy
amount charged on the Amount
line item
tlAmt This is the Tourism Tourism Levy NUMBER Y 18,4
Levy amount charged mount
on the line 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 Amount
line item (Pass 0.0
when not applicable)
totAmt This is the total Tax Total Amount NUMBER Y 18,4
Inclusive Amount of
the line item
JSON REQUEST SAMPLE

{"tpin":"1000000000","bhfId":"000","orgInvcNo":0,"cisInvcNo":"CIS001-1380","custTpin":"2000000000","custNm":"Smart
Customer","salesTyCd":"N","rcptTyCd":"S","pmtTyCd":"01","salesSttsCd":"02","cfmDt":"20240508102010","salesDt":"20240728","stockRlsDt":null,"cnclReqDt":null,"cnclDt":null,"rfdDt":null,"rfdRsnCd":
null,"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,"
taxblAmtIpl2":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,"tax
AmtRvat":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,"cashDc
Rt":25,"cashDcAmt":50,"totAmt":150,"prchrAcptcYn":"N","remark":"","regrId":"admin","regrNm":"admin","modrId":"admin","modrNm":"admin","saleCtyCd":"1","lpoNumber":null,"currencyTyCd":"ZMW"
,"exchangeRt":"1","destnCountryCd":"","dbtRsnCd":"","invcAdjustReason":"","itemList":[{"itemSeq":1,"itemCd":"20056","itemClsCd":"50102518","itemNm":"Bread","bcd":"","pkgUnitCd":"BA","pkg":0.0,"
qtyUnitCd":"BE","qty":1.0,"prc":125,"splyAmt":125,"dcRt":20,"dcAmt":25,"isrccCd":"","isrccNm":"","isrcRt":0.0,"isrcAmt":0.0,"vatCatCd":"A","exciseTxCatCd":null,"tlCatCd":null,"iplCatCd":null,"vatTaxb
lAmt":86.2069,"vatAmt":13.7931,"exciseTaxblAmt":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":"","pkgUnitCd":"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}]}

55
Save Sales Request – Credit Note

Object ID Object Attribute ID Attribute Description Attribute Data Type Required Data Format
Name Name Length
TrnsSalesSaveWrReq Save Sales tpin Taxpayer’s TPIN VARCHAR Y 10
Request identification 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 Original Branch VARCHAR Y 13
where the original Id
invoice was issued from
orgIncNo The invoice number Original Invoice NUMBER Y 38
being referred to if you Number
are 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 Sales Type VARCHAR Y 5 See ‘6.7.

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

56
stockRlsDt Date when the item was Stock Released VARCHAR N 14 yyyyMMddhhmmss
released from the Date
warehouse/branch
cnclReqDt Date time when a Cancell VARCHAR Y 14 yyyyMMddhhmmss
cancellation request Requested Date
was 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 VARCHAR Y 5 See ‘6.15. Refund
refund (empty string Reason Code Reason Code’
when not a refund)
totItemCnt Total number of items Total Item NUMBER Y 10
on the invoice Count
taxblAmtA Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items A
classified as Standard
Rated for VAT purposes
(Pass 0.0 if not
applicable)
taxblAmtB Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line B
items classified as
MTV -Minimum
Taxable Value for VAT
purposes (pass 0.0 if
not applicable)
taxblAmtC1 Total tax exclusive Taxable Amount NUMBER Y 18.4
amount for all line C1
items classified as C1 -
Exports for VAT
purposes (pass 0.0 if
not applicable)
taxblAmtC2 Total tax exclusive Taxable Amount NUMBER Y 18.4
amount for all line C2
items classified as C2 –
Zero rating LPO for
VAT purposes (pass 0.0
if not applicable)
taxblAmtC3 Total tax exclusive Taxable Amount NUMBER Y 18.4
amount for all line C3
items classified as C3
Zero rated by nature for

57
 VAT purposes (pass 0.0
if not applicable)
taxblAmtD Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line D
items classified as D
Exempt for VAT
purposes (pass 0.0 if
not applicable)
taxblAmtRvat Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line RVAT
items classified
as RVAT for VAT
purposes (pass 0.0 if
not applicable)
taxblAmtE Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line E
items classified as E -
Disbursements for VAT
purposes (pass 0.0 if
not applicable)
taxblAmtF Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line F
items classified as F for
VAT purposes (pass 0.0
if not applicable)
taxblAmtIpl1 Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line IPL
items attracting
Insurance Premium
Levy (pass 0.0 if not
applicable)
taxblAmtIpl2 Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line IPL2
items attracting
Insurance Premium
Levy 2 (pass 0.0 if not
applicable)
taxblAmtTl Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line TL
items attracting
Tourism Levy (pass 0.0
if not applicable)
taxblAmtEcm Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line ECM
items attracting Excise
Coal (pass 0.0 if not
applicable)

58
taxblAmtExeeg Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line EXEEG
items attracting Excise
Electricity (pass 0.0 if
not applicable)
taxblAmtTot Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line TOT
items attracting 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- Tax Rate C1 NUMBER Y 7,2
Exports – As per
standard codes
taxRtC2 Tax rate for C2 Zero Tax Rate C2 NUMBER Y 7,2
rating LPO – As per
standard codes
taxRtC3 Tax rate for C3 Zero Tax Rate C3 NUMBER Y 7,2
rated 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 Tax Rate RVAT NUMBER Y 7,2
reverse VAT – As per
standard codes
taxRtE Tax rate E Tax Rate E NUMBER Y 7,2
Disbursements – As per
standard codes
taxRtF Rate for F Service Tax Rate F NUMBER Y 7,2
charge – 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 Tax Rate TL NUMBER Y 7,2
Levy – As per standard
codes

59
taxRtEcm Tax rate for Excise Tax Rate ECM NUMBER Y 7,2
Coal Mining – As per
standard codes
taxRtExeeg Tax rate Electricity and Tax Rate NUMBER Y 7,2
Energy generation – As EXEEG
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)
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

60
 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 Tax Amount NUMBER Y 18,4
Insurance Premium IPL1
Levy IPL on invoice
(Pass 0.0 when not
applicable)
taxAmtIpl2 This is the total Tax Amount NUMBER Y 18,4
Insurance Premium IPL2
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 NUMBER Y 18,4
charged on all Excise ECM
Coal Mining line items
on invoice (Pass 0.0
when not applicable)
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 Tax Amount NUMBER Y 18,4
on invoice] TOT
totTaxblAmt This is the total Tax Total TaxlAmt NUMBER Y 18,4
Exclusive Amount for
all line items on
invoice
totTaxAmt This is the total tax Tot Tax NUMBER Y 18,4
charged on all line Amount
items on invoice
totAmt This is the total Tax Total Amount NUMBER Y 18,4
Inclusive Amount of

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

62
 invcAdjustReason This is the reason for Invoice VARCHAR N
adjusting an invoice Adjustment
Reason
cashDcRt Cash/value discount Cash Discount NUMBER N 18,4
rate Rate
cashDcAmt Cash /value discount Cash discount NUMBER N 18,4
amount amount
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 Item VARCHAR Y 10
code assigned to the Classification
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 Packaging Unit VARCHAR Y 5 See ‘6.4 Packaging
unit code assigned to Code Unit’
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 Quantity Unit VARCHAR Y 5 See ‘6.5. Unit of
single item unit code Code Quantity’
assigned to 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 inclusive Unit Price NUMBER Y 18,4
price of the item
splyAmt This is the total amount Supply Amount NUMBER Y 18,4
of the supplied item
(qty * prc)
dcRt This is the discount rate Discount rate NUMBER Y 5,2
on line item (Pass 0.0 if
not applicable)
dcAmt This is the discount Discount NUMBER Y 18,4
amount on line item Amount
(Pass 0.0 if not
applicable)
isrccCd Insurance Company Insurance VARCHAR N 10
Code Company Code

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

64
 totAmt This is the total Tax Total Amount NUMBER Y 18,4
Inclusive Amount of
the line item
JSON REQUEST SAMPLE

{"tpin":"1000000000","bhfId":"000","cisInvcNo":"INV000001","orgInvcNo":"806","orgSdcId":"SDC000000000","custTpin":"1000000000","prcOrdCd":0,"custNm":"Walkin","salesTyCd":"N","rcptTyCd":"
R","pmtTyCd":"04","salesSttsCd":"02","cfmDt":"20250608063847","salesDt":"20250608","stockRlsDt":null,"cnclReqDt":null,"cnclDt":null,"rfdDt":null,"rfdRsnCd":"01","totItemCnt":2,"taxblAmtA":14975.
862,"taxblAmtB":0,"taxblAmtC":0,"taxblAmtC1":0,"taxblAmtC2":0,"taxblAmtC3":0,"taxblAmtD":0,"taxblAmtRvat":0,"taxblAmtE":0,"taxblAmtF":0,"taxblAmtIpl1":0,"taxblAmtIpl2":0,"taxblAmtTl":0,"tax
blAmtEcm":0,"taxblAmtExeeg":0,"taxblAmtTot":0,"taxRtA":16,"taxRtB":16,"taxRtC1":0,"taxRtC2":0,"taxRtC3":0,"taxRtD":0,"taxRtE":0,"taxRtF":10,"taxRtIpl1":5,"taxRtIpl2":0,"taxRtTl":1.5,"taxRtEcm":
5,"taxRtExeeg":3,"taxRtTot":0,"taxRtRvat":16,"taxAmtA":2396.138,"taxAmtB":0,"taxAmtC1":0,"taxAmtC2":0,"taxAmtC3":0,"taxAmtD":0,"taxAmtC":0,"tlAmt":0,"taxAmtE":0,"taxAmtF":0,"taxAmtIpl1":
0,"taxAmtIpl2":0,"taxAmtTl":0,"taxAmtEcm":0,"taxAmtExeeg":0,"taxAmtTot":0,"taxAmtRvat":0,"totTaxblAmt":14975.862,"totTaxAmt":2396.138,"totAmt":17372,"prchrAcptcYn":"N","remark":"Duplicate
d invoice","regrId":"Admin Manager","regrNm":"Admin Manager","modrId":"Admin Manager","modrNm":"Admin
Manager","saleCtyCd":"1","lpoNumber":null,"currencyTyCd":"ZMW","exchangeRt":1,"destnCountryCd":null,"dbtRsnCd":null,"nvcAdjustReason":"Duplicated
invoice","itemList":[{"itemSeq":1,"itemCd":"ZM2PACKP100000063","itemClsCd":"50501814","itemNm":"Goodhope Almond 1L -
Original","bcd":null,"pkgUnitCd":"NT","pkg":1,"qtyUnitCd":"U","qty":20,"prc":434.3,"splyAmt":8686,"dcRt":0,"dcAmt":0,"isrccCd":"","isrccNm":"","isrcRt":0,"isrcAmt":0,"vatCatCd":"A","iplCatCd":null,
"tlCatCd":null,"exciseCatCd":null,"vatTaxblAmt":7487.931,"vatAmt":1198.069,"exciseTaxblAmt":0,"tlTaxblAmt":0,"iplTaxblAmt":0,"iplAmt":0,"tlAmt":0,"exciseTxAmt":0,"totAmt":8686},{"itemSeq":2,"i
temCd":"ZM2PACKP100000064","itemClsCd":"50501814","itemNm":"Goodhope Almond 1L - Vanilla
Unsweetened","bcd":null,"pkgUnitCd":"NT","pkg":1,"qtyUnitCd":"U","qty":20,"prc":434.3,"splyAmt":8686,"dcRt":0,"dcAmt":0,"isrccCd":"","isrccNm":"","isrcRt":0,"isrcAmt":0,"vatCatCd":"A","iplCatCd"
:null,"tlCatCd":null,"exciseCatCd":null,"vatTaxblAmt":7487.931,"vatAmt":1198.069,"exciseTaxblAmt":0,"tlTaxblAmt":0,"iplTaxblAmt":0,"iplAmt":0,"tlAmt":0,"exciseTxAmt":0,"totAmt":8686}]}

65
Save Sales Request – Value Credit note – This is a transaction adjustment involving amount without affecting stock quantities.

Object ID Object Attribute ID Attribute Description Attribute Data Type Required Data Format
Name Name Length
TrnsSalesSaveWrReq Save Sales tpin Taxpayer’s TPIN VARCHAR Y 10
Request identification 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 Original Branch VARCHAR Y 13
where the original Id
invoice was issued from
orgIncNo The invoice number Original Invoice NUMBER Y 38
being referred to if you Number
are 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 Sales Type VARCHAR Y 5 See ‘6.7.

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

66
stockRlsDt Date when the item was Stock Released VARCHAR N 14 yyyyMMddhhmmss
released from the Date
warehouse/branch
cnclReqDt Date time when a Cancell VARCHAR Y 14 yyyyMMddhhmmss
cancellation request Requested Date
was 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 VARCHAR Y 5 See ‘6.15. Refund
refund(empty string Reason Code Reason Code’
when not a refund)
totItemCnt Total number of items Total Item NUMBER Y 10
on the invoice Count
taxblAmtA Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items A
classified as Standard
Rated for VAT purposes
(Pass 0.0 if not
applicable)
taxblAmtB Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line B
items classified as
MTV -Minimum
Taxable Value for VAT
purposes (pass 0.0 if
not applicable)
taxblAmtC1 Total tax exclusive Taxable Amount NUMBER Y 18.4
amount for all line C1
items classified as C1 -
Exports for VAT
purposes (pass 0.0 if
not applicable)
taxblAmtC2 Total tax exclusive Taxable Amount NUMBER Y 18.4
amount for all line C2
items classified as C2 –
Zero rating LPO for
VAT purposes (pass 0.0
if not applicable)
taxblAmtC3 Total tax exclusive Taxable Amount NUMBER Y 18.4
amount for all line C3
items classified as C3
Zero rated by nature for

67
 VAT purposes (pass 0.0
if not applicable)
taxblAmtD Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line D
items classified as D
Exempt for VAT
purposes (pass 0.0 if
not applicable)
taxblAmtRvat Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line RVAT
items classified
as RVAT for VAT
purposes (pass 0.0 if
not applicable)
taxblAmtE Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line E
items classified as E -
Disbursements for VAT
purposes (pass 0.0 if
not applicable)
taxblAmtF Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line F
items classified as F for
VAT purposes (pass 0.0
if not applicable)
taxblAmtIpl1 Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line IPL
items attracting
Insurance Premium
Levy (pass 0.0 if not
applicable)
taxblAmtIpl2 Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line IPL2
items attracting
Insurance Premium
Levy 2 (pass 0.0 if not
applicable)
taxblAmtTl Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line TL
items attracting
Tourism Levy (pass 0.0
if not applicable)
taxblAmtEcm Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line ECM
items attracting Excise
Coal (pass 0.0 if not
applicable)

68
taxblAmtExeeg Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line EXEEG
items attracting Excise
Electricity (pass 0.0 if
not applicable)
taxblAmtTot Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line TOT
items attracting 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- Tax Rate C1 NUMBER Y 7,2
Exports – As per
standard codes
taxRtC2 Tax rate for C2 Zero Tax Rate C2 NUMBER Y 7,2
rating LPO – As per
standard codes
taxRtC3 Tax rate for C3 Zero Tax Rate C3 NUMBER Y 7,2
rated 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 Tax Rate RVAT NUMBER Y 7,2
reverse VAT – As per
standard codes
taxRtE Tax rate E Tax Rate E NUMBER Y 7,2
Disbursements – As per
standard codes
taxRtF Rate for F Service Tax Rate F NUMBER Y 7,2
charge – 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 Tax Rate TL NUMBER Y 7,2
Levy – As per standard
codes

69
taxRtEcm Tax rate for Excise Tax Rate ECM NUMBER Y 7,2
Coal Mining – As per
standard codes
taxRtExeeg Tax rate Electricity and Tax Rate NUMBER Y 7,2
Energy generation – As EXEEG
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)
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

70
 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 Tax Amount NUMBER Y 18,4
Insurance Premium IPL1
Levy IPL on invoice
(Pass 0.0 when not
applicable)
taxAmtIpl2 This is the total Tax Amount NUMBER Y 18,4
Insurance Premium IPL2
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 NUMBER Y 18,4
charged on all Excise ECM
Coal Mining line items
on invoice (Pass 0.0
when not applicable)
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 Tax Amount NUMBER Y 18,4
on invoice] TOT
totTaxblAmt This is the total Tax Total TaxlAmt NUMBER Y 18,4
Exclusive Amount for
all line items on
invoice
totTaxAmt This is the total tax Tot Tax NUMBER Y 18,4
charged on all line Amount
items on invoice
totAmt This is the total Tax Total Amount NUMBER Y 18,4
Inclusive Amount of

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

72
 invcAdjustReason This is the reason for Invoice VARCHAR N
adjusting an invoice Adjustment
Reason
cashDcRt Cash/value discount Cash Discount NUMBER N 18,4
rate Rate
cashDcAmt Cash /value discount Cash discount NUMBER N 18,4
amount amount
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 Item VARCHAR Y 10
code assigned to the Classification
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 Packaging Unit VARCHAR Y 5 See ‘6.4 Packaging
unit code assigned to Code Unit’
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 Quantity Unit VARCHAR Y 5 See ‘6.5. Unit of
single item unit code Code Quantity’
assigned to 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 inclusive Unit Price NUMBER Y 18,4
price of the item
splyAmt This is the total amount Supply Amount NUMBER Y 18,4
of the supplied item
(qty * prc)
dcRt This is the discount rate Discount rate NUMBER Y 5,2
on line item (Pass 0.0 if
not applicable)
dcAmt This is the discount Discount NUMBER Y 18,4
amount on line item Amount
(Pass 0.0 if not
applicable)
isrccCd Insurance Company Insurance VARCHAR N 10
Code Company Code

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

74
 totAmt This is the total Tax Total Amount NUMBER Y 18,4
Inclusive Amount of
the line item
rebateInvcList NUMBER N 38

JSON REQUEST SAMPLE

{"tpin":"1234567890","bhfId":"000","orgInvcNo":2,"orgSdcId":"SDC0010024844","cisInvcNo":"41","custTpin":"1000000000","custNm":"Walk-In
Customer","salesTyCd":"N","rcptTyCd":"V","pmtTyCd":"01","salesSttsCd":"02","cfmDt":"20250528173452","salesDt":"20250528","stockRlsDt":"20250528173452","cnclReqDt":"20250528173452","cnclDt
":null,"totItemCnt":1,"taxblAmtA":0,"taxblAmtB":0,"taxblAmtC1":7000,"taxblAmtC2":0,"taxblAmtC3":0,"taxblAmtD":0,"taxblAmtRvat":0,"taxblAmtE":0,"taxblAmtF":0,"taxblAmtIpl1":0,"taxblAmtIpl2":0,"
taxblAmtTl":0,"taxblAmtEcm":0,"taxblAmtExeeg":0,"taxblAmtTot":0,"taxAmtA":0,"taxAmtB":0,"taxAmtC":0,"taxAmtC1":0,"taxAmtC2":0,"taxAmtC3":0,"taxAmtD":0,"taxAmtRvat":0,"taxAmtE":0,"taxAm
tF":0,"taxAmtIpl1":0,"taxAmtIpl2":0,"taxAmtTl":0,"taxAmtEcm":0,"taxAmtExeeg":0,"taxAmtTot":0,"totTaxblAmt":7000,"totTaxAmt":0,"totAmt":7000,"taxRtA":16,"taxRtB":16,"taxRtC1":0,"taxRtC2":0,"ta
xRtC3":0,"taxRtD":0,"tlAmt":0,"taxRtRvat":16,"taxRtE":0,"taxRtF":10,"taxRtIpl1":5,"taxRtIpl2":0,"taxRtTl":1.5,"taxRtEcm":5,"taxRtExeeg":3,"taxRtTot":0,"prchrAcptcYn":"N","remark":"","regrId":"admin"
,"regrNm":"admin","modrId":"admin","modrNm":"admin","lpoNumber":null,"currencyTyCd":"ZMW","exchangeRt":"1.0","destnCountryCd":"SA","dbtRsnCd":null,"rfdRsnCd":"","invcAdjustReason":null,"b
ankCd":"ABSA","swiftCd":"3123","bnkBranch":"Lusaka","bankAccntNo":"121321312","bankAccntHldr":"Yvette","custTyCd":"01","travelPurposeCd":"01","permanentRsdncAdrs":"Gasaba
downtown","permanentRsdncCountryCd":"RW","originCountryCd":"RW","bookingAgentNm":"Lusaka
Tour","tourPackageNames":[],"rebateInvcList":[],"itemList":[{"itemSeq":1,"itemCd":"ZA2NTNO0000027","itemClsCd":"25101917","itemNm":"Rice","bcd":"","pkgUnitCd":"NT","pkg":1,"qtyUnitCd":"NO",
"qty":1,"prc":7000,"splyAmt":7000,"dcRt":0,"dcAmt":0,"vatCatCd":"C1","vatTaxblAmt":7000,"vatAmt":0,"totAmt":7000}]}

Save Sales Request – Debit Note

Object ID Object Attribute ID Attribute Description Attribute Data Type Required Data Format
Name Name Length
TrnsSalesSaveWrReq Save Sales tpin Taxpayer’s TPIN VARCHAR Y 10
Request identification number as
registered on core Tax
Administration System
TaxOnline
bhfId Taxpayer branch (store) Branch Id VARCHAR Y 3
location identifier
orgIncNo The invoice number Original Invoice NUMBER Y 38
being refered to in the Number
event that 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

75
 Administration System
TaxOnline
custNm Customers name Customer Name VARCHAR N 60

salesTyCd Code associated with Sales Type VARCHAR Y 5 See ‘1.7.

type of sale e.g Normal Code ’
sales, Copy sale
rcptTyCd Type of receipt Receipt Type VARCHAR Y 5 See ‘6.8. Sale
Code 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 Invoice/Sale VARCHAR Y 5 See ‘6.10.
e.g Approved, Refunded Status Code Transaction
etc Progress’
cfmDt Date time when invoice Confirmation VARCHAR Y 14 yyyyMMddhhmmss
was issued Date
salesDt Date when sale was Sales Date VARCHAR Y 8 yyyyMMdd
made
stockRlsDt Date when the item was Stock Released VARCHAR N 14 yyyyMMddhhmmss
released from the Date
warehouse/branch
cnclReqDt Date time when a Cancell VARCHAR N 14 yyyyMMddhhmmss
cancellation request was Requested Date
made. This is used when
one needs to cancel an
invoice
cnclDt Date when cancellation Cancel Date VARCHAR N 14 yyyyMMddhhmmss
was approved
rfdDt Date when refund was Refunded Date VARCHAR N 14 yyyyMMddhhmmss
made (null when not a
refund)
rfdRsnCd Reason for issuing a Refunded VARCHAR N 5 See ‘6.15. Refund
refund (empty string Reason Code Reason Code’
when not a refund)
totItemCnt Total number of items Total Item NUMBER Y 10
on the invoice Count
taxblAmtA Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items A
classified as Standard
Rated for VAT purposes
(Pass 0.0 if not
applicable)
taxblAmtB Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items B
classified as
-Minimum Taxable
Value for VAT purposes

76
 (pass 0.0 if not
applicable)
taxblAmtC1 Total tax exclusive Taxable Amount NUMBER Y 18.4
amount for all line items C1
classified as C1 -
Exports for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtC2 Total tax exclusive Taxable Amount NUMBER Y 18.4
amount for all line items C2
classified as C2 – Zero
rating LPO for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtC3 Total tax exclusive Taxable Amount NUMBER Y 18.4
amount for all line items C3
classified as C3 Zero
rated by nature for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtD Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items D
classified as D Exempt
for VAT purposes (pass
0.0 if not applicable)
taxblAmtRvat Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items RVAT
classified as RVAT for
VAT purposes (pass 0.0
if not applicable)
taxblAmtE Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items E
classified as E -
Disbursements for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtF Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items F
classified as F for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtIpl1 Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items IPL
attracting Insurance
Premium Levy (pass 0.0
if not applicable)

77
taxblAmtIpl2 Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items IPL2
attracting Insurance
Premium Levy 2 (pass
0.0 if not applicable)
taxblAmtTl Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items TL
attracting Tourism Levy
(pass 0.0 if not
applicable)
taxblAmtEcm Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items ECM
attracting Excise Coal
(pass 0.0 if not
applicable)
taxblAmtExeeg Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items EXEEG
attracting Excise
Electricity (pass 0.0 if
not applicable)
taxblAmtTot Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items TOT
attracting 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 Tax Rate C2 NUMBER Y 7,2
rating LPO – As per
standard codes
taxRtC3 Tax rate for C3 Zero Tax Rate C3 NUMBER Y 7,2
rated 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 Tax Rate RVAT NUMBER Y 7,2
reverse VAT – As per
standard codes
taxRtE Tax rate E Tax Rate E NUMBER Y 7,2
Disbursements – As per
standard codes

78
taxRtF Rate for F Service Tax Rate F NUMBER Y 7,2
charge – 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 Tax Rate TL NUMBER Y 7,2
Levy – 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 NUMBER Y 7,2
Energy generation – As EXEEG
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)
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

79
 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 Tax Amount NUMBER Y 18,4
Insurance Premium IPL1
Levy IPL on invoice
(Pass 0.0 when not
applicable)
taxAmtIpl2 This is the total Tax Amount NUMBER Y 18,4
Insurance Premium IPL2
Levy IPL2
(ReInsurance) on
invoice (Pass 0.0 when
not applicable)
taxAmtTl This is the total tax Tax Amount TL NUMBER Y 18,4
Tourism Levy charged
on invoice (Pass 0.0
when not applicable)
taxAmtEcm This is the total tax Tax Amount NUMBER Y 18,4
charged on all Excise ECM
Coal Mining line items
on invoice (Pass 0.0
when not applicable)
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)

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

81
 exchangeRt This is the exchange rate Exchange rate NUMBER Y 18,4
used in the transaction.
destnCountryCd This is the destination Destination VARCHAR N 5
country of the item Country Code
being exported.
dbtRsnCd This is the reason code Debit Reason VARCHAR Y 5
for issuing a debit. Code
invcAdjustReason This is the reason for Invoice VARCHAR Y
adjusting an invoice Adjustment
Reason
cashDcRt Cash/value discount rate Cash Discount NUMBER N 18,4
Rate
cashDcAmt Cash /value discount Cash discount NUMBER N 18,4
amount amount
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 VARCHAR Y 10
assigned to the item Classification
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 Packaging Unit VARCHAR Y 5 See ‘6.4. Packaging
unit code assigned to the Code Unit’
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 Quantity Unit VARCHAR Y 5 See ‘6.5. Unit of
single item unit code Code Quantity’
assigned to 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 inclusive Unit Price NUMBER Y 18,4
price of the item
splyAmt This is the total amount Supply Amount NUMBER Y 18,4
of the supplied item (qty
* prc)
dcRt This is the discount rate Discount rate NUMBER Y 5,2
on line item (Pass 0.0 if
not applicable)

82
dcAmt This is the discount Discount NUMBER Y 18,4
amount on line item Amount
(Pass 0.0 if not
applicable)
isrccCd Insurance Company Insurance VARCHAR N 10
Code Company Code
isrccNm Insurance Company Insurance VARCHAR N 100
name Company name
isrcAmt This is the insurance Insurance NUMBER N 18,4
amount on line item Amount
vatCatCd This represents the tax Vat Category VARCHAR Y 5
category code for VAT Code
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 VAT Taxable NUMBER Y 18,4
Exclusive Amount for Amount
VAT at line-item level
(Pass 0.0 when not
applicable)
exciseTaxblAmt This is the Tax Excise Taxable NUMBER Y 18,4
Exclusive Amount for Amount
Excise at line item level
(Pass 0.0 when not
applicable)
tlTaxblAmt This is the Tax Tourism Levy NUMBER Y 18,4
Exclusive Amount for Taxable
Tourism Lecy at line- Amount
item level (Pass 0.0
when not applicable)
iplTaxblAmt This is the Tax Insurance NUMBER Y 18,4
Exclusive Amount for Premium Levy
IPL at line-item level Taxable
(Pass 0.0 when not Amount
applicable)
iplAmt This is the insurance Insurance NUMBER Y 18,4
premium levy tax Premium Levy
amount charged on the Amount
line item
tlAmt This is the Tourism Tourism Levy NUMBER Y 18,4
Levy amount charged on mount
the line-item
(Pass 0.0 when not
applicable)
vatAmt This is the VAT amount VAT Amount NUMBER Y 18,4
charged on the line item

83
 exciseTxAmt This is the excise tax Excise Tax NUMBER Y 18,4
amount charged on the Amount
line item (Pass 0.0 when
not applicable)
totAmt This is the total Tax Total Amount NUMBER Y 18,4
Inclusive Amount of
the line item
JSON REQUEST SAMPLE

{"tpin":"1000000000","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,"to
tItemCnt":1,"taxblAmtA":862.069,"taxblAmtB":0,"taxblAmtC1":0,"taxblAmtC2":0,"taxblAmtC3":0,"taxblAmtD":0,"taxblAmtRvat":0,"taxblAmtE":0,"taxblAmtF":0,"taxblAmtIpl1":0,"taxblAmtIpl2":0,"taxb
lAmtTl":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,"taxRtTl":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,"totTaxb
lAmt":862.069,"totTaxAmt":137.931,“cashDcRt”:0,“cashDcAmt”:0,"totAmt":1000,"prchrAcptcYn":"N","remark":"","regrId":"ADMIN","regrNm":"ADMIN","modrId":"ADMIN","modrNm":"ADMIN","sal
eCtyCd":"1",”lpoNumber”:null,"currencyTyCd":"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":nul
l,"vatTaxblAmt":862.069,"exciseTaxblAmt":0,"vatAmt":137.931,"exciseTxAmt":0,"totAmt":1000}]}

Save Sales Request – LPO Transactions

Note: For LPO transactions, a valid combination of seller TPIN, customer TPIN and LPO number are required as registered on TaxOnline.
(Sample LPO details will be shared for test purposes)

Object ID Object Attribute ID Attribute Description Attribute Name Data Type Required Data Format
Name Length
TrnsSalesSaveWr Save Sales tpin This is the Taxpayer’s TPIN VARCHAR Y 10
Req Request Identification Number
bhfId Taxpayer branch (store) location Branch ID VARCHAR Y 3
identifier
orgInvcNo This is the original invoice Original Invoice NUMBER N 38
number referred to in the event Number
of a reversal or debit note
cisInvcNo Invoice number as generated on CIS Invoice number VARCHAR Y 50
Taxpayers Certified invoicing
solutions
custTpin This is the buyer’s Taxpayer’s Customer TPIN VARCHAR N 10
Identification number (The
privileged person to whom the
LPO is issued)

84
custNm Customers name Customer Name VARCHAR N 60

salesTyCd Type of sale e.g Normal sales, Sales Type Code VARCHAR Y 5 See ‘6.7.
Copy 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 Payment Type Code VARCHAR N 5 See ‘6.9. Payment
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 yyyyMMddhhmm
issued ss
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 yyyyMMddhhmm
from the warehouse/branch ss
cnclReqDt Date time when a cancellation Cancel Reqeuested VARCHAR N 14 yyyyMMddhhmm
request was made. This is used Date ss
when one needs to cancel an
invoice
cnclDt Date when cancellation was Cancel Date VARCHAR N 14 yyyyMMddhhmm
approved ss
rfdDt Date when refund was made Refunded Date VARCHAR N 14 yyyyMMddhhmm
(null when not a refund) ss
rfdRsnCd Reason for issuing a refund( Refunded Reason VARCHAR N 5 See ‘6.15. Refund
empty string when not a Code Reason Code’
refund)
totItemCnt Total number of items on Total Item Count NUMBER Y 10
the invoice
taxblAmtA Total amount taxable for all Taxable Amount A NUMBER Y 18,4
line 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)

85
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 NUMBER Y 18,4
items attracting RVAT reverse RVAT
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 NUMBER Y 18,4
items attracting Insurance IPL2
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)
taxblAmtEcm Total amount taxable for all line Taxable Amount NUMBER Y 18,4
items attracting Excise Coal ECM
(pass 0.0 if not applicable)
taxblAmtExeeg Total amount taxable for all line Taxable Amount NUMBER Y 18,4
items attracting Excise EXEEG
Electricity (pass 0.0 if not
applicable)
taxblAmtTot Total amount taxable for all line Taxable Amount NUMBER Y 18,4
items attracting TOT (pass 0.0 if TOT
not applicable)
taxRtA Tax rate VAT category A– As Tax Rate A NUMBER Y 7,2
per 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 Tax Rate C1 NUMBER Y 7,2
per standard codes

86
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 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 Tax Rate E NUMBER Y 7,2
per standard codes
taxRtF Rate for F Service charge – As Tax Rate F NUMBER Y 7,2
per 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 Tax Rate TL NUMBER Y 7,2
per 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 Tax Amount A NUMBER Y 18,4
all VAT category A line items
on invoice (Pass 0.0 when not
applicable)
taxAmtB This is the total tax charged on Tax Amount B NUMBER Y 18,4
all VAT category A line items
on invoice (Pass 0.0 when not
applicable)
taxAmtC1 This is the total tax charged on Tax Amount C1 NUMBER Y 18,4
all VAT category C1 line items
on invoice (Pass 0.0 when not
applicable)
taxAmtC2 This is the total tax charged on Tax Amount C2 NUMBER Y 18,4
all VAT category C2 line items
on invoice (Pass 0.0 when not
applicable)
taxAmtC3 This is the total tax charged on Tax Amount C3 NUMBER Y 18,4
all VAT category C3 line items
on invoice (Pass 0.0 when not
applicable)
taxAmtD This is the total tax charged on Tax Amount D NUMBER Y 18,4
all VAT category D line items

87
 on invoice (Pass 0.0 when not
applicable)
taxAmtRvat This is the total tax charged on Tax Amount RVAT NUMBER Y 18,4
all VAT category RVAT line
items on invoice (Pass 0.0 when
not applicable)
taxAmtE This is the total tax charged on Tax Amount E NUMBER Y 18,4
all VAT category E line items
on invoice (Pass 0.0 when not
applicable)
taxAmtF This is the total tax charged on Tax Amount F NUMBER Y 18,4
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 on Tax Amount ECM NUMBER Y 18,4
all Excise Coal Mining line
items on invoice (Pass 0.0 when
not applicable)
taxAmtExeeg This is the total tax charged on Tax Amount EXEEG NUMBER Y 18,4
all Excise 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 Exclusive Total TaxlAmt NUMBER Y 18,4
Amount for all line items on
invoice
totTaxAmt This is the total tax charged on Tot Tax Amount NUMBER Y 18,4
all line items on invoice
totAmt This is the total Tax Inclusive Total Amount NUMBER Y 18,4
Amount of all line items on the
invoice
PrchrAcptcYn This specifies whether a Purchase Accepted VARCHAR Y 1
purchase has been accepted or Yes or No
not. (Pass N)
remark This is any comment/remark on Remark VARCHAR N 400
the transaction

88
 regrId This refers to the ID of the user Registrant Id VARCHAR Y 20
of the system adding the item
regrNm This refers to the username of Registrant Name VARCHAR Y 60
the person making the sale on
the system.
modrId This refers to the ID of the user Modifier Id VARCHAR Y 20
of the system adding the item
modrNm This refers to the username of Modifier Name VARCHAR Y 60
the 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 Invoice Adjustment VARCHAR N
an invoice Reason
cashDcRt Cash/value discount rate Cash Discount Rate NUMBER N 18,4

cashDcAmt Cash /value discount amount Cash discount amount NUMBER N 18,4

List<Trns itemSeq Item Sequence Number Item Sequence NUMBER Y 11

SalesSave Number
WrItem> itemCd This is the item code as defined Item Code VARCHAR Y 100
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 defined Item Name VARCHAR Y 200
on your system
bcd This is the barcode assigned to Barcode VARCHAR N 20
the item
pkgUnitCd This is the packaging unit code Packaging Unit Code VARCHAR Y 5 See ‘6.4.
assigned to the item as per Packaging Unit’
standard codes.
pkg This is the number of package Package NUMBER Y 13,2
items being sold.

89
 qtyUnitCd This is the assigned single item Quantity Unit Code VARCHAR Y 5 See ‘6.5. Unit of
unit code assigned to the item as Quantity’
per standard codes
qty This is the quantity of items Quantity NUMBER Y 13,2
being sold
prc This is the tax inclusive price of Unit Price NUMBER Y 18,4
the 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 Discount Amount NUMBER Y 18,4
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 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 VAT Taxable NUMBER Y 18,4
Amount for VAT at line-item Amount
level (Pass 0.0 when not
applicable)
exciseTaxblAmt This is the Tax Exclusive Excise Taxable NUMBER Y 18,4
Amount for Excise at line-item Amount
level (Pass 0.0 when not
applicable)
vatAmt This is the VAT amount charged VAT Amount NUMBER Y 18,4
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 Inclusive Total Amount NUMBER Y 18,4
Amount of the line item
JSON REQUEST SAMPLE
{ "tpin": "1000000000", "bhfId": "000", "orgInvcNo": 0, "cisInvcNo": "CIS001-22", "custTpin": "2000000000", "custNm": "LPO CUSTOMER", "salesTyCd": "N", "rcptTyCd": "S", "pmtTyCd": "01",
"salesSttsCd": "02", "cfmDt": "20240814102010", "salesDt": "20240814", "stockRlsDt": null, "cnclReqDt": null, "cnclDt": null, "rfdDt": null, "rfdRsnCd": null, "totItemCnt": 1, "taxblAmtA": 0.0, "taxblAmtB":
0.0, "taxblAmtC1": 0.0, "taxblAmtC2": 86.2069, "taxblAmtC3": 0.0, "taxblAmtD": 0.0, "taxblAmtRvat": 0.0, "taxblAmtE": 0.0, "taxblAmtF": 0.0, "taxblAmtIpl1": 0, "taxblAmtIpl2": 0, "taxblAmtTl": 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": 0.0, "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": 0.0, "taxAmtEcm": 0.0, "taxAmtExeeg": 0.0, "taxAmtTot": 0.0, "totTaxblAmt": 86.2069, "totTaxAmt": 0, "cashDcRt": 0,

90
 "cashDcAmt": 0, "totAmt": 86.2069, "prchrAcptcYn": "N", "remark": "", "regrId": "admin", "regrNm": "admin", "modrId": "admin", "modrNm": "admin", "saleCtyCd": "1", "lpoNumber": "109506957",
"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": 86.2069, "splyAmt": 86.2069, "dcRt": 0, "dcAmt": 0.0, "vatCatCd": "C2", "vatTaxblAmt": 86.2069, "vatAmt": 0, "totAmt": 86.2069
}]}

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

91
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 refund Refunded Reason VARCHAR N 5 See ‘6.15. Refund Reason
(empty string when not a Code Code’
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

92
 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
taxRtC2 Tax rate for C2 Zero rating Tax Rate C2 NUMBER Y 7,2
LPO – As per standard
codes

93
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
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

94
 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)
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,4
Exclusive Amount for all
line items on invoice

95
totTaxAmt This is the total tax charged Tot Tax Amount NUMBER Y 18,4
on all line items on invoice
totAmt This is the total Tax Total Amount NUMBER Y 18,4
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 N)
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
cashDcRt Cash/value discount rate Cash Discount Rate NUMBER N 18,4

96
 cashDcAmt Cash /value discount Cash discount NUMBER N 18,4
amount amount
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 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 inclusive 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,4
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

97
 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
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,4
Inclusive Amount of the
line item
JSON REQUEST SAMPLE
{"tpin":"1000000000","bhfId":"000","orgInvcNo":0,"cisInvcNo":"CIS000000","custTpin":"2000000000","custNm":"SMART
CUSTOMER","salesTyCd":"N","rcptTyCd":"S","pmtTyCd":"01","salesSttsCd":"02","cfmDt":"20250608102010","salesDt":"20250608","stockRlsDt":null,"cnclReqDt":null,"cnclDt":null,"rfdDt":null,"rfdRsnCd":
null,"totItemCnt":1,"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,"taxAmtIpl
2":0,"taxAmtTl":0,"taxAmtEcm":0,"taxAmtExeeg":0,"taxAmtTot":0,"totTaxblAmt":400,"totTaxAmt":0,"cashDcRt":0,"cashDcAmt":0,"totAmt":400,"prchrAcptcYn":"N","remark":"","regrId":"admin","regrNm":"
admin","modrId":"admin","modrNm":"admin","saleCtyCd":"1","lpoNumber":null,"currencyTyCd":"ZMW","exchangeRt":"1","destnCountryCd":"ZM","dbtRsnCd":"","invcAdjustReason":"","itemList":[{"itemSe
q":1,"itemCd":"20054","itemClsCd":"50102517","itemNm":"Maize meal - African

98
 Pride","bcd":"","pkgUnitCd":"BA","pkg":0,"qtyUnitCd":"BE","qty":4,"prc":100,"splyAmt":400,"dcRt":0,"dcAmt":0,"isrccCd":"","isrccNm":"","isrcRt":0,"isrcAmt":0,"vatCatCd":"C1","exciseTxCatCd":null,"vatT
axblAmt":400,"exciseTaxblAmt":0,"vatAmt":0,"exciseTxAmt":0,"totAmt":400}]}

GET PRINCIPAL
● Endpoint: /trnsSales/selectPrincipals
● Request method: POST.
● Requirement: OPTIONAL (RVAT agents only).
● Description: This endpoint is designed to get principals for RVAT agents
● Request Parameters: principal data including Tpin, bhfId, last request date.
● Response: Returns success or failure. On success it returns list of principals.
● Note: This endpoint is intended solely for use by RVAT Agents to retrieve principal details for processing RVAT transactions.
Select Principal request
Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Required Data Length

selectPrincipals Search tpin Taxpayer’s identification number as registered on core Tax TPIN VARCHAR Y 10
principal 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

{"tpin":"1000000000","bhfId":"000","lastReqDt":"20240123121449"}
Request Body

Select Principal Response

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

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

resultMsg This is the VSDC response message Result Message VARCHAR Y

resultDt This is the VSDC response date-time Result Date VARCHAR Y 14
tpin This is the taxpayer’s identification number as TPIN VARCHAR N 10
registered on the core tax administration system
TaxOnline

99
 principalNm This is the principal name Princilal Name VARCHAR N 255

principalAddress This is the principal address Pincipal Addeess VARCHAR N 255

principalEmail This is the principal Email Principal Email VARCHAR N 255

principalTelNo This is principal telephone number Principal Telephone VARCHAR N 50

Number
RegDt This is the Registration date Registration VARCHAR N 14
date
modDt This is the modification date Modification date VARCHAR N 14

accountNo This is the Agent account number Agent account VARCHAR N 50

number
JSON RESPONSE SAMPLE

{ "resultCd": "000", "resultMsg": "It is succeeded", "resultDt": "20240728181556","data": {"taxpayerPrincipalList": [{"id": 100,"tpin": "1000277594","tin": "1000277594", "principalNm":
"KASONGO 1 17","principalAddress": "IBEX","principalEmail": "kasongo@kasongo.com", "principalTelNo": "+260924567890","regDt": null, "modDt": null, "accountNo": "1232312117"},{"id":
101,"tpin": "1000277594","tin": "1000277594", "principalNm": "KASONGO 2 18","principalAddress": "IBEX","principalEmail": "kasongo@kasongo.com","principalTelNo":
"+260924567890","regDt": null,"modDt": null,"accountNo": "1232312218"}]}
}

Save Sales Request – RVAT with Agent

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

TrnsSalesSaveWrReq Save Sales tpin Taxpayer’s TPIN VARCHAR Y 10

Request identification number as
registered on core Tax
Administration System
TaxOnline
bhfId Taxpayer branch (store) Branch Id VARCHAR Y 3
location identifier
orgIncNo The invoice number Original Invoice NUMBER N 38
being referred to if you Number
are issuing a credit note
or debit note
cisInvcNo Invoice number as CIS Invoice VARCHAR Y 50
generated on Taxpayers number

100
 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 (Pass N) Transaction Type’
rcptTyCd Type of receipt Receipt Type VARCHAR Y 5 See ‘6.8. Sale
Code Receipt Type’
pmtTyCd The mode of payment Payment Type VARCHAR Y 5 See ‘6.9. Payment
used for this transaction Code Method’
salesSttsCd Progress of transaction Invoice/Sale VARCHAR Y 5 See ‘6.10.
e.g. Approved, Refunded Status Code Transaction
etc. Progress’
cfmDt Date time when invoice Confirmation VARCHAR Y 14 yyyyMMddhhmmss
was issued Date
salesDt Date when sale was Sales Date VARCHAR Y 8 yyyyMMdd
made
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 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
refund (empty string Code Reason Code’
when not a refund)
totItemCnt Total number of items Total Item Count NUMBER Y 10
on the invoice
taxblAmtA Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items A
classified as Standard
Rated for VAT purposes
(Pass 0.0 if not
applicable)

101
taxblAmtB Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items B
classified as MTV -
Minimum Taxable
Value for VAT purposes
(pass 0.0 if not
applicable)
taxblAmtC1 Total tax exclusive Taxable Amount NUMBER Y 18.4
amount for all line items C1
classified as C1 -
Exports for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtC2 Total tax exclusive Taxable Amount NUMBER Y 18.4
amount for all line items C2
classified as C2 – Zero
rating LPO for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtC3 Total tax exclusive Taxable Amount NUMBER Y 18.4
amount for all line items C3
classified as C3 Zero
rated by nature for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtD Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items D
classified as D Exempt
for VAT purposes (pass
0.0 if not applicable)
taxblAmtRvat Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items RVAT
classified as RVAT for
VAT purposes (pass 0.0
if not applicable)
taxblAmtE Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items E
classified as E -
Disbursements for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtF Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items F
classified as F for VAT
purposes (pass 0.0 if not
applicable)

102
taxblAmtIpl1 Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items IPL
attracting Insurance
Premium Levy (pass 0.0
if not applicable)
taxblAmtIpl2 Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items IPL2
attracting Insurance
Premium Levy 2 (pass
0.0 if not applicable)
taxblAmtTl Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items TL
attracting Tourism Levy
(pass 0.0 if not
applicable)
taxblAmtEcm Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items ECM
attracting Excise Coal
(pass 0.0 if not
applicable)
taxblAmtExeeg Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items EXEEG
attracting Excise
Electricity (pass 0.0 if
not applicable)
taxblAmtTot Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items TOT
attracting 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 Tax Rate C2 NUMBER Y 7,2
rating LPO – As per
standard codes
taxRtC3 Tax rate for C3 Zero Tax Rate C3 NUMBER Y 7,2
rated by nature – As per
standard codes
taxRtD Tax rate for D Exempt – Tax Rate D NUMBER Y 7,2
As per standard codes

103
taxRtRvat Tax rate for RVAT Tax Rate RVAT NUMBER Y 7,2
reverse VAT – As per
standard codes
taxRtE Tax rate E Tax Rate E NUMBER Y 7,2
Disbursements – As per
standard codes
taxRtF Rate for F Service Tax Rate F NUMBER Y 7,2
charge – 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 Tax Rate TL NUMBER Y 7,2
Levy – 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 NUMBER Y 7,2
Energy generation – As EXEEG
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)
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)

104
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 Tax Amount NUMBER Y 18,4
Insurance Premium IPL1
Levy IPL on invoice
(Pass 0.0 when not
applicable)
taxAmtIpl2 This is the total Tax Amount NUMBER Y 18,4
Insurance Premium IPL2
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 NUMBER Y 18,4
charged on all Excise ECM
Coal Mining line items

105
 on invoice (Pass 0.0
when not applicable)
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 Tax Amount NUMBER Y 18,4
on invoice] TOT
totTaxblAmt This is the total Tax Total TaxlAmt NUMBER Y 18,4
Exclusive Amount for
all line items on invoice
totTaxAmt This is the total tax Tot Tax Amount NUMBER Y 18,4
charged on all line items
on invoice
totAmt This is the total Tax Total Amount NUMBER Y 18,4
Inclusive Amount of all
line items on the
invoice
prchrAcptcYn This specifies whether a Purchase VARCHAR Y 1
purchase has been Accepted Yes or
accepted or not. (Pass N) No
remark This is any Remark VARCHAR N 400
comment/remark on the
transaction
regrId This refers to the ID of Registrant Id VARCHAR Y 20
the user of the system
adding the item
regrNm This refers to the Registrant Name VARCHAR Y 60
username of the person
making the sale on the
system.
modrId This refers to the ID of Modifier Id VARCHAR Y 20
the user of the system
adding the item
modrNm This refers to the Modifier Name VARCHAR Y 60
username 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 LPO Number VARCHAR N 50
Purchase order number

106
 as presented by the
buyer. This will be
validated.
currencyTyCd This is the currency code Currency Type VARCHAR Y 5
used in the transaction – Code
as 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 VARCHAR N 5
country of the item Country Code
being exported.
dbtRsnCd This is the reason code Debit Reason VARCHAR N 5
for issuing a debit. Code
invcAdjustReason This is the reason for Invoice VARCHAR N
adjusting an invoice Adjustment
Reason
principalId Principal ID for RVAT Principal ID NUMBER N 18,0
transaction with Agents
cashDcRt Cash/value discount rate Cash Discount NUMBER N 18,4
Rate
cashDcAmt Cash /value discount Cash discount NUMBER N 18,4
amount amount
List<Trns itemSeq Item Sequence Number Item Sequence NUMBER Y 11
SalesSave Number
WrItem>
itemCd This is the item Item Code VARCHAR Y 100
identifier on the
taxpayer’s system
itemClsCd This is the UNSCP code Item VARCHAR Y 10
assigned to the item Classification
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 Packaging Unit VARCHAR Y 5 See ‘6.4 Packaging
unit code assigned to the Code Unit’
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 Quantity Unit VARCHAR Y 5 See ‘6.5. Unit of
single item unit code Code Quantity’
assigned to the item as
per standard codes

107
qty This is the quantity of Quantity NUMBER Y 13,2
items being sold
prc This is the tax inclusive Unit Price NUMBER Y 18,4
price of the item
splyAmt This is the total amount Supply Amount NUMBER Y 18,4
of the supplied item (qty
* prc)
dcRt This is the discount rate Discount rate NUMBER Y 5,2
on line item (Pass 0.0 if
not applicable)
dcAmt This is the discount Discount NUMBER Y 18,4
amount on line item Amount
(Pass 0.0 if not
applicable)
isrccCd Insurance Company Insurance VARCHAR N 10
Code Company Code
isrccNm Insurance Company Insurance VARCHAR N 100
name Company name
isrcAmt This is the insurance Insurance NUMBER N 18,4
amount on line item Amount
vatCatCd This represents the tax Vat Category VARCHAR Y 5
category code for VAT Code
purposes on line item.
Pass null where not
applicable
exciseTxCatCd This represents the tax Excise Tax VARCHAR Y 5
category code for Excise Category Code
on line item. Pass null
where not applicable
vatTaxblAmt This is the Tax VAT Taxable NUMBER Y 18,4
Exclusive Amount for Amount
VAT at line-item level
(Pass 0.0 when not
applicable)
exciseTaxblAmt This is the Tax Excise Taxable NUMBER Y 18,4
Exclusive Amount for Amount
Excise at line-item level
(Pass 0.0 when not
applicable)
tlTaxblAmt This is the Tax Tourism Levy NUMBER Y 18,4
Exclusive Amount for Taxable Amount
Tourism Lecy at line-
item level (Pass 0.0
when not applicable)
iplTaxblAmt This is the Tax Insurance NUMBER Y 18,4
Exclusive Amount for Premium Levy
IPL at line-item level Taxable Amount

108
 (Pass 0.0 when not
applicable)
iplAmt This is the insurance Insurance NUMBER Y 18,4
premium levy tax Premium Levy
amount charged on the Amount
line item
tlAmt This is the Tourism Tourism Levy NUMBER Y 18,4
Levy amount charged on mount
the line 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 Amount
line item (Pass 0.0 when
not applicable)
totAmt This is the total Tax Total Amount NUMBER Y 18,4
Inclusive Amount of
the line item
JSON REQUEST SAMPLE

{"tpin":"1000000000","bhfId":"000","orgInvcNo":0,"cisInvcNo":"CIS001-1379","custTpin":"2000000000","custNm":"Smart
Customer","principalId":"8","salesTyCd":"N","rcptTyCd":"S","pmtTyCd":"01","salesSttsCd":"02","cfmDt":"20250508102010","salesDt":"20250508","stockRlsDt":null,"cnclReqDt":null,"cnclDt":null,"rfdDt
":null,"rfdRsnCd":null,"totItemCnt":2,"taxblAmtA":86.2069,"taxblAmtB":0.0,"taxblAmtC1":0.0,"taxblAmtC2":0.0,"taxblAmtC3":0.0,"taxblAmtD":0.0,"taxblAmtRvat":86.2069,"taxblAmtE":0.0,"taxblAmtF"
:0.0,"taxblAmtIpl1":0.0,"taxblAmtIpl2":0.0,"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,"taxAmt
C3":0.0,"taxAmtD":0.0,"taxAmtRvat":13.7931,"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":172.4
138,"totTaxAmt":27.5862,"cashDcRt":0,"cashDcAmt":0,"totAmt":200,"prchrAcptcYn":"N","remark":"","regrId":"admin","regrNm":"admin","modrId":"admin","modrNm":"admin","saleCtyCd":"1","lpoNum
ber":null,"currencyTyCd":"ZMW","exchangeRt":"1","destnCountryCd":"","dbtRsnCd":"","invcAdjustReason":"","itemList":[{"itemSeq":1,"itemCd":"20056","itemClsCd":"50102518","itemNm":"Bread","bc
d":"","pkgUnitCd":"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":"A","exciseTxCatCd":null,
"tlCatCd":null,"iplCatCd":null,"vatTaxblAmt":86.2069,"vatAmt":13.7931,"exciseTaxblAmt":0,"tlTaxblAmt":0.0,"iplTaxblAmt":0.0,"iplAmt":0.0,"tlAmt":0.0,"exciseTxAmt":0,"totAmt":100},{"itemSeq":2,"i
temCd":"20056","itemClsCd":"50102518","itemNm":"Reinsurance","bcd":"","pkgUnitCd":"BA","pkg":0.0,"qtyUnitCd":"BE","qty":1.0,"prc":100,"splyAmt":100,"dcRt":0.0,"dcAmt":0.0,"isrccCd":"","isrccN
m":"","isrcRt":0.0,"isrcAmt":0.0,"vatCatCd":"RVAT","exciseTxCatCd":null,"vatTaxblAmt":86.2069,"exciseTaxblAmt":0,"tlTaxblAmt":0.0,"tlCatCd":null,"tlAmt":0.0,"iplCatCd":null,"iplAmt":0.0,"iplTaxbl
Amt":0.0,"vatAmt":13.7931,"exciseTxAmt":0,"totAmt":100}]}

Save Sales Request – MTV

Object ID Object Attribute ID Attribute Description Attribute Data Type Required Data Format
Name Name Length
TrnsSalesSaveWrReq Save Sales tpin Taxpayer’s TPIN VARCHAR Y 10
Request identification number as
registered on core Tax
Administration System
TaxOnline
bhfId Taxpayer branch (store) Branch Id VARCHAR Y 3
location identifier

109
orgIncNo The invoice number Original Invoice NUMBER N 38
being referred to if you Number
are 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 Sales Type VARCHAR Y 5 See ‘6.7.

type of sale (Pass N) Code Transaction Type’
rcptTyCd Type of receipt Receipt Type VARCHAR Y 5 See ‘6.8. Sale
Code Receipt Type’
pmtTyCd The mode of payment Payment Type VARCHAR Y 5 See ‘6.9. Payment
used for this Code Method’
transaction
salesSttsCd Progress of transaction Invoice/Sale VARCHAR Y 5 See ‘6.10.
e.g. Approved, Refunded Status Code Transaction
etc. Progress’
cfmDt Date time when invoice Confirmation VARCHAR Y 14 yyyyMMddhhmmss
was issued Date
salesDt Date when sale was Sales Date VARCHAR Y 8 yyyyMMdd
made
stockRlsDt Date when the item was Stock Released VARCHAR N 14 yyyyMMddhhmmss
released from the Date
warehouse/branch
cnclReqDt Date time when a Cancell VARCHAR Y 14 yyyyMMddhhmmss
cancellation request Requested Date
was 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 VARCHAR Y 5 See ‘6.15. Refund
refund (empty string Reason Code Reason Code’
when not a refund)
totItemCnt Total number of items Total Item NUMBER Y 10
on the invoice Count

110
taxblAmtA Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line items A
classified as Standard
Rated for VAT purposes
(Pass 0.0 if not
applicable)
taxblAmtB Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line B
items classified as MTV
-Minimum Taxable
Value for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtC1 Total tax exclusive Taxable Amount NUMBER Y 18.4
amount for all line C1
items classified as C1 -
Exports for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtC2 Total tax exclusive Taxable Amount NUMBER Y 18.4
amount for all line C2
items classified as C2 –
Zero rating LPO for
VAT purposes (pass 0.0
if not applicable)
taxblAmtC3 Total tax exclusive Taxable Amount NUMBER Y 18.4
amount for all line C3
items classified as C3
Zero rated by nature for
VAT purposes (pass 0.0
if not applicable)
taxblAmtD Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line D
items classified as D
Exempt for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtRvat Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line RVAT
items classified as
RVAT for VAT
purposes (pass 0.0 if not
applicable)
taxblAmtE Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line E
items classified as E -
Disbursements for VAT

111
 purposes (pass 0.0 if not
applicable)
taxblAmtF Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line F
items classified as F for
VAT purposes (pass 0.0
if not applicable)
taxblAmtIpl1 Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line IPL
items attracting
Insurance Premium
Levy (pass 0.0 if not
applicable)
taxblAmtIpl2 Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line IPL2
items attracting
Insurance Premium
Levy 2 (pass 0.0 if not
applicable)
taxblAmtTl Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line TL
items attracting
Tourism Levy (pass 0.0
if not applicable)
taxblAmtEcm Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line ECM
items attracting Excise
Coal (pass 0.0 if not
applicable)
taxblAmtExeeg Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line EXEEG
items attracting Excise
Electricity (pass 0.0 if
not applicable)
taxblAmtTot Total tax exclusive Taxable Amount NUMBER Y 18,4
amount for all line TOT
items attracting 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

112
taxRtC1 Tax rate for C1- Tax Rate C1 NUMBER Y 7,2
Exports – As per
standard codes
taxRtC2 Tax rate for C2 Zero Tax Rate C2 NUMBER Y 7,2
rating LPO – As per
standard codes
taxRtC3 Tax rate for C3 Zero Tax Rate C3 NUMBER Y 7,2
rated 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 Tax Rate NUMBER Y 7,2
reverse VAT – As per RVAT
standard codes
taxRtE Tax rate E Tax Rate E NUMBER Y 7,2
Disbursements – As per
standard codes
taxRtF Rate for F Service Tax Rate F NUMBER Y 7,2
charge – 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 Tax Rate TL NUMBER Y 7,2
Levy – As per standard
codes
taxRtEcm Tax rate for Excise Tax Rate ECM NUMBER Y 7,2
Coal Mining – As per
standard codes
taxRtExeeg Tax rate Electricity and Tax Rate NUMBER Y 7,2
Energy generation – As EXEEG
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

113
 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)
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 Tax Amount NUMBER Y 18,4
Insurance Premium IPL1
Levy IPL on invoice
(Pass 0.0 when not
applicable)
taxAmtIpl2 This is the total Tax Amount NUMBER Y 18,4
Insurance Premium IPL2
Levy IPL2 (Re-

114
 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 NUMBER Y 18,4
charged on all Excise ECM
Coal Mining line items
on invoice (Pass 0.0
when not applicable)
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 Tax Amount NUMBER Y 18,4
on invoice] TOT
totTaxblAmt This is the total Tax Total TaxlAmt NUMBER Y 18,4
Exclusive Amount for
all line items on
invoice
totTaxAmt This is the total tax Tot Tax NUMBER Y 18,2
charged on all line Amount
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 VARCHAR Y 1
purchase has been Accepted Yes or
accepted or not. (Pass No
N)
remark This is any Remark VARCHAR N 400
comment/remark on the
transaction
regrId This refers to the ID of Registrant Id VARCHAR Y 20
the user of the system
adding the item
regrNm This refers to the Registrant VARCHAR Y 60
username of the person Name
making the sale on the
system.

115
 modrId This refers to the ID of Modifier Id VARCHAR Y 20
the user of the system
adding the item
modrNm This refers to the Modifier Name VARCHAR Y 60
username of the person
modifying the sale on
the system. (Default to
ADMIN when not
applicable)
saleCtyCd This is the sales Sales Category VARCHAR Y 2
category code. Code
(pass 1)
lpoNumber This is the Local LPO Number VARCHAR N 50
Purchase order number
as presented by the
buyer. This will be
validated.
currencyTyCd This is the currency Currency Type VARCHAR Y 5
code used in the Code
transaction – as per
standard codes
exchangeRt This is the exchange Exchange rate NUMBER Y 18,4
rate used in the
transaction.
destnCountryCd This is the destination Destination VARCHAR N 5
country of the item Country Code
being exported.
dbtRsnCd This is the reason code Debit Reason VARCHAR N 5
for issuing a debit. Code
invcAdjustReason This is the reason for Invoice VARCHAR N
adjusting an invoice Adjustment
Reason
cashDcRt Cash/value discount Cash Discount NUMBER N 18,4
rate Rate
cashDcAmt Cash /value discount Cash discount NUMBER N 18,4
amount amount
List<Trns itemSeq Item Sequence Number Item Sequence NUMBER Y 11
SalesSave Number
WrItem>
itemCd This is the item Item Code VARCHAR Y 100
identifier on the
taxpayer’s system
itemClsCd This is the UNSCP Item VARCHAR Y 10
code assigned to the Classification
item Code
itemNm This is the item name as Item Name VARCHAR Y 200
defined on your system

116
bcd This is the barcode Barcode VARCHAR N 20
assigned to the item
pkgUnitCd This is the packaging Packaging Unit VARCHAR Y 5 See ‘6.4 Packaging Unit’
unit code assigned to Code
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 Quantity Unit VARCHAR Y 5 See ‘6.5. Unit of
single item unit code Code Quantity’
assigned to 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 inclusive Unit Price NUMBER Y 18,4
price of the item
splyAmt This is the total amount Supply Amount NUMBER Y 18,4
of the supplied item
(qty * prc)
dcRt This is the discount rate Discount rate NUMBER Y 5,2
on line item (Pass 0.0 if
not applicable)
dcAmt This is the discount Discount NUMBER Y 18,2
amount on line item Amount
(Pass 0.0 if not
applicable)
isrccCd Insurance Company Insurance VARCHAR N 10
Code Company Code
isrccNm Insurance Company Insurance VARCHAR N 100
name Company name
isrcAmt This is the insurance Insurance NUMBER N 18,4
amount on line item Amount
vatCatCd This represents the tax Vat Category VARCHAR Y 5
category code for VAT Code
purposes on line item.
Pass null where not
applicable
exciseTxCatCd This represents the tax Excise Tax VARCHAR Y 5
category code for Category Code
Excise on line
item. Pass null where
not applicable
rrp Recommended Retailed RRP NUMBER N 18,4
Price
vatTaxblAmt This is the Tax VAT Taxable NUMBER Y 18,4
Exclusive Amount for Amount

117
 VAT at line-item level
(Pass 0.0 when not
applicable)
exciseTaxblAmt This is the Tax Excise Taxable NUMBER Y 18,4
Exclusive Amount for Amount
Excise at line-item level
(Pass 0.0 when not
applicable)
tlTaxblAmt This is the Tax Tourism Levy NUMBER Y 18,4
Exclusive Amount for Taxable
Tourism Lecy at line- Amount
item level (Pass 0.0
when not applicable)
iplTaxblAmt This is the Tax Insurance NUMBER Y 18,4
Exclusive Amount for Premium Levy
IPL at line-item level Taxable
(Pass 0.0 when not Amount
applicable)
iplAmt This is the insurance Insurance NUMBER Y 18,4
premium levy tax Premium Levy
amount charged on the Amount
line item
tlAmt This is the Tourism Tourism Levy NUMBER Y 18,4
Levy amount charged mount
on the line 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 Amount
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": "1000000000","bhfId": "000","cisInvcNo":"INV00004","orgInvcNo": 0,"custTpin": "2000000000","custNm": "Mulonda Mubita","salesTyCd": "N","rcptTyCd": "S","pmtTyCd": "01","salesSttsCd":
"02","cfmDt": "20240508102010","salesDt": "20240508","stockRlsDt": null,"cnclReqDt": null,"cnclDt": null,"rfdDt": null,"rfdRsnCd": null,"totItemCnt": 2,"taxblAmtA": 0.0,
"taxblAmtB": 215.5172,"taxblAmtC": 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.0,"taxblAmtTl": 0,"taxblAmtEcm": 0,"taxblAmtExeeg": 0.0,"taxblAmtTot": 0.0,"taxRtA": 16,"taxRtB": 16,"taxRtC1": 0,"taxRtC2": 0,"taxRtC3": 0,"taxRtD": 0,"taxRtRvat": 16,"taxRtE":
0,
"taxRtF": 10,"taxRtIpl1": 5,"taxRtIpl2": 0,"taxRtTl": 1.5,"taxRtEcm": 5,"taxRtExeeg": 3,"taxRtTot": 0,"taxAmtA": 0.0,"taxAmtB": 34.4828,"taxAmtC": 0.0,"taxAmtC1": 0.0,"taxAmtC2": 0.0,"taxAmtC3":
0.0,"taxAmtD": 0.0,"taxAmtRvat": 0.0,"taxAmtE": 0.0,"taxAmtF": 0,"taxAmtIpl1": 0,"taxAmtIpl2": 0.0,"taxAmtTl": 0,"taxAmtEcm": 0.0,"taxAmtExeeg": 0.0,"taxAmtTot": 0.0,"totTaxblAmt": 215.5172,

118
 "totTaxAmt": 34.4828,"totAmt": 200,"prchrAcptcYn": "N","remark": "","regrId": "admin","regrNm": "admin","modrId": "admin","modrNm": "admin","saleCtyCd": "1","lpoNumber": null,"currencyTyCd":
"ZMW","exchangeRt": "1","destnCountryCd": "","dbtRsnCd": "","invcAdjustReason":"","receipt":{"prchrAcptcYn":"N"},"itemList": [{"itemSeq": 1,"itemCd": "20044","itemClsCd": "50102517",
"itemNm": "Chicken Wings","bcd": "","pkgUnitCd": "BA","pkg": 0.0,"qtyUnitCd": "BE","qty": 1.0,"rrp": 150,"prc": 100,"splyAmt": 150,"dcRt": 0.0,"dcAmt": 0.0,"isrccCd": "","isrccNm": "","isrcRt":
0.0,"isrcAmt": 0.0,"vatCatCd": "B","exciseTxCatCd": null,"vatTaxblAmt": 129.3103,"exciseTaxblAmt": 0,"vatAmt": 20.6897,"exciseTxAmt": 0,"totAmt": 100},{"itemSeq": 2,"itemCd":
"20044","itemClsCd": "50102517","itemNm": "Chips","bcd": "","pkgUnitCd": "BA","pkg": 0.0,"qtyUnitCd": "BE","qty": 1.0,"rrp": 50,"prc": 100,"splyAmt": 100,"dcRt": 0.0,"dcAmt": 0.0,"isrccCd":
"","isrccNm": "","isrcRt": 0.0,"isrcAmt": 0.0,"vatCatCd": "B","exciseTxCatCd": null,"vatTaxblAmt": 86.2069,"exciseTaxblAmt": 0,"vatAmt": 13.7931,"exciseTxAmt": 0,"totAmt": 100}]}

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"}}

SELECT INVOICE
● Endpoint: /trnsSales/selectInvoice
● Request method: POST.
● Requirement: OPTIONAL
● Description: This endpoint facilitates the retrieval of invoice transactions already posted to ZRA.
● Request Parameters: TPIN, Branch ID, Invoice SDC ID and CIS Invoice number.
● Response: Returns details of an already uploaded invoice.
● 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.

119
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
invcSdcId This is the device id where the invoice was Invoice SDC Id VARCHAR Y 13
issued from
cisInvcNo This is the invoice number being retrieved CIS Invoice Number VARCHAR Y 50

JSON REQUEST SAMPLE

{"tpin": "1000000000", "bhfId": "000", "invcSdcId": "SDC0060000356", "cisInvcNo": "CIS001-7"}

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": "20240613184837", "data": { "cisInvcNo": "CIS001-7", "rcptNo": 21, "intrlData": "YO53RJAA7IKAGABBV4BWJ5SS4Q", "rcptSign":
"STKXHWQ72I2O4WIX", "vsdcRcptPbctDate": "2024-06-13 18:46:20", "sdcId": "SDC0060000356", "mrcNo": "WIS00001200", "qrCodeUrl":
"https://sandboxportal.zra.org.zm/common/link/ebm/receipt/indexEbmReceiptData?Data=1000000668000STKXHWQ72I2O4WIX"}}

120
TAX INVOICE ENHANCEMENT REQUEST

ENDPOINT: /trnsSale/saveSales

Attribute Leng
Object ID Object name Attribute ID Attribute name description Data Type Required th Format

commInvcNo Commercial Invoice Number Number 38

see ‘6.24’. Customer type

custTyCd Customer category Varchar 5 code’

see ‘6.25’ Travelpurpose

travelPurposeCd Travel purpose code Varchar 5 code

see ‘6.25’ travel purpose

nonResidenTyCd customer Non residence type or category Varchar 5 code’

permenentRsdnc
Adrs Customer Permanent residence address Varchar 100

permanentRsncC See ‘6.3. Country Codes’

ountryCd Customer Permanent residence country code Varchar 5

See ‘6.3. Country Codes’

originCountryCd Origin country code Varchar 5

121
 saleDetail
See ‘6.3. Country Codes’
countriesVisited List of countries visited List<String> 5

countriesToBeVisit See ‘6.3. Country Codes’

ed List of countries to be visited List<String> 5

tourPkgNmDtl List of tour package names List<String> 100

JSON RESPONSE SAMPLE

{"tpin":"1234567890","bhfId":"000","orgInvcNo":0,"cisInvcNo":"9","custTpin":"1000000000","custNm":"Walk-In
Customer","salesTyCd":"N","rcptTyCd":"S","pmtTyCd":"01","salesSttsCd":"02","cfmDt":"20250528173452","salesDt":"20250528","stockRlsDt":"20250528173452","cnclReqDt":"20250528173452","cnclDt":null,"t
otItemCnt":1,"taxblAmtA":0,"taxblAmtB":0,"taxblAmtC1":7000,"taxblAmtC2":0,"taxblAmtC3":0,"taxblAmtD":0,"taxblAmtRvat":0,"taxblAmtE":0,"taxblAmtF":0,"taxblAmtIpl1":0,"taxblAmtIpl2":0,"taxblAmtTl":0,
"taxblAmtEcm":0,"taxblAmtExeeg":0,"taxblAmtTot":0,"taxAmtA":0,"taxAmtB":0,"taxAmtC":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":7000,"totTaxAmt":0,"totAmt":7000,"taxRtA":16,"taxRtB":16,"taxRtC1":0,"taxRtC2":0,"taxRtC3":0,"taxRtD":0,"tlAmt":
0,"taxRtRvat":16,"taxRtE":0,"taxRtF":10,"taxRtIpl1":5,"taxRtIpl2":0,"taxRtTl":1.5,"taxRtEcm":5,"taxRtExeeg":3,"taxRtTot":0,"prchrAcptcYn":"N","remark":"","regrId":"admin","regrNm":"admin","modrId":"admin"
,"modrNm":"admin","lpoNumber":null,"currencyTyCd":"ZMW","exchangeRt":"1.0","destnCountryCd":"RW","dbtRsnCd":null,"invcAdjustReason":null,"bankCd":"ABSA","swiftCd":"3123","bnkBranch":"Lusaka","
bankAccntNo":"121321312","bankAccntHldr":"Yvette","custTyCd":"01","travelPurposeCd":"01","permanentRsdncAdrs":"Gasaba
downtown","permanentRsdncCountryCd":"RW","originCountryCd":"RW","bookingAgentNm":"Lusaka
Tour","tourPackageNames":[],"rebateInvcList":[],"itemList":[{"itemSeq":1,"itemCd":"ZA2NTNO0000027","itemClsCd":"25101917","itemNm":"Rice","bcd":"","pkgUnitCd":"NT","pkg":1,"qtyUnitCd":"NO","qty":1,
"prc":7000,"splyAmt":7000,"dcRt":0,"dcAmt":0,"vatCatCd":"C1","vatTaxblAmt":7000,"vatAmt":0,"totAmt":7000}]}

Tax invoice enhancement Response

Save Sales Response

122
Object ID Object Name Attribute ID Attribute Description Attribute Name Data Type Require Data Format
d Length

TrnsSalesSaveWrR Save resultCd This is the VSDC response code Result Code VARCHAR 3
es Sales
Response resultMsg This is the VSDC response message Result Message VARCHAR 200

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"}}

123
 5.10. Commercial invoice information

SAVE COMMERCIAL INVOICE

· Endpoint:/trnsSales/saveCommercialInvoice
· Request method: POST
· Requirement: Required for mining sector
· Description: For all export of goods and incidental services (e.g. Transport and Insurance), suppliers will be required to issue a
commercial invoice using Smart Invoice. It serves as a customs declaration provided by the person or corporation that is exporting an
item across international borders. (It is used in capturing imports and exports entries)
· Request Parameters: Invoice data including sender details, receiver details, transporter details, delivery details, shipment details
invoice type, invoice number, and transaction timestamp.
· Response: Returns the success or failure of invoice data submission.
· Dependency: A commercial invoice is required before any export of minerals, and should be followed by customs declaration,
Provisional invoice (If applicable) and Final Tax Invoice or Final credit note
· Commercial invoice acquittal process: A commercial invoice is acquitted upon creating associated provisional invoice or Final Tax
invoice.

Attribute Data Require Data

Object ID Oject name ID Attribute Name Attribute Description Type d Length Format
TrnsSaveComercialInv Commercial VARCHA
oice Invoice 1 tpin TPIN R Yes 10
VARCHA
2 bhfId Branch ID R Yes 3
VARCHA
3 customsCd Customs Code R Yes 50
4 invcNo Commercial Invoice number NUMBER Yes 38
VARCHA
5 cisInvcNo CIS Invoice Number R Yes 50
VARCHA
6 orgSdcId Original Invoice Number R No 14

124
 7 orgInvcNo Original Invoice number NUMBER No 38
VARCHA
yyyyMMdd
8 invcDt Invoice date R Yes 8
VARCHA
9 ucrNo UCR Number R Yes 20
VARCHA
10 loadingPort Loading Port R No -
VARCHA
11 consignmentNo Consignment Number R No -
VARCHA
yyyyMMddhhmmss
12 shippingDt Shipping date R Yes -
VARCHA
13 shipmentNo Shipment Number R Yes 20
VARCHA
See 6.6. Currency
14 currencyTyCd Currency R Yes 5
15 exchangeRt Exchange rate NUMBER Yes -
VARCHA
16 exportRsnTxt Reason for export description R Yes 100
VARCHA
17 senderAddrssDesc Sender address R Yes 100
VARCHA
18 senderPostalCd Sender postal code/City R Yes 50
VARCHA
6.3. Countries code
19 exportCountryCd Country of Export code R Yes 5
VARCHA
20 senderNm Sender name R Yes 255
VARCHA
21 senderTelNo Sender telephone R Yes 13
VARCHA
22 senderEmail Sender email R Yes 100
VARCHA
23 rcvCompanyNm Receiver company name R Yes 255
VARCHA
24 rcvAddrssDesc Receiver address R Yes 100
VARCHA
25 rcvPostalCd Receiver postal code/city R Yes 100
VARCHA
26 destnCountryCd Country of Destination code R Yes 5 See 6.3. Countries code
VARCHA
27 dischargePort Port of Discharge R Yes 50
VARCHA 1.20. Destination
28 dstntnIncotermCd Destination incoterm code R Yes 5 Incortem

125
 VARCHA
29 dstntnIncoterm Destination incoterm R No -
dstntnIncotermOthe VARCHA
30 r Other departure incoterm R Yes 30
VARCHA
31 rcvNm Receiver name R Yes 255
VARCHA
32 rcvTelNo Receiver telephone R Yes 15
VARCHA
33 rcvEmail Receiver email R Yes 100
VARCHA
34 dlvryCompanyNm Delivery company name R Yes 255
VARCHA
35 dlvryAddrssDesc Delivery address R Yes 100
VARCHA
36 dlvryPostalCd Delivery postal code/city R Yes 50
VARCHA
37 dlvryLoc Delivery location R Yes 100
VARCHA
38 loadingPortCd Port of Loading R Yes 5 6.19. Zambia ports
VARCHA 6.21. Departure
39 dprtrIncotermCd Departure incoterm R Yes 5 Incoterm
VARCHA
40 dprtrIncoterm Departure incoterm R No -
VARCHA
41 dprtrIncotermOther Other departure incoterm R Yes 20
VARCHA
42 dlvryContact Delivery contact R Yes 50
VARCHA
43 dlvryTelNo Delivery telephone R Yes 15
VARCHA
44 dlvryEmail Delivery email R Yes 100
VARCHA
45 transporterNm Name of transporter R Yes 255
VARCHA
46 transporterTpin TPIN of Transporter R No 10
transporterAddrssD VARCHA
47 esc Address of Transporter R Yes 100
VARCHA
6.3. Countries code
48 orgnNatCd Country of Origin of Transporter R Yes 5
VARCHA
49 transporterInvcNo Transporter’s Invoice Number R No 30

126
 Transporter’s vehicle registration VARCHA
50 trnsptVhclRegNo number R Yes 20
VARCHA
51 vesselNo Vessel Number R Yes 50
52 totAmt Total Commercial Invoice Value NUMBER Yes -
VARCHA
53 bankCd Beneficiary Bank code R Yes 5 6.23. Banks
VARCHA
54 swiftCd SWIFT Code R Yes 20
VARCHA
55 bnkBranch Bank Branch R Yes 20
VARCHA
56 bankAccntNo Beneficiary Bank account no R Yes 50
VARCHA
57 bankAccntHldr Beneficiary Bank account holder R Yes 50
VARCHA
58 pymntTerms Terms of payment R Yes 100
VARCHA See ‘6.7. Transaction
59 salesTyCd Sales Type Code R No - type’
VARCHA
See ‘6.8. Sale
60 rcptTyCd Receipt Type Code R Yes 5
VARCHA See 1.22. Commercial
61 salesSttsCd Sales Status Code R Yes 5 Invoice status
VARCHA See ‘6.15. Refund
62 rfdRsnCd Refund Reason Code R No 5 Reason Code’
63 totItemCnt Total Item Count NUMBER Yes -
64 subTot Subtotal NUMBER Yes -
65 totFreightCosts Total Freight Costs NUMBER Yes -
66 totHandlingCosts Total Handling Costs NUMBER Yes -
67 totStorageCosts Total Storage Costs NUMBER Yes -
68 totInsuranceCosts Total Insurance Costs NUMBER Yes -
69 totOtherCosts Total Other Costs NUMBER Yes -
VARCHA
70 buyerRefNo Buyer Reference R Yes 50
VARCHA
71 frghtForwarder Freight Forwarder R Yes 50
VARCHA
72 regDt Registration Date R Yes -
itemList Item List 1 itemSeq Item sequence NUMBER YES 3

127
 VARCHA
2 itemCd Item code R YES 100
VARCHA
3 itemNm Item name R YES 200
VARCHA
4 itemClsCd Item class code R YES 10 See UNSPC code
VARCHA
5 hsCd HS code R 20
6 pkg Number of Package NUMBER 18,4
VARCHA See ‘6.4 Packaging
7 pkgUnitCd Packaging Unit code R 5 Unit’
8 qty Quantity NUMBER YES 18,4
VARCHA See ‘6.5. Unit of
9 qtyUnitCd quantity unit code R YES 5 Quantity’
10 prc Tax inclusive price of an item NUMBER YES 18,4
11 shpmntVal Shipment value NUMBER YES 18,4
12 dcRt Discount rate NUMBER YES 18,4
13 dcAmt discount amount NUMBER YES 18,4
14 subTot Sub total NUMBER YES 18,4
15 freightCosts Freight costs NUMBER YES 18,4
16 handlingCosts Handling costs NUMBER YES 18,4
17 storageCosts Storage costs NUMBER YES 18,4
18 insuranceCosts Insurance costs NUMBER YES 18,4
19 otherCosts Other costs NUMBER YES 18,4
20 totAmt Total commercial invoice value NUMBER YES 18,4
{"tpin":"100000000","bhfId":"000","cisInvcNo":"CI/1","orgSdcId":null,"orgInvcNo":0,"invcDt":"20241015","salesTyCd":"CI","rcptTyCd":"S","salesSttsCd":"01","shippingDt":"20231015120000","shipmentNo
":"21212","ucrNo":"SHIP12345","currencyTyCd":"USD","exchangeRt":1.2345,"exportRsnTxt":"Reason for export example","senderAddrssDesc":"Addis abba
Dr","senderPostalCd":"12345","exportCountryCd":"SA","senderNm":"Bupe Karima","senderTelNo":"0912345678","senderEmail":"sender@zra.zm","rcvCompanyNm":"Google cloud Datacenter
Ltd","rcvAddrssDesc":"456 Market St","rcvPostalCd":"54321","destnCountryCd":"SA","dischargePort":"Cape town","buyerRefNo":"BUY_REF_001","rcvNm":"Alex
Zulu","rcvTelNo":"0987654321","rcvEmail":"receiver@zulu.com","dlvryCompanyNm":"Delivery Company","dlvryAddrssDesc":"789 Industrial Rd","dlvryPostalCd":"67890","dlvryLoc":"Warehouse
1","loadingPortCd":"QEW","dlvryContact":"John Doe","dlvryTelNo":"1230987654","dlvryEmail":"delivery@example.com","transporterNm":"Transporter
Inc","transporterTpin":"TRAN123456","transporterAddrssDesc":"101 Transport St","orgnNatCd":"US","transporterInvcNo":"TRANINV123","frghtForwarder":"Lusaka logistics
Ltd","vesselNo":"VESSEL001","bankCd":"BOZ","swiftCd":"SWIFT01","bnkBranch":"BRANCH01","bankAccntNo":"12345678901234","bankAccntHldr":"Account Holder","pymntTerms":"90
DAYS","totItemCnt":2,"totAmt":10184,"subTot":10000,"totFreightCosts":100,"totHandlingCosts":50,"totStorageCosts":20,"totInsuranceCosts":10,"totOtherCosts":4,"consignmentNo":"CONS12345","customsC
d":"CUST01","trnsptVhclRegNo":"VHCL123","dprtrIncotermCd":"EXW","dprtrIncotermOther":"Makeni","dstntnIncotermCd":"EXW","dstntnIncotermOther":"Durban","regrId":"ADMIN","regrNm":"admin","
regDt":"20241015100000","itemList":[{"itemSeq":1,"itemCd":"ITEM001","itemNm":"Product
A","itemClsCd":"CLS001","hsCd":"HS123456","pkg":10.0000,"pkgUnitCd":"BA","qty":100.0000,"qtyUnitCd":"4B","prc":50.0000,"splyAmt":5000.0000,"freightCosts":50.0000,"handlingCosts":25.0000,"stora
geCosts":10.0000,"insuranceCosts":5.0000,"otherCosts":2.0000,"totAmt":5092.0000},{"itemSeq":2,"itemCd":"ITEM002","itemNm":"Product

128
 B","itemClsCd":"CLS001","hsCd":"HS123456","pkg":10.0000,"pkgUnitCd":"BA","qty":100.0000,"qtyUnitCd":"4B","prc":50.0000,"splyAmt":5000.0000,"freightCosts":50.0000,"handlingCosts":25.0000,"stora
geCosts":10.0000,"insuranceCosts":5.0000,"otherCosts":2.0000,"totAmt":5092.0000}]}

Commercial invoice Response

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

TrnsSalesSaveWrR Save resultCd This is the VSDC response code Result Code VARCHAR 3
es Sales
Response resultMsg This is the VSDC response message Result Message VARCHAR 200

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":
"http://172.21.3.130:8081/indexCommInvoiceData?Data=10004266010006BJQHZPR6ZPG7LJ4"}}

REVERSE A COMMERCIAL INVOICE/CREDIT NOTE

· Endpoint:/trnsSales/saveCommercialInvoice
· Request method: POST
· Requirement: Required when reversing a commercial invoice

Object ID Oject name Attribute ID Attribute Name Attribute Description Data Type Required Data Length Format
TrnsSaveComercialInv Commercial VARCHA
oice Invoice 1 tpin TPIN R Yes 10
VARCHA
2 bhfId Branch ID R Yes 3

129
 VARCHA
3 customsCd Customs Code R Yes 50
4 invcNo Commercial Invoice number NUMBER Yes 38
VARCHA
5 cisInvcNo CIS Invoice Number R Yes 50
VARCHA
6 orgSdcId Original Invoice Number R No 14
7 orgInvcNo Original Invoice number NUMBER No 38
VARCHA
yyyyMMdd
8 invcDt Invoice date R Yes 8
VARCHA
9 ucrNo UCR Number R Yes 20
VARCHA
10 loadingPort Loading Port R No -
VARCHA
11 consignmentNo Consignment Number R No -
VARCHA
yyyyMMddhhmmss
12 shippingDt Shipping date R Yes -
VARCHA
13 shipmentNo Shipment Number R Yes 20
VARCHA
See 6.6. Currency
14 currencyTyCd Currency R Yes 5
15 exchangeRt Exchange rate NUMBER Yes -
VARCHA
16 exportRsnTxt Reason for export description R Yes 100
VARCHA
17 senderAddrssDesc Sender address R Yes 100
VARCHA
18 senderPostalCd Sender postal code/City R Yes 50
VARCHA
6.3. Countries code
19 exportCountryCd Country of Export code R Yes 5
VARCHA
20 senderNm Sender name R Yes 255
VARCHA
21 senderTelNo Sender telephone R Yes 13
VARCHA
22 senderEmail Sender email R Yes 100
VARCHA
23 rcvCompanyNm Receiver company name R Yes 255
VARCHA
24 rcvAddrssDesc Receiver address R Yes 100

130
 VARCHA
25 rcvPostalCd Receiver postal code/city R Yes 100
VARCHA
26 destnCountryCd Country of Destination code R Yes 5 See 6.3. Countries code
VARCHA
27 dischargePort Port of Discharge R Yes 50
VARCHA 1.20. Destination
28 dstntnIncotermCd Destination incoterm code R Yes 5 Incortem
VARCHA
29 dstntnIncoterm Destination incoterm R No -
dstntnIncotermOthe VARCHA
30 r Other departure incoterm R Yes 30
VARCHA
31 rcvNm Receiver name R Yes 255
VARCHA
32 rcvTelNo Receiver telephone R Yes 15
VARCHA
33 rcvEmail Receiver email R Yes 100
VARCHA
34 dlvryCompanyNm Delivery company name R Yes 255
VARCHA
35 dlvryAddrssDesc Delivery address R Yes 100
VARCHA
36 dlvryPostalCd Delivery postal code/city R Yes 50
VARCHA
37 dlvryLoc Delivery location R Yes 100
VARCHA
38 loadingPortCd Port of Loading R Yes 5 6.19. Zambia ports
VARCHA 6.21. Departure
39 dprtrIncotermCd Departure incoterm R Yes 5 Incoterm
VARCHA
40 dprtrIncoterm Departure incoterm R No -
VARCHA
41 dprtrIncotermOther Other departure incoterm R Yes 20
VARCHA
42 dlvryContact Delivery contact R Yes 50
VARCHA
43 dlvryTelNo Delivery telephone R Yes 15
VARCHA
44 dlvryEmail Delivery email R Yes 100
VARCHA
45 transporterNm Name of transporter R Yes 255

131
 VARCHA
46 transporterTpin TPIN of Transporter R No 10
transporterAddrssD VARCHA
47 esc Address of Transporter R Yes 100
VARCHA
6.3. Countries code
48 orgnNatCd Country of Origin of Transporter R Yes 5
VARCHA
49 transporterInvcNo Transporter’s Invoice Number R No 30
Transporter’s vehicle registration VARCHA
50 trnsptVhclRegNo number R Yes 20
VARCHA
51 vesselNo Vessel Number R Yes 50
52 totAmt Total Commercial Invoice Value NUMBER Yes -
VARCHA
53 bankCd Beneficiary Bank code R Yes 5 6.23. Banks
VARCHA
54 swiftCd SWIFT Code R Yes 20
VARCHA
55 bnkBranch Bank Branch R Yes 20
VARCHA
56 bankAccntNo Beneficiary Bank account no R Yes 50
VARCHA
57 bankAccntHldr Beneficiary Bank account holder R Yes 50
VARCHA
58 pymntTerms Terms of payment R Yes 100
VARCHA See ‘6.7. Transaction
59 salesTyCd Sales Type Code R No - type’
VARCHA
See ‘6.8. Sale
60 rcptTyCd Receipt Type Code R Yes 5
VARCHA See 1.22. Commercial
61 salesSttsCd Sales Status Code R Yes 5 Invoice status
VARCHA See ‘6.15. Refund
62 rfdRsnCd Refund Reason Code R Yes 5 Reason Code’
63 totItemCnt Total Item Count NUMBER Yes -
64 subTot Subtotal NUMBER Yes -
65 totFreightCosts Total Freight Costs NUMBER Yes -
66 totHandlingCosts Total Handling Costs NUMBER Yes -
67 totStorageCosts Total Storage Costs NUMBER Yes -
68 totInsuranceCosts Total Insurance Costs NUMBER Yes -

132
 69 totOtherCosts Total Other Costs NUMBER Yes -
VARCHA
70 buyerRefNo Buyer Reference R Yes 50
VARCHA
71 frghtForwarder Freight Forwarder R Yes 50
VARCHA
72 regDt Registration Date R Yes -
1 itemSeq Item sequence NUMBER YES 3
VARCHA
2 itemCd Item code R YES 100
VARCHA
3 itemNm Item name R YES 200
VARCHA
4 itemClsCd Item class code R YES 10 See UNSPC code
VARCHA
5 hsCd HS code R 20
6 pkg Number of Package NUMBER 18,4
VARCHA See ‘6.4 Packaging
7 pkgUnitCd Packaging Unit code R 5 Unit’
8 qty Quantity NUMBER YES 18,4
VARCHA See ‘6.5. Unit of
9 qtyUnitCd quantity unit code R YES 5 Quantity’
10 prc Tax inclusive price of an item NUMBER YES 18,4
11 shpmntVal Shipment value NUMBER YES 18,4
12 dcRt Discount rate NUMBER YES 18,4
13 dcAmt discount amount NUMBER YES 18,4
14 subTot Sub total NUMBER YES 18,4
15 freightCosts Freight costs NUMBER YES 18,4
16 handlingCosts Handling costs NUMBER YES 18,4
17 storageCosts Storage costs NUMBER YES 18,4
18 insuranceCosts Insurance costs NUMBER YES 18,4
19 otherCosts Other costs NUMBER YES 18,4
itemList Item List 20 totAmt Total commercial invoice value NUMBER YES 18,4
{"tpin":"1000426601","bhfId":"000","cisInvcNo":"CI/14","orgSdcId":"SDC0030000001","orgInvcNo":2,"rfdRsnCd":"01","invcDt":"20241015","salesTyCd":"CI","rcptTyCd":"R","salesSttsCd":"01","shippingDt":"20
231015120000","shipmentNo":"21212","ucrNo":"SHIP12345","currencyTyCd":"USD","exchangeRt":1.2345,"exportRsnTxt":"Reason for export example","senderAddrssDesc":"Addis abba
Dr","senderPostalCd":"12345","exportCountryCd":"SA","senderNm":"Bupe Karima","senderTelNo":"0912345678","senderEmail":"sender@zra.zm","rcvCompanyNm":"Google cloud Datacenter
Ltd","rcvAddrssDesc":"456 Market St","rcvPostalCd":"54321","destnCountryCd":"SA","dischargePort":"Cape town","buyerRefNo":"BUY_REF_001","rcvNm":"Alex

133
 Zulu","rcvTelNo":"0987654321","rcvEmail":"receiver@zulu.com","dlvryCompanyNm":"Delivery Company","dlvryAddrssDesc":"789 Industrial Rd","dlvryPostalCd":"67890","dlvryLoc":"Warehouse
1","loadingPortCd":"QEW","dlvryContact":"John Doe","dlvryTelNo":"1230987654","dlvryEmail":"delivery@example.com","transporterNm":"Transporter
Inc","transporterTpin":"TRAN123456","transporterAddrssDesc":"101 Transport St","orgnNatCd":"US","transporterInvcNo":"TRANINV123","frghtForwarder":"Lusaka logistics
Ltd","vesselNo":"VESSEL001","bankCd":"BOZ","swiftCd":"SWIFT01","bnkBranch":"BRANCH01","bankAccntNo":"12345678901234","bankAccntHldr":"Account Holder","pymntTerms":"90
DAYS","totItemCnt":2,"totAmt":10184,"subTot":10000,"totFreightCosts":100,"totHandlingCosts":50,"totStorageCosts":20,"totInsuranceCosts":10,"totOtherCosts":4,"consignmentNo":"CONS12345","customsCd":"C
UST01","trnsptVhclRegNo":"VHCL123","dprtrIncotermCd":"EXW","dprtrIncotermOther":"Makeni","dstntnIncotermCd":"EXW","dstntnIncotermOther":"Durban","regrId":"ADMIN","regrNm":"admin","regDt":"202
41015100000","itemList":[{"itemSeq":1,"itemCd":"ITEM001","itemNm":"Product
A","itemClsCd":"CLS001","hsCd":"HS123456","pkg":10.0000,"pkgUnitCd":"BA","qty":100.0000,"qtyUnitCd":"4B","prc":50.0000,"splyAmt":5000.0000,"freightCosts":50.0000,"handlingCosts":25.0000,"storageCost
s":10.0000,"insuranceCosts":5.0000,"otherCosts":2.0000,"totAmt":5092.0000},{"itemSeq":2,"itemCd":"ITEM002","itemNm":"Product
B","itemClsCd":"CLS001","hsCd":"HS123456","pkg":10.0000,"pkgUnitCd":"BA","qty":100.0000,"qtyUnitCd":"4B","prc":50.0000,"splyAmt":5000.0000,"freightCosts":50.0000,"handlingCosts":25.0000,"storageCost
s":10.0000,"insuranceCosts":5.0000,"otherCosts":2.0000,"totAmt":5092.0000}]}

Credit note Response

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

TrnsSalesSaveWrR Save resultCd This is the VSDC response code Result Code VARCHAR 3
es Sales
Response resultMsg This is the VSDC response message Result Message VARCHAR 200

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":
"http://172.21.3.130:8081/indexCommInvoiceData?Data=10004266010006BJQHZPR6ZPG7LJ4"}}

134
 5.11. Provisional and Final invoice Information

The Provisional invoice API facilitates the transmission of detailed provisional invoice 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 provisional invoice information, ensuring accurate invoicing and efficient management of
customer transactions.

SAVE PROVISIONAL INVOICE

● Endpoint: /trnsSales/saveProvisionalInvoice
● Request method: POST.
● Requirement: Required for mining sector
● Description: This endpoint facilitates the submission of provisional invoice data from the third-party system into Smart Invoice.
● Request Parameters: 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 provisional invoice transaction, 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.
● Business rule:
o No Provisional Invoice must be created without related Commercial Invoices.
o Each provisional invoice must make reference to the commercial Invoices.
o The commercial invoice must have been already issued.
o The commercial invoice must be picked without changes to quantities
o The provisional invoice must be equal the quantity of Commercial Invoices issued
o A provisional invoice can reference to multiple commercial 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.

135
Object ID Object name Attribute ID Attribute name Attribute description Data Type Required Length Format

TrnsSaveProvisionalnvoi Save Provisional

ce invoice
tpin Taxpayer Identification Number Varchar 10

bhfId Branch or Business Unit ID Varchar 3

orgInvcNo Original Invoice Number Number 38,0

cisInvcNo CIS Invoice Number Varchar 50

custNm Customer Name Varchar 50

Code associated with type of invoice ( (e.g., PI for See ‘6.7.

salesTyCd Provisional invoice) Varchar 5 Transaction Type

See ‘6.8. Sale

rcptTyCd Receipt Type Code Varchar 5 Receipt Type’

See ‘1.9. Payment

pmtTyCd Payment Type Code Varchar 5 Method’

See ‘6.10.
Transaction
salesSttsCd Sales Status Code Varchar 5 Progress’

136
 Confirmation Date (format:
cfmDt YYYYMMDDHHMMSS) Varchar 14

salesDt Sales Date (format: YYYYMMDD) Varchar 8

See ‘6.15. Refund

rfdRsnCd Refund Reason Code Varchar 5 Reason code’

invcAdjustR
eason Invoice Adjustment Reason Varchar 255

totItemCnt Total Item Count Number 38,0

taxblAmtC1 Taxable Amount (Category 1) Number 18,4

taxRtC1 Tax Rate (Category 1) Number 5,2

taxAmtC1 Tax Amount (Category 1) Number 18,4

totTaxblAmt Total Taxable Amount Number 18,4

totTaxAmt Total Tax Amount Number 18,4

remark Remarks or Additional Information Varchar 255

137
prchseOrdrN
o Purchase Order Number Varchar YES 15

commInvcN List<Long
oList Commercial Invoice Number > YES 38,0

treatmentCha
rges Treatment Charges (deduction) Number YES 18,4

processingC
harges Processing Charges (deduction) Number YES 18,4

tollingCharg
es Tolling Charges (deduction) Number YES 18,4

refineryChar
ges Refinery Charges (deduction) Number YES 18,4

freightOrTra
nsport Freight or Transportation Charges (deduction) Number YES 18,4

moistureDed
uctions Moisture Deductions (deduction) Number YES 18,4

insolubleDed
uctions Insoluble Deductions (deduction) Number YES 18,4

totalDeductio
ns Total Deductions Number YES 18,4

totAmt Total Amount Number YES 18,4

regrId Registrar ID (user performing registration) Varchar YES 50

138
 regrNm Registrar Name Varchar YES 50

modrId Modifier ID (user performing modification) Varchar YES 50

modrNm Modifier Name Varchar YES 50

currencyTyC
d Currency Type Code (e.g., USD) Varchar YES 5

exchangeRt Exchange Rate Number YES 18,4

itemList Item list

itemSeq Item Sequence Number 10,0

itemCd Item Code Varchar 10

itemClsCd Item Classification Code Varchar 10

itemNm Item Name Varchar 50

See ‘6.4 Packaging

pkgUnitCd Package Unit Code Varchar 5 Unit’

pkg Package Quantity Number 10,2

139
 See ‘6.5. Unit of
qtyUnitCd Quantity Unit Code String 5 Quantity’

qty Quantity Number 18,10

prc Tax inclusive price of an item Number 18,10

splyAmt Supply Amount Number 18,4

dcRt Discount Rate Number 5,2

dcAmt Discount Amount Number 18,4

vatCatCd VAT Category Code String 5

vatTaxblAmt VAT Taxable Amount Number 18,4

vatAmt VAT Amount Number 18,4

totAmt Total Amount Number 18,4

JSON REQUEST SAMPLE

140
 {"tpin":"1000000000","bhfId":"000","custTpin":"1000000001","destnCountryCd":"RW","cisInvcNo":"PROV00022433235","orgCommInvcNoList":[8],"totTaxAmt":1350.1063,"taxRtTot":0,"taxRtExeeg":3,"taxblAmtC3":0,"
taxRtA":16,"taxblAmtC2":0,"taxRtB":16,"rfdDt":null,"taxblAmtC1":0,"taxRtD":0,"taxRtE":0,"taxRtF":10,"currencyTyCd":"ZMW","orgInvcNo":"0","taxAmtTot":0,"taxblAmtIpl2":0,"salesSttsCd":"02","taxblAmtIpl1":0,"mo
drId":"1001666658","rcptTyCd":"S","invcAdjustReason":"","taxAmtTl":0,"taxAmtExeeg":0,"cnclReqDt":null,"salesDt":"20241204","taxRtIpl2":0,"taxblAmtExeeg":0,"taxRtIpl1":5,"exchangeRt":1,"taxblAmtRvat":0,"pmtTy
Cd":"08","cfmDt":"20241204123409","totTaxblAmt":8438.18,"dbtRsnCd":"","taxRtTl":1.5,"taxblAmtEcm":0,"taxRtC1":0,"taxRtEcm":5,"taxblAmtA":8438.1636,"taxblAmtB":0,"modrNm":"Colgate Palmolive (Zambia)
Inc.","orgSdcId":null,"taxRtC2":0,"taxRtC3":0,"prchrAcptcYn":"Y","remark":"","regrId":"1001666658","taxAmtEcm":0,"taxRtRvat":16,"taxAmtD":0,"taxAmtIpl1":0,"taxAmtC":0,"taxAmtB":0,"taxAmtA":1350.1063,"taxA
mtIpl2":0,"taxAmtF":0,"taxAmtE":0,"taxblAmtC":0,"taxblAmtTl":0,"taxblAmtD":0,"taxblAmtE":0,"taxblAmtF":0,"rfdRsnCd":null,"custNm":"Choppies Lake road","permanentRsdncAdrs":"Kigali,
Rw","originCountryCd":"RW","permanentRsdncCountryCd":"ZM","lpoNumber":null,"cnclDt":null,"totItemCnt":7,"totAmt":9788.2699,"salesTyCd":"PI","taxAmtRvat":0,"regrNm":"Colgate Palmolive (Zambia)
Inc.","taxblAmtTot":0,"taxAmtC1":0,"taxAmtC3":0,"taxAmtC2":0,"bankCd":"ECO","swiftCd":"3123123123","bnkBranch":"KATWE","bankAccntNo":"194712974192749","bankAccntHldr":"Karim
Ahmed","prchseOrdrNo":"PUR000980","itemList":[{"prc":619.1152,"vatTaxblAmt":960.696,"qtyUnitCd":"BX","bcd":16001067021541,"exciseTxCatCd":"","dcAmt":123.82,"itemClsCd":"41104211","pkgUnitCd":"EA","ite
mCd":"FZA02154C","splyAmt":1238.2304,"totAmt":1114.4074,"itemNm":"STA SOFT BABY
2L","pkg":18,"itemSeq":1,"dcRt":10,"qty":2,"vatAmt":153.7114,"vatCatCd":"A"},{"prc":619.1152,"vatTaxblAmt":960.696,"qtyUnitCd":"BX","bcd":16001067093937,"dcAmt":123.82,"itemClsCd":"41104211","pkgUnitCd":
"EA","itemCd":"FZA00314E","splyAmt":1238.2304,"totAmt":1114.4074,"itemNm":"STA-SOFT 2L LAVENDER (F.
BOOSTER)","pkg":18,"isrcAmt":"","itemSeq":2,"dcRt":10,"qty":2,"vatAmt":153.7114,"vatCatCd":"A"},{"prc":619.1152,"vatTaxblAmt":960.696,"qtyUnitCd":"BX","bcd":16001067093692,"exciseTxCatCd":"","dcAmt":123
.82,"itemClsCd":"41104211","pkgUnitCd":"EA","itemCd":"FZA00305E","splyAmt":1238.2304,"totAmt":1114.4074,"itemNm":"STA-SOFT 2L SPRING FRESH (F.
BOOSTER)","pkg":18,"itemSeq":3,"dcRt":10,"qty":2,"vatAmt":153.7114,"vatCatCd":"A"},{"prc":1996.7892,"vatTaxblAmt":1514.8056,"qtyUnitCd":"BX","bcd":16920354817820,"exciseTxCatCd":"","dcAmt":239.61,"item
ClsCd":"53131502","pkgUnitCd":"EA","itemCd":"61041185","splyAmt":1996.7892,"totAmt":1757.1745,"itemNm":"COLGATE TP HERBAL
140G","pkg":72,"isrcAmt":"","itemSeq":4,"dcRt":12,"qty":1,"vatAmt":242.3689,"vatCatCd":"A"},{"prc":1340.148,"vatTaxblAmt":1155.3,"qtyUnitCd":"BX","bcd":16920354817813,"exciseTxCatCd":"","dcAmt":0,"itemCls
Cd":"53131502","pkgUnitCd":"EA","itemCd":"61041186","splyAmt":1340.148,"totAmt":1340.148,"itemNm":"COL TP HERBAL
70G","pkg":72,"isrcAmt":"","itemSeq":5,"dcRt":0,"qty":1,"vatAmt":184.848,"vatCatCd":"A"},{"prc":1815.0752,"vatTaxblAmt":1564.72,"qtyUnitCd":"BX","bcd":8718951289505,"exciseTxCatCd":"","dcAmt":0,"itemClsCd"
:"53131502","pkgUnitCd":"EA","itemCd":"61031123","splyAmt":1815.0752,"totAmt":1815.0752,"itemNm":"COL TP MAX FRESH COOL MINT
75ML","pkg":72,"isrcAmt":"","itemSeq":6,"dcRt":0,"qty":1,"vatAmt":250.3552,"vatCatCd":"A"},{"prc":1532.65,"vatTaxblAmt":1321.25,"qtyUnitCd":"BX","bcd":8718951350878,"exciseTxCatCd":"","dcAmt":0,"itemClsCd
":"53131502","pkgUnitCd":"EA","itemCd":"61013331","splyAmt":1532.65,"totAmt":1532.65,"itemNm":"Charcoal Gentle Clean 120g","pkg":48,"isrcAmt":"","itemSeq":7,"dcRt":0,"qty":1,"vatAmt":211.4,"vatCatCd":"A"}]}

SAVE FINAL TAX INVOICE

● Endpoint: /trnsSales/saveFinalInvoice
● Request method: POST.
● Requirement: Required for mining sector
● Description: This endpoint facilitates the submission of final tax invoice which finalize a provisional from the third-party system into
Smart Invoice.
● Request Parameters: data including customer details, sale type, invoice number, and transaction timestamp.
● Response: Returns the success or failure of sales data submission.
● Dependency:
o After completing a provisional invoice transaction, 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

141
 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.
● Business rule:
o Final tax invoice always follows a credit not of a Provisional invoice
o Final invoice should reference to a provisional invoice or commercial invoice
o One Final invoice can finalize multiple provisional invoices
o One Final invoice can acquit multiple commercial invoices

Object ID Object name Attribute ID Attribute name Attribute description Data Type Required Length Format

TrnsSaveProvisionalnvoi Save Provisional

ce invoice
tpin Taxpayer Identification Number Varchar 10

bhfId Branch or Business Unit ID Varchar 3

orgInvcNo Original Invoice Number Number 38,0

cisInvcNo CIS Invoice Number Varchar 50

custNm Customer Name Varchar 50

Code associated with type of invoice ( (e.g., PI for See ‘6.7.

salesTyCd Provisional invoice) Varchar 5 Transaction Type

142
orgProvInvc List of original provisional invoices number to be List<Long
NoList finalized >

orgCommInv List of original commercial invoice numbers to be List<Long

cNoList acquitted >

See ‘6.8. Sale

rcptTyCd Receipt Type Code Varchar 5 Receipt Type’

See ‘1.9. Payment

pmtTyCd Payment Type Code Varchar 5 Method’

See ‘6.10.
Transaction
salesSttsCd Sales Status Code Varchar 5 Progress’

Confirmation Date (format:

cfmDt YYYYMMDDHHMMSS) Varchar 14

salesDt Sales Date (format: YYYYMMDD) Varchar 8

See ‘6.15. Refund

rfdRsnCd Refund Reason Code Varchar 5 Reason code’

invcAdjustR
eason Invoice Adjustment Reason Varchar 255

totItemCnt Total Item Count Number 38,0

143
taxblAmtC1 Taxable Amount (Category 1) Number 18,4

taxRtC1 Tax Rate (Category 1) Number 5,2

taxAmtC1 Tax Amount (Category 1) Number 18,4

totTaxblAmt Total Taxable Amount Number 18,4

totTaxAmt Total Tax Amount Number 18,4

remark Remarks or Additional Information Varchar 255

prchseOrdrN
o Purchase Order Number Varchar YES 15

commInvcN
o Commercial Invoice Number Number YES 38,0

treatmentCha
rges Treatment Charges (deduction) Number YES 18,4

processingC
harges Processing Charges (deduction) Number YES 18,4

tollingCharg
es Tolling Charges (deduction) Number YES 18,4

refineryChar
ges Refinery Charges (deduction) Number YES 18,4

144
 freightOrTra
nsport Freight or Transportation Charges (deduction) Number YES 18,4

moistureDed
uctions Moisture Deductions (deduction) Number YES 18,4

insolubleDed
uctions Insoluble Deductions (deduction) Number YES 18,4

totalDeductio
ns Total Deductions Number YES 18,4

totAmt Total Amount Number YES 18,4

regrId Registrar ID (user performing registration) Varchar YES 50

regrNm Registrar Name Varchar YES 50

modrId Modifier ID (user performing modification) Varchar YES 50

modrNm Modifier Name Varchar YES 50

currencyTyC
d Currency Type Code (e.g., USD) Varchar YES 5

exchangeRt Exchange Rate Number YES 18,4

itemList Item list

itemSeq Item Sequence Number 10,0

145
itemCd Item Code Varchar 10

itemClsCd Item Classification Code Varchar 10

itemNm Item Name Varchar 50

See ‘6.4 Packaging

pkgUnitCd Package Unit Code Varchar 5 Unit’

pkg Package Quantity Number 10,2

See ‘6.5. Unit of

qtyUnitCd Quantity Unit Code String 5 Quantity’

qty Quantity Number 18,10

prc Tax inclusive price of an item Number 18,10

splyAmt Supply Amount Number 18,4

dcRt Discount Rate Number 5,2

dcAmt Discount Amount Number 18,4

146
 vatCatCd VAT Category Code String 5

vatTaxblAmt VAT Taxable Amount Number 18,4

vatAmt VAT Amount Number 18,4

totAmt Total Amount Number 18,4

JSON REQUEST SAMPLE

{"tpin":"1000426601","bhfId":"000","custTpin":"1003084830","destnCountryCd":"RW","cisInvcNo":"PROV00022431","orgProvInvcNoList":[1,3],"totTaxAmt":153.7114,"taxRtTot":0,"taxRtExeeg":3,"taxblAmtC3":0,"taxR
tA":16,"taxblAmtC2":0,"taxRtB":16,"rfdDt":null,"taxblAmtC1":0,"taxRtD":0,"taxRtE":0,"taxRtF":10,"currencyTyCd":"ZMW","orgInvcNo":"0","taxAmtTot":0,"taxblAmtIpl2":0,"salesSttsCd":"02","taxblAmtIpl1":0,"modrId
":"1001666658","rcptTyCd":"S","invcAdjustReason":"","taxAmtTl":0,"taxAmtExeeg":0,"cnclReqDt":null,"salesDt":"20241204","taxRtIpl2":0,"taxblAmtExeeg":0,"taxRtIpl1":5,"exchangeRt":1,"taxblAmtRvat":0,"pmtTyCd":
"08","cfmDt":"20241204123409","totTaxblAmt":960.696,"dbtRsnCd":"","taxRtTl":1.5,"taxblAmtEcm":0,"taxRtC1":0,"taxRtEcm":5,"taxblAmtA":960.696,"taxblAmtB":0,"modrNm":"Colgate Palmolive (Zambia)
Inc.","orgSdcId":null,"taxRtC2":0,"taxRtC3":0,"prchrAcptcYn":"Y","remark":"","regrId":"1001666658","taxAmtEcm":0,"taxRtRvat":16,"taxAmtD":0,"taxAmtIpl1":0,"taxAmtC":0,"taxAmtB":0,"taxAmtA":153.7114,"taxAmt
Ipl2":0,"taxAmtF":0,"taxAmtE":0,"taxblAmtC":0,"taxblAmtTl":0,"taxblAmtD":0,"taxblAmtE":0,"taxblAmtF":0,"rfdRsnCd":null,"custNm":"Choppies Lake road","permanentRsdncAdrs":"Kigali,
Rw","originCountryCd":"RW","permanentRsdncCountryCd":"ZM","lpoNumber":null,"cnclDt":null,"totItemCnt":1,"totAmt":1114.4074,"salesTyCd":"F","taxAmtRvat":0,"regrNm":"Colgate Palmolive (Zambia)
Inc.","taxblAmtTot":0,"taxAmtC1":0,"taxAmtC3":0,"taxAmtC2":0,"bankCd":"ECO","swiftCd":"3123123123","bnkBranch":"KATWE","bankAccntNo":"194712974192749","bankAccntHldr":"Karim
Ahmed","prchseOrdrNo":"PUR000980","itemList":[{"prc":619.1152,"vatTaxblAmt":960.696,"qtyUnitCd":"BX","bcd":16001067021541,"exciseTxCatCd":"","dcAmt":123.82,"itemClsCd":"41104211","pkgUnitCd":"EA","ite
mCd":"FZA02154C","splyAmt":1238.2304,"totAmt":1114.4074,"itemNm":"STA SOFT BABY 2L","pkg":18,"itemSeq":1,"dcRt":10,"qty":2,"vatAmt":153.7114,"vatCatCd":"A"}]}

SAVE FINAL CREDIT NOTE

● Endpoint: /trnsSales/saveFinalCreditNote
● Request method: POST.
● Requirement: Required for mining sector
● Description: This endpoint enables the submission of a final credit note, which finalizes a previously overstated provisional invoice from
the third-party system into Smart Invoice.
● Request Parameters: data including customer details, sale type, invoice number, and transaction timestamp.
● Response: Returns the success or failure of sales data submission.

147
● Business rule:
o Final credit note always follows a previously overstated Provisional invoice
o Final credit note should reference to a provisional invoice
o One Final credit note can finalize multiple provisional invoices
o One Final credit note can acquit multiple commercial invoices
o The final credit note enables users to submit downward adjustments to a previously understated provisional invoice

Object ID Object name Attribute ID Attribute name Attribute description Data Type Required Length Format

TrnsSaveProvisionalnvoi Save Provisional

ce invoice
tpin Taxpayer Identification Number Varchar 10

bhfId Branch or Business Unit ID Varchar 3

orgInvcNo Original Invoice Number Number 38,0

cisInvcNo CIS Invoice Number Varchar 50

custNm Customer Name Varchar 50

Code associated with type of invoice ( (e.g., PI for See ‘6.7.

salesTyCd Provisional invoice) Varchar 5 Transaction Type

148
orgProvInvc List of original provisional invoices number to be List<Long
NoList finalized >

See ‘6.8. Sale

rcptTyCd Receipt Type Code Varchar 5 Receipt Type’

See ‘1..9. Payment

pmtTyCd Payment Type Code Varchar 5 Method’

See ‘6.10.
Transaction
salesSttsCd Sales Status Code Varchar 5 Progress’

Confirmation Date (format:

cfmDt YYYYMMDDHHMMSS) Varchar 14

salesDt Sales Date (format: YYYYMMDD) Varchar 8

See ‘6.15. Refund

rfdRsnCd Refund Reason Code Varchar 5 Reason code’

invcAdjustR
eason Invoice Adjustment Reason Varchar 255

totItemCnt Total Item Count Number 38,0

taxblAmtC1 Taxable Amount (Category 1) Number 18,4

149
taxRtC1 Tax Rate (Category 1) Number 5,2

taxAmtC1 Tax Amount (Category 1) Number 18,4

totTaxblAmt Total Taxable Amount Number 18,4

totTaxAmt Total Tax Amount Number 18,4

remark Remarks or Additional Information Varchar 255

prchseOrdrN
o Purchase Order Number Varchar YES 15

commInvcN
o Commercial Invoice Number Number YES 38,0

treatmentCha
rges Treatment Charges (deduction) Number YES 18,4

processingC
harges Processing Charges (deduction) Number YES 18,4

tollingCharg
es Tolling Charges (deduction) Number YES 18,4

refineryChar
ges Refinery Charges (deduction) Number YES 18,4

freightOrTra
nsport Freight or Transportation Charges (deduction) Number YES 18,4

150
 moistureDed
uctions Moisture Deductions (deduction) Number YES 18,4

insolubleDed
uctions Insoluble Deductions (deduction) Number YES 18,4

totalDeductio
ns Total Deductions Number YES 18,4

totAmt Total Amount Number YES 18,4

regrId Registrar ID (user performing registration) Varchar YES 50

regrNm Registrar Name Varchar YES 50

modrId Modifier ID (user performing modification) Varchar YES 50

modrNm Modifier Name Varchar YES 50

currencyTyC
d Currency Type Code (e.g., USD) Varchar YES 5

exchangeRt Exchange Rate Number YES 18,4

itemList Item list

itemSeq Item Sequence Number 10,0

itemCd Item Code Varchar 10

151
itemClsCd Item Classification Code Varchar 10

itemNm Item Name Varchar 50

See ‘6.4 Packaging

pkgUnitCd Package Unit Code Varchar 5 Unit’

pkg Package Quantity Number 10,2

See ‘6.5. Unit of

qtyUnitCd Quantity Unit Code String 5 Quantity’

qty Quantity Number 18,10

prc Tax inclusive price of an item Number 18,10

splyAmt Supply Amount Number 18,4

dcRt Discount Rate Number 5,2

dcAmt Discount Amount Number 18,4

vatCatCd VAT Category Code String 5

152
 vatTaxblAmt VAT Taxable Amount Number 18,4

vatAmt VAT Amount Number 18,4

totAmt Total Amount Number 18,4

JSON REQUEST SAMPLE

{"tpin":"1000000000","bhfId":"000","custTpin":"1000000000","destnCountryCd":"RW","cisInvcNo":"PROV00022431","orgProvInvcNoList":[1,6],"totTaxAmt":153.7114,"taxRtTot":0,"taxRtExeeg":3,"taxblAmtC3":0,"taxR
tA":16,"taxblAmtC2":0,"taxRtB":16,"rfdDt":null,"taxblAmtC1":0,"taxRtD":0,"taxRtE":0,"taxRtF":10,"currencyTyCd":"ZMW","orgInvcNo":"0","taxAmtTot":0,"taxblAmtIpl2":0,"salesSttsCd":"02","taxblAmtIpl1":0,"modrId
":"1001666658","rcptTyCd":"R","invcAdjustReason":"","taxAmtTl":0,"taxAmtExeeg":0,"cnclReqDt":null,"salesDt":"20241204","taxRtIpl2":0,"taxblAmtExeeg":0,"taxRtIpl1":5,"exchangeRt":1,"taxblAmtRvat":0,"pmtTyCd":
"08","cfmDt":"20241204123409","totTaxblAmt":960.696,"dbtRsnCd":"","taxRtTl":1.5,"taxblAmtEcm":0,"taxRtC1":0,"taxRtEcm":5,"taxblAmtA":960.696,"taxblAmtB":0,"modrNm":"Colgate Palmolive (Zambia)
Inc.","orgSdcId":null,"taxRtC2":0,"taxRtC3":0,"prchrAcptcYn":"Y","remark":"","regrId":"1001666658","taxAmtEcm":0,"taxRtRvat":16,"taxAmtD":0,"taxAmtIpl1":0,"taxAmtC":0,"taxAmtB":0,"taxAmtA":153.7114,"taxAmt
Ipl2":0,"taxAmtF":0,"taxAmtE":0,"taxblAmtC":0,"taxblAmtTl":0,"taxblAmtD":0,"taxblAmtE":0,"taxblAmtF":0,"rfdRsnCd":"02","custNm":"Choppies Lake road","permanentRsdncAdrs":"Kigali,
Rw","originCountryCd":"RW","permanentRsdncCountryCd":"ZM","lpoNumber":null,"cnclDt":null,"totItemCnt":1,"totAmt":1114.4074,"salesTyCd":"F","taxAmtRvat":0,"regrNm":"Colgate Palmolive (Zambia)
Inc.","taxblAmtTot":0,"taxAmtC1":0,"taxAmtC3":0,"taxAmtC2":0,"bankCd":"ECO","swiftCd":"3123123123","bnkBranch":"KATWE","bankAccntNo":"194712974192749","bankAccntHldr":"Karim
Ahmed","prchseOrdrNo":"PUR000980","itemList":[{"prc":619.1152,"vatTaxblAmt":960.696,"qtyUnitCd":"BX","bcd":16001067021541,"exciseTxCatCd":"","dcAmt":123.82,"itemClsCd":"41104211","pkgUnitCd":"EA","ite
mCd":"FZA02154C","splyAmt":1238.2304,"totAmt":1114.4074,"itemNm":"STA SOFT BABY 2L","pkg":18,"itemSeq":1,"dcRt":10,"qty":2,"vatAmt":153.7114,"vatCatCd":"A"}]}

SAVE FINAL CREDIT NOTE

● Endpoint: /trnsSales/saveFinalCombined
● Request method: POST.
● Requirement: Required for mining sector
● Description: This endpoint enables the submission of a final combined invoice, which finalizes a previously understated provisional
invoice from the third-party system into Smart Invoice.
● Request Parameters: data including customer details, sale type, invoice number, and transaction timestamp.
● Response: Returns the success or failure of sales data submission.
● Business rule:
o Final combined invoice always follows a previously understated Provisional invoice
o Final combined invoice should reference to a provisional invoice

153
 o One Final combined invoice can finalize multiple provisional invoices
o One Final combined invoice can acquit multiple commercial invoices
o Final invoice allows users to submit additional adjustments on a previously understated provisional invoice

Request body

Object ID Object name Attribute ID Attribute name Attribute description Data Type Required Length Format

TrnsSaveProvisionalnvoi Save Provisional

ce invoice
tpin Taxpayer Identification Number Varchar 10

bhfId Branch or Business Unit ID Varchar 3

orgInvcNo Original Invoice Number Number 38,0

cisInvcNo CIS Invoice Number Varchar 50

custNm Customer Name Varchar 50

Code associated with type of invoice ( (e.g., PI for See ‘6.7.

salesTyCd Provisional invoice) Varchar 5 Transaction Type

orgProvInvcNoL List of original provisional invoices number to be List<Long

ist finalized >

154
 See ‘6.8. Sale
rcptTyCd Receipt Type Code Varchar 5 Receipt Type’

See ‘1.9. Payment

pmtTyCd Payment Type Code Varchar 5 Method’

See ‘6.10.
Transaction
salesSttsCd Sales Status Code Varchar 5 Progress’

Confirmation Date (format:

cfmDt YYYYMMDDHHMMSS) Varchar 14

salesDt Sales Date (format: YYYYMMDD) Varchar 8

See ‘6.15. Refund

rfdRsnCd Refund Reason Code Varchar 5 Reason code’

invcAdjustReaso
n Invoice Adjustment Reason Varchar 255

totItemCnt Total Item Count Number 38,0

taxblAmtC1 Taxable Amount (Category 1) Number 18,4

taxRtC1 Tax Rate (Category 1) Number 5,2

155
taxAmtC1 Tax Amount (Category 1) Number 18,4

totTaxblAmt Total Taxable Amount Number 18,4

totTaxAmt Total Tax Amount Number 18,4

remark Remarks or Additional Information Varchar 255

prchseOrdrNo Purchase Order Number Varchar YES 15

commInvcNo Commercial Invoice Number Number YES 38,0

treatmentCharge
s Treatment Charges (deduction) Number YES 18,4

processingCharg
es Processing Charges (deduction) Number YES 18,4

tollingCharges Tolling Charges (deduction) Number YES 18,4

refineryCharges Refinery Charges (deduction) Number YES 18,4

freightOrTranspo
rt Freight or Transportation Charges (deduction) Number YES 18,4

moistureDeducti
ons Moisture Deductions (deduction) Number YES 18,4

156
 insolubleDeducti
ons Insoluble Deductions (deduction) Number YES 18,4

totalDeductions Total Deductions Number YES 18,4

totAmt Total Amount Number YES 18,4

regrId Registrar ID (user performing registration) Varchar YES 50

regrNm Registrar Name Varchar YES 50

modrId Modifier ID (user performing modification) Varchar YES 50

modrNm Modifier Name Varchar YES 50

currencyTyCd Currency Type Code (e.g., USD) Varchar YES 5

exchangeRt Exchange Rate Number YES 18,4

itemList Item list

itemSeq Item Sequence Number 10,0

itemCd Item Code Varchar 10

itemClsCd Item Classification Code Varchar 10

157
itemNm Item Name Varchar 50

See ‘6.4 Packaging

pkgUnitCd Package Unit Code Varchar 5 Unit’

pkg Package Quantity Number 10,2

See ‘6.5. Unit of

qtyUnitCd Quantity Unit Code String 5 Quantity’

qty Quantity Number 18,10

prc Tax inclusive price of an item Number 18,10

splyAmt Supply Amount Number 18,4

dcRt Discount Rate Number 5,2

dcAmt Discount Amount Number 18,4

vatCatCd VAT Category Code String 5

vatTaxblAmt VAT Taxable Amount Number 18,4

158
 vatAmt VAT Amount Number 18,4

totAmt Total Amount Number 18,4

JSON REQUEST SAMPLE

{"tpin":"1000000000","bhfId":"000","custTpin":"1000000000","destnCountryCd":"RW","cisInvcNo":"PROV00022431","orgProvInvcNoList":[1,6],"totTaxAmt":153.7114,"taxRtTot":0,"taxRtExeeg":3,"taxblAmtC3":0,"taxRtA":
16,"taxblAmtC2":0,"taxRtB":16,"rfdDt":null,"taxblAmtC1":0,"taxRtD":0,"taxRtE":0,"taxRtF":10,"currencyTyCd":"ZMW","orgInvcNo":"0","taxAmtTot":0,"taxblAmtIpl2":0,"salesSttsCd":"02","taxblAmtIpl1":0,"modrId":"1001
666658","rcptTyCd":"R","invcAdjustReason":"","taxAmtTl":0,"taxAmtExeeg":0,"cnclReqDt":null,"salesDt":"20241204","taxRtIpl2":0,"taxblAmtExeeg":0,"taxRtIpl1":5,"exchangeRt":1,"taxblAmtRvat":0,"pmtTyCd":"08","cfm
Dt":"20241204123409","totTaxblAmt":960.696,"dbtRsnCd":"","taxRtTl":1.5,"taxblAmtEcm":0,"taxRtC1":0,"taxRtEcm":5,"taxblAmtA":960.696,"taxblAmtB":0,"modrNm":"Colgate Palmolive (Zambia)
Inc.","orgSdcId":null,"taxRtC2":0,"taxRtC3":0,"prchrAcptcYn":"Y","remark":"","regrId":"1001666658","taxAmtEcm":0,"taxRtRvat":16,"taxAmtD":0,"taxAmtIpl1":0,"taxAmtC":0,"taxAmtB":0,"taxAmtA":153.7114,"taxAmtIpl
2":0,"taxAmtF":0,"taxAmtE":0,"taxblAmtC":0,"taxblAmtTl":0,"taxblAmtD":0,"taxblAmtE":0,"taxblAmtF":0,"rfdRsnCd":"02","custNm":"Choppies Lake road","permanentRsdncAdrs":"Kigali,
Rw","originCountryCd":"RW","permanentRsdncCountryCd":"ZM","lpoNumber":null,"cnclDt":null,"totItemCnt":1,"totAmt":1114.4074,"salesTyCd":"F","taxAmtRvat":0,"regrNm":"Colgate Palmolive (Zambia)
Inc.","taxblAmtTot":0,"taxAmtC1":0,"taxAmtC3":0,"taxAmtC2":0,"bankCd":"ECO","swiftCd":"3123123123","bnkBranch":"KATWE","bankAccntNo":"194712974192749","bankAccntHldr":"Karim
Ahmed","prchseOrdrNo":"PUR000980","itemList":[{"prc":619.1152,"vatTaxblAmt":960.696,"qtyUnitCd":"BX","bcd":16001067021541,"exciseTxCatCd":"","dcAmt":123.82,"itemClsCd":"41104211","pkgUnitCd":"EA","itemC
d":"FZA02154C","splyAmt":1238.2304,"totAmt":1114.4074,"itemNm":"STA SOFT BABY 2L","pkg":18,"itemSeq":1,"dcRt":10,"qty":2,"vatAmt":153.7114,"vatCatCd":"A"}]}

5.12. 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.

159
 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

TrnsPurchaseSalesRe Search tpin Taxpayer’s identification number as registered on core Tax TPIN VARCHAR Y 10
q 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": "1000000000","bhfId": "000","lastReqDt":"20231215000000"}

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

160
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
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 tax inclusive price of Price NUMBER 18,4
the item

161
 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
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":"1000000000","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}]}]}}

162
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.
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

163
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
TPIN
core Tax Administration
System TaxOnline
bhfId Taxpayer branch (store) VARCHAR Y 3
Branch ID
location identifier
cisInvcNo Invoice number as Cis invoice number CHAR Y 50
generated on the taxpayer’s
ERP
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
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 NUMBER N 38
generated on suppliers Supplier Invoice
Certified invoicing Number
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 VARCHAR Y 5 See ‘1.9. Payment
Payment Type Code
for 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 Cancel Requested VARCHAR N 14 yyyyMMddhhmmss
Date
cnclDt Cancel date VARCHAR N 14 yyyyMMddhhmmss
Canceled Date
totItemCnt Total number of items on NUMBER Y 10
Total Item Count
the invoice
totTaxblAmt Total taxable amount Total Taxable NUMBER Y 18,2
Amount

164
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 Y 3
Number
itemCd This is the item identifier Item Code VARCHAR N 100
on the taxpayer’s 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
spplrItemClsCd This is the supplier Supplier Item VARCHAR N 10
UNSCP code assigned to Classification Code
the item
spplrItemCd This is the supplier item Supplier Item Code VARCHAR N 20
code as defined on your
system
spplrItemNm This is the supplier item Supplier Item Name VARCHAR N 200
name as defined on your
system
pkgUnitCd This is the packaging unit Packaging Unit Code VARCHAR N 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 measures
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 inclusive Unit Price NUMBER Y 18,2
price of the item
splyAmt This is the total amount of Supply Price NUMBER Y 18,2
the supplied item (qty *
prc)
dcRt This is the discount rate on Discount Rate NUMBER Y 5,2
the line item (Pass 0.0 if
not applicable)
dcAmt This is the discount amount Discount Amount NUMBER Y 18,2
on the line item (Pass 0.0 if
not applicable)

165
 iplCatCd This represents the tax IPL Category Code VARCHAR Y 5
category code for IPL
purposes on the line item
tlCatCd This represents the tax TL Category Code VARCHAR Y 5
category code for TL
purposes on the line item
exciseCatCd This represents the tax Excise Category VARCHAR Y 5
category code for EXCISE Code
purposes on line item
taxblAmt This is the Tax Exclusive VAT Taxable NUMBER Y 18,2
Amount for VAT at line Amount
item level (Pass 0.0 when
not applicable)
vatCatCd This represents the tax VAT Category Code VARCHAR Y 5
category 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
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 IPL Tax Amount NUMBER Y 18,2
charged on the line item
tlAmt This is the TL amount TL Tax Amount NUMBER Y 18,2
charged 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 Total Amount NUMBER Y 18,2
Inclusive Amount of the
line item

JSON REQUEST SAMPLE

{"tpin":"1000000000","bhfId":"000"," cisInvcNo":"cis134","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

166
 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

TrnsPurchaseSaveRe Save Purchase Response resultCd This is the VSDC response code Result Code VARCHAR 3
s
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}

5.13. 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.

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

StockMoveRe Select Stock tpin Taxpayer’s identification number as registered on core Tax TPIN VARCHAR Y 10
q 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": "1000000000","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)

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

168
 itemCd This is the item code Item code VARCHAR 100

itemClsCd This is the item classification code Item classisifcation 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": "1000000000","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 (EXCEPT SERVICE INDUSTRY)
● 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.
Save Stock Items Update Smart Invoice with the stock item
POST /stock/saveStockItems
data

169
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.
custBhfId The branch (store) Customer BHF ID
identifier of the VARCHAR N 2
location
sarTyCd Stock Accounting Stored and released See ‘6.14. Stock In/Out Type’
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
NUMBER Y 10
items included in the

170
 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
individual who
VARCHAR Y 20
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

171
 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. “IPL1”
tlCatCd This represents the tax TL Category Code
category for TL VARCHAR Y 5
purposes e.g.”TL”
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 tax amount Tax Amount
NUMBER Y 18,4
of the item

172
 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": "1000000000", "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

{"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

173
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

{"tpin":"1000000000","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}

174
6. Code Definition
6.1. Tax Type
Code Classification Name
Tax Type
Code Code Name Code Description remark
Category applies to products and services which attract VAT at
VAT A Standard Rated 16% 16% by nature
Minimum Taxable Value (MTV) 16% is charged on the Retail Price recommended by manufacturer
B of MTV goods.

C1 Exports 0% Applies to exports

Zero-rating Local Purchases
Applies to transactions involving customers or projects granted
C2 Order transactions 0%
exemption from paying taxes
Category applies to products and services which do not attract
C3 Zero-rated by nature 0% VAT at 16% by nature.
The category applies to specific class of products and services
D Exempt No tax charge exempted from VAT

E Disbursement Applies to expenses incurred by suppliers on behalf of customers

while supplying a product or service.
RVA Reverse VAT Applies to transactions involving imported services. (For both
T Appointed Tax Agent and Self-invoicing).
Applies to the hospitality industry and computed on a total net
Insurance IPL1 Insurance Premium Levy transaction amount. Applies to all classes of insurance except re-
Premium insurance.
Levy IPL2 Re-Insurance
Applies only to re-insurance.
Tourism levy TL Tourism Levy
Applies to accommodation and conference facilities.
F Service Charge 10%
Applies to services rendered
Excise ECM Excise on Coal
The tax rate is charged per ton
EXEE Excise Electricity
G The tax rate is charged per 100kwh
Direct tax – tax amount does not reflect on an invoice. For
Turnover Tax TOT No tax charge purposes of accounting for turnover relating to taxpayers not
registered for VAT.

6.2. Product Type

Code Classification Name

Product Type
Code Code Name Code Description remark

1 Raw Material Raw Material

2 Finished Product Finished Product
3 Service Service without stock

175
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 BARBUDA ANTIGUA AND BARBUDA

AI 5 ANGUILLA ANGUILLA
AL 6 ALBANIA ALBANIA
AM 7 ARMENIA ARMENIA
NETHERLANDS
AN 8 ANTILLES NETHERLANDS ANTILLES

AO 9 ANGOLA ANGOLA
AQ 10 ANTARCTICA ANTARCTICA
AR 11 ARGENTINA ARGENTINA
AS 12 AMERICAN SAMOA AMERICAN SAMOA

176
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 HERZEGOVINA BOSNIA AND 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 DARUSSALAM BRUNEI 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 REPUBLIC CENTRAL AFRICAN 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

177
CV 52 CAPE VERDE CAPE VERDE
CX 53 CHRISTMAS ISLAND CHRISTMAS ISLAND
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 REPUBLIC DOMINICAN 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 METROPOLITA FRANCE, METROPOLITAN
N
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
GS 91 S. GEORGIA AND S. SANDWICH ISLS.
S. SANDWICH
ISLS.
GT 92 GUATEMALA GUATEMALA

178
GU 93 GUAM GUAM
GW 94 GUINEA BISSAU GUINEA BISSAU
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 OCEAN TERRITORY BRITISH INDIAN 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

179
LT 134 LITHUANIA LITHUANIA
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 (MACEDONIA) F.Y.R.O.M. (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 ISLANDS NORTHERN MARIANA 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 (AOTEAROA) NEW ZEALAND (AOTEAROA)

OM 173 OMAN OMAN

PA 174 PANAMA PANAMA

180
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 FEDERATION RUSSIAN 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 &
SJ 202 JAN MAYEN SVALBARD & JAN MAYEN ISLANDS
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 PRINCIPE SAO TOME AND 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 ISLANDS TURKS AND CAICOS ISLANDS

181
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 THE GRENADINES SAINT VINCENT & THE GRENADINES

VE 239 VENEZUELA VENEZUELA

BRITISH VIRGIN
VG 240 BRITISH VIRGIN ISLANDS
ISLANDS
VIRGIN ISLANDS
VI 241 (U.S.) VIRGIN ISLANDS (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

182
6.4. Packaging Unit

For an exhaustive lists of packaging units refer to class code 17 of /code/selectCodes

Code Classification Name

Packaging Unit
Code Code Name Code Description remark
AM Ampoule Ampoule
BA Barrel Barrel
BC Bottle crate Bottle crate
BE Bundle Bundle
BF Balloon, non- Balloon, non-protected
protected
BG Bag Bag
BJ Bucket Bucket
BK Basket Basket
BL Bale Bale
Bottle,
BQ protected Bottle, protected cylindrical
cylindrical
BR Bar Bar
BV Bottle, bulbous Bottle, bulbous
BZ Bag Bag
CA Can Can
CH Chest Chest

Code Classification Name

Packaging Unit
Code Code Name Code Description remark

CJ Coffin Coffin
CL Coil Coil
Wooden Box, Wooden
CR Wooden Box, Wooden Case
Case
CS Cassette Cassette
CT Carton Carton
CTN Container Container
CY Cylinder Cylinder
DR Drum Drum
GT Extra Countable Item Extra Countable Item
HH Hand Baggage Hand Baggage
IZ Ingots Ingots
JR Jar Jar

183
JU Jug Jug
JY Jerry CAN Cylindrical Jerry CAN Cylindrical
KZ Canester Canester
Logs, in
LZ bundle/bunch/truss Logs, in bundle/bunch/truss

NT Net Net
Non-Exterior Packaging
OU Unit Non-Exterior Packaging Unit

PD Poddon Poddon
PG Plate Plate
PI Pipe Pipe
PO Pilot Pilot
PU Traypack Traypack
RL Reel Reel
RO Roll Roll
Rods, in
RZ bundle/bunch/truss Rods, in bundle/bunch/truss

SK Skeletoncase Skeletoncase
TY Tank, cylindrical Tank, cylindrical
Bulk,gas(at 1031 mbar 15
VG Bulk,gas(at 1031 mbar 15 oC)
oC)
Bulk,liquid(at normal
VL temperature/pressure) Bulk,liquid(at normal temperature/pressure)
Bulk, solid, large
VO Bulk, solid, large particles("nodules")
particles(nodules)
Bulk, gas (liquefied at
VQ abnormal Bulk, gas(liquefied at abnormal temperature/pressure)
temperature/pressure)
Bulk, solid, granular
VR particles(grains) Bulk, solid, granular particles("grains")

VT Extra Bulk Item Extra Bulk Item

Bulk, fine
VY Bulk, fine particles("powder")
particles(powder)
ML Mills cigarette Mills
TN TAN 1TAN REFER TO 20BAGS
Code Classification Name

Packaging Unit
Code Code Name Code Description remark

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

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

BOUQ Bouquet A collection of flowers or other items bundled together

BOWL Bowl A round or oval container used for holding food or other
items.
BOX Box A rectangular container typically used for packaging and
storage.
BUBG Budget Bag A bag designed for economical or budget-conscious
purposes.
BULK Bulk Pack Packaging designed for large quantities of items.
BUNC Bunch A grouping or collection of items, often tied together.
BUND Bundle A group of items bound or packaged together.
CLEA Clear Lid A lid or covering that is transparent or see-through.
EA Each Indicates individual units or items.
EACH Each Similar to "EA," denotes individual units or items.
ECON Economy Bag A bag designed for cost-effective or budget-friendly use.

184
 ECPO Econo Poc Sell Refers to an economical or budget-friendly pocket for
selling items.
Green Lugs
G/L Lugs or containers that are green in color.

KARR Karripoc Specific packaging or container type.

Labels
LABE Refers to adhesive labels used for marking or identifying
items.
MESH Mesh Packaging material made of interconnected strands or
fibers.
NETL Netlon Refers to a type of net or netting used in packaging.
P/KG Per Kilogram Indicates pricing or packaging based on weight in
kilograms.
PACK PACK General term for packaging or packaging units.
PCRT PCRT Specific type of packaging or container.
PILP Pilpac Specific type of packaging or container.
POC Pocket A small container or compartment.
Poc Sell
POCS Refers to a pocket or small container used for selling
items.
POLY Poly Bags Bags made of polyethylene or similar materials.
POT Pots Containers typically used for planting or holding plants.
Prepack
PREP Items or units that are prepackaged or prepared.
Pun DTray
PUND Refers to a tray or container for specific items.
Punnet - Packaging
PUNN A specific type of packaging often used for fruits or
vegetables.
SLEE Sleeve A covering or protective layer.

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

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

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

6.5. Units of measure

For an exhaustive lists of units of measure refer to class code 10 of /code/selectCodes

Code Classification Name

Unit of measures
Code Code Name Code Description remark
4B Pair Pair
AV Cap Cap
BA Barrel Barrel
BE bundle bundle
BG bag bag
BL block block
BLL BLL Barrel BLL Barrel (petroleum) (158,987 dm3)
BX box box
CA Can Can

185
CEL Cell Cell
CMT centimetre centimetre
CR CARAT CARAT
DR Drum Drum
DZ Dozen Dozen
GLL Gallon Gallon
GRM Gram Gram
GRO Gross Gross
KG Kilo-Gramme Kilo-Gramme
KTM kilometre kilometre
KWT kilowatt kilowatt
L Litre Litre
LBR pound pound
LK link link
LTR Litre Litre
M Metre Metre
M2 Square Metre Square Metre
M3 Cubic Metre Cubic Metre
MGM milligram milligram
MTR metre metre
megawatt hour
MWT (1000 kW.h) megawatt hour (1000 kW.h)
NO Number Number
NX part per thousand part per thousand
PA packet packet
PG plate plate
PR pair pair
RL reel reel
RO roll roll
SET set set
ST sheet sheet
TNE tonne (metric ton) tonne (metric ton)
TU tube tube
U Pieces/item [Number] Pieces/item [Number]
YRD yard yard
P1 Pack Pack
PL Pallet Pallet
Ft Feet Feet
MM Millimetre Millimetre
In Inches Inches
Oz Ounce Ounce
YR Year Year
M Month Month
Wk Week Week
D Day Day
hr Hour Hour
ha Hectare Hectare

186
 yd2 Square yards Square yards
ft2 Square feet Square feet
cm2 Square centimetre Square centimetre
m2 Square metre Square metre
pt Pints Pints
qt Quarts Quarts
mm Millilitre Millilitre
2X Meter/Minute Meter/Minute
4G Microliter Microliter
4O Microfarad Microfarad
4T Pikofarad Pikofarad
A Ampere Ampere
A87 Gigaohm Gigaohm
A93 Gram/Cubic meter Gram/Cubic meter
ACR Acre Acre
B34 Kilogram/cubic Kilogram/cubic decimeter
decimeter
B45 Kilomol Kilomol
B47 Kilonewton Kilonewton
B73 Meganewton Meganewton
B75 Megohm Megohm
B78 Megavolt Megavolt
B84 Microampere Microampere
BAG Bag Bag
BAR bar bar
BOT Bottle Bottle
BQK Becquerel/kilogram Becquerel/kilogram
C10 Millifarad Millifarad
C36 Mol per cubic meter Mol per cubic meter
C38 Mol per liter Mol per liter
C39 Nanoampere Nanoampere
C3S Cubic Cubic centimeter/second
centimeter/second
C41 Nanofarad Nanofarad
C56 Newton/Square Newton/Square millimeter
millimeter
CCM Cubic centimeter Cubic centimeter
CD Candela Candela
CDM Cubic decimeter Cubic decimeter
EA Each Indicates individual units or items.

6.6. Currency

Code Classification Code Classification Name

33 Currency
Code Code Name Code Description remark
ZMW Zambian kwacha Zambian kwacha

187
 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 Name
Transaction Type
Code Code Name Code Description remark
C Copy Sales and purchase type: Copy
N Normal Sales and purchase type: Normal
CI Commercial Commercial Invoice
PI Provisional Provisional Invoice
F Final Final Invoice

6.8. Sales Receipt Type

Code Classification Name
Sales Receipt Type
Code Code Name Code Description remark
S Sale Sale
R Reversal after Sale Refund after Sale Credit Note
D Adjustment upwards Adjustment upwards after Sale Debit Note
after Sale

6.9. Payment Method

Code Classification Name
Payment Method
Code Code Name Code Description remark
01 CASH CASH
02 CREDIT CREDIT
03 CASH/CREDIT CASH/CREDIT
04 BANK CHECK BANK CHECK PAYMENT
05 DEBIT&CREDIT PAYMENT USING CARD
CARD
ANY TRANSACTION USING MOBILE
06 MOBILE MONEY MONEY SYSTEM
08 Bank transfer
07 OTHER OTHER MEANS OF PAYMENT

6.10. Transaction Progress

Code Classification Name

188
 Transaction progress
Code Code Name Code Description remark

02 Approved Approved
05 Refunded Refunded
06 Transferred Transferred
04 Rejected Rejected

6.11. Registration Type

Code Classification Name
Registration Type
Code Code Name Code Description remark

A 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 Manual Manual – Purchases registered directly from the CIS,
that are not retrieved via the getPurchase endpoint.

6.12. Purchase Receipt Type

Code Classification Name

Purchase Receipt Type

Code Code Name Code Description remark

P Purchase Purchase
R 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
801 Client There is no data to retransmit.
802 Client There is data that has not been transferred. After transfer is possible.
803 Client This is a report that transfer is complete.
804 Client There is no data to send for the report.
805 Client Corresponding retransmission data exists.
834 Client SalesType and ReceiptType must be NS-NR-ND-TS-TR-TD-CS-CR-CD-PS check your
inputs
836 Client Your Sequences have been altered, Connect to ZRA API to get Sequences.
838 Client Connection to API is not established: check connection.
884 Client Invalid customer TPIN was provided
891 Client An error occurred while Request URL is created.

189
 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.
913 Client Code value error among request parameters.
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.
924 Client CIS Invoice number already exists.
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

6.14. Stock In/Out Type

Code Classification Name

Stock In/Out Type

Code Code Name Code Description remark

01 Import Incoming-Import
02 Purchase Incoming- Purchase
03 Return Incoming- Return
04 Stock Movement Incoming- Stock Movement
05 Processing Incoming- Processing
06 Adjustment Incoming- Adjustment
11 Sale Outgoing- Sale
12 Return Outgoing- Return

Code Classification Name

Stock In/Out Type

190
 Code Code Name Code Description remark

13 Stock Movement Outgoing- Stock Movement

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

6.15. Credit Note Reason Code

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

01 1 Wrong product(s) Wrong product(s)

02 2 Wrong price Wrong price
03 3 Damaged Goods Damaged Goods
04 4 Wrong Customer Invoiced Wrong Customer Invoiced
05 5 Duplicated invoice Duplicated invoice
06 6 Excess supplies Excess supplies
07 7 Other (Provide other Other (Provide other reason in brief)
reason in brief)

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.

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 Name

Import item Status

Code Code Name Code Description remark

3 Approved These are imported items approved to be stocked-in

4 Rejected These are non-stock imports

6.18. Debit note reason.

Code Classification Name

Reason for debit note

Code Code Name Code Description remark

01 Wrong quantity invoiced

191
 02 Wrong invoice amount
03 Omitted item
04 Other [specify]

6.19. Zambia ports

Code Classification Name

Zambia ports
Code Code Name Code description remark
CGA CHINGOLA AIRPORT
CHA CHAVUMA
CHD CHANIDA
CHE CHEMBE
CHG CHIPUNGU
CHI CHINSALI
CHN CHINGOLA
CHO CHOMA
CHP CHIPATA
CHR CHIRUNDU
CHT CHIPATA AIRPORT
GWA GWEMBE VALLEY
HQO HEAD QUARTERS OFFICE
JIM JIMBE BRIDGE
KAS KASAMA
KIP KIPUSHI
KPM KAPIRI MPOSHI
KRB KARIBA
KSH KASHIBA
KSU KASUMBALESA
KTA KITWE AIRPORT
KTM KATIMA MULILO
KTW KITWE PORT OFFICE
KZU KAZUNGULA
LGA LUANGWA
LIA LUSAKA INTERNATIONAL AIRPORT
LKA LUSAKA PORT OFFICE
LON LONSHI BORDER POST
LUF LUFUWA BORDER POST
LUK LUKWESA
LUM LUMI
LUN LUNDAZI
LUS LUSUNTHA
LVA LIVINGSTONE AIRPORT
LVI LIVINGSTONE PORT OFFICE
MAS MANSA
MAT MATANDA
MBA MBALA AIRPORT
MFA MFUWE AIRPORT
MKA MOKAMBO
MLS MULIASHI
MOA MONGU AIRPORT
MON MONGU OFFICE
MPO MPOROKOSO
MPU MPULUNGU
MWA MWAMI BORDER POST

192
 MWI MWINILUNGA
NDA NDOLA AIRPORT
NDO NDOLA PORT OFFICE
NGE NCHELENGE
NKO NAKONDE
NYA NYALA
SKA SAKANYA
SOL SOLWEZI
SVO SIAVONGA
SZE SINAZONGWE
VFL VICTORIA FALLS
ZOM ZOMBE

6.20. Destination Incortem

Code Classification Name

Destination Incortem

Cod Code Code description Remark

e Name
1 FCA Free Carrier

2 FAS Free Alongside Ship

3 FOB Free On Board

4 CFR Cost and Freight

5 CIF Cost, Insurance, and Freight

6 CPT Carriage Paid To

7 CIP Carriage and Insurance Paid To

8 DAP Delivered at Place

9 DPU Delivered at Place Unloaded

10 DDP Delivered Duty Paid

11 Other

6.21. Departure Incoterm

Code Classification Name

Departure Incortem

Code Code Code description Remark

Name
01 EXW Free Carrier

02 Other

6.22. Commercial Invoice status

Code Classification Name

Commercial Invoice status

193
 Code Code Name Code description Remark

01 Pending Acquittal

02 Acquitted

03 Cancelled

04 Reversed

6.23. Banks

Code Classification Name

Banks
Code Code Name Code description Remark

FAB FAB First alliance bank limited

ZIC ZICB Zambia industrial commercial bank plc
ABB AB BANK Ab bank zambia limited
BBZ ABSA Absa bank zambia plc
ACZ ACCESS Access bank zambia limited
BOC BOC Bank of china (zambia) limited
CIT CITIBANK Citibank zambia limited
ECO ECOBANK Ecobank zambia limited
FCB FCB First capital bank zambia
FNB FNB First national bank zambia limited
IZB INDO - ZAMBIA Indo-zambia bank limited
SBZ STANBIC Stanbic bank zambia limited
SCB STANCHART Standard chartered bank plc
UBA UBA United bank for africa zambia limited
ZNC ZANACO Zambia national commercial bank plc
BANK OF
BOZ ZAMBIA Bank of zambia

6.24. Customer type

Code Classification Code Classification Name

20 customer type
Code Sort Order Code Name Code Description remark

01 1 Resident
02 2 Non resident
Transporter
03 3

6.23. travel purpose

Code Classification Code Classification Name

22 travel purpose

194
 Code Sort Order Code Name Code Description remark

01 1 Business
02 2 Holiday Travels
Other (Please specify)
03 3

195