Getting Started

The Octa API provides secure, JSON-based REST endpoints that allow seamless integration with any modern programming language or framework. Designed for flexibility and scalability, it enables developers to connect directly with Octa GST services for tasks such as generating e-invoices & e-waybills, getting GSTIN registration information, retrieving returns data and compliance data. With a single base URL and consistent request/response formats, the Octa API ensures a simple, reliable, and developer-friendly experience.

All APIs can be accessed using the following base URL:

https://app.octagst.com/api/...

#Authentication

API authentication is done using the http basic authentication. This is done using the Authorization http header in the request. This header can be constructed as follows:

• The username and password are combined with a single colon :.
• The resulting string is encoded in byte array using UTF-8 encoding.
• The resulting string is encoded in base64 string.
• The resulting string is prefixed with the authorization method Basic.

For example, if username is ramesh and password is elephant@123 then http header would be:

Authorization: Basic cmFtZXNoOmVsZXBoYW50QDEyMw==

The Key Id and Key Secret generated in Octa act as your API credentials. When making API calls, use the Key Id as the username and the Key Secret as the password for authentication.

Refer to the next section for instructions on how to generate your Key Id and Key Secret.

#Generate API Key

• Login to Octa GST
• Go to the API Keys page (check the buttons on the top).
• Click on New Key button, accept the confirmation. This will generate a new API Key and display on screen. This key will be displayed only once. So please copy the Key Id and Key Secret shown on the screen.
• This Key Id and Key Secret can be configured in the ERP (or any other external system) to access Octa APIs.

#Using an API

Depending on the endpoint, the Octa API supports either GET or POST HTTP methods. All requests follow standard HTTP conventions. For authentication, every request must include the Authorization header. Additional headers may be required based on the specific API being called, as detailed in the documentation for each endpoint.

#Error Handling

When an API request cannot be processed successfully, Octa provides a clear error response to help you diagnose and fix the issue quickly.

• Standard HTTP status codes: Any code in the 4xx or 5xx range indicates an error.
• Octa-specific error details: Additional information is returned in the response headers:
  • Octa-ErrorCode: A unique code identifying the type of error. (Refer Octa Error Codes)
  • Octa-ErrorMessage: A descriptive message explaining the reason for the failure.

#Fair Use

To protect Octa GST from abuse and ensure fair usage, the system may enforce rate limits. When a rate limit is exceeded, the API will respond with the HTTP status code:

429 Too Many Requests

In this case, clients should implement delays with exponential back-off before retrying the request. This helps prevent repeated failures and ensures compliance with Octa’s fair use policy.

#Check API Usage

You can check the summary of your API usage and current API balance anytime on Octa app:

• Login to Octa GST
• Go to the API Usage page (check the buttons on the top).
• Select a month to check the API usage summary in that month.
• Your current API balance will be displayed in the top.