MyInvois SDK

A TypeScript SDK for interacting with the Malaysia e-invoicing system (MyInvois) API.

Features

• Authenticate with the MyInvois system
• Submit, retrieve, and manage e-invoices
• Sign invoices with digital certificates
• Support for acting as an intermediary for multiple taxpayers
• Automatic token management and renewal
• Taxpayer TIN validation

Installation

npm install myinvois-sdk

Quick Start

import { MyInvoisClient } from "myinvois-sdk";
import path from "path";

// Initialize the client
const client = new MyInvoisClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
  tin: "YOUR_TIN",
  certificatePath: path.resolve(__dirname, "./certs/certificate.crt"),
  privateKeyPath: path.resolve(__dirname, "./certs/private.key"),
  privateKeyPassphrase: "YOUR_PASSPHRASE",
  environment: "sandbox", // or 'production'
});

// Authenticate
await client.authenticate();

// Create and submit an invoice
const invoice = client.invoices.createInvoice();
// ... set invoice properties
const signedInvoice = await client.invoices.signInvoice(invoice);
const result = await client.invoices.submitInvoice(signedInvoice);

Acting as an Intermediary

This SDK supports submitting documents on behalf of multiple taxpayers as an intermediary:

// Authenticate as intermediary for a specific taxpayer
const token = await client.authenticateAsIntermediary("TAXPAYER_TIN");

// Submit an invoice on behalf of a taxpayer
const result = await client.invoices.submitInvoice(
  signedInvoice,
  "TAXPAYER_TIN"
);

Multi-TIN Support

The SDK includes built-in token management for working with multiple TINs:

// Authenticate for multiple TINs
await client.authenticateAsIntermediary("TAXPAYER_TIN_1");
await client.authenticateAsIntermediary("TAXPAYER_TIN_2");

// Get all authenticated TINs
const tins = client.getAllAuthenticatedTINs();

// Use authTIN parameter to specify which authentication to use
await client.invoices.submitInvoice(
  signedInvoice,
  "TAXPAYER_TIN_1"
);
await client.documents.getDocumentStatus(
  "DOC_UUID",
  "TAXPAYER_TIN_1"
);

The SDK automatically manages and refreshes tokens for each TIN as needed. When making API calls, you can specify the authTIN parameter to determine which token to use for authentication.

TIN Validation

The SDK provides a method to validate taxpayer TINs against the MyInvois system:

// Validate a taxpayer's TIN
const validationResult = await client.validateTaxpayerTIN(
  "C12345678901", // TIN to validate
  "BRN", // ID type (Business Registration Number)
  "201901234567", // ID value
  "YOUR_AUTH_TIN" // TIN to use for authentication
);

// Check the result
if (validationResult.isValid) {
  console.log("TIN is valid");
} else {
  console.log(`Invalid TIN: ${validationResult.message}`);
  console.log(`Status code: ${validationResult.statusCode}`);
}

The validation method returns a consistent object format:

{
  isValid: boolean;      // Whether the TIN is valid
  statusCode: number;    // HTTP status code (e.g., 200, 404)
  message: string;       // Human-readable message
  data?: any;            // Any additional data (for valid TINs)
}

This allows you to verify if a taxpayer's TIN is valid in the MyInvois system before attempting to submit invoices on their behalf.

Certificate Management

The SDK provides methods to work with digital certificates required for signing invoices:

// Get details about the certificate chain
const certDetails = await client.getCertificateDetails();

console.log("Signing Certificate Subject:", certDetails.signing.subject);
console.log("Signing Certificate Expiry:", certDetails.signing.validTo);
console.log("Days until expiry:", certDetails.signing.daysUntilExpiry);
console.log("Is valid:", certDetails.signing.isValid);

// Check intermediate and root certificates
console.log(
  "Intermediate Certificate Subject:",
  certDetails.intermediate.subject
);
console.log("Root Certificate Subject:", certDetails.root.subject);

The getCertificateDetails method returns information about the entire certificate chain including:

• Subject and issuer details
• Serial numbers
• Validity dates
• Days until expiry
• Validation status

Use this to monitor certificate health and prepare for renewal before expiration.

API Documentation

Authentication

// Authenticate as the system owner
const token = await client.authenticate();

// Authenticate as an intermediary for a taxpayer
const token = await client.authenticateAsIntermediary("TAXPAYER_TIN");

// Get a valid token for a specific TIN
const token = await client.getToken("TIN");

// Get all TINs with valid tokens
const tins = client.getAllAuthenticatedTINs();

Invoice Operations

// Create an invoice
const invoice = client.invoices.createInvoice();

// Sign an invoice
const signedInvoice = await client.invoices.signInvoice(invoice);

// Submit an invoice
const result = await client.invoices.submitInvoice(
  signedInvoice,
  authTIN
);

// Submit multiple invoices
const results = await client.invoices.submitInvoices(
  signedInvoices,
  authTIN
);

// Cancel an invoice
await client.invoices.cancelInvoice(
  "DOCUMENT_UUID",
  "Cancellation reason",
  authTIN
);

Document Operations

// Get document status
const status = await client.documents.getDocumentStatus(
  "DOCUMENT_UUID",
  authTIN
);

// Get submission details
const details = await client.documents.getSubmissionDetails(
  "SUBMISSION_UUID",
  authTIN
);

// List documents
const documents = await client.documents.listDocuments(authTIN, {
  pageNo: 1,
  pageSize: 10,
  fromDate: "2023-01-01",
  toDate: "2023-12-31",
  status: "active",
});

License

MIT

myinvois