BizCARE MyInvois
API Reference

Validations API

Complete API reference for validation services in the E-Invoice system

Validations API

This section covers all validation-related endpoints for validating invoice codes, TIN numbers, adjustment note codes, and company names in the Malaysian e-invoicing system.

Authentication

All endpoints require authentication via API key:

X-API-Key: your-api-key-here

Base URL

/api

Validate Invoice Code

Validate whether an invoice code already exists in the system.

Endpoint

POST /api/validation/invoice-code

Headers

X-API-Key: your-api-key-here
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
codenumberYesInvoice code to validate
typestringNoInvoice type: INVOICE, SELF_BILLED_INVOICE

Request Example

{
  "code": 12345,
  "type": "INVOICE"
}

Response Examples

Code Available (200)

{
  "data": {
    "is_valid": true,
    "message": "Invoice code is available",
    "code": 12345
  }
}

Code Already Exists (200)

{
  "data": {
    "is_valid": false,
    "message": "Invoice code already exists for current year",
    "code": 12345,
    "existing_invoice_id": 456
  }
}

Validation Error (422)

{
  "message": "Validation failure",
  "errors": [
    {
      "message": "The code field is required",
      "rule": "required",
      "field": "code"
    }
  ]
}

Validate TIN

Validate a Tax Identification Number (TIN) against the MyInvois system.

Endpoint

POST /api/validation/tin

Headers

X-API-Key: your-api-key-here
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
tinstringYesTax Identification Number to validate
registration_typestringYesRegistration type: NRIC, BRN, PASSPORT
registration_numberstringYesRegistration number

Request Example

{
  "tin": "IG12345678901",
  "registration_type": "NRIC",
  "registration_number": "991021081111"
}

Response Examples

Valid TIN (200)

{
  "data": {
    "is_valid": true,
    "message": "TIN validation successful",
    "tin": "IG12345678901",
    "entity_name": "John Doe",
    "registration_details": {
      "type": "NRIC",
      "number": "991021081111"
    }
  }
}

Invalid TIN (200)

{
  "data": {
    "is_valid": false,
    "message": "TIN validation failed",
    "tin": "IG12345678901",
    "error_details": "TIN not found in MyInvois system"
  }
}

Validation Error (422)

{
  "message": "Validation failure",
  "errors": [
    {
      "message": "The tin field is required",
      "rule": "required",
      "field": "tin"
    },
    {
      "message": "Invalid registration type",
      "rule": "enum",
      "field": "registration_type"
    }
  ]
}

Validate Adjustment Note Code

Validate whether an adjustment note code already exists in the system.

Endpoint

POST /api/validation/adjustment-note-code

Headers

X-API-Key: your-api-key-here
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
codenumberYesAdjustment note code to validate
typestringNoAdjustment note type: CREDIT_NOTE, DEBIT_NOTE

Request Example

{
  "code": 789,
  "type": "CREDIT_NOTE"
}

Response Examples

Code Available (200)

{
  "data": {
    "is_valid": true,
    "message": "Adjustment note code is available",
    "code": 789
  }
}

Code Already Exists (200)

{
  "data": {
    "is_valid": false,
    "message": "Adjustment note code already exists for current year",
    "code": 789,
    "existing_adjustment_note_id": 123
  }
}

Validation Error (422)

{
  "message": "Validation failure",
  "errors": [
    {
      "message": "The code field is required",
      "rule": "required",
      "field": "code"
    }
  ]
}

Validate Company Name

Validate a company name for uniqueness and compliance.

Endpoint

POST /api/validation/company-name

Headers

X-API-Key: your-api-key-here
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
namestringYesCompany name to validate
registration_typestringNoRegistration type: BRN, NRIC

Request Example

{
  "name": "ABC Sdn Bhd",
  "registration_type": "BRN"
}

Response Examples

Name Available (200)

{
  "data": {
    "is_valid": true,
    "message": "Company name is available",
    "name": "ABC Sdn Bhd",
    "suggestions": []
  }
}

Name Already Exists (200)

{
  "data": {
    "is_valid": false,
    "message": "Company name already exists",
    "name": "ABC Sdn Bhd",
    "suggestions": [
      "ABC Trading Sdn Bhd",
      "ABC Business Sdn Bhd",
      "ABC Solutions Sdn Bhd"
    ]
  }
}

Invalid Name Format (200)

{
  "data": {
    "is_valid": false,
    "message": "Company name format is invalid",
    "name": "ABC Sdn Bhd",
    "error_details": "Name must end with proper business entity suffix",
    "valid_suffixes": ["Sdn Bhd", "Bhd", "PLT", "LLP"]
  }
}

Validation Error (422)

{
  "message": "Validation failure",
  "errors": [
    {
      "message": "The name field is required",
      "rule": "required",
      "field": "name"
    },
    {
      "message": "The name must be at least 3 characters",
      "rule": "minLength",
      "field": "name"
    }
  ]
}

Validation Response Structure

Common Response Fields

All validation endpoints return a consistent response structure:

FieldTypeDescription
data.is_validbooleanWhether the validation passed
data.messagestringHuman-readable validation result
data.error_detailsstringAdditional error information (if validation failed)

Invoice Code Validation Response

FieldTypeDescription
data.codenumberThe validated invoice code
data.existing_invoice_idnumberID of existing invoice (if code exists)

TIN Validation Response

FieldTypeDescription
data.tinstringThe validated TIN
data.entity_namestringName of the entity (if valid)
data.registration_detailsobjectRegistration information

Adjustment Note Code Validation Response

FieldTypeDescription
data.codenumberThe validated adjustment note code
data.existing_adjustment_note_idnumberID of existing note (if code exists)

Company Name Validation Response

FieldTypeDescription
data.namestringThe validated company name
data.suggestionsarrayAlternative name suggestions (if name exists)
data.valid_suffixesarrayValid business entity suffixes

Validation Rules

Invoice Code Validation

  1. Uniqueness: Invoice codes must be unique within a company for each calendar year
  2. Format: Must be a positive integer
  3. Type-specific: Different prefixes may apply based on invoice type

TIN Validation

  1. Format: Must follow Malaysian TIN format (e.g., "IG" prefix for individuals)
  2. MyInvois Check: Validated against the official MyInvois database
  3. Registration Match: TIN must match the provided registration details

Adjustment Note Code Validation

  1. Uniqueness: Codes must be unique within a company for each calendar year
  2. Format: Must be a positive integer
  3. Type-specific: Different prefixes may apply based on note type

Company Name Validation

  1. Format: Must include proper business entity suffix
  2. Length: Minimum 3 characters, maximum 200 characters
  3. Characters: Only alphanumeric characters, spaces, and specific symbols allowed
  4. Uniqueness: Name should be unique within the registration jurisdiction

Common Error Codes

Status CodeDescription
200OK - Validation completed (check is_valid field for result)
400Bad Request - Invalid request format
401Unauthorized - Invalid or missing API key
422Unprocessable Entity - Validation errors in request data
429Too Many Requests - Rate limit exceeded
500Internal Server Error - MyInvois system unavailable

Important Notes

  1. Real-time Validation: All validations are performed in real-time against the MyInvois system when applicable.

  2. Rate Limiting: Validation endpoints may have rate limits to prevent abuse. Check response headers for rate limit information.

  3. Caching: Some validation results may be cached for a short period to improve performance.

  4. Business Rules: Validation rules may change based on Malaysian regulatory requirements and MyInvois system updates.

  5. Calendar Year Scope: Code uniqueness validations are scoped to the current calendar year.

  6. Registration Types:

    • NRIC: National Registration Identity Card (Malaysian individuals)
    • BRN: Business Registration Number (Malaysian businesses)
    • PASSPORT: Passport number (foreign individuals/entities)

  7. TIN Formats:

    • Individual: "IG" prefix (e.g., IG12345678901)
    • Business: Various prefixes based on entity type
    • Foreign: Special prefixes for foreign entities

  8. Async Operations: Some validations may take longer if external systems are involved.

  9. Error Handling: Always check the is_valid field even for 200 responses, as validation failure is not an HTTP error.

  10. Integration: These endpoints are designed for real-time validation during data entry in forms and applications.

Invoices API

Complete API reference for managing invoices in the E-Invoice system

Adjustment Notes API

Complete API reference for managing adjustment notes (credit notes and debit notes)