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:
- Compliance: Ensures that your e-Invoicing system meets the requirements set by LHDN and IRBM.
- Efficiency: Automates the process of e-Invoice generation and submission, reducing manual errors and saving time.
- Real-Time Validation: Facilitates immediate validation of e-Invoices by the IRBM, ensuring accuracy and compliance.
- 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:
- Login as Taxpayer System: This API helps a business's ERP system prove its identity to access other invoicing tools.
- 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.
- Get All Document Types: This API gives a list of all the types of documents that can be created in the MyInvois system.
- Get Document Type: This API provides details about a specific type of document, helping businesses create correct invoices.
- Get Document Type Version: This API offers information about different versions of a document type, ensuring businesses use the latest format.
- 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.
