The implemented e-invoice flow starts on an xMatix Invoice. Its server action builds and stores an e-invoice payload on that Invoice and marks the request Pending. A separately configured integration must submit the payload to an Invoice Registration Portal/GSP and record the response. IRN, acknowledgment, QR and signed-response fields remain on the source Invoice.
This distinction is important: although the domain also contains an EInvoice entity, the reviewed runtime action does not create or update a separate EInvoice record. A blank New E-Invoice form therefore does not represent the supported generation workflow and is intentionally not shown here.
Fields on the source Invoice
The active services read and write these Invoice fields:
| Stage | Invoice fields |
|---|---|
| Staging | EINVPayload, EINVStatus |
| Successful writeback | EINVIRN, EINVAckNo, EINVAckDate, EINVQRCode, EINVSignedInvoice, EINVResponse, generated status |
The built-in response recorder is a success path: it requires a nonblank IRN and then sets the Invoice to Generated. It does not expose a companion failure-recording method, so the integration design must define where rejected-provider evidence is retained.
The Generate action refuses to stage a second request once the Invoice already has an IRN. That is the implemented duplicate-generation guard.
Before enabling the integration
The repository includes a ClearTax connector manifest as an example integration definition, but the Finance action does not automatically select, authenticate or execute that connector. Configure and test an Integration Hub flow explicitly for each filing context, including how it:
- detects or receives an Invoice whose
EINVStatusis Pending; - submits
EINVPayloadto the intended provider; - maps successful responses back to the same Invoice and retains failed-provider responses in an explicitly designed error/audit path; and
- prevents duplicate or out-of-order writeback.
Also validate the staged payload against the provider before production use. The current payload builder fills core document, GSTIN, place-of-supply, value and tax fields, but currently leaves seller and buyer legal name/location/PIN values null, leaves line Unit null, and marks every line IsService = false. An integration may enrich those values, but the built-in staging code by itself does not. Do not assume the word “staged” means the payload is portal-complete for every invoice type.
Procedure
Step 1 — Validate the Invoice
Open the source Invoice and verify the issuing branch and GST registration, buyer GSTIN, document number and date, place of supply, HSN/SAC, quantities, values and per-head tax. The e-invoice action itself checks whether an IRN already exists, but it does not currently require the Invoice to be Approved or Posted. Make approval/posting state part of your operational control before anyone invokes Generate.
Step 2 — Stage the payload
Run the Invoice's e-invoice generation action once. It serializes the request into EINVPayload and marks EINVStatus Pending. Inspect the staged payload or integration trace and confirm it references the same Invoice ID and filer GSTIN.
Staging is not portal submission. If no bound workflow consumes the Pending Invoice, it will remain Pending indefinitely and no IRN will appear.
Step 3 — Let the configured flow submit and write back
Allow the tested integration flow to send the staged payload and call the response-recording path for that Invoice. On success, verify all of the following together:
- IRN;
- acknowledgment number and date;
- signed QR payload;
- signed Invoice/provider response; and
- generated status.
On failure, retain the exact provider response in the integration's controlled error/audit path, correct the source or mapping that caused it, and stage again only when it is safe to do so. The built-in response recorder cannot record a failure because it requires an IRN.
Step 4 — Verify the output and control edits
Preview the final Invoice document and verify that its IRN, acknowledgment and QR agree with the provider response. The current e-invoice service does not impose a general edit lock on an Invoice after IRN generation; it only refuses another generation request when IRN is present. Use permissions, document lifecycle controls and your correction process to prevent content edits that would make the Invoice disagree with its registered payload.
Expected result
One source Invoice contains the staged request and the response fields written by the configured integration. A complete success has an IRN, acknowledgment number/date and signed QR evidence that agree with the printed Invoice. No separate EInvoice record or automatic Invoice edit lock should be expected from the current action.
Common problems
The Invoice remains Pending
The staging action completed, but no integration consumed it or wrote back a response. Inspect the configured workflow run and its connection; creating a separate EInvoice record will not advance the Invoice.
The provider rejects missing party or item detail
Inspect the actual staged JSON. Several legal-name/address values and line Unit are currently left blank by the built-in builder, and every line is marked as goods. Correct the integration mapping or product implementation for the provider's required schema before retrying.
Generate is unavailable or refuses to run
If IRN is already populated, the duplicate-generation guard is working. The service does not implement portal cancellation; follow your statutory cancellation/correction process and control the Invoice record separately.
Can a registered Invoice still be edited?
The e-invoice service does not currently add a global edit lock. Treat permission/lifecycle control as a required implementation and audit check rather than assuming IRN writeback freezes every Invoice field.