GST Reconciliation

Compares invoice records with ledger records and returns reconciliation results, including matched records, mismatches and reported missing-record counts.

API Details

Method: POST

Endpoint: /gst-recon/reconcile

Base URL: https://uatapi.wowpe.in/api/api/api-module

Authentication

Header	Type	Description
X-Client-Id	String	Client ID provided by WowPe.
X-Client-Secret	String	Client secret provided by WowPe.
Content-Type	String	application/json.

Comparison Types

The endpoint is designed to support two reconciliation modes.

comparisonType	Purpose	Availability
Omitted or ledger	Compares invoice records against ledger records.	Existing UAT behaviour documented.
statement	Compares a purchase register against a GSTR-2A/GSTR-2B statement snapshot.	Proposed; unified endpoint integration and UAT testing are pending.

Existing callers can omit comparisonType to retain the original ledger flow. Do not use statement mode until the integration is deployed and validated.

Request Parameters: Ledger Mode

Content-Type: application/json

Parameter	Type	Mandatory	Description
invoices	Array	As required by the existing contract	Invoice records to reconcile.
ledger	Array	As required by the existing contract	Ledger records to compare.
tolerance	Number	Optional	Amount variance tolerance. The supplied model default is 0.01.
invoiceId	String	Optional	Invoice identifier or reference.
ledgerName	String	Optional	Ledger name or reference.
comparisonType	String	Optional	Use ledger to explicitly select invoice-versus-ledger reconciliation.

Invoice objects use fields such as id, sourceFile, sourcePages, beneficiaryName, uniqueRefNo, gstin, documentDate, documentType, extractionMethod, taxableValue, cgst, sgst, igst, gstAmount and reviewed.

Ledger objects use line, the corresponding supplier/reference/document fields and the five amount fields. Confirm the full DTO before constructing a production request.

Sample Request: Ledger Mode

JSON

{
  "comparisonType": "ledger",
  "invoices": [],
  "ledger": [],
  "tolerance": 0.01,
  "ledgerName": "example-ledger"
}

This shows the top-level structure only. Populate the arrays with records matching the approved DTO. Empty arrays are not a substitute for actual invoice or ledger data.

Sample Response: Ledger Mode

JSON

{
  "statusCode": 1,
  "message": "Success",
  "invoiceId": null,
  "ledgerName": "example-ledger",
  "totalInvoices": 1,
  "totalLedgerRows": 1,
  "matchedCount": 1,
  "mismatchCount": 0,
  "missingInLedgerCount": 0,
  "missingInInvoicesCount": 0,
  "tolerance": 0.01,
  "results": [
    {
      "id": "example-invoice-id",
      "beneficiary": "Example Supplier",
      "reference": "0007",
      "source": "invoice.pdf",
      "ledgerLine": 1,
      "invoiceGst": 180,
      "ledgerGst": 180,
      "variance": 0,
      "state": "Matched",
      "issues": []
    }
  ]
}

Note: Representative of the existing UAT response structure. The sample values are illustrative.

Request Parameters: Statement Mode

Availability: Proposed. Do not use until unified dispatch, authorization and UAT validation are complete.

Parameter	Type	Description
comparisonType	String	Must be statement.
recipientGstin	String	GSTIN associated with the purchase statement. The host must verify that the caller is authorized for this GSTIN.
statementType	String	GSTR-2A or GSTR-2B.
statementPeriod	String	Statement period in yyyy-MM format.
statementDownloadedAt	String	Statement snapshot timestamp with timezone offset.
purchasePeriodStart	String	Inclusive start date for purchase documents.
purchasePeriodEnd	String	Inclusive end date for purchase documents.
tolerance	Number	Variance tolerance, default 0.01, supported range 0–100 currency units per numeric field.
purchases	Array	Normalized purchase-register records.
statementRows	Array	Normalized rows from the supplied portal statement snapshot.

The statement request supports up to 5,000 rows across both arrays. Submit one normalized statement snapshot per request. Raw nested portal exports, PDFs and multi-sheet files are not automatically parsed by this reconciliation mode.

Sample Request: Statement Mode

Proposed request only. This has not been executed through the unified HTTP endpoint.

JSON

{
  "comparisonType": "statement",
  "recipientGstin": "27FGHIJ5678K1Z2",
  "statementType": "GSTR-2B",
  "statementPeriod": "2026-04",
  "statementDownloadedAt": "2026-05-15T10:00:00Z",
  "purchasePeriodStart": "2026-04-01",
  "purchasePeriodEnd": "2026-04-30",
  "tolerance": 0.01,
  "purchases": [
    {
      "sourceId": "purchase-1",
      "sourceFile": "purchase-register.json",
      "sourceLocation": "rows[0]",
      "recipientGstin": "27FGHIJ5678K1Z2",
      "supplierGstin": "27ABCDE1234F1Z5",
      "documentNumber": "INV/1",
      "documentDate": "2026-04-01",
      "documentType": "Invoice",
      "taxableValue": 100,
      "cgst": 9,
      "sgst": 9,
      "igst": 0,
      "cess": 0
    }
  ],
  "statementRows": [
    {
      "sourceId": "statement-1",
      "sourceFile": "2b-normalized.json",
      "sourceLocation": "b2b[0]",
      "recipientGstin": "27FGHIJ5678K1Z2",
      "supplierGstin": "27ABCDE1234F1Z5",
      "documentNumber": "INV/1",
      "documentDate": "2026-04-01",
      "documentType": "Invoice",
      "statementPeriod": "2026-04",
      "isAmendment": false,
      "taxableValue": 100,
      "cgst": 9,
      "sgst": 9,
      "igst": 0,
      "cess": 0
    }
  ]
}

The example uses synthetic identifiers and amounts. Use authorized recipient and supplier data only after the integration and access checks have been implemented.

Statement Record Fields

Both purchases and statementRows use normalized document records. Important fields include:

Parameter	Type	Description
sourceId	String	Unique identifier within the input array.
sourceFile	String	Original source file name.
sourceLocation	String	Original row, sheet or JSON location.
recipientGstin	String	Recipient GSTIN associated with the document.
supplierGstin	String	Supplier GSTIN used for matching.
documentNumber	String	Invoice or document reference.
documentDate	String	Document date.
documentType	String	Invoice, CreditNote or DebitNote.
statementPeriod	String	Statement period for statement rows; must match the request period.
isAmendment	Boolean	Indicates whether the statement row is an amendment.
originalDocumentNumber	String	Original document reference, where applicable.
originalDocumentDate	String	Original document date, where applicable.
taxableValue	Number / Null	Taxable amount.
cgst	Number / Null	Central GST amount.
sgst	Number / Null	State GST amount.
igst	Number / Null	Integrated GST amount.
cess	Number / Null	Cess amount.
portalItcStatus	String	Original portal ITC status retained as evidence, not an eligibility decision.

Supply explicit zero only when the source confirms zero. Keep unknown amounts distinct from zero. Credit-note amounts must use the agreed normalized accounting sign.

Response Parameters: Ledger Mode

Parameter	Type	Description
statusCode	Number	Business-level status. In observed UAT responses, 1 indicated success and 0 indicated rejection.
message	String	Response message.
invoiceId	String / Null	Invoice identifier, which may be null.
ledgerName	String	Ledger name or reference.
totalInvoices	Number	Reported invoice count.
totalLedgerRows	Number	Reported ledger row count.
matchedCount	Number	Reported matched count.
mismatchCount	Number	Reported mismatch count.
missingInLedgerCount	Number	Reported count of records missing from the ledger.
missingInInvoicesCount	Number	Reported count of records missing from invoice data.
tolerance	Number	Variance tolerance used.
results	Array	Individual reconciliation results.
state	String	Reconciliation state reported for a result.
issues	Array	Issues associated with a result.

Inspect each result and its issues. Historical UAT counters did not always agree with detailed missing-row issues.

Response Parameters: Statement Mode

The following describes the proposed core-service result. The unified HTTP response envelope and casing remain unverified.

The statement result contains:

Parameter	Description
isValid	Indicates whether the statement request passed core validation.
message	Validation or processing message.
recipientGstin	Recipient GSTIN used for the comparison.
statementType	Statement type used.
statementPeriod	Statement period used.
tolerance	Variance tolerance used.
totalPurchases	Number of purchase records.
totalStatementRows	Number of statement rows.
matchedCount	Number of numeric matches.
mismatchCount	Number of mismatches.
reviewCount	Number of result groups requiring review.
missingInStatementCount	Number of purchase records absent from the supplied statement snapshot.
missingInPurchasesCount	Number of statement records absent from the supplied purchase register.
validationErrors	Request validation errors.
results	Individual comparison results.

Each statement result may contain status, matchBasis, requiresReview, reviewFlags, purchases, statementRows and amounts.

Supported result statuses are:

• Matched
• Mismatch
• MissingInStatement
• MissingInPurchases
• ReviewRequired

Each amount evidence object contains field, purchaseAmount, statementAmount, difference and withinTolerance. The difference is calculated as purchase amount minus statement amount.

All statement results retain requiresReview: true, including numeric matches. A matched result does not establish legal input tax credit eligibility.

Error Handling

For the existing ledger mode, inspect the HTTP status, business-level statusCode and individual result issues.

For the proposed statement mode, the intended validation behaviour includes:

HTTP Status	Intended behaviour
200 OK	Statement comparison completed and returned evidence results.
400 Bad Request	Invalid comparison type, conflicting fields or invalid statement request.
401 Unauthorized	Statement merchant or recipient authorization rejected.

These statement-mode HTTP behaviours are proposed and have not been validated through the unified endpoint. The final response envelope must be confirmed after integration.

Important Notes

• Keep existing ledger-mode requests and responses backward-compatible.
• Do not send ledger and statement field sets together.
• Invalid or blank comparisonType values must not silently trigger a different comparison mode.
• Statement mode requires recipient GSTIN ownership authorization in the host application.
• Match candidates use supplier GSTIN, reference, document type and Indian financial year. Document dates must agree for a numeric match.
• Duplicates, amendments, missing values and identity/date conflicts require review.
• Missing records refer only to absence from the supplied statement snapshot or purchase register.
• Do not infer tax eligibility, supplier ownership or data persistence from a match.
• The statement matching engine was tested separately; unified endpoint integration and UAT testing are still pending.

What's Next

For ledger mode, review and approve the invoice and ledger records before reconciliation. For statement mode, wait for the unified integration to be deployed and validated, then review every result, amount variance and review flag before using the output.