GST API Integration Guide

How to connect Lekhya to production GST APIs through a GSP gateway for e-invoicing, GSTIN validation, GSTR filing, and more.

Architecture Rule

Lekhya NEVER calls GST APIs directly. All calls go through a GstGateway interface. This lets you swap between the mock gateway (for testing) and a real GSP gateway (for production) by changing one line in config. You are never locked to a specific GSP provider.

GST API Ecosystem — What You Need

GSP (GST Suvidha Provider)

Mandatory intermediary to access NIC/GSTN APIs. Examples: Karvy, Masters India, ClearTax, IRIS, Mastercard, E2I. Your company must register with one.

GSTIN Validation

Free API via GST portal. Validates GSTIN format + returns legal name, trade name, status, registration date.

e-Invoice (IRN Generation)

Available through GSP. Required if annual turnover > ₹5 crore (threshold configurable in Lekhya settings).

e-Way Bill

Available through GSP. For movement of goods > ₹50,000. Auto-generated when e-invoice is created.

GSTR-1 Filing

File monthly/quarterly outward supply return via GSP or GST portal APIs.

GSTR-2B Pull

Pull auto-drafted ITC statement from GSTN via GSP. Used for GSTR-2B reconciliation.

Step 1 — Choose & Register with a GSP

Register your business with a GSP. Popular options:

GSPWebsiteBest ForPricing
Masters Indiamastersindia.coSME & Enterprise₹1-3/IRN
ClearTaxcleartax.inCA Firms, Mid-Market₹2-4/IRN
IRIS Businessirisgst.comEnterpriseVolume pricing
Karvy Computersharekarvy.comLarge EnterpriseCustom
E2I Technologiese2i.inSME₹1-2/IRN

Step 2 — Configure Lekhya .env

# In lekhya-app/.env

GST_DRIVER=masters_india # or: cleartax | iris | karvy | mock

GST_CLIENT_ID=your-client-id

GST_CLIENT_SECRET=your-client-secret

GST_USERNAME=your-gstn-username

GST_PASSWORD=your-gstn-password

# E-invoice threshold (turnover in crores)

GST_EINVOICE_THRESHOLD_CRORE=5

# GSP base URLs (example: Masters India)

GST_API_BASE=https://api.mastersindia.co/mastersindia

GST_AUTH_URL=https://api.mastersindia.co/oauth/token

Step 3 — Implement Your GSP Gateway Class

Create a new class implementing the GstGateway interface for your GSP:

// app/Services/GST/MastersIndiaGateway.php

class MastersIndiaGateway implements GstGateway {

private string $accessToken;

public function generateIrn(array $payload): array {

$token = $this->getAccessToken();

$response = Http::withToken($token)

->post(config('services.gst.base') . '/einvoice/generate', [

'gstin' => config('services.gst.gstin'),

'payload' => $payload,

]);

return $response->json();

}

// ... implement all GstGateway methods

}

Then register in AppServiceProvider::register():

$this->app->singleton(GstGateway::class, function () {

return match(config('services.gst.driver')) {

'masters_india' => new MastersIndiaGateway(),

'cleartax' => new CleartaxGateway(),

default => new MockGstGateway(),

};

});

GST APIs Available in Lekhya

GET /gst/validate-gstin?gstin=29ABCDE1234F1Z5 Validates format + checksum + live status from GSTN
POST /gst/e-invoice/{invoice}/generate Builds e-invoice JSON, calls GSP, stores IRN + QR
POST /gst/eway-bill/{invoice}/generate Auto-creates EWB from invoice data
POST /gst/gstr1/generate Aggregates posted invoices into GSTR-1 JSON format
POST /gst/gstr1/file Pushes GSTR-1 JSON to GSTN via GSP. Returns ARN.
POST /gst/gstr2b/import Upload 2B JSON from GST portal → stored for reconciliation
GET /gst/gstr2b/reconcile Match purchase invoices vs 2B. Flag mismatches.

Testing in Sandbox Mode

# Use mock gateway (default in development)

GST_DRIVER=mock

# For GSP sandbox (if your GSP provides one)

GST_DRIVER=masters_india

GST_API_BASE=https://sandbox-api.mastersindia.co

# Run e-invoice generation test

php artisan gst:test-irn --invoice=1