Endpoints

Detailed documentation for all InvoisX API endpoints.

Buyers

List Buyers

GET /buyers

Query Parameters:

Parameter	Type	Description
search	string	Search by name
per_page	integer	Results per page (default: 15)
page	integer	Page number

Create Buyer

POST /buyers

Request Body:

{
  "name": "Company Name",
  "tin": "C12345678000",
  "id_type": "BRN",
  "id_value": "202301012345",
  "is_draft": false,
  "address": {
    "line1": "123 Street",
    "line2": "Suite 456",
    "line3": "Building A",
    "city": "Kuala Lumpur",
    "state": "14",
    "postCode": "50000",
    "countryCode": "MYS"
  },
  "contact": {
    "phone": "+60123456789",
    "email": "billing@company.com",
    "name": "Contact Person",
    "fax": "+60123456780"
  }
}

Get Buyer

GET /buyers/{id}

Update Buyer

PUT /buyers/{id}

Delete Buyer

DELETE /buyers/{id}

---

Invoices

List Invoices

GET /invoices

Query Parameters:

Parameter	Type	Description
status	string	Filter by status
search	string	Search by invoice number
per_page	integer	Results per page
page	integer	Page number

Create Invoice

POST /invoices

Request Body:

{
  "buyerId": "buyer-uuid",
  "invoiceSerialNumber": "INV-2024-001",
  "currencyCode": "MYR",
  "exchangeRate": 1.00,
  "autoCalculate": true,
  "erpIssuedAt": "2024-01-15T10:00:00+08:00",
  "invoiceDiscountAmount": 100.00,
  "invoiceDiscountDescription": "Loyalty discount",
  "invoiceFeeAmount": 25.00,
  "invoiceFeeDescription": "Processing fee",
  "invoiceLines": [
    {
      "classifications": ["001"],
      "productDescription": "Product/Service Description",
      "quantity": 1,
      "unitCode": "H87",
      "unitPrice": 1000.00,
      "discountRate": 5,
      "discountDescription": "Volume discount",
      "feeOrChargeRate": 2,
      "feeOrChargeDescription": "Handling fee",
      "invoiceLineTaxes": [
        {
          "taxType": "01",
          "taxRate": 8
        }
      ]
    }
  ],
  "payment": {
    "paymentMode": "03",
    "paymentTerms": "Net 30",
    "supplierBankAccountNumber": "1234567890",
    "prepaymentAmount": 500.00,
    "prepaymentDate": "2024-01-10",
    "prepaymentReferenceNumber": "PRE-001"
  },
  "delivery": {
    "recipientName": "Recipient",
    "recipientTin": "C98765432100",
    "recipientIdType": "BRN",
    "recipientIdValue": "202301054321",
    "recipientAddress": {
      "line1": "456 Delivery Street",
      "city": "Petaling Jaya",
      "state": "10",
      "countryCode": "MYS"
    }
  },
  "invoicePeriod": {
    "frequencyOfBilling": "Monthly",
    "billingPeriodStartDate": "2024-01-01",
    "billingPeriodEndDate": "2024-01-31"
  }
}

Get Invoice

GET /invoices/{id}

Update Invoice

PUT /invoices/{id}

WARNING

Only draft invoices can be updated.

Delete Invoice

DELETE /invoices/{id}

WARNING

Only draft invoices can be deleted.

---

Credit Notes

Same as invoices, with additional documentReferences field:

POST /credit-notes

{
  "buyerId": "buyer-uuid",
  "documentReferences": [
    {
      "referenceNumber": "INV-2024-001",
      "uuid": "lhdn-document-uuid"
    }
  ],
  "isPreEinvoicing": false,
  "invoiceLines": [/* ... */]
}

---

Debit Notes

POST /debit-notes

Same structure as credit notes.

---

Refund Notes

POST /refund-notes

Same structure as credit notes.

---

Consolidated Invoices

POST /consolidated-invoices

Same structure as regular invoices.

---

Self-Billed Documents

Self-Billed Invoice

POST /self-billed-invoices

Uses onBehalfSellerId instead of buyerId:

{
  "onBehalfSellerId": "seller-uuid",
  "invoiceSerialNumber": "SBI-2024-001",
  "invoiceLines": [/* ... */]
}

Other Self-Billed Types

• POST /self-billed-credit-notes
• POST /self-billed-debit-notes
• POST /self-billed-refund-notes

All require onBehalfSellerId and documentReferences (except the invoice).

---

Document Operations

Validate Document

POST /documents/{id}/validate

Response:

{
  "success": true,
  "data": {
    "id": "document-uuid",
    "status": "ready",
    "validation_passed": true,
    "message": "Document validated successfully"
  }
}

Submit to LHDN

POST /documents/{id}/submit

Response:

{
  "success": true,
  "data": {
    "id": "document-uuid",
    "status": "Submitted",
    "document_uuid": "LHDN-UUID",
    "invoice_code_number": "INV-2024-001"
  }
}

Check Status

GET /documents/{id}/status

Response:

{
  "success": true,
  "data": {
    "id": "document-uuid",
    "status": "Valid",
    "document_uuid": "LHDN-UUID",
    "document_long_id": "...",
    "validated_at": "2024-01-15T10:30:00+08:00"
  }
}

Get QR Code

GET /documents/{id}/qr

Headers:

Accept	Response
application/json	JSON with base64
image/png	PNG image
image/jpeg	JPEG image

Get PDF

GET /documents/{id}/pdf

Bulk Submit

POST /documents/submit-bulk

Request Body:

{
  "document_ids": ["uuid-1", "uuid-2", "uuid-3"]
}

---

Reference Data

States

GET /states

Returns Malaysian state codes.

Countries

GET /countries

Returns ISO country codes.

Classifications

GET /classifications

Returns LHDN product classification codes.

Unit Types

GET /unit-types

Returns unit of measurement codes.

Tax Types

GET /tax-types

Returns tax type codes.

Currencies

GET /currencies

Returns ISO currency codes.

Payment Modes

GET /payment-modes

Returns payment method codes.

ID Types

GET /id-types

Returns identification type codes.