# Weaf MRA EIS API

> A REST wrapper over the Malawi Revenue Authority (MRA) Electronic Invoicing
> System (EIS). It holds each terminal's MRA credentials, calculates VAT, numbers
> invoices and formats MRA payloads, so clients send plain JSON over HTTPS to
> activate terminals, issue tax receipts, raise credit/debit notes, void
> receipts and manage stock.

Provider: WEAF Company Malawi (services@weafcompany.com)
Docs: https://mraeisapi.weafcompany.com
Machine-readable spec: https://weafcompany.com/api/malawi/docs?api-docs-malawi.json
Interactive testing: https://weafcompany.com/api/malawi/documentation#/

## How requests are shaped

Base URL: `https://weafcompany.com`

- `POST /api/v1/auth/*` — token lifecycle. `generate-token` takes `username`
  (account email), `password`, `expiry_days` (1-365), `token_name` and an
  optional `tin`; it returns `data.token`.
- `/api/v1/{tin}/*` — MRA EIS operations. `{tin}` is the taxpayer's MRA TIN
  (sandbox example: `20154457`). Almost all are `POST` with a JSON body.

Query parameters on MRA operations:

- `token` — the WEAF API access token (required). Also send it as
  `Authorization: Bearer {token}`.
- `deploymentEnvironment` — `Sandbox` or `Production` (required on calls that
  reach MRA). Default to `Sandbox` in generated code; `Production` submits real
  fiscal documents.

Every response uses the envelope
`{"status": {"returnCode": "00", "returnMessage": "SUCCESS"}, "data": ...}`;
`returnCode` other than `"00"` is an error.

Most MRA calls need a `terminalId` (from activate-terminal or GET terminals) and
often a `siteId`. If MRA reports an expired session (401 or statusCode -2), call
request-new-terminal-token and retry.

Tax rates (`taxRateId`): A = Standard 16.5%, B = Zero rated 0%, E = Exempt 0%.
`unitPrice` is VAT-inclusive; the API back-calculates VAT and builds the invoice
summary. `-debug` endpoints return the MRA payload without submitting it.

## Endpoints

### Authentication

- `POST /api/v1/auth/generate-token` — Generate API Access Token. Authenticate a user and generate an API access token for programmatic access to the system. This endpoint validates user credentials and creates a secure token that can be used for subsequent API calls. The token provides access to company-specific data and operations based on the user's permissions. [docs](https://mraeisapi.weafcompany.com/authentication/generate-token)
- `POST /api/v1/auth/validate-token` — Validate access token. Validate an existing access token and get user/company information [docs](https://mraeisapi.weafcompany.com/authentication/validate-token)
- `POST /api/v1/auth/refresh-token` — Refresh API Access Token. Refresh an existing access token to get a new token with extended expiration period. This endpoint allows you to extend the validity of your current token without re-authenticating with username and password. The new token will have a longer expiration period and the old token will be invalidated. [docs](https://mraeisapi.weafcompany.com/authentication/refresh-token)

### Terminal Onboarding

- `POST /api/v1/{tin}/activate-terminal` — Activate terminal. Activate a new terminal with Malawi Revenue Authority (MRA) EIS system. Returns JWT tokens and security configurations on success. [docs](https://mraeisapi.weafcompany.com/onboarding/activate-terminal)
- `POST /api/v1/{tin}/confirm-terminal-activation` — Confirm terminal activation. Confirm a terminal activation with Malawi Revenue Authority (MRA) EIS system. This finalizes the terminal setup after initial activation. [docs](https://mraeisapi.weafcompany.com/onboarding/confirm-terminal-activation)
- `GET /api/v1/{tin}/terminals` — Get configured terminals. Retrieve all configured and activated terminals for a given TIN from the WEAF backend database. [docs](https://mraeisapi.weafcompany.com/onboarding/terminals)
- `POST /api/v1/{tin}/request-new-terminal-token` — Request New Terminal Token. Retrieve the latest terminal security credentials (JWT token and Secret Key) from the MRA system. This is required when your current session has expired (indicated by a 401 Unauthorized response or MRA statusCode -2). The local database is automatically updated with the new credentials. [docs](https://mraeisapi.weafcompany.com/onboarding/request-new-terminal-token)

### Configuration

- `POST /api/v1/{tin}/sync-latest-configurations` — Sync latest configurations. Synchronize the latest terminal configurations from Malawi Revenue Authority (MRA) EIS system. This updates tax rates, terminal settings, and taxpayer configuration. Requires an activated terminal. [docs](https://mraeisapi.weafcompany.com/configuration/sync-latest-configurations)

### Utilities

- `POST /api/v1/{tin}/get-site-terminal-products` — Get terminal site products. Retrieve products and services for a specific terminal site from Malawi Revenue Authority (MRA) EIS system. [docs](https://mraeisapi.weafcompany.com/utilities/get-site-terminal-products)
- `POST /api/v1/{tin}/get-warehouse-products` — Get warehouse products. Retrieve warehouse inventory products with pagination from Malawi Revenue Authority (MRA) EIS system. Requires an activated terminal with valid JWT credentials. [docs](https://mraeisapi.weafcompany.com/utilities/get-warehouse-products)
- `POST /api/v1/{tin}/check-tin-authorization-requirement` — Check TIN Authorization Requirement. Check if a specific TIN requires a purchase authorization code from the Malawi Revenue Authority (MRA). [docs](https://mraeisapi.weafcompany.com/utilities/check-tin-authorization-requirement)
- `POST /api/v1/{tin}/check-terminal-unblock-status` — Check Terminal Unblock Status. Check if a specific terminal is currently unblocked by the Malawi Revenue Authority (MRA). Uses the stored terminal UUID for the provided siteId. [docs](https://mraeisapi.weafcompany.com/utilities/check-terminal-unblock-status)
- `POST /api/v1/{tin}/get-terminal-blocking-message` — Get Terminal Blocking Message. Retrieve detailed information about why a terminal might be blocked by the Malawi Revenue Authority (MRA). Uses the stored terminal UUID for the provided siteId. [docs](https://mraeisapi.weafcompany.com/utilities/get-terminal-blocking-message)
- `POST /api/v1/{tin}/validate-vat5-certificate` — Validate VAT5 Certificate. Validate a VAT5 certificate with the Malawi Revenue Authority (MRA) EIS system. This check ensures the certificate is valid, matches the project and terminal, and hasn't exceeded its quantity. [docs](https://mraeisapi.weafcompany.com/utilities/validate-vat5-certificate)

### Stock Management

- `POST /api/v1/{tin}/stock-adjustment-reasons` — Get stock adjustment reasons. Retrieve available stock adjustment reasons from Malawi Revenue Authority (MRA) EIS system. These reasons are used when adjusting inventory quantities. [docs](https://mraeisapi.weafcompany.com/stock-management/stock-adjustment-reasons)
- `POST /api/v1/{tin}/get-suppliers` — Get suppliers. Retrieve available suppliers from Malawi Revenue Authority (MRA) EIS system. Requires an activated terminal and valid JWT token. [docs](https://mraeisapi.weafcompany.com/stock-management/get-suppliers)
- `POST /api/v1/{tin}/get-units-of-measure` — Get units of measure. Retrieve available units of measure from Malawi Revenue Authority (MRA) EIS system. Requires an activated terminal and valid JWT token. [docs](https://mraeisapi.weafcompany.com/stock-management/get-units-of-measure)
- `POST /api/v1/{tin}/get-hs-codes` — Get HS codes. Retrieve available Harmonized System (HS) codes from Malawi Revenue Authority (MRA) EIS system. Requires an activated terminal and valid JWT token. [docs](https://mraeisapi.weafcompany.com/stock-management/get-hs-codes)
- `POST /api/v1/{tin}/add-product` — Add a new product. Add a new product to master products and create zero-quantity warehouse inventory for the taxpayer on the Malawi Revenue Authority (MRA) EIS system. Requires an activated terminal and valid JWT token.   Sample HS Codes:     HS Code  Description  Tax Rate     94061010   GREEN HOUSES OF WOOD  E     94061090   OTHER PREFABRICATED BUILDINGS  E     94062000   MODULAR BUILDING UNITS, OF STEEL  A     94069000   OTHER PREFABRICATED BUILDINGS  A     Sample UOM Codes:     UOM  Description     DR   Drum     %   Percentage     %O   Per mille     D   Day [docs](https://mraeisapi.weafcompany.com/stock-management/add-product)
- `POST /api/v1/{tin}/stock-adjustment` — Submit Stock Adjustment. Submit a stock adjustment request to the Malawi Revenue Authority (MRA) EIS system. Use this for adjustments like Theft, Damage, Loss, etc. Requires an activated terminal and valid JWT token. [docs](https://mraeisapi.weafcompany.com/stock-management/stock-adjustment)
- `POST /api/v1/{tin}/stock-adjustment-debug` — Stock Adjustment DEBUG. Debug endpoint for stock adjustment. Returns the formatted payload that would be sent to the MRA EIS system without actually sending it. [docs](https://mraeisapi.weafcompany.com/stock-management/stock-adjustment-debug)
- `POST /api/v1/{tin}/increase-descrease-stock-request` — Submit Informal Purchase. Submit an informal purchase request to the Malawi Revenue Authority (MRA) EIS system. This is typically used to increase stock from non-VAT registered suppliers. Requires an activated terminal and valid JWT token. [docs](https://mraeisapi.weafcompany.com/stock-management/increase-descrease-stock-request)
- `POST /api/v1/{tin}/query-stock-adjustments` — Query Stock Adjustments. Retrieve a list of stock adjustments stored in the local database. [docs](https://mraeisapi.weafcompany.com/stock-management/query-stock-adjustments)
- `POST /api/v1/{tin}/check-product-status` — Check Product Status. Retrieve detailed stock information, tax rates, and descriptions for a specific product directly from the MRA system. [docs](https://mraeisapi.weafcompany.com/stock-management/check-product-status)
- `POST /api/v1/{tin}/stock-transfer` — Stock Transfer. Transfer inventory from warehouse to site or between sites. Requires an activated terminal and valid JWT token. [docs](https://mraeisapi.weafcompany.com/stock-management/stock-transfer)
- `POST /api/v1/{tin}/get-raw-materials` — Get Raw Materials. Retrieve a paginated list of raw materials from the Malawi Revenue Authority (MRA) EIS system. This refers to goods that are used as inputs for production processes. [docs](https://mraeisapi.weafcompany.com/stock-management/get-raw-materials)
- `POST /api/v1/{tin}/submit-raw-material-conversion` — Submit Raw Material Conversion. Submit a production conversion request to the Malawi Revenue Authority (MRA) EIS system. This endpoint records the processing of raw materials into finished goods, ensuring inventory levels are adjusted accordingly for both input and output products. [docs](https://mraeisapi.weafcompany.com/stock-management/submit-raw-material-conversion)
- `POST /api/v1/{tin}/ping-server` — Ping MRA Server. Check the connectivity between the WEAF system and the Malawi Revenue Authority (MRA) EIS system. This endpoint verifies that the terminal is correctly activated and the JWT token is valid for the selected environment. [docs](https://mraeisapi.weafcompany.com/stock-management/ping-server)

### Sales Management

- `POST /api/v1/{tin}/generate-tax-receipt` — Generate Tax Receipt. Submit a sales transaction to the Malawi Revenue Authority (MRA) EIS system. This endpoint simplifies the integration process by handling complex tax calculations, invoice numbering, and MRA data formatting automatically. [docs](https://mraeisapi.weafcompany.com/sales-management/generate-tax-receipt)
- `POST /api/v1/{tin}/generate-tax-receipt-debug` — Generate Tax Receipt DEBUG. Debug endpoint for generating a tax receipt. Returns the formatted payload that would be sent to the MRA EIS system without actually sending it. Use this to verify your payload structure and calculations before live submission. [docs](https://mraeisapi.weafcompany.com/sales-management/generate-tax-receipt-debug)
- `POST /api/v1/{tin}/generate-tax-receipt-offline` — Generate Tax Receipt OFFLINE SIMULATION. Simulates an offline transaction generation. This endpoint computes the required offlineSignature and constructs the local validationURL exactly as a frontend POS should. Use this to verify your local signature implementation. [docs](https://mraeisapi.weafcompany.com/sales-management/generate-tax-receipt-offline)
- `POST /api/v1/{tin}/query-local-receipts` — Query Local Receipts. Retrieve a list of tax receipts generated for a specific company (TIN) and site, stored in the local database. [docs](https://mraeisapi.weafcompany.com/sales-management/query-local-receipts)
- `POST /api/v1/{tin}/last-online-transaction` — Get Last Online Transaction. Retrieve the last successfully submitted online transaction from the MRA system for a specific terminal. This simplifies reconciliation by confirming what the MRA side has recorded. [docs](https://mraeisapi.weafcompany.com/sales-management/last-online-transaction)
- `POST /api/v1/{tin}/last-offline-transaction` — Get Last Offline Transaction. Retrieve the last successfully submitted offline transaction from the MRA system for a specific terminal. [docs](https://mraeisapi.weafcompany.com/sales-management/last-offline-transaction)
- `POST /api/v1/{tin}/query-void-receipts` — Query Void/Refunded Receipts. Retrieve a list of voided or refunded tax receipts directly from the Malawi Revenue Authority (MRA) system. This endpoint allows for tracking the status of cancellation requests across different time periods. [docs](https://mraeisapi.weafcompany.com/sales-management/query-void-receipts)
- `POST /api/v1/{tin}/cancel-sales-receipt` — Cancel Sales Receipt (Void). Submit a request to void/cancel an already submitted sales receipt in the MRA EIS system. Requires approval on the MRA side. [docs](https://mraeisapi.weafcompany.com/sales-management/cancel-sales-receipt)
- `POST /api/v1/{tin}/query-local-void-requests` — Query Local Void Requests. Retrieve a list of void requests stored in our local database for tracking and reconciliation. [docs](https://mraeisapi.weafcompany.com/sales-management/query-local-void-requests)
- `POST /api/v1/{tin}/validate-buyer-auth-code` — Validate Buyer Authorization Code. Validate an authorization code issued by MRA for a specific buyer/reason. This is used when a buyer claims to be purchasing on behalf of an organization or for specific tax-exempt purposes. [docs](https://mraeisapi.weafcompany.com/sales-management/validate-buyer-auth-code)
- `POST /api/v1/{tin}/get-invoice-by-number` — Get Invoice Details By Number. Retrieve full details of a specific tax receipt from the MRA system using its invoice number. This endpoint returns the complete invoice header, line items, and summary details as recorded by MRA. [docs](https://mraeisapi.weafcompany.com/sales-management/get-invoice-by-number)
- `POST /api/v1/{tin}/process-credit-debit-note` — Process Credit or Debit Note. Generate a credit note (if the total is lower) or a debit note (if the total is higher) against an existing invoice. Our system automatically recalculates tax components and simplifies the submission process. [docs](https://mraeisapi.weafcompany.com/sales-management/process-credit-debit-note)
- `POST /api/v1/{tin}/process-credit-debit-note-debug` — Process Credit/Debit Note DEBUG. Debug endpoint for processing a credit or debit note. Returns the formatted payload that would be sent to the MRA EIS system without actually sending it. [docs](https://mraeisapi.weafcompany.com/sales-management/process-credit-debit-note-debug)