INTRODUCTION:

 

The purpose of the document is to facilitate LEATHER AND TEXTILE SECTOR to understand methods for invoice data sharing with FBR. Taxpayer directly connect to FBR system to upload sales invoices in bulk. This mechanism is provided temporarily to upload all the sales invoice data to FBR System till the implementation of Fiscalization Solution.

Taxpayer can directly integrate their system with FBR using the provided web service to upload the sale invoices in bulk. This web service will reside on FBR server and expose web method for the bulk data sharing from Leather/Textile taxpayers Server/POS to FBR server.

The web method will be used by Leather and Textile sector taxpayers to send invoice data to FBR server to get FBR Fiscal Invoice Number.

Following is the two-step process for sharing invoice data with FBR.

1. Register each store (POS) in FBR system for which you want to upload the data. Details are given in Section POS Registration.
2. Taxpayer will integrate their system with FBR using the provided Web Service. Details are given in Section Integration of Taxpayer System with FBR System.

SCOPE:

 

The scope of the document is limited to technical description of FBR-IMS Web Service, web methods, data sharing details and data security implementation.

This service is being provided to Leather/Textile sector taxpayer temporarily for the bulk invoice data transformation from their POS/Servers to FBR System. Until the implementation of Fiscal Solution to all Leather and Textile taxpayers in which each and every invoice will be fiscalize on real-time basis by directly integrating the POS as per the rules/regulation mentioned in FBR S.R.O 1360(I)/2018 chapter 14.

 

DEFINITION AND ACRONYMS

 

ACRONYMN	DEFINITION
FBR	Federal Board of Revenue
HTTP	Hypertext Transfer Protocol
URL	Uniform Resource Locator
NTN	National Tax Number
POS_RN	Point of Sale Registration Number
PB	Public Key for Signature Verification
PV	Private Key for Data Signing
EC	Encryption Key

POS Registration:

 

Textile and leather sector will register their POS for each branch using eFBR portal by providing the required data. Following data is required for POS registration:

Name	Status	Sample Value
POS Identification Number (Device No.)	Compulsory	POS-123-8D
NTN	Compulsory	1000007-9
Business Name	Compulsory	IDEAS by Gul Ahmed
Branch Name	Compulsory	F-10 Markaz Outlet
Business Address	Compulsory	F-10 Markaz Islamabad
City	Compulsory	Islamabad
IP Address	Compulsory	192.68.52.01
Latitude	Compulsory	33.0254155
Longitude	Compulsory	73.254354
Mode	Compulsory	Live Service

For POS registration, log in on web site https://e.fbr.gov.pk ^[23] with your user credential and get registered by accessing the page Registration-> POS Client Registration

On successful submission of data, FBR will generate POS registration no which will be referenced in the compiling each invoice into required format.

Integration of Taxpayer System with FBR System:

 

FBR has provided the web service to textile and leather sector to share the invoice data with FBR. This web service will be accessible only to registered POS Clients. Transaction handling and relevant data dissemination to FBR PRAL will be the responsibility of registered POS Clients. FBR will impose such restrictions so that no un-authorized POS Clients have access to the Web Service. Network team shall further apply the standard network security checks required.

For the integration of taxpayer system with FBR system require following steps:

1. Consume the Web Service in their system according to given instruction at Web Methods Detail.
2. Fill the invoice data according to given format against each record as provided at Calling FBR Web Service.
3. Upload each invoice one by one by calling the web service method in a loop.
4. FBR service will return the invoice number against each record.

User Authentication to invoke the web service:

 

The web service exposed web method shall be invoked only after the ‘Request Validation’. The user credentials should be provided in Web API header as authentication Token.

Web Methods Details:

 

Web API (http://72.255.56.29:7001/api/live ^[24]) will expose one post method (PostData) for the data sharing. The details of this web method is as following.

Web API Method to accept the Invoice model and return the unique FBR Invoice number.

Web API method will get the full invoice details with items from the POS Clients and return the unique FBR number. The fields of the model will be as given below.

Invoice Model Detail

Name	Data Type	Status	Sample Value
FBRInvoiceNumber	varchar(30)	Blank
POSID (POS Registration Number given by FBR on registration)	bigint	Compulsory	100000
USIN	varchar(50)	Compulsory	001897
DateTime	datetime	Compulsory	2018-11-01 00:00:00.000
BuyerName	varchar(150)	Optional	Shahzad Ahmed
BuyerPhoneNumber	varchar(20)	Optional	923001234567
TotalSaleValue	decimal(18, 0)	Compulsory	1000.00
TotalQuantity	double	Compulsory	10.00
TotalTaxCharged	float	Compulsory	6.0
Discount	decimal(18, 0)	Optional	10.00
TotalBillAmount	decimal(18, 0)	Optional	10.00
PaymentMode	Int	Compulsory	1.      Cash 2.      Card
RefUSIN	Varchar	Optional (In case of Credit or Debit Note)	001897
InvoiceType	Int	Compulsory	1.      New 2.      Debit 3.      Credit
List<InvoiceItems>	list	Compulsory	Table No 2

Table No. 2 (recursive, will contain multiple items record in an invoice)

Name	Data Type	Status	Sample Value
ItemCode	varchar(50)	Compulsory	0001
ItemName	varchar(150)	Compulsory	Blanket
PCTCode	varchar(8)	Compulsory	01011000
Quantity	double	Compulsory	1.00
TaxRate	float	Compulsory	6.0
SaleValue	decimal(18, 0)	Compulsory	1000.00
TaxCharged	decimal(18, 0)	Compulsory	100
TotalAmount	decimal(18, 0)	Optional	10.00

Following are String return from the Web API.

Json Response string from FBR Web API

{“FBRInvoiceNumber”:11000120181112000369,”Response”:”Invoice received successfully”,”Code”:”100”}

 

Response Message Details:

Message Code	Message Detail
100	Invoice received successfully
101	Error while receiving invoice
102	Invalid data received
103	Some error occurred. Please contact your service provider
104	You are not authorized to use this service

Calling FBR Web Service:

 

Client will add reference of DLL (provided by FBR, PRAL) in their system to access the FBR service. This DLL used other DLL(s) for encryption and signing of data. Following code explains the process of populating invoice mode and passing model.

Integration with JAVA:

 

Create an object of invoice model and fill all the required properties as mentioned below:

Fill the invoice object according to the following example.

Invoice obj = new Invoice();
obj.FBRInvoiceNumber = string.Empty;
obj.POSID = POSID;
obj.USIN = “Test123”
obj.DateTime = “2018-11-01 00:00:00.000”;
obj.BuyerName = “Abdul Rauf”;
obj.BuyerPhoneNumber = “923001234567”;
obj.TotalBillAmount = 1000.00;
obj.TotalQuantity = 10.00;
obj.TotalSaleValue = 100;
obj.TotalTaxCharged = 60.00
obj.Discount = 10.0;

Obj.PaymentMode = 1  // (1: Cash, 2: Card);

model.RefUSIN= string.Empty;

model.InvoiceType=1;  //(1:New, 2:Debit, 3:Credit)
obj.Items = Items();

Below function is to generate list of invoice items.

Public final List<InvoiceItems> Items() {
List<InvoiceItems> lst = new List<InvoiceItems>();
InvoiceItems objItem = new InvoiceItems();
objItem.ItemCode = “12345”;
objItem.ItemName = “Test Name”;

objItem.PCTCode = 01011000;
objItem.Quantity =  10.00;

objItem.TaxRate =  10.00;

objItem.SaleValue =  100;

objItem.TaxCharged =  10.00;
objItem.TotalAmount =  10.00;

lst.Add(objItem);
return lst;
}

Convert Model to JSON String using FlexJSON API

To consume the FBR WEB API in JAVA Flex Json API is used to convert the model object to JSON format.

Below function can convert the object passed to json based string.

Public static String getJsonFromObject(Object object) {

if(object ==null) return null;

Object val=object;

JSONSerializer serializer = new JSONSerializer();

String statusJSON = serializer.deepSerialize(val);

System.out.println(“respose ” + statusJSON);

return statusJSON;

}

 Java.net.URL to post data to provided URL and get the response

Below function is used to call the FBR WebAPI. JSON string is passed to the function along with API URL to which data is being posted. To post the data java.net.URL will be used.

public static String callFBRService(String jsonString,String serverURL) throws IOException{

URL url = new URL(serverURL);

HttpURLConnection conn = (HttpURLConnection) url.openConnection();

conn.setRequestMethod(“POST”);

conn.setRequestProperty(“charset”, “utf-8”);

conn.setRequestProperty( “Content-Type”, “application/json”);

conn.setUseCaches(false);

conn.setDoOutput(true);

DataOutputStream wr = new DataOutputStream(conn.getOutputStream());

wr.write(jsonString.getBytes());

BufferedReader br = null;

StringBuilder outputBuilder = new StringBuilder();

System.out.println(conn.getResponseCode());

br = new BufferedReader(new InputStreamReader((conn.getInputStream())));

String output;

System.out.println(“Output from Server …. n”);

while ((output = br.readLine()) != null) {

System.out.println(output);

outputBuilder.append(output);

}

conn.disconnect();

return outputBuilder.toString();

}

Integration with .NET

Create an object of invoice model and fill all the required properties as mentioned below:

Fill the invoice object according to the following code example.

Invoice obj = new Invoice();

int POSID = 123456;

string baseAddress = “http://72.255.56.29:7001/”

string endPoint = “api/Live/PostData”;

obj.FBRInvoiceNumber = string.Empty;

obj.POSID = POSID;
obj.USIN = “Test123”
obj.DateTime = “2018-11-01 00:00:00.000”;
obj.BuyerName = “Abdul Rauf”;
obj.BuyerPhoneNumber = “923001234567”;
obj.TotalBillAmount = 1000.00;
obj.TotalQuantity = 10.00;
obj.TotalSaleValue = 100;
obj.TotalTaxCharged = 60.00
obj.Discount = 10.0;

obj.PaymentMode = 1  // (1: Cash, 2: Card);

model.RefUSIN= string.Empty;

model.InvoiceType=1;  //(1:New, 2:Debit, 3:Credit)
obj.Items = Items();

private List<InvoiceItems> Items()

{

List<InvoiceItems> lst = new List<InvoiceItems>();

InvoiceItems objItem = new InvoiceItems();

objItem.ItemCode = “12345”;
objItem.ItemName = “Test Name”;

objItem.PCTCode = 01011000;
objItem.Quantity =  10.00;

objItem.TaxRate =  10.00;

objItem.SaleValue =  100;

objItem.TaxCharged =  10.00;
objItem.TotalAmount =  10.00;

lst.Add(objItem);

return lst;

}

Convert Model to JSON String using NewtonSoft JSON API

To consume the FBR WEB API in .NET NewtonSoft Json API is used to convert the model object to JSON format.

String json = JsonConvert.SerializeObject(invoiceObject));

JSON String Example Format:

{

“FBRInvoiceNumber”:””,

“POSID”:112345,

“USIN”:”WBTC_123456″,

“DateTime”:   “2018-11-12T18:11:42.8549029+05:00   “,

“BuyerName”:”WBTC_Test Buyer”,

“BuyerPhoneNumber”:”03455275501″,

“TotalBillAmount”:4000.0,

“TotalQuantity”:10.00,

“TotalSaleValue”:16.0,

“TotalTaxCharged”:10.0,

“Discount”:10.0,

“PaymentMode”:1,

” RefUSIN “:””,

” InvoiceType “:1,

“Items”:[

{

“ItemCode”:”12345″,

“ItemName”:”Test Description”,

“PCTCode”:”01011000″,

“TaxRate”:6.0

“SaleValue”:1000,

“TaxCharged”:100,

“Quantity”:10,

“TotalAmount”:1100

}

]

}

WebClient to post data to provided URL and get the response

Below code is used to call the FBR WebAPI. JSON string is passed to the function along with API URL to which data is being posted.

InvoiceResponseModel objMR = null;

string response = string.Empty;

try

{

string APIURL = string.Empty;

using (var client = new WebClient())

{

APIURL = _baseAddress + _endPoint;

client.Headers.Add(“Content-Type:application/json”);

client.Headers.Add(“Accept:application/json”);

client.Encoding = UTF8Encoding.UTF8;

var result = client.UploadString(APIURL, JsonConvert.SerializeObject(_invoice));

objMR = JsonConvert.DeserializeObject<InvoiceResponseModel>(result);

response = JsonConvert.SerializeObject(objMR);

}

}

catch (Exception ex)

{

response = ex.Message;

}

return response;

 

Add supporting DLL(s) for .Net Integration:

 

For the further ease of use for .Net consumers we have provided following dll(s) that facilitate easy integration with FBR web service.

Reference following dynamic link libraries in .Net POS project

1. FBRIMS.dll
2. NewtonSoft.dll

Use the following code to upload the invoice data in FBR System.

Fill the Invoice object as did in the Fill the invoice object as in section 7.2.1

 After filling invoice data into the Invoice object, use the following code to post data to FBR System.

FBRIMS.API objAPI = new FBRIMS.API(int  POSID, String baseAddress, String endPoint, int PosMode, Invoice  objInvoice);

InvoiceResponseModel response = JsonConvert.DeserializeObject< InvoiceResponseModel >(objAPI.Send());

Technical Support

• Email: helpline@fbr.gov.pk ^[25]
• Phone: (051) 111-772-772