> For the complete documentation index, see [llms.txt](https://amast-einvoice.gitbook.io/amast-einvoice-sass/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://amast-einvoice.gitbook.io/amast-einvoice-sass/integration-workflow.md).

# Integration Workflow

## Recommended architecture

```mermaid
sequenceDiagram
  participant ERP as Your system
  participant API as AMAST eInvoice
  participant LHDN as LHDN MyInvois

  Note over ERP: Your Customer Master Data creation
  ERP->>API: GET /v1/einvoice/validate-taxpayer-tin/:tin
  API->>LHDN: Validate your and your customer TIN combination
  LHDN-->>API: 200 / 404
  API-->>ERP: valid true/false
  ERP->>ERP: Store in customer master

  Note over ERP: During or post sale/billing event
  ERP->>API: POST /submit
  API->>LHDN: Submit your documents with proper UBL format
  LHDN-->>API: Accepted / Rejected
  API-->>ERP: submissionBatchId + documentIds

 
Note over ERP: Polling latest submission status
 
    ERP->>API: GET /v1/saas/submissions/:id/status
    API->>LHDN: Fetch latest documents status in batch 
    LHDN-->>API: Submitted / Valid / Invalid / Cancelled
    API-->>ERP: batch + per-doc status
 

  ERP->>ERP: Mark document Valid / Invalid
```

## Step-by-step

### Phase 1 — Onboarding (dashboard, not API)

1. Register organisation and complete onboarding (supplier TIN, entity type, address).
2. Purchase credits.
3. Set us as your Intermediary. Refer [MyTax Intermediary Setup](/amast-einvoice-sass/appendix/mytax-intermediary-setup.md)
4. Create API key.

### Phase 2 — Buyer master (optional but recommended)

Before high-volume B2B invoicing:

1. Call [Validate taxpayer TIN](broken://pages/228d8e3a8bd2385033d9c57235461be5a89d6aca) when creating/updating customers.
2. Persist  TIN + NRIC/Passport Number @ BRN in your DB. 
3. Do **not** call validate on every Submit Document API.

### Phase 3 — Submit

1. Build payload (`consolidated` or `non-consolidated`).
2. `POST /v1/einvoice/submit` with unique `idempotency-key`.
3. On `200`, persist `submissionBatchId` and each `documentId`.
4. On `402`, pause and top up credits.
5. On `409`, inspect message (idempotency vs duplicate document).

### Phase 4 — Track

1. `GET /v1/saas/submissions/{submissionBatchId}/status`
2. Start polling every few seconds; back off as the batch ages.
3. There is **no webhook,** polling is the only supported pattern.
4. Status endpoint reads **stored** state; it does not call LHDN on each request.

### Phase 5 — Cancel (if needed)

1. Only when document LHDN status is **Valid** (see dashboard or status API).
2. `POST /v1/einvoice/cancel` with `documentId` from submit response.
3. Poll status or dashboard for `Cancelled` on LHDN.

## Retry policy

| Situation                            | Action                                                         |
| ------------------------------------ | -------------------------------------------------------------- |
| Network timeout after unknown result | Retry with **same** idempotency-key and body                   |
| `400` validation                     | Fix payload; **new** idempotency-key                           |
| `409` duplicate document             | Do not retry; use new `referenceId` or wait for terminal state |
| `500` Internal Server Error          | Retry later with same key + same body                          |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://amast-einvoice.gitbook.io/amast-einvoice-sass/integration-workflow.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.