Technical Specification for Data Sharing Web Services from Textile and Leather sector with FBR

Print This Post Print This Post

INTRODUCTION

The purpose of the article 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

                                                          POS Registration 0‑1

For POS registration, log in on web site https://e.fbr.gov.pk 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) 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) Compulsory 10.00
PaymentMode Int Compulsory 1.      Cash

2.      Card

3.      Gift Voucher

4.      Loyalty Card

5.      Mixed

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

                                                                  Invoice Data 1

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
Discount decimal(18, 0) Optional 10.00
TaxCharged decimal(18, 0) Compulsory 100
TotalAmount decimal(18, 0) Compulsory 10.00
InvoiceType Int Compulsory 1.      New

2.      Debit

3.      Credit

RefUSIN Varchar Optional (In case of Credit or Debit Note)  

001897

                                                                    Invoice Item 1

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

                                               Response Messages 1

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 to

Integration with JAVA

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

Code:

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, 3: Gift voucher, 4: Loyalty card, 5:Mixed);

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.Discount = 10.0;

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

objItem.RefUSIN= string.Empty;

objItem.InvoiceType=1;  //(1:New, 2:Debit, 3:Credit, )

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.Discount = 10.0;

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

objItem.RefUSIN= string.Empty;

objItem.InvoiceType=1;  //(1:New, 2:Debit, 3:Credit, )

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,

\”Discount\”:\1000,

\”TaxCharged\”:\100,

\”Quantity\”:10,

\”TotalAmount\”:1100

\” RefUSIN \”:\”\”,

\” InvoiceType \”:1,

}

]

}

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:

Post Rating
[Total: 0 Average: 0]

Leave a Reply

Your email address will not be published. Required fields are marked *

three × one =