{"openapi":"3.0.0","info":{"title":"UrusHQ API","version":"1.0.0","description":"Malaysian business operating system API for LHDN MyInvois e-invoicing, Peppol BIS 3.0, double-entry accounting, statutory payroll (EPF/SOCSO/EIS/PCB), and multi-bank reconciliation.","contact":{"name":"UrusHQ Developer Relations","url":"https://urushq.my/developers","email":"dev@urushq.my"},"license":{"name":"Proprietary","url":"https://urushq.my/terms"}},"servers":[{"url":"https://api.urushq.my/v1","description":"Production API Gateway (High-throughput & LHDN Live)"},{"url":"https://sandbox-api.urushq.my/v1","description":"Sandbox API Gateway (LHDN MyInvois Pre-production Sandbox)"}],"security":[{"apiKey":[],"apiSecret":[]}],"paths":{"/invoices":{"get":{"summary":"List invoices","description":"Retrieve a paginated list of sales invoices with optional status and date filters.","tags":["Invoices"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Page number for pagination"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Number of items per page"},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","submitted","validated","paid","overdue","cancelled"]},"description":"Filter invoices by clearance or payment status"},{"name":"contact_id","in":"query","schema":{"type":"string"},"description":"Filter invoices by buyer/customer ID"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Search invoice number or buyer name"}],"responses":{"200":{"description":"A paginated list of invoices","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}},"post":{"summary":"Create invoice","description":"Create a new draft or validated sales invoice with Malaysian SST calculations and MyInvois fields.","tags":["Invoices"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoiceRequest"},"example":{"invoice_number":"INV-2026-0881","issue_date":"2026-08-18","due_date":"2026-09-17","contact_id":"ct_9a8f2940bc2","currency":"MYR","payment_terms_days":30,"notes":"Payment via DuitNow or Maybank Corporate Account.","line_items":[{"description":"Cloud Infrastructure Advisory & Implementation","product_id":"prod_9012384","quantity":1,"unit_price_cents":850000,"tax_code":"SST_8","tax_rate":0.08,"classification_code":"022"},{"description":"Monthly Maintenance & Monitoring Retainer","quantity":1,"unit_price_cents":150000,"tax_code":"SST_8","tax_rate":0.08,"classification_code":"022"}]}}}},"responses":{"201":{"description":"Invoice successfully created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Invoice"}}}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/invoices/{id}":{"get":{"summary":"Get invoice details","description":"Fetch detailed invoice information including line items, tax breakdown, and LHDN MyInvois status.","tags":["Invoices"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Unique invoice ID or invoice number"}],"responses":{"200":{"description":"Detailed invoice object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Invoice"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"}}},"patch":{"summary":"Update invoice","description":"Update fields on a draft invoice prior to LHDN MyInvois submission.","tags":["Invoices"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Unique invoice ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInvoiceRequest"}}}},"responses":{"200":{"description":"Invoice successfully updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Invoice"}}}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"404":{"$ref":"#/components/responses/NotFoundError"}}},"delete":{"summary":"Delete draft invoice","description":"Permanently remove a draft invoice. Validated/submitted invoices cannot be deleted (must be cancelled via LHDN).","tags":["Invoices"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Unique invoice ID"}],"responses":{"200":{"description":"Invoice successfully deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Invoice INV-2026-0881 deleted successfully."}}}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"404":{"$ref":"#/components/responses/NotFoundError"}}}},"/invoices/{id}/submit":{"post":{"summary":"Submit to MyInvois","description":"Submit an invoice directly to LHDN MyInvois for validation, XAdES digital signing, and QR clearance.","tags":["Invoices","MyInvois"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Unique invoice ID"}],"responses":{"200":{"description":"LHDN clearance successful and QR payload generated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/MyInvoisSubmissionResult"}}}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/contacts":{"get":{"summary":"List contacts","description":"Retrieve a paginated list of customers and suppliers with Malaysian TIN and SSM numbers.","tags":["Contacts"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"type","in":"query","schema":{"type":"string","enum":["customer","supplier","both"]},"description":"Filter contacts by role"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Search contact name, TIN, or BRN"}],"responses":{"200":{"description":"List of contacts","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"summary":"Create contact","description":"Register a new customer or vendor with Malaysian Tax Identification Number (TIN) & BRN.","tags":["Contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateContactRequest"},"example":{"name":"Petronas Dagangan Berhad","type":"customer","email":"procurement@petronas.com.my","phone":"+60320515000","tin":"C20589876543","brn":"198901004512","sst_no":"W10-1808-32000045","address_line1":"Tower 1, PETRONAS Twin Towers","address_line2":"Kuala Lumpur City Centre","city":"Kuala Lumpur","state":"Wilayah Persekutuan Kuala Lumpur","postcode":"50088","country":"Malaysia","payment_terms_days":30,"credit_limit_cents":50000000}}}},"responses":{"201":{"description":"Contact created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Contact"}}}}}},"400":{"$ref":"#/components/responses/BadRequestError"}}}},"/contacts/{id}":{"get":{"summary":"Get contact details","tags":["Contacts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Contact details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Contact"}}}}}},"404":{"$ref":"#/components/responses/NotFoundError"}}},"patch":{"summary":"Update contact","tags":["Contacts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContactRequest"}}}},"responses":{"200":{"description":"Contact updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Contact"}}}}}}}},"delete":{"summary":"Archive contact","tags":["Contacts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Contact archived","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Contact archived successfully."}}}}}}}}},"/products":{"get":{"summary":"List products and services","description":"Get all catalog items with MSIC codes and MyInvois classification codes.","tags":["Products"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"type","in":"query","schema":{"type":"string","enum":["product","service"]}},{"name":"search","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of products and services","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"summary":"Create product or service","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProductRequest"},"example":{"name":"Enterprise ERP LHDN Sync Module","sku":"MOD-LHDN-ENT","description":"Real-time middleware sync agent with MyInvois API integration.","type":"service","unit":"license","selling_price_cents":1200000,"cost_price_cents":300000,"tax_code":"SST_8","msic_code":"62010","classification_code":"022","track_inventory":false}}}},"responses":{"201":{"description":"Product created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Product"}}}}}}}}},"/bills":{"get":{"summary":"List vendor bills","description":"Retrieve accounts payable purchase bills from suppliers.","tags":["Bills"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","approved","paid","overdue"]}}],"responses":{"200":{"description":"List of vendor bills","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Bill"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"summary":"Create vendor bill","tags":["Bills"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBillRequest"},"example":{"bill_number":"BILL-AWS-202608","supplier_id":"ct_supplier_aws89","issue_date":"2026-08-01","due_date":"2026-08-31","currency":"MYR","line_items":[{"description":"Cloud Server Infrastructure (Singapore & KL Edge)","quantity":1,"unit_price_cents":345000,"tax_code":"SST_8","tax_amount_cents":27600,"amount_cents":372600}]}}}},"responses":{"201":{"description":"Bill recorded successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Bill"}}}}}}}}},"/payments":{"get":{"summary":"List payments","description":"Get record of payments received for invoices or disbursed for bills.","tags":["Payments"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"invoice_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of recorded payments","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"summary":"Record payment","description":"Record an incoming invoice settlement or outgoing vendor bill payment.","tags":["Payments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordPaymentRequest"},"example":{"invoice_id":"inv_88192a01","amount_cents":1080000,"payment_date":"2026-08-18","payment_method":"duitnow","reference_number":"DN-20260818-MBB-991204","bank_account_id":"bank_mbb_01","notes":"Received payment via Maybank2u Biz DuitNow transfer."}}}},"responses":{"201":{"description":"Payment recorded and invoice balance updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Payment"}}}}}}}}},"/employees":{"get":{"summary":"List employees","description":"Get directory of active and separated employees with statutory IDs (NRIC, EPF, SOCSO).","tags":["Payroll & HR"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"status","in":"query","schema":{"type":"string","enum":["active","probation","terminated","resigned"]}}],"responses":{"200":{"description":"List of employees","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Employee"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"summary":"Create employee","tags":["Payroll & HR"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEmployeeRequest"},"example":{"employee_no":"EMP-0042","official_full_name":"Muhammad Faris bin Zainal","nric":"940512-10-5843","nationality":"Malaysian","is_foreign_worker":false,"gender":"male","marital_status":"married","hired_at":"2025-01-15","basic_salary_cents":650000,"epf_no":"20938472","socso_no":"940512105843","tax_no":"SG29384710020","bank_name":"Maybank","bank_account_no":"514012948192"}}}},"responses":{"201":{"description":"Employee onboarded","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Employee"}}}}}}}}},"/payroll/runs":{"get":{"summary":"List payroll runs","description":"Get historical statutory payroll calculations by month/year.","tags":["Payroll & HR"],"parameters":[{"name":"year","in":"query","schema":{"type":"integer","example":2026}}],"responses":{"200":{"description":"List of payroll runs","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/PayrollRun"}}}}}}}}},"post":{"summary":"Create payroll run","description":"Initialize a monthly payroll run and calculate EPF, SOCSO, EIS, and PCB for all active staff.","tags":["Payroll & HR"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["period_month","period_year"],"properties":{"period_month":{"type":"integer","minimum":1,"maximum":12,"example":8},"period_year":{"type":"integer","example":2026},"notes":{"type":"string","example":"August 2026 Standard Salary Run"}}}}}},"responses":{"201":{"description":"Payroll run computed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/PayrollRun"}}}}}}}}},"/payroll/runs/{id}/finalize":{"post":{"summary":"Finalize and generate bank files","description":"Lock payroll figures and produce statutory payment files (Maybank Autopay MAS / CIMB / EPF Borang A / SOCSO Borang 8A).","tags":["Payroll & HR"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Payroll Run ID"}],"responses":{"200":{"description":"Payroll finalized and bank files ready for download","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/FinalizePayrollResponse"}}}}}}}}},"/banking/accounts":{"get":{"summary":"List connected bank accounts","description":"Retrieve corporate bank accounts, current balances, and integration feed statuses.","tags":["Banking"],"responses":{"200":{"description":"List of corporate bank accounts","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/BankAccount"}}}}}}}}}},"/banking/transactions":{"get":{"summary":"List bank transactions","description":"Get imported bank statements lines and current reconciliation status.","tags":["Banking"],"parameters":[{"name":"account_id","in":"query","schema":{"type":"string"}},{"name":"is_reconciled","in":"query","schema":{"type":"boolean"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}}],"responses":{"200":{"description":"List of bank transactions","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/BankTransaction"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}}},"/banking/reconcile":{"post":{"summary":"Reconcile bank line","description":"Match an imported bank transaction to an existing sales invoice, supplier bill, or GL journal.","tags":["Banking"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconcileTransactionRequest"},"example":{"transaction_id":"tx_bank_994108","matched_invoice_id":"inv_88192a01","match_type":"manual"}}}},"responses":{"200":{"description":"Transaction successfully reconciled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"transaction_id":{"type":"string"},"is_reconciled":{"type":"boolean","example":true},"matched_invoice_id":{"type":"string"},"reconciled_at":{"type":"string","format":"date-time"}}}}}}}}}}},"/reports/trial-balance":{"get":{"summary":"Get Trial Balance report","description":"Retrieve real-time double-entry trial balance ledger report.","tags":["Reports"],"parameters":[{"name":"as_of_date","in":"query","schema":{"type":"string","format":"date","example":"2026-08-18"}}],"responses":{"200":{"description":"Trial Balance summary","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/TrialBalanceReport"}}}}}}}}},"/reports/profit-loss":{"get":{"summary":"Get Profit & Loss statement","description":"Generate Income Statement (P&L) with revenue, COGS, gross margin, and operating expenses.","tags":["Reports"],"parameters":[{"name":"from_date","in":"query","schema":{"type":"string","format":"date","example":"2026-01-01"}},{"name":"to_date","in":"query","schema":{"type":"string","format":"date","example":"2026-08-18"}}],"responses":{"200":{"description":"Profit and Loss statement","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/ProfitLossReport"}}}}}}}}},"/reports/balance-sheet":{"get":{"summary":"Get Balance Sheet","description":"Generate Balance Sheet statement covering Assets, Liabilities, and Shareholders Equity.","tags":["Reports"],"parameters":[{"name":"as_of_date","in":"query","schema":{"type":"string","format":"date","example":"2026-08-18"}}],"responses":{"200":{"description":"Balance Sheet statement","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/BalanceSheetReport"}}}}}}}}},"/reports/aging":{"get":{"summary":"Get AR/AP Aging report","description":"Retrieve accounts receivable or payable aged balances (Current, 1-30 days, 31-60 days, 61-90 days, 90+ days).","tags":["Reports"],"parameters":[{"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["receivable","payable"]}}],"responses":{"200":{"description":"Aging report","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/AgingReport"}}}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"UrusHQ Live or Sandbox API Key (e.g. urus_live_... / urus_test_...)"},"apiSecret":{"type":"apiKey","in":"header","name":"X-API-Secret","description":"UrusHQ API Secret associated with the API Key"}},"schemas":{"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer","example":1},"limit":{"type":"integer","example":20},"total":{"type":"integer","example":142},"total_pages":{"type":"integer","example":8}}},"Invoice":{"type":"object","properties":{"id":{"type":"string","example":"inv_88192a01"},"invoice_number":{"type":"string","example":"INV-2026-0881"},"status":{"type":"string","enum":["draft","submitted","validated","paid","overdue","cancelled"],"example":"validated"},"issue_date":{"type":"string","format":"date","example":"2026-08-18"},"due_date":{"type":"string","format":"date","example":"2026-09-17"},"currency":{"type":"string","example":"MYR"},"subtotal_cents":{"type":"integer","example":1000000},"sst_rate_pct":{"type":"number","example":8},"sst_amount_cents":{"type":"integer","example":80000},"total_amount_cents":{"type":"integer","example":1080000},"paid_amount_cents":{"type":"integer","example":0},"balance_cents":{"type":"integer","example":1080000},"contact":{"$ref":"#/components/schemas/Contact"},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceLineItem"}},"myinvois":{"type":"object","nullable":true,"properties":{"uuid":{"type":"string","example":"LHDN-9F8A-77C2-4E10-B29A"},"submission_uid":{"type":"string","example":"SUB-20260818-8819"},"status":{"type":"string","example":"Valid"},"validation_date_time":{"type":"string","example":"2026-08-18T10:14:02Z"},"qr_code_url":{"type":"string","example":"https://myinvois.hasil.gov.my/verify/LHDN-9F8A-77C2-4E10-B29A"}}},"created_at":{"type":"string","format":"date-time","example":"2026-08-18T08:00:00Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-08-18T08:15:00Z"}}},"InvoiceLineItem":{"type":"object","properties":{"id":{"type":"string","example":"line_01828"},"description":{"type":"string","example":"Industrial Middleware API Gateway License"},"product_id":{"type":"string","nullable":true,"example":"prod_9012384"},"quantity":{"type":"number","example":1},"unit_price_cents":{"type":"integer","example":1000000},"tax_code":{"type":"string","example":"SST_8"},"tax_rate":{"type":"number","example":0.08},"tax_amount_cents":{"type":"integer","example":80000},"line_total_cents":{"type":"integer","example":1080000},"classification_code":{"type":"string","example":"022"}}},"CreateInvoiceRequest":{"type":"object","required":["invoice_number","issue_date","contact_id","line_items"],"properties":{"invoice_number":{"type":"string","example":"INV-2026-0881"},"issue_date":{"type":"string","format":"date","example":"2026-08-18"},"due_date":{"type":"string","format":"date","example":"2026-09-17"},"contact_id":{"type":"string","example":"ct_9a8f2940bc2"},"currency":{"type":"string","default":"MYR"},"payment_terms_days":{"type":"integer","default":30},"notes":{"type":"string"},"line_items":{"type":"array","items":{"type":"object","required":["description","quantity","unit_price_cents"],"properties":{"description":{"type":"string"},"product_id":{"type":"string"},"quantity":{"type":"number","minimum":0.01},"unit_price_cents":{"type":"integer","minimum":0},"tax_code":{"type":"string","default":"SST_8"},"tax_rate":{"type":"number","default":0.08},"classification_code":{"type":"string","default":"022"}}}}}},"UpdateInvoiceRequest":{"type":"object","properties":{"due_date":{"type":"string","format":"date"},"notes":{"type":"string"},"payment_terms_days":{"type":"integer"}}},"MyInvoisSubmissionResult":{"type":"object","properties":{"invoice_id":{"type":"string","example":"inv_88192a01"},"lhdn_uuid":{"type":"string","example":"LHDN-9F8A-77C2-4E10-B29A"},"status":{"type":"string","example":"Valid"},"validation_timestamp":{"type":"string","example":"2026-08-18T10:14:02Z"},"qr_code_url":{"type":"string","example":"https://myinvois.hasil.gov.my/verify/LHDN-9F8A-77C2-4E10-B29A"},"digital_signature_algorithm":{"type":"string","example":"RSA-SHA256-XAdES"}}},"Contact":{"type":"object","properties":{"id":{"type":"string","example":"ct_9a8f2940bc2"},"name":{"type":"string","example":"Petronas Dagangan Berhad"},"type":{"type":"string","enum":["customer","supplier","both"],"example":"customer"},"email":{"type":"string","format":"email","example":"procurement@petronas.com.my"},"phone":{"type":"string","example":"+60320515000"},"tin":{"type":"string","example":"C20589876543"},"brn":{"type":"string","example":"198901004512"},"sst_no":{"type":"string","example":"W10-1808-32000045"},"address_line1":{"type":"string","example":"Tower 1, PETRONAS Twin Towers"},"address_line2":{"type":"string","example":"Kuala Lumpur City Centre"},"city":{"type":"string","example":"Kuala Lumpur"},"state":{"type":"string","example":"Wilayah Persekutuan Kuala Lumpur"},"postcode":{"type":"string","example":"50088"},"country":{"type":"string","example":"Malaysia"},"outstanding_cents":{"type":"integer","example":1080000},"credit_limit_cents":{"type":"integer","example":50000000},"payment_terms_days":{"type":"integer","example":30},"is_active":{"type":"boolean","example":true}}},"CreateContactRequest":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string","example":"Petronas Dagangan Berhad"},"type":{"type":"string","enum":["customer","supplier","both"]},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"tin":{"type":"string","example":"C20589876543"},"brn":{"type":"string","example":"198901004512"},"sst_no":{"type":"string","example":"W10-1808-32000045"},"address_line1":{"type":"string"},"address_line2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postcode":{"type":"string"},"country":{"type":"string","default":"Malaysia"},"payment_terms_days":{"type":"integer","default":30},"credit_limit_cents":{"type":"integer"}}},"UpdateContactRequest":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"tin":{"type":"string"},"brn":{"type":"string"},"sst_no":{"type":"string"},"payment_terms_days":{"type":"integer"}}},"Product":{"type":"object","properties":{"id":{"type":"string","example":"prod_9012384"},"name":{"type":"string","example":"Enterprise ERP LHDN Sync Module"},"sku":{"type":"string","example":"MOD-LHDN-ENT"},"description":{"type":"string","example":"Real-time middleware sync agent with MyInvois API integration."},"type":{"type":"string","enum":["product","service"],"example":"service"},"unit":{"type":"string","example":"license"},"selling_price_cents":{"type":"integer","example":1200000},"cost_price_cents":{"type":"integer","example":300000},"tax_code":{"type":"string","example":"SST_8"},"msic_code":{"type":"string","example":"62010"},"classification_code":{"type":"string","example":"022"},"track_inventory":{"type":"boolean","example":false},"is_active":{"type":"boolean","example":true}}},"CreateProductRequest":{"type":"object","required":["name","selling_price_cents","type"],"properties":{"name":{"type":"string"},"sku":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["product","service"]},"unit":{"type":"string"},"selling_price_cents":{"type":"integer"},"cost_price_cents":{"type":"integer"},"tax_code":{"type":"string","default":"SST_8"},"msic_code":{"type":"string","example":"62010"},"classification_code":{"type":"string","example":"022"},"track_inventory":{"type":"boolean","default":false}}},"Bill":{"type":"object","properties":{"id":{"type":"string","example":"bill_091823"},"bill_number":{"type":"string","example":"BILL-AWS-202608"},"supplier_id":{"type":"string","example":"ct_supplier_aws89"},"status":{"type":"string","enum":["draft","approved","paid","overdue"],"example":"approved"},"issue_date":{"type":"string","format":"date","example":"2026-08-01"},"due_date":{"type":"string","format":"date","example":"2026-08-31"},"currency":{"type":"string","example":"MYR"},"subtotal_cents":{"type":"integer","example":345000},"tax_cents":{"type":"integer","example":27600},"total_cents":{"type":"integer","example":372600},"created_at":{"type":"string","format":"date-time"}}},"CreateBillRequest":{"type":"object","required":["bill_number","supplier_id","issue_date","due_date","line_items"],"properties":{"bill_number":{"type":"string"},"supplier_id":{"type":"string"},"issue_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"currency":{"type":"string","default":"MYR"},"line_items":{"type":"array","items":{"type":"object","required":["description","quantity","unit_price_cents"],"properties":{"description":{"type":"string"},"quantity":{"type":"number"},"unit_price_cents":{"type":"integer"},"tax_code":{"type":"string"},"tax_amount_cents":{"type":"integer"},"amount_cents":{"type":"integer"}}}}}},"Payment":{"type":"object","properties":{"id":{"type":"string","example":"pay_994102"},"invoice_id":{"type":"string","nullable":true,"example":"inv_88192a01"},"bill_id":{"type":"string","nullable":true},"amount_cents":{"type":"integer","example":1080000},"currency":{"type":"string","example":"MYR"},"payment_date":{"type":"string","format":"date","example":"2026-08-18"},"payment_method":{"type":"string","example":"duitnow"},"reference_number":{"type":"string","example":"DN-20260818-MBB-991204"},"reconciliation_status":{"type":"string","example":"reconciled"},"created_at":{"type":"string","format":"date-time"}}},"RecordPaymentRequest":{"type":"object","required":["amount_cents","payment_date","payment_method"],"properties":{"invoice_id":{"type":"string"},"bill_id":{"type":"string"},"amount_cents":{"type":"integer","minimum":1},"payment_date":{"type":"string","format":"date"},"payment_method":{"type":"string","enum":["duitnow","fpx","bank_transfer","cheque","card"]},"reference_number":{"type":"string"},"bank_account_id":{"type":"string"},"notes":{"type":"string"}}},"Employee":{"type":"object","properties":{"id":{"type":"string","example":"emp_0042"},"employee_no":{"type":"string","example":"EMP-0042"},"official_full_name":{"type":"string","example":"Muhammad Faris bin Zainal"},"nric":{"type":"string","example":"940512-10-5843"},"nationality":{"type":"string","example":"Malaysian"},"is_foreign_worker":{"type":"boolean","example":false},"status":{"type":"string","example":"active"},"hired_at":{"type":"string","format":"date","example":"2025-01-15"},"basic_salary_cents":{"type":"integer","example":650000},"epf_no":{"type":"string","example":"20938472"},"socso_no":{"type":"string","example":"940512105843"},"tax_no":{"type":"string","example":"SG29384710020"}}},"CreateEmployeeRequest":{"type":"object","required":["employee_no","official_full_name","nationality","basic_salary_cents"],"properties":{"employee_no":{"type":"string"},"official_full_name":{"type":"string"},"nric":{"type":"string"},"passport":{"type":"string"},"nationality":{"type":"string","default":"Malaysian"},"is_foreign_worker":{"type":"boolean","default":false},"gender":{"type":"string","enum":["male","female"]},"marital_status":{"type":"string","enum":["single","married","divorced"]},"hired_at":{"type":"string","format":"date"},"basic_salary_cents":{"type":"integer","minimum":150000},"epf_no":{"type":"string"},"socso_no":{"type":"string"},"tax_no":{"type":"string"},"bank_name":{"type":"string","example":"Maybank"},"bank_account_no":{"type":"string","example":"514012948192"}}},"PayrollRun":{"type":"object","properties":{"id":{"type":"string","example":"pr_2026_08"},"period":{"type":"string","example":"2026-08"},"status":{"type":"string","enum":["draft","computed","finalized"],"example":"finalized"},"employee_count":{"type":"integer","example":28},"gross_cents":{"type":"integer","example":18200000},"net_cents":{"type":"integer","example":15150000},"epf_employee_cents":{"type":"integer","example":2002000},"epf_employer_cents":{"type":"integer","example":2366000},"socso_employee_cents":{"type":"integer","example":91000},"socso_employer_cents":{"type":"integer","example":318500},"eis_employee_cents":{"type":"integer","example":36400},"eis_employer_cents":{"type":"integer","example":36400},"pcb_tax_cents":{"type":"integer","example":920600},"finalized_at":{"type":"string","format":"date-time","nullable":true}}},"FinalizePayrollResponse":{"type":"object","properties":{"payroll_run_id":{"type":"string","example":"pr_2026_08"},"status":{"type":"string","example":"finalized"},"finalized_at":{"type":"string","format":"date-time"},"bank_files":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","example":"maybank_autopay_mas"},"filename":{"type":"string","example":"MBB_AUTOPAY_202608.txt"},"download_url":{"type":"string","example":"https://api.urushq.my/v1/payroll/runs/pr_2026_08/bank-files/mbb"}}}},"statutory_files":{"type":"array","items":{"type":"object","properties":{"authority":{"type":"string","example":"KWSP_EPF"},"form_name":{"type":"string","example":"Borang A"},"download_url":{"type":"string","example":"https://api.urushq.my/v1/payroll/runs/pr_2026_08/statutory/epf"}}}}}},"BankAccount":{"type":"object","properties":{"id":{"type":"string","example":"bank_mbb_01"},"name":{"type":"string","example":"Maybank Corporate Main Current Account"},"bank_name":{"type":"string","example":"Malayan Banking Berhad (Maybank)"},"bank_account_no":{"type":"string","example":"514012998877"},"swift_code":{"type":"string","example":"MBBEMYKL"},"currency":{"type":"string","example":"MYR"},"balance_cents":{"type":"integer","example":48920500},"is_active":{"type":"boolean","example":true},"last_synced_at":{"type":"string","format":"date-time","example":"2026-08-18T09:30:00Z"}}},"BankTransaction":{"type":"object","properties":{"id":{"type":"string","example":"tx_bank_994108"},"bank_account_id":{"type":"string","example":"bank_mbb_01"},"transaction_date":{"type":"string","format":"date","example":"2026-08-18"},"description":{"type":"string","example":"DUITNOW CR PETRONAS DAGANGAN BHD INV-2026-0881"},"reference":{"type":"string","example":"DN-20260818-MBB-991204"},"amount_cents":{"type":"integer","example":1080000},"type":{"type":"string","enum":["credit","debit"],"example":"credit"},"is_reconciled":{"type":"boolean","example":false},"matched_invoice_id":{"type":"string","nullable":true},"matched_bill_id":{"type":"string","nullable":true}}},"ReconcileTransactionRequest":{"type":"object","required":["transaction_id"],"properties":{"transaction_id":{"type":"string"},"matched_invoice_id":{"type":"string"},"matched_bill_id":{"type":"string"},"match_type":{"type":"string","enum":["auto","manual","suggested"],"default":"manual"}}},"TrialBalanceReport":{"type":"object","properties":{"as_of_date":{"type":"string","format":"date","example":"2026-08-18"},"currency":{"type":"string","example":"MYR"},"total_debit_cents":{"type":"integer","example":258900000},"total_credit_cents":{"type":"integer","example":258900000},"is_balanced":{"type":"boolean","example":true},"accounts":{"type":"array","items":{"type":"object","properties":{"account_code":{"type":"string","example":"1000"},"account_name":{"type":"string","example":"Maybank Operating Account"},"account_type":{"type":"string","example":"asset"},"debit_cents":{"type":"integer","example":48920500},"credit_cents":{"type":"integer","example":0}}}}}},"ProfitLossReport":{"type":"object","properties":{"from_date":{"type":"string","format":"date","example":"2026-01-01"},"to_date":{"type":"string","format":"date","example":"2026-08-18"},"currency":{"type":"string","example":"MYR"},"revenue_cents":{"type":"integer","example":145000000},"cost_of_sales_cents":{"type":"integer","example":42000000},"gross_profit_cents":{"type":"integer","example":103000000},"operating_expenses_cents":{"type":"integer","example":51200000},"net_profit_before_tax_cents":{"type":"integer","example":51800000}}},"BalanceSheetReport":{"type":"object","properties":{"as_of_date":{"type":"string","format":"date","example":"2026-08-18"},"currency":{"type":"string","example":"MYR"},"total_assets_cents":{"type":"integer","example":198000000},"total_liabilities_cents":{"type":"integer","example":62000000},"total_equity_cents":{"type":"integer","example":136000000},"is_balanced":{"type":"boolean","example":true}}},"AgingReport":{"type":"object","properties":{"report_type":{"type":"string","example":"receivable"},"as_of_date":{"type":"string","format":"date","example":"2026-08-18"},"total_outstanding_cents":{"type":"integer","example":28450000},"current_cents":{"type":"integer","example":18200000},"days_1_30_cents":{"type":"integer","example":6450000},"days_31_60_cents":{"type":"integer","example":2800000},"days_61_90_cents":{"type":"integer","example":700000},"days_90_plus_cents":{"type":"integer","example":300000}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Validation error: Missing required parameter"},"code":{"type":"string","example":"INVALID_REQUEST"},"details":{"type":"object","nullable":true}}}},"responses":{"UnauthorizedError":{"description":"Authentication failed: Missing or invalid API key / secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Unauthorized: Missing or invalid X-API-Key header.","code":"UNAUTHORIZED"}}}},"NotFoundError":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Resource not found with the specified identifier.","code":"NOT_FOUND"}}}},"BadRequestError":{"description":"Malformed request body or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Malformed JSON payload or missing mandatory parameters.","code":"BAD_REQUEST"}}}},"ValidationError":{"description":"Business validation failed (e.g. LHDN MyInvois pre-validation rejection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Pre-validation failed: Buyer TIN C20589876543 format mismatch.","code":"LHDN_VALIDATION_ERROR"}}}}}}}