Malaysia e-Invoice Software Development Kit (SDK)

Discover Malaysia's Electronic Invoice SDK by IRBM for easy e-invoicing compliance. Learn to automate processes and boost efficiency with this comprehensive toolkit.

By
Ajith Kumar M
March 28, 2024
20 min

Welcome to a simpler way of doing business! Malaysia's Inland Revenue Board (IRBM) has introduced a new tool called the e-Invoice Software Development Kit (SDK). Launched on 9 February 2024, this tool is here to make invoicing easier and more accurate for businesses of all sizes.

The e-Invoice SDK is part of Malaysia's big plan to use more digital technology in business and tax work. It's made to handle all kinds of sales, whether you're selling to other businesses, to customers, or even to the government. This means that no matter what your business does, this tool can help you create and send invoices quickly and correctly.

Join us as we explore how Malaysia's e-Invoice SDK can make invoicing a breeze for your business, saving you time and reducing mistakes.

Explore the capabilities of Malaysia's e-Invoice SDK, where efficiency meets compliance. Discover how this potent tool can transform your invoicing process, making it more streamlined and error-free.

Benefits for Businesses:

  1. Compliance: Ensures that your e-Invoicing system meets the requirements set by LHDN and IRBM.
  2. Efficiency: Automates the process of e-Invoice generation and submission, reducing manual errors and saving time.
  3. Real-Time Validation: Facilitates immediate validation of e-Invoices by the IRBM, ensuring accuracy and compliance.
  4. Security: Incorporates data security and privacy monitoring to protect sensitive information.

Getting Started:

Businesses can access the e-Invoice SDK through the MyInvois portal provided by IRBM. The portal offers step-by-step guidance on key aspects of e-Invoice implementation, including compliance, recordkeeping, and integration with existing systems.

Understanding the e-Invoice API in Malaysia's MyInvois System

The MyInvois system in Malaysia offers a set of e-Invoice APIs to make invoicing easier for businesses. Here's what each API does:

  1. Login as Taxpayer System: This API helps a business's ERP system prove its identity to access other invoicing tools.
  2. Login as Intermediary System: If a business is working on behalf of another, this API helps its ERP system get access to the invoicing tools it needs.
  3. Get All Document Types: This API gives a list of all the types of documents that can be created in the MyInvois system.
  4. Get Document Type: This API provides details about a specific type of document, helping businesses create correct invoices.
  5. Get Document Type Version: This API offers information about different versions of a document type, ensuring businesses use the latest format.
  6. Get Notifications: This API lets a business's ERP system find out about any updates or messages related to their invoices.

Simplifying Invoicing with MyInvois e-Invoice API

1. Login as Taxpayer System

In the MyInvois system, the "Login as Taxpayer System" API plays a crucial role in streamlining the authentication process for businesses. Here's how it works:

Purpose:

This API is designed to authenticate the Enterprise Resource Planning (ERP) system associated with a specific taxpayer. By issuing an access token, it grants the ERP system access to other protected APIs within the MyInvois system.

Overview:

This API secures access to MyInvois's protected APIs by authenticating the taxpayer's ERP system and issuing an access token.

Signature:

  • Endpoint: POST /connect/token

Inputs:

Header Parameters:

Parameter Type Description Example
client_id String Client ID for the ERP system.
client_secret String Client secret for the ERP system.

Body Parameters:

Parameter Type Description Example
grant_type String Must be client_credentials. client_credentials
scope String Optional parameter asking for a specific access scope. InvoicingAPI

Outputs:

Successful Response (HTTP status code 200):

Parameter Type Description Example
access_token JWT token Encoded JWT token structure. Encoded token value
token_type String Returns only Bearer authentication tokens. Bearer
expires_in Number The lifetime of the access token in seconds. 3600
scope String Optional: Information on scope granted to token. InvoicingAPI

Error Responses (400 Bad Request):

Parameter Type Description Example
error String Possible error values. invalid_request
error_description String Optional: Detailed error message. User blocked
error_uri URI Optional: URI with more error information.

Additional Considerations:

  • The issued token includes information about the taxpayer represented by the system.
  • Authentication can be rejected if invalid client ID and secret are used, or if the system user registered against the taxpayer is blocked or expired.
  • Tokens are valid for a pre-configured limited time, typically one hour. The system should obtain a new access token before the expiry of the current token to continue calling the APIs.

By integrating the "Login as Taxpayer System" API, businesses can securely authenticate their ERP systems with the MyInvois system, enabling seamless access to e-invoicing functionalities.

2. Login as Intermediary System

The "Login as Intermediary System" API is an integral part of Malaysia's MyInvois system, designed to authenticate the Enterprise Resource Planning (ERP) system of an intermediary representing a specific taxpayer.

API Purpose:

The primary purpose of this API is to enable intermediaries to securely access MyInvois's protected APIs on behalf of the taxpayers they represent. By authenticating the intermediary's ERP system and issuing an access token, this API ensures that intermediaries can manage e-invoicing for their clients efficiently and compliantly.

Overview:

This API facilitates secure access for intermediaries to MyInvois's protected APIs by authenticating the intermediary's ERP system and issuing an access token.

Signature:

  • Endpoint: POST /connect/token

Inputs:

Header Parameters:

Parameter Type Description Example
client_id String Client ID for the ERP system.
client_secret String Client secret for the ERP system.
onbehalfof String Tax Identification Number (TIN) of the taxpayer the intermediary is representing. C2584563202

Body Parameters:

API Parameters
Parameter Type Description Example
grant_type String Must be client_credentials. client_credentials
scope String Optional parameter asking for a specific access scope. InvoicingAPI

Outputs:

Successful Response (HTTP status code 200):

Parameter Type Description Example
access_token JWT token Encoded JWT token structure. Encoded token value
token_type String Returns only Bearer authentication tokens. Bearer
expires_in Number The lifetime of the access token in seconds. 3600
scope String Optional: Information on scope granted to token. InvoicingAPI

Error Responses (400 Bad Request):

Parameter Type Description Example
error String Possible error values. invalid_request
error_description String Optional: Detailed error message. User blocked
error_uri URI Optional: URI with more error information.

Additional Considerations:

  • The issued token includes information about the taxpayer represented by the intermediary.
  • Authentication can be rejected if invalid client ID and secret are used, or if the system user registered against the taxpayer is blocked or expired.
  • Tokens are valid for a pre-configured limited time, typically one hour. The system should obtain a new access token before the expiry of the current token to continue calling the APIs.

By integrating the "Login as Intermediary System" API, intermediaries can securely authenticate their ERP systems with the MyInvois system, enabling access to e-invoicing functionalities on behalf of their clients.

By using these APIs, businesses can automate their invoicing process, reduce mistakes, and stay in line with tax rules. The e-Invoice API in the MyInvois system is a step towards making invoicing straightforward and efficient for businesses in Malaysia.

3. Get All Document Types

API Purpose:

The "Get All Document Types" API is designed to retrieve a comprehensive list of document types available in the MyInvois System, enabling taxpayer ERP systems to access definitions for various document types required for tax submission.

Overview:

This API plays a crucial role in facilitating the submission of documents to the tax authority by providing the necessary document type definitions.

Signature:

  • Endpoint: GET /api/v1.0/documenttypes

Inputs:

  • This API requires standard e-Invoice API header parameters for an authenticated call. No additional URL or request body parameters are needed.

Outputs:

Successful Response (HTTP status code 200):

The response includes a single object containing a list of DocumentType elements.

Output Parameters:

Output Parameter Type Description Value Example
id Number Unique identifier of the document type. 45
invoiceTypeCode Number Document type code from possible values. 04
description String Description of the document type. Invoice
activeFrom Date Date when the activity of the document type started. 2015-02-13T13:15Z
activeTo Date Optional: date when the activity of the document type ends. 2027-03-01T00:00:00Z
documentTypeVersions Array of document type version summary objects Summary objects for different versions of the document type. 1 or more array values

Error Response:

  • The API reports error situations through the standard error response, without providing custom error codes.

Additional Considerations:

  • When the document type list is returned, callers can query more detailed information about a document type or document type version using the returned internal identifiers.

By leveraging the "Get All Document Types" API, businesses can efficiently access and utilize the various document types supported by the MyInvois system for their tax submission needs.

4. Get Document Type

API Purpose:

The "Get Document Type" API enables taxpayer ERP systems to retrieve detailed information about a specific document type, including its structure definitions. This API is crucial for ensuring that documents are created and submitted in accordance with the required format and standards.

Overview:

By providing access to the details of individual document types, this API facilitates accurate document preparation and submission to the tax authority.

Signature:

  • Endpoint: GET /api/v1.0/documenttypes/{id}

Inputs:

  • URL Parameter:
    • id (Number): The unique ID of the existing document type.

Outputs:

  • Successful Response (HTTP status code 200): The response includes a single object of type DocumentType.

Output Parameters:

Output Parameter Type Description Value Example
id Number Unique identifier of the document type. 45
invoiceTypeCode Number Document type code from possible values. 04
description String Description of the document type. Invoice
activeFrom Date Date when the activity of the document type started. 2015-02-13T13:15Z
activeTo Date Optional: date when the activity of the document type ends. 2027-03-01T00:00:00Z
documentTypeVersions Array of document type version summary objects Summary objects for different versions of the document type. 1 or more array values
workflowParameters Array of workflow parameters Parameters related to the workflow of the document type. 1 or more array values

Error Response:

  • The API reports error situations through the standard error response, without providing custom error codes.

Additional Considerations:

  • To use this API, the taxpayer system needs to first obtain the unique ID of the document type by calling the "Get All Document Types" API.

By utilizing the "Get Document Type" API, businesses can access detailed information about specific document types, ensuring that their documents are correctly formatted and compliant with the MyInvois system's requirements.

4. Get Document Type Version

API Purpose:

The "Get Document Type Version" API enables taxpayer ERP systems to retrieve detailed information about a specific version of a document type, including its structure definitions. This API is crucial for ensuring that documents comply with the evolving standards and formats required for submission.

Overview:

Document type versions allow for the evolution of data fields over time, ensuring that documents remain up-to-date with current requirements. This API provides access to these version details, facilitating accurate document preparation and submission.

Signature:

  • Endpoint: GET /api/v1.0/documenttypes/{id}/versions/{vid}

Inputs:

  • URL Parameters:
    • id (Number): The unique ID of the existing document type.
    • vid (Number): The unique ID of the existing document type version that is published or deactivated.

Outputs:

  • Successful Response (HTTP status code 200): The response includes a single object of type DocumentTypeVersion.

Output Parameters:

Output Parameter Type Description Value Example
invoiceTypeCode Number Document type code from possible values. 04
name String Name of the document type version. 1.0
description String Description of the document type version. Credit note version 1.0
versionNumber Decimal Unique version number of the document type version. 1.0
status String Status of the document type version (e.g., published, deactivated). published
activeFrom Date Date when the activity of the document type version started. 2015-02-13T13:15Z
activeTo Date Optional: date when the activity of the document type version ends. 2027-03-01T00:00:00Z
jsonSchema String Base64 encoded JSON schema definition for the document type version. Base64 encoded string
xmlSchema String Base64 encoded XML schema definition for the document type version. Base64 encoded string

Error Response:

  • The API reports error situations through the standard error response, without providing custom error codes.

Additional Considerations:

  • To use this API, the taxpayer system needs to first obtain the unique IDs of the document type and the document type version by calling the relevant APIs.

By utilizing the "Get Document Type Version" API, businesses can access detailed information about specific document type versions, ensuring that their documents are correctly formatted and compliant with the MyInvois system's requirements.

5. Get Notifications

API Purpose:

The "Get Notifications" API enables ERP systems to query and retrieve previously sent notifications. This API is essential for keeping businesses informed about the status of their documents and any related events.

Overview:

The MyInvois System supports sending out notifications via email, which are stored in the notification history. This API provides access to this history, allowing businesses to stay updated on their e-invoicing activities.

Signature:

  • Endpoint: GET /api/v1.0/notifications/taxpayer?dateFrom={dateFrom}&dateTo={dateTo}&type={type}&language={language}&status={status}&channel={channel}&pageNo={pageNo}&pageSize={pageSize}

Inputs:

  • URL Parameters (all optional):
    • dateFrom (DateTime): Start date and time for notifications to retrieve.
    • dateTo (DateTime): End date and time for notifications to retrieve.
    • type (String): Type of notifications to retrieve, specified as ID of the type.
    • language (String): Language of the notifications to retrieve (e.g., "ms" for Malay, "en" for English).
    • status (String): Status of the notifications to retrieve (e.g., "delivered", "pending").
    • channel (String): Channel of the notifications to retrieve (e.g., "email", "push").
    • pageNo (Number): Number of the page to retrieve.
    • pageSize (Number): Number of notifications to retrieve per page.

Outputs:

  • Successful Response (HTTP status code 200): The response includes a single object containing the result structure and metadata structure.

Output Parameters:

Output Parameter Type Description Value Example
notificationId String Unique ID of the notification. 73DKLJHH78NJUHQ
receivedDateTime DateTime Date and time when the notification was sent out. 2015-02-13T14:20Z
deliveredDateTime DateTime Optional date and time when the notification was delivered. 2015-02-13T14:23Z
typeId String ID of the type of the message. 34
typeName String Type name of the message. Invoice received
finalMessage String Optional final message that was sent out. Taxpayer 893838273 has received new documents
channel String Channel used for delivery. email
address String Channel address used to deliver the message. test@test.com
language String Language used for delivery. en
status String Status of the notification delivery. delivered
deliveryAttempts Delivery Attempt[] Structure containing information about delivery attempts. See structure
totalPages Number Total count of pages based on the supplied page size. 23
totalCount Number Total count of matching objects. 157

Error Response:

  • The API reports error situations through the standard error response, without providing custom error codes.

Additional Considerations:

  • The system limits the number of notifications that can be received through a single request by implementing a paging mechanism.
  • The list of notifications is ordered based on the descending notification date.
  • The maximum page size allowed is defined by the e-Invoice system administrators.

By utilizing the "Get Notifications" API, businesses can efficiently access their notification history, ensuring they stay informed about important updates and events related to their e-invoicing activities.

Conclusion:

The e-Invoice SDK is a vital resource for businesses to adapt to the new e-Invoicing requirements in Malaysia. By leveraging this toolkit, companies can ensure compliance with LHDN and IRBM regulations, streamline their invoicing processes, and contribute to the growth of the digital economy.