API Documentation

1. Introduction

Welcome to JomeInvoice API. This API allows you to create, list, view, and download invoices as PDFs. Below you’ll find the necessary information to get started, including how to authenticate and the available endpoints.

2. Authentication & Rate Limiting

To use the API, you need to authenticate via oAuth2 access tokens.

Your access tokens can be generated by using your client_id and client_secret, which will be available on your dashboard.

Using your client_id and client_secret, you will make a POST request:

https://app.jomeinvoice.my/oauth/token

Body (form-data):

grant_type: client_credentials
client_id: YOUR_CLIENT_ID
client_secret: YOUR_CLIENT_SECRET

Which will return a JSON:

{
    "token_type": "Bearer",
    "expires_in": 31536000,
    "access_token": "YOUR_ACCESS_TOKEN"
}

Store your access token and use it in all your requests in the header:

Header Example:

Authorization: Bearer YOUR_ACCESS_TOKEN

Rate Limiting

All API endpoints are rate-limited to ensure fair usage and to prevent abuse. Rate limits are included in the response headers.

The following headers are included in each response to provide information about your current rate limit status:

X-RateLimit-Limit: The maximum number of requests that you are allowed to make.
X-RateLimit-Remaining: The number of requests remaining in the current rate limit window.
Retry-After: The number of seconds to wait before making a new request, included when the rate limit has been exceeded.

Example Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
Retry-After: 120

Please ensure to handle rate limiting in your client implementation to avoid receiving HTTP 429 (Too Many Requests) responses.

3. Endpoints

a. Create New Invoices

Endpoint:

POST /api/invoices

Description:
Creates a new invoice.

Tax types:

01: sales tax
02: service tax
03: tourism tax
04: high value goods tax
05: sales tax on low value goods
06: not applicable
E: tax exemption

Request Body:

{
  "invoices": [
    {
      "type": "string", // The code type of invoice (e.g., "01", "02") 
      "buyer_uuid": "UUID", // The buyer UUID (optional -- or submit buyer in the same request)
      "supplier_uuid": "UUID", // The supplier UUID (optional based on invoice type, and you can submit supplier details in the same request) 
      "invoice": {
        "number": "string", // Invoice number
        "issue_date": "string", // Date when the invoice was issued
        "due_date": "string", // Due date for the invoice (optional)
        "payment_terms": "string", // Payment terms (optional) 
        "payment_mode": "string", // Payment method ex 01 (https://sdk.myinvois.hasil.gov.my/codes/payment-methods/) (optional)
        "currency": "string", // Currency code (e.g., "MYR")
        "description": "string", // Description of the invoice
        "offset_invoice_uuid": "string", // Offset invoice UUID, if applicable
        "msic_code": "string" // MSIC code
      },
      "supplier": { // Supplier details (optional if you want to add a new supplier in the same request)
        "email": "string", // The email of the supplier
        "registration_number": "string", // Registration number
        "registration_document_type": "string", // Registration document type (BRN, NRIC, PASSPORT, ARMY)
        "tin": "string", // TIN number 
        "name": "string", // Company name
        "sst": "string", // SST (optional)
        "cif_number": "string", // CIF number (optional)
        "office_contact": "string", // Office contact number 
        "contact_number": "string", // Contact number (optional)
        "address_line0": "string", // Address line 0
        "address_line1": "string", // Address line 1 (optional)
        "address_line2": "string", // Address line 2 (optional)
        "address_city": "string", // Address city (ex: Kuala Lumpur)
        "address_postal_code": "string", // Address postal code
        "address_country": "string", // Address country (ex: MYS https://sdk.myinvois.hasil.gov.my/codes/countries/)
        "address_state": "string" // Address state (ex: 00 https://sdk.myinvois.hasil.gov.my/codes/state-codes/)
      }
      "buyer": { // Buyer details (optional if you want to add a new supplier in the same request)
        "email": "string", // The email of the buyer
        "registration_number": "string", // Registration number
        "registration_document_type": "string", // Registration document type (BRN, NRIC, PASSPORT, ARMY)
        "tin": "string", // TIN number 
        "name": "string", // Company name
        "sst": "string", // SST (optional)
        "cif_number": "string", // CIF number (optional)
        "office_contact": "string", // Office contact number 
        "contact_number": "string", // Contact number (optional)
        "address_line0": "string", // Address line 0
        "address_line1": "string", // Address line 1 (optional)
        "address_line2": "string", // Address line 2 (optional)
        "address_city": "string", // Address city (ex: Kuala Lumpur)
        "address_postal_code": "string", // Address postal code
        "address_country": "string", // Address country (ex: MYS https://sdk.myinvois.hasil.gov.my/codes/countries/)
        "address_state": "string" // Address state (ex: 00 https://sdk.myinvois.hasil.gov.my/codes/state-codes/)
      }
      "line_items": [
        {
          "item": "string", // Description of the item
          "uom": "string", // Unit of measurement (optional: https://sdk.myinvois.hasil.gov.my/codes/unit-types/)
          "qty": "number", // Quantity of the item (optional
          "price": "number", // Unit price of the item 
          "subtotal": "number", // Your item line subtotal (price * quantity)
          "disc": "number", // Discount amount (optional)
          "disc_type": "string", // Discount type (e.g., "percentage", "exact") (optional)
          "tax_type": "string", // Tax type (e.g., "01", "02")
          "tax_amount": "number", // Your item line tax amount (subtotal + tax)
          "classification_code": "string" // Classification code (ex: 022)
        }
      ],
      "total_excluding_tax": "number", // Total amount excluding tax
      "total_tax": "number", // Total tax amount
      "total_including_tax": "number" // Total amount including tax
    }
  ]
}

Response Example:

{
  "accepted_invoices": [
    {
      "invoice_number": "INV-001",
    },
    {
      "invoice_number": "INV-002",
    }
  ],
  "rejected_invoices": [
    {
      "invoice_number": "INV-003",
      "message": "Buyer UUID is invalid."
    },
    {
      "invoice_number": "INV-004",
      "message": "Total amount cannot be negative."
    }
  ]
}

b. Listing Invoices

Endpoint:

GET /api/invoices

Description:
Retrieves a list of invoices with optional filtering parameters.

Parameters:

type (string, required): Filter by invoice type.
- 01: invoice
- 02: credit note
- 03: debit note
- 04: refund note
- 11: self billed invoice
- 12: self billed credit note
- 13: self billed debit note
- 14: self billed refund note
buyer_uuid (string, optional): Filter by buyer UID.
supplier_uuid (string, optional): Filter by supplier UID.
status (string, optional): Filter by invoice status.
- error – means invoice have incorrect information, cannot be sent to LHDN
- submitted – user successfully submitted invoice to LHDN
- valid – invoice successfully validated
- invalid – invoice failed validation – return error summary
- awaiting – invoice awaiting buyer/recipient to take action (accept/request to reject) (invoice within 72hr upon validation)
- accepted – invoice accepted by buyer/recipient
- rejected – recipient requested to cancel by issuer
- cancelled – invoice cancelled by issuer/supplier (accept reject request)
date_from (string, required): Filter invoices issued from this date (format: YYYY-MM-DD).
date_to (string, required): Filter invoices issued up to this date (format: YYYY-MM-DD).
due_date_from (string, optional): Filter invoices with due dates from this date (format: YYYY-MM-DD).
due_date_to (string, optional): Filter invoices with due dates up to this date (format: YYYY-MM-DD).
sort_by (string, optional): Sort results by a specific field (e.g., “date”, “due_date”, “total”).
order (string, optional): Sort order, either “asc” or “desc”.

Response Example:

[
  {
    "uuid": "5c801b23-d6b9-421b-b792-0b46c0e19a02",
    "type": "01",
    "buyer_name": "John Doe",
    "supplier_name": "John Doe",
    "total": 106,
    "status": "valid",
    "issue_date": "2024-05-24",
    "due_date": "2024-06-24",
    "validation_date": "2024-05-25",
    "lhdn_unique_id": "ABC123456",
    "digital_signature": "XYZ
    "lhdn_verify_url": "LINK_HERE_FOR_VALID_INVOICES",",
    "failure_reason": null,
    "rejected_reason": null
  },
  {
    "uuid": "caa62174-ec95-445a-9e4a-f94ccce744c9",
    "type": "02",
    "buyer_name": "Jane Smith",
    "total": 200,
    "status": "error",
    "issue_date": "2024-05-23",
    "due_date": "2024-06-23",
    "validation_date": "2024-05-24",
    "lhdn_unique_id": "DEF789101",
    "digital_signature": "XYZ
    "lhdn_verify_url": "LINK_HERE_FOR_VALID_INVOICES",",
    "failure_reason": "Invalid buyer ID",
    "rejected_reason": null
  }
]

c. Viewing Invoice

Endpoint:

GET /api/invoices/{uuid}

Description:
Retrieves details of a specific invoice by its Unique ID, including all invoice fields and its line items.

Parameters:

uuid (string, required): The Unique ID of the invoice.

Response Example:

{
  "uuid": "5e1beb03-6c16-491c-8752-817f90839aea",
  "type": "01",
  "status": "submitted",
  "invoice_number": "INV-001",
  "issue_date": "2024-05-24",
  "due_date": "2024-06-24",
  "terms": "Net 30",
  "payment_method": "Credit Card",
  "currency": "MYR",
  "buyer_uuid": "e8ee0a24-f3b3-4227-9622-6f036abbac6a",
  "buyer_name": "John Doe",
  "buyer_address": "123 Main St",
  "description": "Monthly subscription fee",
  "total_excluding_tax": 100,
  "total_tax_amount": 6,
  "total_including_tax": 106,
  "total_payable_amount": 106,
  "validation_date": "2024-05-25",
  "lhdn_unique_id": "ABC123456",
  "digital_signature": "XYZ
  "lhdn_verify_url": "LINK_HERE_FOR_VALID_INVOICES",",
  "failure_reason": null,
  "rejected_reason": null,
  "line_items": [
    {
      "description": "Service Fee",
      "item_code": "SF-001",
      "classification_code": "022",
      "measurement": "Unit",
      "quantity": 2,
      "unit_price": 50,
      "subtotal": 100,
      "discount_amount": 0,
      "discount_rate": 0,
      "taxable_amount": 100,
      "tax_amount": 6,
      "tax_type": "sales-tax"
    }
  ],
  "created_at": "2024-05-24T12:00:00Z",
  "updated_at": "2024-05-24T12:00:00Z"
}

Invoice Fields:

uuid: The invoice Unique ID.
type: The type of invoice.
status: The status of invoice.
invoice_number: The invoice number.
issue_date: The date when the invoice was issued.
due_date: The due date for the invoice.
terms: Payment terms.
payment_method: Payment method.
currency: Currency code.
buyer_uuid: Buyer UID.
buyer_name: Buyer name.
buyer_address: Buyer address.
supplier_uuid: Supplier UID.
supplier_name: Supplier name.
supplier_address: Supplier address.
description: Description of the invoice.
total_excluding_tax: Total amount excluding tax.
total_tax_amount: Total tax amount.
total_including_tax: Total amount including tax.
total_payable_amount: Total payable amount.
validation_date: The date when the invoice was validated.
lhdn_unique_id: A unique identifier for the invoice, provided by LHDN (if applicable).
failure_reason: The reason for any failure during processing, if applicable.
rejected_reason: The reason for rejection, if applicable.
created_at: Timestamp of when the invoice was created.
updated_at: Timestamp of when the invoice was last updated.

Line Item Fields:

description: Description of the item.
item_code: Code of the item.
classification_code: Classification code of the item.
measurement: Unit of measurement.
quantity: Quantity of the item.
unit_price: Unit price of the item.
subtotal: Subtotal amount for the item.
discount_amount: Discount amount applied to the item.
discount_rate: Discount rate applied to the item.
taxable_amount: Taxable amount for the item.
tax_amount: Tax amount applied to the item.
tax_type: Type of tax applied to the item.

d. PDF Invoices

Endpoint:

GET /api/invoices/{uuid}/pdf

Description:
Returns a URL to download the PDF version of a specific invoice. The URL expires after 24 hours. The PDF is available only if it is ready.

Parameters:

uuid (string, required): The UUID of the invoice.

Response Example (Success):

{
  "status": "success",
  "pdf_url": "https://app.jomeinvoice.my/downloads/invoice-uuid.pdf",
  "expires_in": "24 hours"
}

Response Example (Error):

{
  "status": "error",
  "message": "Invoice PDF is not ready."
}

Response Fields:

status: Indicates the status of the request (success or error).
pdf_url: The URL to download the PDF version of the invoice (only if status is success).
expires_in: Indicates the time duration for which the URL is valid (only if status is success).
message: Error message providing details if the invoice PDF is not ready (only if status is error).

e. Create New Buyer

Endpoint:

POST /api/buyer

Description:
Creates new buyers or updates existing buyers based on the provided buyer email. Supports creating or updating up to 100 buyers at a time.

Request Body:

{
  "buyers": [
    {
      "email": "string", // The email of the buyer
      "registration_number": "string", // Registration number
      "registration_document_type": "string", // Registration document type (BRN, NRIC, PASSPORT, ARMY)
      "tin": "string", // TIN number 
      "name": "string", // Company name
      "sst": "string", // SST (optional)
      "cif_number": "string", // CIF number (optional)
      "office_contact": "string", // Office contact number 
      "contact_number": "string", // Contact number (optional)
      "address_line0": "string", // Address line 0
      "address_line1": "string", // Address line 1 (optional)
      "address_line2": "string", // Address line 2 (optional)
      "address_city": "string", // Address city (ex: Kuala Lumpur)
      "address_postal_code": "string", // Address postal code
      "address_country": "string", // Address country (ex: MYS https://sdk.myinvois.hasil.gov.my/codes/countries/)
      "address_state": "string" // Address state (ex: 00 https://sdk.myinvois.hasil.gov.my/codes/state-codes/)
    }
  ]
}

Response Example (Success):

{
  "status": "success",
  "accepted_buyers": [
    {
      "buyer_uuid": d380bbe4-ba1a-462c-b613-c6513c2dc5ff,
      "message": "Buyer created or updated successfully."
    },
    {
      "buyer_uuid": e8ee0a24-f3b3-4227-9622-6f036abbac6a,
      "message": "Buyer created or updated successfully."
    }
  ],
  "rejected_buyers": [
    {
      "email": "[email protected]",
      "message": "Invalid email address."
    }
  ]
}

Response Example (Error):

{
  "status": "error",
  "message": "An error occurred while processing buyers."
}

f. Create New Supplier

Endpoint:

POST /api/supplier

Description:
Creates new suppliers or updates existing suppliers based on the provided supplier email. Supports creating or updating up to 100 suppliers at a time.

Request Body:

{
  "suppliers": [
    {
     "email": "string", // The email of the supplier
      "registration_number": "string", // Registration number
      "registration_document_type": "string", // Registration document type (BRN, NRIC, PASSPORT, ARMY)
      "tin": "string", // TIN number 
      "name": "string", // Company name
      "sst": "string", // SST (optional)
      "cif_number": "string", // CIF number (optional)
      "office_contact": "string", // Office contact number 
      "contact_number": "string", // Contact number (optional)
      "address_line0": "string", // Address line 0
      "address_line1": "string", // Address line 1 (optional)
      "address_line2": "string", // Address line 2 (optional)
      "address_city": "string", // Address city (ex: Kuala Lumpur)
      "address_postal_code": "string", // Address postal code
      "address_country": "string", // Address country (ex: MYS https://sdk.myinvois.hasil.gov.my/codes/countries/)
      "address_state": "string" // Address state (ex: 00 https://sdk.myinvois.hasil.gov.my/codes/state-codes/)
    }
  ]
}

Response Example (Success):

{
  "status": "success",
  "accepted_suppliers": [
    {
      "supplier_uid": d380bbe4-ba1a-462c-b613-c6513c2dc5ff,
      "message": "Supplier created or updated successfully."
    },
    {
      "supplier_uid": e8ee0a24-f3b3-4227-9622-6f036abbac6a,
      "message": "Supplier created or updated successfully."
    }
  ],
  "rejected_suppliers": [
    {
      "email": "[email protected]",
      "message": "Invalid email address."
    }
  ]
}

Response Example (Error):

{
  "status": "error",
  "message": "An error occurred while processing suppliers."
}

1. Introduction

2. Authentication & Rate Limiting

Rate Limiting

Example Headers

3. Endpoints

a. Create New Invoices

b. Listing Invoices

c. Viewing Invoice

d. PDF Invoices

e. Create New Buyer

f. Create New Supplier

Contact Us

Quick Links