Test API

This section covers testing utilities and manual trigger endpoints for debugging and testing purposes in the Malaysian e-invoicing system.

⚠️ Warning: These endpoints are intended for testing and debugging purposes only. Use with caution in production environments.

Authentication

All endpoints require authentication via API key:

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

Base URL

/api

Manual Trigger Submit Consolidate

Manually trigger the consolidation and submission process for invoices.

Endpoint

POST /api/test/manual-trigger-submit-consolidate

Headers

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

Request Body

Field	Type	Required	Description
`company_id`	number	No	Specific company ID to process (if not provided, processes all companies)
`invoice_ids`	array	No	Specific invoice IDs to consolidate
`force_submit`	boolean	No	Force submission even if validation fails (default: false)
`dry_run`	boolean	No	Perform dry run without actual submission (default: false)

Request Example

{
  "company_id": 2,
  "invoice_ids": [123, 124, 125],
  "force_submit": false,
  "dry_run": true
}

Response Examples

Success (200)

{
  "success": true,
  "message": "Consolidation process triggered successfully",
  "data": {
    "processed_companies": 1,
    "consolidated_invoices": 3,
    "submitted_documents": 1,
    "processing_time_ms": 1250,
    "consolidation_results": [
      {
        "consolidated_invoice_id": 45,
        "original_invoice_ids": [123, 124, 125],
        "status": "SUBMITTED",
        "myinvois_uuid": "ABC123XYZ789",
        "submission_timestamp": "2025-09-23T10:30:00.000Z"
      }
    ]
  }
}

Dry Run Success (200)

{
  "success": true,
  "message": "Dry run completed successfully",
  "data": {
    "dry_run": true,
    "would_process_companies": 1,
    "would_consolidate_invoices": 3,
    "would_submit_documents": 1,
    "estimated_processing_time_ms": 1200,
    "validation_results": [
      {
        "invoice_id": 123,
        "status": "VALID",
        "warnings": []
      },
      {
        "invoice_id": 124,
        "status": "VALID",
        "warnings": ["Missing optional buyer email"]
      },
      {
        "invoice_id": 125,
        "status": "INVALID",
        "errors": ["Invalid tax calculation"]
      }
    ]
  }
}

Error (400)

{
  "success": false,
  "message": "Consolidation process failed",
  "error_details": {
    "error_code": "INVALID_INVOICE_STATE",
    "error_message": "Some invoices are not ready for consolidation",
    "invalid_invoice_ids": [125],
    "details": [
      {
        "invoice_id": 125,
        "error": "Invoice is not in submitted state"
      }
    ]
  }
}

Manual Sync Status and Fail Reason

Manually trigger synchronization of submission status and failure reasons from MyInvois.

Endpoint

POST /api/test/manual-sync-status-and-fail-reason

Headers

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

Request Body

Field	Type	Required	Description
`company_id`	number	No	Specific company ID to sync (if not provided, syncs all companies)
`document_ids`	array	No	Specific submitted document IDs to sync
`max_age_hours`	number	No	Only sync documents submitted within this many hours (default: 72)
`force_sync`	boolean	No	Force sync even if recently synced (default: false)

Request Example

{
  "company_id": 2,
  "document_ids": [45, 46, 47],
  "max_age_hours": 24,
  "force_sync": false
}

Response Examples

Success (200)

{
  "success": true,
  "message": "Status synchronization completed successfully",
  "data": {
    "synced_documents": 3,
    "processing_time_ms": 850,
    "sync_results": [
      {
        "document_id": 45,
        "previous_status": "SUBMITTED",
        "current_status": "VALID",
        "myinvois_uuid": "ABC123XYZ789",
        "last_sync_timestamp": "2025-09-23T10:35:00.000Z",
        "changes_detected": true
      },
      {
        "document_id": 46,
        "previous_status": "SUBMITTED",
        "current_status": "REJECTED",
        "myinvois_uuid": "DEF456UVW012",
        "fail_reason": "Invalid tax calculation",
        "fail_details": {
          "error_code": "TAX_CALC_ERROR",
          "error_description": "Tax amount does not match calculated value",
          "field_errors": [
            {
              "field": "lineItems[0].taxAmount",
              "expected": 10.0,
              "actual": 9.5
            }
          ]
        },
        "last_sync_timestamp": "2025-09-23T10:35:01.000Z",
        "changes_detected": true
      },
      {
        "document_id": 47,
        "previous_status": "VALID",
        "current_status": "VALID",
        "myinvois_uuid": "GHI789ABC345",
        "last_sync_timestamp": "2025-09-23T10:35:02.000Z",
        "changes_detected": false
      }
    ],
    "summary": {
      "total_checked": 3,
      "status_changed": 2,
      "newly_valid": 1,
      "newly_rejected": 1,
      "no_changes": 1
    }
  }
}

Partial Success (200)

{
  "success": true,
  "message": "Status synchronization completed with some failures",
  "data": {
    "synced_documents": 2,
    "failed_documents": 1,
    "processing_time_ms": 950,
    "sync_results": [
      {
        "document_id": 45,
        "status": "SUCCESS",
        "current_status": "VALID"
      },
      {
        "document_id": 46,
        "status": "SUCCESS",
        "current_status": "REJECTED"
      }
    ],
    "sync_failures": [
      {
        "document_id": 47,
        "error": "MyInvois API timeout",
        "error_code": "TIMEOUT",
        "retry_after": 300
      }
    ]
  }
}

Error (400)

{
  "success": false,
  "message": "Status synchronization failed",
  "error_details": {
    "error_code": "MYINVOIS_UNAVAILABLE",
    "error_message": "MyInvois API is currently unavailable",
    "retry_after": 600,
    "failed_document_count": 3
  }
}

Test Endpoint Response Structure

Common Response Fields

All test endpoints return a consistent response structure:

Field	Type	Description
`success`	boolean	Whether the operation succeeded
`message`	string	Human-readable operation result
`data`	object	Detailed operation results
`error_details`	object	Error information (if operation failed)

Processing Metrics

Test endpoints include performance metrics:

Field	Type	Description
`processing_time_ms`	number	Total processing time in milliseconds
`processed_companies`	number	Number of companies processed
`synced_documents`	number	Number of documents synchronized
`failed_documents`	number	Number of documents that failed processing

Validation Results

For dry run operations:

Field	Type	Description
`dry_run`	boolean	Indicates this was a dry run
`validation_results`	array	Validation results for each item
`estimated_processing_time_ms`	number	Estimated processing time

Use Cases

Testing Consolidation Process

Dry Run First: Always perform a dry run to validate invoices before actual consolidation
Specific Invoice Testing: Test consolidation with specific invoice IDs
Company-specific Testing: Test consolidation for a specific company
Force Submission: Use force_submit for testing edge cases (use with caution)

Testing Status Synchronization

Recent Documents: Sync status for recently submitted documents
Specific Documents: Test sync for specific document IDs
Company-wide Sync: Sync all documents for a company
Force Refresh: Use force_sync to refresh cached status information

Common Error Codes

Status Code	Description
`200`	OK - Operation completed (check `success` field for result)
`400`	Bad Request - Invalid request parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Test endpoints not enabled
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - System error
`503`	Service Unavailable - MyInvois system unavailable

Important Notes

Production Warning: These endpoints should be used with extreme caution in production environments as they can trigger actual submissions to MyInvois.
Rate Limiting: Test endpoints may have strict rate limits to prevent abuse.
Dry Run Mode: Always use dry run mode first to validate operations before executing them.
Error Handling: Test endpoints provide detailed error information to help with debugging.
Performance Monitoring: Processing time metrics help identify performance bottlenecks.
Data Integrity: Operations may modify data state, so ensure proper backups before running tests.
MyInvois Dependency: Operations depend on MyInvois API availability and may fail during maintenance windows.
Logging: All test operations are logged for audit and debugging purposes.
Access Control: Test endpoints may require additional permissions or may be disabled in production.
Batch Processing: Both endpoints support batch operations for efficiency, but large batches may timeout.
State Validation: Endpoints validate document/invoice states before processing to prevent invalid operations.
Retry Logic: Failed operations may include retry recommendations with appropriate backoff times.

Test API

On this page