E-Way Bill System User Manual for API Interface

Introduction OF e-Way Bill System API Interface

The introduction of Goods and Services Tax (GST) in India on July 1, 2017, marked a significant milestone in the country’s indirect tax reforms. As part of this reform, all check posts across India were abolished to facilitate the smooth movement of goods throughout the country. To ensure seamless transportation and compliance, the GST system introduced the concept of an electronic waybill or e-Way Bill. The e-Way Bill is a digitally generated document that the person in charge of the conveyance must carry.

To implement the e-Way Bill system, an ICT-based solution was required. In line with the approval of the Goods and Services Tax (GST) Council, the National Informatics Centre developed a web-based solution for taxpayers and transporters to generate e-Way Bills. An API interface mechanism was also enabled, allowing taxpayers to directly link their systems with the e-Way Bill system for generating e-Way Bills.

This web-based solution and API interface mechanism aim to streamline and simplify the process of generating e-Way Bills, ensuring the efficient movement of goods and compliance with GST regulations.

Purpose and Intended Audience

The purpose of this document is to provide a comprehensive explanation of the operational procedure for using the API-based interface to generate e-Way Bills. It also outlines the key features and provides sample methods for utilizing this system effectively.

The intended audience for this document primarily includes two main stakeholders of the e-Way Bill system under GST:

• Big registered taxpayers under GST: This refers to large businesses or organizations registered under the Goods and Services Tax system. They play a crucial role in generating e-Way Bills for the movement of their goods. This document will provide them with the necessary information to efficiently understand and utilize the API-based interface for e-Way Bill generation.
• Transporters: Transporters are responsible for physically moving goods from one location to another. They also play a significant role in the e-Way Bill system. This document will help transporters understand how to use the API-based interface for e-Way Bill generation and ensure compliance with the necessary procedures.

By providing detailed guidance on the API-based interface and its usage, this document aims to assist the intended audience in effectively generating e-Way Bills and facilitating the smooth movement of goods by the GST regulations.

URL or Website Address

The official website for e-Way Bill generation and related services under the Goods and Services Tax (GST) system is https://ewaybillgst.gov.in. This website is the central platform for taxpayers, transporters, and other stakeholders to access and utilize the e-Way Bill system. Users can visit this website to register, generate, update, cancel, and perform other necessary actions related to e-Way Bills.

2. e-Way Bill API Interface

The E-Way Bill team is pleased to offer the API interface with the E-Way Bill (EWB) system. This API allows taxpayers or transporters who have automated their systems to generate e-way bills online from their systems seamlessly. The API interface enables taxpayers or transporters to integrate their automated systems with the EWB system. This allows them to initiate requests for e-way bill generation, updates, and retrieval of data related to their e-way bills.

By utilizing the API interface, taxpayers or transporters can establish direct system-to-system communication with the EWB system, eliminating the need for manual entry or duplication of data. This not only saves time but also reduces the chances of errors during the e-way bill generation process.

The API interface empowers taxpayers or transporters to streamline their operations by automating the generation and management of e-way bills within their existing systems. It offers a convenient and efficient solution for integrating the EWB system into their workflow, ensuring seamless data exchange and synchronization.

With the API interface, taxpayers or transporters can enhance their overall business processes and comply with the e-Way Bill regulations more efficiently and reliably.

3. Benefits of e-Way Bill System

Using APIs in the e-Way Bill system benefits taxpayers, transporters, and GST Suvidha Providers. Here are some of the key advantages of having an API interface integrated with their systems:

• Avoidance of duplicate or double entry of invoices: With the API integration, the need for manual entry of sales details in the computerized system and separately generating the e-Way Bill is eliminated. This helps avoid duplicate or double entries of invoice data, saving time and reducing the risk of errors.
• Reduction of errors in e-Way Bill generation: When generating e-Way Bills manually, there is a possibility of mistakes or errors in data entry. Utilizing the API interface can minimize such errors as the data is automatically fetched from the integrated system, reducing the chances of inaccuracies in the e-Way Bill.
• Eliminating the need for separate prints of invoice and e-Way Bill: In the manual process, the invoice and the e-Way Bill must be printed separately. However, with API integration, including the e-Way Bill number on the invoice print is possible. This eliminates the need for separate prints and streamlines the documentation process.
• Automatic linking of e-Way Bill with invoice number: Manual processes cannot often link the e-Way Bill with the corresponding invoice number in the taxpayer’s system. The e-Way Bill number can be automatically linked and associated with the invoice details in the taxpayer’s system using the API interface. This ensures proper synchronization of data and improves overall efficiency.

By leveraging the benefits of API integration, taxpayers and transporters can streamline their processes, reduce errors, save time, and enhance compliance with the e-Way Bill requirements under GST.

4. Prerequisites for e-Way Bill

To utilize the API interface for e-Way Bill generation, taxpayers or transporters must fulfill the following prerequisites:

• Automated invoice generation process: The taxpayer or transporter should have an automated invoice generation system. This system should be able to integrate with the e-Way Bill API to exchange data seamlessly.
• Minimum activity threshold: The taxpayer or transporter must generate or update 1000 activities per day on the e-Way Bill system. This ensures that entities with significant transactions utilize the API integration.
• SSL or TSL-based domain name: The taxpayer or transporter system must have a domain name that supports SSL (Secure Sockets Layer) or TLS (Transport Layer Security) encryption. This ensures secure communication between the system and the e-Way Bill API.
• Static IP address: The taxpayer or transporter’s system should have a static IP address. A static IP address enables consistent and reliable connectivity between their and e-Way Bill systems.
• Modification of automated system: The taxpayer or transporter needs to make necessary modifications to their automated system to enable data exchange with the e-Way Bill system using the API. This includes incorporating the required API endpoints and data formats into their existing system.
• Pre-production system for testing: The taxpayer or transporter should have a separate pre-production environment to test the integration of their modified system with the e-Way Bill API. This allows for thorough testing and validation of the API functionality before deploying it in a production environment.
• Comprehensive testing: The taxpayer or transporter is advised to test their modified system on the e-Way Bill pre-production site, covering all activities and services. This ensures the integration functions smoothly and accurately handles various scenarios and transactions.

By meeting these prerequisites, taxpayers or transporters can effectively integrate their systems with the e-Way Bill API and leverage its capabilities for streamlined e-Way Bill generation and management.

5. Onboarding process

To onboard and start using the API interface for e-Way Bill generation, taxpayers or transporters need to follow these steps:

• Read the API-related documents: Familiarize yourself with the documentation provided for the e-Way Bill API. Understand the API endpoints, data formats, and authentication mechanisms.
• Log in to the e-way bill system: Access the e-way bill system using your credentials.
• Select the ‘For API’ option: Navigate to the ‘Registration’ menu and choose the ‘For API’ option. This indicates your intention to integrate your system with the e-Way Bill API.
• Enter request details: In the provided fields, provide the required information, such as your domain name and static IP address. These details ensure a secure and reliable connection between your system and the e-Way Bill system.
• Submit the request: After entering the necessary details, submit the request for API integration.
• Obtain credentials: Upon submission, the e-Way Bill system generates and displays the following credentials: Client_Id, Client_Secret, UserName, and Password. These credentials will be used for authentication and authorization when making API requests.
• Modify the automated system: Share the generated credentials with your IT team, who will be responsible for changing or modifying your automated system to incorporate the API functionality. This includes updating endpoints, data structures, and authentication mechanisms as per the API documentation.
• Test the modified system: Utilize your pre-production system to thoroughly test the modified system’s integration with the e-Way Bill pre-production system. Conduct tests covering all activities and services, ensuring accurate data exchange and system functionality.
• Complete testing with 200 activities: As a best practice, perform extensive testing by simulating at least 200 activities on your pre-production system. This ensures that the integration is robust and can handle real-world scenarios effectively.
• Move to production: After successful testing and validation, you can transition from the pre-production environment to the production environment. Your modified system will be ready for live usage at this stage, and you can begin generating e-Way Bills using the API interface.

6. Interfacing examples

6.1. API Interface for Tax Payer system – One of the ways of interfacing

This example represents one possible method of interfacing the EWB API into a taxpayer system. The taxpayer can design their own process based on their specific business requirements. The following steps outline this particular method:

• Taxpayer enters invoice details: The invoice details are entered in the taxpayer’s automated system.
• Invoice generation and storage: Upon submitting the invoice details, the taxpayer’s system generates the invoice number and stores it in their system for future reference.
• Call to EWB API: The taxpayer’s system initiates a call to the EWB API, providing the relevant information required to generate the e-way Bill. This information may include invoice details, transporter details, item details, etc.
• Authentication and verification: The EWB API authenticates and verifies the provided information to ensure its accuracy and compliance with e-Way Bill regulations.
• E-way bill generation: After successful authentication and verification, the EWB API generates the e-way Bill and returns an EBN (E-Way Bill Number).
• EBN storage: The taxpayer’s system receives the EBN and saves in their database, associating it with the corresponding invoice record. This linkage allows for easy retrieval and tracking of the e-way Bill associated with each invoice.
• Invoice preparation and printing: The taxpayer’s system prepares the invoice printout, including the EBN of the bottom. This printed invoice serves as a legal document accompanying the goods during transportation.
• Handing over the invoice: The taxpayer provides the printed invoice to the transporter or driver responsible for the movement of goods. The presence of the EBN on the invoice ensures compliance with e-Way Bill requirements and facilitates the seamless movement of goods across the country.

It is important to note that this is just one example of how the taxpayer system can interface with the EWB API. The implementation may vary based on the taxpayer’s specific workflow and system capabilities.

6.2. API Interface for Transporter system – One of the ways of interfacing

Note: This is just one example of how the EWB API can be integrated into a transporter system. The specific process or method can be tailored according to the business needs of the transporter.

Here is a sample method of interfacing the EWB API with a transporter system:

• On an hourly basis, the transporter system retrieves all the e-way bills assigned to them by using the EWB API. These e-way bills are then stored in the transporter’s system for further processing.
• Before moving goods, the transporter enters the vehicle number associated with their consignment and saves it in their system.
• The transporter system then initiates a request to the EWB system using the EBN (e-way bill number) and other relevant details, seeking to update Part B of the specific e-way bill.
• The EWB system authenticates and verifies the details provided and updates the vehicle details for the e-way bill upon successful validation. An acknowledgment (ACK) is generated and returned to the transporter system.
• The transporter system captures this ACK and updates it in their system, indicating that the vehicle details have been successfully updated. The transporter can then generate and print the trip sheet or manifesto containing the updated information.
• With the trip sheet or manifesto, the transporter will transport the goods with the updated e-way bill and relevant documentation.

It is important to note that this is just one way to integrate the EWB API into a transporter system. Transporters can customize their processes and methods based on their specific requirements and operational workflows.

7. List of E-Way Bill API Services/Methods

Sl No.	API Service	API Description	Response (data)	Applicable To
1.	Authenticate	Authenticate with the credential to access the APIs	Token	Tax Payer, Transporter, Suvidha Provider
2.	Get e-Way Bill	Get the e-Way Bill details based on EWB Number EW	EWB Object, Vehicle details	Tax Payer, Transporter, Suvidha Provider
3.	Get Consolidated E-Way Bill	Get the Consolidated eWay Bill details based on EWB Number	CEWB Object, Vehcile Details	Transporter, Suvidha Provider
4.	Get E-Way bill generated by others	Get the list of e-Way Bills generated by other party for my name based on generated date	List of EWBs (EWB_No, Date, Gen_GSTIN, Oth_party_GSTIN, TRN_Type, Sub_TRN_Type, Doc_no, Doc_date, Tot_value)	Tax Payer, Suvidha Provider
5.	Get assigned E-Way Bills of my state	Get the list of e-Way Bills assigned to me for transportation in my state	List of EWBs (EWB_No, EWB_Date, Gen_GSTIN, TRANS_Doc_No, TRANS_Doc_Date, DEL_PIN_CODE, DEL_State)	Transporter
6.	Get assigned E-Way Bill by GSTIN	Get the list of e-Way Bills assigned to me for transportation by particular GSTIN	List of EWBs (EWB_No, EWB_Date, Gen_GSTIN, TRANS_Doc_No, TRANS_Doc_Date, DEL_PIN_CODE, DEL_State)	Transporter
7.	Generate EWay Bill	Generate e-Way Bill	EWB_No, Date	Tax Payer, Transporter, Suvidha Provider
8.	Update Vehicle Number to EWay Bill	Update new vehicle number for the e-way Bill	EWB_No, Date, Ref_Uniq_No	Tax Payer, Transporter, Suvidha Provider
9.	Cancel EWay Bill	Cancel the e-Way Bill	EWB_No, Date, Ref_Uniq_No	Tax Payer, Transporter, Suvidha Provider
10.	Reject EWay Bill	Reject the e-Way Bill	EWB_No, Date, Ref_Uniq_No	Tax Payer, Suvidha Provider
11.	Generate Consolidate E-Way Bill	Generate Consolidated e-Way Bill	CEWB_No, Date	Tax Payer, Transporter, Suvidha Provider

8. Authentication API

To access the EWB API, an application needs to go through the authentication process by using the provided credentials and obtaining an access token. This access token is used for subsequent API calls.

The authentication API is responsible for issuing the access token. Once obtained, the access token should be included in the header information of each API request for authentication and authorization purposes.

It is important to note that the access token has a configured expiration time of 360 minutes. Once the token expires, the application must invoke the authentication API again to obtain a new access token.

By including the access token in the API header, the system can authenticate and authorize the application to perform the requested actions securely.

9. Service Request API

The Service Request API allows the user application to access services such as generating e-way bills, updating vehicles, and canceling e-way bills. To utilize these services, the user application must obtain a valid authentication token through the authentication process.

Using the authentication token, the user application can send requests to the Service Request API with the relevant parameters required for the specific service. These parameters may include invoice details, vehicle numbers, and cancellation reasons.

Upon receiving the request, the API processes the information and provides a response or result based on the requested service. This response can include the generated e-way bill number, confirmation of vehicle update, or acknowledgment of the e-way bill cancellation.

By leveraging the Service Request API and providing the necessary parameters, the user application can interact with the e-Way Bill system to perform various actions related to e-way bills.

10. API Overview 

The EWAYBILL APIs facilitate communication between Tax Payers and Transporters within the e-way Bill System. These APIs follow certain standards and formats to define the interactions with the EWAYBILL systems. The APIs are implemented as RESTful web services.

Here are some key points regarding the EWAYBILL APIs:

• The APIs are published as RESTful web services accessible over HTTPS.
• The HTTP methods used for the API interactions are GET, which is used to fetch data from the EWAYBILL system, and POST, which is used to submit data to the EWAYBILL system.
• The content type used for the API requests and responses is JSON. This means the data exchanged between the client and the server will be in JSON format.

By adhering to these standards and utilizing the EWAYBILL APIs, Tax Payers and Transporters can effectively communicate and interact with the e-way Bill System to perform various operations related to e-way billsAPI supporting Documents

11. API supporting Documents

When a taxpayer registers for API access, they will have access to the following supporting documents online:

• API Specification Details: This document provides detailed information about the API endpoints, request/response formats, authentication methods, and other technical specifications.
• API field details: This document lists all the fields and parameters that can be used in API requests and provides information about their data types, formats, and usage.
• Master Codes: This document contains a list of codes or identifiers used in the API for specific purposes, such as identifying tax types, modes of transport, or document types. It helps in understanding and populating the relevant codes in API requests.
• Error Codes: This document outlines the error codes and messages the API can return in case of failures or invalid requests. It assists in understanding and handling error scenarios.
• Sample JSON Data format: This document provides sample JSON data structures for API requests and responses. It helps understand the expected data format and structure when interacting with the API.
• DSC for encryption: This document provides information about Digital Signature Certificate (DSC) requirements and encryption mechanisms that may be used for secure communication and data exchange with the API.

These supporting documents are valuable for taxpayers to understand and implement the API integration effectively. They provide necessary technical information, guidelines, and examples to ensure seamless interaction with the e-way Bill System through the API.