RESTv1 API Documentation

Welcome to the RESTv1 API documentation. This API allows you to fiscalise documents (invoices and credit notes) with the MRA (Mauritius Revenue Authority) system. You can also check the status of your fiscalised documents and receive callbacks upon completion.

Introduction

RESTv1 lets you integrate your ERP, billing, or POS systems directly with our MRA-compliant e-invoicing platform. You can programmatically submit invoices and credit notes and track their fiscalisation status.

The RESTv1 API is designed for reliability: it supports immediate fiscalisation, background processing during MRA outages, and callback notifications when processing completes.

Download the Postman collection for this API: RESTv1 Postman Collection

How to Use the RESTv1 API

1. Obtain an API Key

All RESTv1 API requests must be authenticated using an API Key. To obtain your API Key, please contact our support team at support@ebsmauritius.com.

2. Base URL

For testing and development, the base URL for all RESTv1 API endpoints is: https://test1.ebsmauritius.com/api/restv1/

Once your integration tests are complete and verified, please contact our support team at support@ebsmauritius.com to obtain your live production URL.

3. Authentication

Your API Key must be included in the JSON request body for every RESTv1 API call under the field api_key.

4. Request Format

  • All requests must be sent using the HTTP POST method.
  • All request and response bodies are in JSON format.
  • Ensure your requests are sent over HTTPS for security.
  • Set the Content-Type header to application/json.

5. Error Handling

The RESTv1 API provides detailed error messages in JSON format. In case of MRA outages, the system includes retry mechanisms to ensure eventual delivery. If an error occurs, the response will contain a status of "error" and a descriptive message.

6. Rate Limiting

A rate limit of one call per second per API ID is enforced. Excess requests will be queued and processed in order, not rejected.

RESTv1 API Endpoints

Fiscalise Document

Submit an invoice or credit note for fiscalisation. The request includes a document_queue_id and a callback_url so the system can notify you of the final result.

Endpoint URL

POST https://test1.ebsmauritius.com/api/restv1/fiscalise/

Check Document Status

Retrieve the current status for a previously submitted document using your document_queue_id.

Endpoint URL

POST https://test1.ebsmauritius.com/api/restv1/status/

1. Fiscalise Document (/api/restv1/fiscalise/)

This endpoint is used to submit documents for fiscalisation. It accepts POST requests with a JSON payload.

Request Parameters:

Parameter Type Required Description Checks
api_key String Yes Your unique API key for authentication. Must be a valid and active API key.
reference_number String Yes The invoice or credit note number you want to fiscalise. Must match the next expected sequence number for the seller.
document_type String Yes Type of document to fiscalise. Must be either "invoice" or "credit_note".
callback_url String Yes An HTTPS URL where the fiscalisation result will be sent. Must be a valid URL starting with "https://".
invoice_number String (Max 99 chars) Conditional The invoice number corresponding to the credit note. Required if document_type is "credit_note". Required if document_type is "credit_note".
reason String (Max 99 chars) Conditional The reason for issuing the credit note. Required if document_type is "credit_note". Required if document_type is "credit_note".
buyer_name String (Max 99 chars) Yes Name of the buyer.
buyer_transaction_type String Yes Type of transaction with the buyer. Must be one of:
"B2B" (Business to Business),
"B2C" (Business to Consumer),
"B2G" (Business to Government),
"EXP" (Export), or
"B2E" (Business to Employee).
buyer_brn String (9 or 10 chars) Conditional Buyer's Business Registration Number. Required for "B2B" transactions. For "B2B" transactions: Must be provided, start with a letter, and be 9 or 10 characters long.
buyer_vat_type String Yes Buyer's VAT registration type. Must be one of:
"VATR" (VAT Registered),
"NVTR" (Non VAT Registered),
"EXMP" (VAT Exempt).
buyer_vat_number String (8 digits) Conditional Buyer's VAT number. Required for "B2B" transactions where buyer_vat_type is "VATR". For "B2B" and "VATR": Must be 8 digits and numeric.
buyer_address String (Max 240 chars) No Buyer's address.
payment_method String Yes Method of payment. Must be one of:
"CASH",
"BNKTRANSFER",
"CHEQUE",
"CARD" (these are considered instant payment methods, similar to a cash sale), or
"CREDIT" (this indicates a deferred payment, such as an invoice to be paid in 30 or 60 days).
currency String (3 uppercase alphabetic chars) Yes Three-letter currency code. Must be three uppercase alphabetic characters (e.g., "MUR", "USD").
rate_to_mur Decimal (4 decimal places) Conditional Exchange rate to MUR. Required if currency is not "MUR". Must be a valid decimal number.
line_items Array of Objects Yes A list of line items for the document. Must contain at least one item.
Line Item Parameters:
line_items[].unit_price Decimal (2 decimal places) Yes Unit price of the item. Must be a valid decimal number.
line_items[].quantity Decimal (2 decimal places) Yes Quantity of the item. Must be a valid decimal number greater than 0.
line_items[].discount Decimal (2 decimal places) Yes Discount applied to the item. Must be a valid decimal number, cannot be greater than unit_price.
line_items[].tax_code String Yes Tax code for the item. Must be one of:
"TC01",
"TC02",
"TC03",
"TC04", or
"TC05".
line_items[].nature String Yes Nature of the item. Must be either:
"GOODS" or
"SERVICES".
line_items[].description String (Max 100 chars) Yes Description of the item.

Example Request Body:

The document_queue_id is generated internally and returned only when a document is queued. Use that value with the status endpoint to check progress.

The reference_number is the invoice or credit note number you intend to fiscalise. This must be the next expected sequence number for the seller. If the number does not match the expected sequence, the request will be rejected. 


{
    "api_key": "YOUR_API_KEY",
    "reference_number": "INV00001",
    "document_type": "invoice",
    "callback_url": "https://your-callback-url.com/webhook",
    "buyer_name": "Test Buyer",
    "buyer_transaction_type": "B2C",
    "buyer_vat_type": "NVTR",
    "payment_method": "CASH",
    "currency": "MUR",
    "line_items": [
        {
            "tax_code": "TC01",
            "nature": "GOODS",
            "description": "Item 1",
            "unit_price": 100.0,
            "quantity": 1,
            "discount": 0.0
        }
    ]
}

Important: Only queued documents return a document_queue_id. Persist it so you can reconcile responses and status checks.

Additional Notes on Buyer Information:

For individual buyers where specific name details are not available, you can set the buyer_transaction_type to "B2C" and the buyer_name to "CASH SALE". This is typically used for on-the-spot retail transactions.

Overall Fiscalisation Flow:

When you submit a document for fiscalisation via the /fiscalise/ endpoint, the system attempts to process it with the MRA in real-time. There are a few possible outcomes:

For documents that are queued, a dedicated background process will continuously attempt to fiscalise them with the MRA. Once the MRA becomes available and the document is processed (either successfully fiscalised or rejected by the MRA due to an error), the system will initiate a callback to the callback_url you provided. This callback will contain the final status of the fiscalisation (success with QR code/IRN, or error details).

The callback mechanism includes a robust retry strategy. The system will attempt to deliver the callback 15 times with an exponential back-off strategy. The delay between retries increases with each attempt: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, and 16384 seconds (approximately 4.5 hours for the last retry). If all 15 attempts fail, the document status will be updated to indicate a callback failure.

Important: If you receive a callback indicating a fiscalisation error or if the callback itself fails after all retries, you should review the error details and resubmit the document with the necessary corrections. The system will not automatically re-attempt fiscalisation for documents that have resulted in a final error or callback failure.

Important: Your callback must return a HTTP Status Code of 2xx. If not the system will retry.

Document Reference Numbers: You provide the reference_number in your request, and it must match the next expected sequence number for the seller. Upon success, the API returns that same value as document_number.

Response:

Upon successful submission, the API will return a JSON response indicating the status. If the document is successfully fiscalised immediately, you will receive the QR code, IRN, and document number. If the document is queued for background processing, you will receive a document_queue_id.

The document_number in the response matches the reference_number you submitted.

The qr_verify_url field provides a direct link to an independent verification page for the generated QR code. We highly recommend that you make the displayed QR code in your application clickable, opening this URL. This allows users to independently verify the authenticity and details of the fiscalised document directly with the MRA. 


// Immediate Fiscalisation Success (HTTP Status: 200 OK)
{
    "status": "success",
    "message": "QR Code Data",
    "irn": "Generated IRN",
    "document_number": "Reference number you submitted",
    "qr_verify_url": "URL to verify QR code"
}

// Queued for Background Processing (HTTP Status: 202 Accepted)
{
    "status": "queued",
    "document_queue_id": "Generated queue ID"
}

// Error (HTTP Status: 400 Bad Request or 404 Not Found depending on the error)
{
    "status": "error",
    "message": "Error description"
}

Background Processing and Callback Mechanism:

When a document is queued, it means it will be processed in the background by a dedicated process. This process runs continuously, checking for new documents to fiscalise. Once the fiscalisation is complete (either successfully or with an error), the system will attempt to make a POST request to the callback_url you provided in the initial request.

The callback mechanism includes a robust retry strategy. The system will attempt to deliver the callback 15 times with an exponential back-off strategy. The delay between retries increases with each attempt: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, and 16384 seconds (approximately 4.5 hours for the last retry). If all 15 attempts fail, the document status will be updated to indicate a callback failure.

Important: Your callback must return a HTTP Status Code of 2xx. If not the system will retry.

The callback payload will be a JSON object containing the fiscalisation result, similar to the direct API response: 


// Callback for successful fiscalisation
{
    "status": "success",
    "message": "QR Code Data",
    "irn": "Generated IRN",
    "document_number": "Generated Document Number",
    "document_queue_id": "The document queue ID you provided",
    "qr_verify_url": "URL to verify QR code"
}

// Callback for fiscalisation error
{
    "status": "error",
    "document_queue_id": "The document queue ID you provided",
    "message": "Error description"
}

2. Check Document Status (/api/restv1/status/)

This endpoint allows you to check the current status of a document that was previously submitted for fiscalisation, especially those that were queued for background processing. It accepts POST requests with a JSON payload.

Use the document_queue_id returned by the 202 Accepted response when a document is queued.

Request Parameters:

Parameter Type Required Description
api_key String Yes Your unique API key for authentication.
document_queue_id String Yes The ID of the document which is the document_queue_id provided when the document was submitted for fiscalisation.

Response:

The response will indicate the current status of the document:

The qr_verify_url field provides a direct link to an independent verification page for the generated QR code. We highly recommend that you make the displayed QR code in your application clickable, opening this URL. This allows users to independently verify the authenticity and details of the fiscalised document directly with the MRA. 


// Document still in queue (HTTP Status: 202 Accepted)
{
    "status": "queued",
    "message": "Document still in queue awaiting processing"
}

// Document fiscalised successfully (HTTP Status: 200 OK)
{
    "status": "success",
    "document_status": "Fiscalised - Callback Success",
    "document_queue_id": "Your provided document queue ID",
    "message": "QR Code Data",
    "irn": "Generated IRN",
    "document_number": "Generated Document Number",
    "qr_verify_url": "URL to verify QR code"
}

// Document fiscalisation failed (HTTP Status: 400 Bad Request)
{
    "status": "error",
    "document_status": "Error - MRA Error",
    "message": "Error description"
}

// Invalid API Key or Document Queue ID (HTTP Status: 404 Not Found)
{
    "status": "error",
    "message": "Invalid API Key"
}
// or
{
    "status": "error",
    "message": "Invalid document queue ID"
}