{"openapi":"3.0.3","info":{"title":"Invoice SaaS API","description":"AI-powered invoice generation system with multi-language support, PDF templates, and WhatsApp integration.\n\n## Features\n- 🤖 AI-powered natural language invoice parsing (English & Cantonese)\n- 📄 6 professional PDF templates \n- 🌐 Multi-language support (English/Chinese)\n- 💱 Multi-currency support\n- 🏢 Company-level settings and branding\n- 📱 WhatsApp Business integration\n- 🧪 Comprehensive testing suite\n","version":"1.0.0","contact":{"name":"Invoice SaaS Support","email":"support@invoicesaas.com"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://www.invochat.app/api","description":"Current server"},{"url":"http://localhost:3000/api","description":"Development server"},{"url":"http://localhost:3002/api","description":"Alternative development server"}],"security":[{"sessionAuth":[]}],"tags":[{"name":"Companies","description":"Company management and settings"},{"name":"Invoices","description":"Invoice creation and management"},{"name":"AI Generation","description":"AI-powered invoice generation"},{"name":"PDF","description":"PDF generation and templates"},{"name":"Recipients","description":"Recipient management"},{"name":"WhatsApp","description":"WhatsApp Business integration"},{"name":"Testing","description":"Admin testing endpoints"}],"paths":{"/companies":{"get":{"tags":["Companies"],"summary":"List companies","description":"Get all companies for the authenticated user","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":100}}],"responses":{"200":{"description":"List of companies","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}},"post":{"tags":["Companies"],"summary":"Create company","description":"Create a new company with settings and branding","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyCreate"}}}},"responses":{"201":{"description":"Company created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"company":{"$ref":"#/components/schemas/Company"}}}}}}}}},"/companies/{id}":{"get":{"tags":["Companies"],"summary":"Get company","description":"Get a specific company by ID","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"mongodb-objectid"}}],"responses":{"200":{"description":"Company details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"tags":["Companies"],"summary":"Update company","description":"Update company settings and branding","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"mongodb-objectid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyUpdate"}}}},"responses":{"200":{"description":"Company updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"company":{"$ref":"#/components/schemas/Company"}}}}}}}},"delete":{"tags":["Companies"],"summary":"Delete company","description":"Delete a company and all associated data","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"mongodb-objectid"}}],"responses":{"200":{"description":"Company deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}}}}},"/invoices":{"get":{"tags":["Invoices"],"summary":"List invoices","description":"Get all invoices for the authenticated user","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":10}},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","sent","paid","overdue"]}},{"name":"companyId","in":"query","schema":{"type":"string","format":"mongodb-objectid"}}],"responses":{"200":{"description":"List of invoices","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}},"post":{"tags":["Invoices"],"summary":"Create invoice manually","description":"Create a new invoice with manual input","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceCreate"}}}},"responses":{"201":{"description":"Invoice created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"invoice":{"$ref":"#/components/schemas/Invoice"}}}}}}}}},"/invoices/{id}":{"get":{"tags":["Invoices"],"summary":"Get invoice","description":"Get a specific invoice by ID","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"mongodb-objectid"}}],"responses":{"200":{"description":"Invoice details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}}}},"put":{"tags":["Invoices"],"summary":"Update invoice","description":"Update an existing invoice","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"mongodb-objectid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceUpdate"}}}},"responses":{"200":{"description":"Invoice updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"invoice":{"$ref":"#/components/schemas/Invoice"}}}}}}}},"delete":{"tags":["Invoices"],"summary":"Delete invoice","description":"Delete an invoice","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"mongodb-objectid"}}],"responses":{"200":{"description":"Invoice deleted successfully"}}}},"/invoices/generate":{"post":{"tags":["AI Generation"],"summary":"Generate invoice with AI","description":"Generate an invoice from natural language input using AI parsing.\nSupports English and Cantonese input.\n\n**Examples:**\n- English: \"Bill ABC Company for website development $2000 and logo design $800\"\n- Cantonese: \"開發票俾張三，網站設計2000蚊，標誌設計1000蚊\"\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text","companyId"],"properties":{"text":{"type":"string","description":"Natural language invoice description","minLength":1,"maxLength":1000,"example":"Bill ABC Company for website development $2000 and logo design $800, due in 30 days"},"companyId":{"type":"string","format":"mongodb-objectid","description":"Company ID for invoice generation"},"useAI":{"type":"boolean","default":true,"description":"Whether to use AI parsing (false for fallback regex parsing)"}}}}}},"responses":{"201":{"description":"Invoice generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"invoice":{"$ref":"#/components/schemas/Invoice"},"originalText":{"type":"string","example":"Bill ABC Company for website development $2000"},"parseMethod":{"type":"string","enum":["openai","fallback"],"example":"openai"}}}}}},"400":{"description":"Needs clarification or parsing failed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"needsClarification":{"type":"array","items":{"type":"string"},"example":["recipient","amount"]},"partialData":{"type":"object","description":"Partially parsed data"},"error":{"type":"string","example":"Could not determine recipient information"}}}}}}}}},"/invoices/{id}/pdf":{"get":{"tags":["PDF"],"summary":"Generate PDF","description":"Generate PDF for an invoice using specified template","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"mongodb-objectid"}},{"name":"template","in":"query","schema":{"type":"string","enum":["classic-hk","modern-minimal","corporate-blue","minimalist-gray","elegant-serif","tech-modern"],"default":"classic-hk"}},{"name":"download","in":"query","schema":{"type":"boolean","default":false},"description":"Whether to force download or display inline"}],"responses":{"200":{"description":"PDF generated successfully","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}},"headers":{"Content-Disposition":{"schema":{"type":"string","example":"attachment; filename=invoice-INV-2024-001.pdf"}}}}}}},"/recipients":{"get":{"tags":["Recipients"],"summary":"List recipients","description":"Get saved recipients for autocomplete","parameters":[{"name":"search","in":"query","schema":{"type":"string"},"description":"Search term for recipient name or email"}],"responses":{"200":{"description":"List of recipients","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Recipient"}}}}}}}}}},"/webhooks/whatsapp":{"get":{"tags":["WhatsApp"],"summary":"WhatsApp webhook verification","description":"Verify WhatsApp webhook endpoint","parameters":[{"name":"hub.mode","in":"query","required":true,"schema":{"type":"string"}},{"name":"hub.challenge","in":"query","required":true,"schema":{"type":"string"}},{"name":"hub.verify_token","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook verified","content":{"text/plain":{"schema":{"type":"string"}}}}}},"post":{"tags":["WhatsApp"],"summary":"WhatsApp webhook","description":"Receive WhatsApp messages for invoice generation","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhatsAppWebhook"}}}},"responses":{"200":{"description":"Message processed successfully"}}}},"/test/ai-parsing":{"post":{"tags":["Testing"],"summary":"Test AI parsing","description":"Test AI invoice parsing functionality","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","example":"Bill ABC Company for consulting $1500"},"locale":{"type":"string","default":"en-US","example":"zh-HK"}}}}}},"responses":{"200":{"description":"Parsing test results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestResult"}}}}}}},"/test/compare-generation":{"post":{"tags":["Testing"],"summary":"Compare AI vs Manual generation","description":"Test AI generation vs manual creation for accuracy","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["aiInput","manualInput"],"properties":{"aiInput":{"type":"string","example":"Bill ABC Company for consulting $1500"},"manualInput":{"type":"object","properties":{"recipient":{"type":"object","properties":{"name":{"type":"string"}}},"items":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"quantity":{"type":"number"},"unitPrice":{"type":"number"}}}},"currency":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Comparison test results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestResult"}}}}}}},"/test/database":{"get":{"tags":["Testing"],"summary":"Test database connectivity","description":"Test database connection and basic operations","responses":{"200":{"description":"Database test results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestResult"}}}}}}},"/test/pdf-template":{"post":{"tags":["Testing"],"summary":"Test PDF template","description":"Test PDF generation for specific template","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["template"],"properties":{"template":{"type":"string","enum":["classic-hk","modern-minimal","corporate-blue","minimalist-gray","elegant-serif","tech-modern"]},"testData":{"type":"object","description":"Optional test invoice data"}}}}}},"responses":{"200":{"description":"PDF template test results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestResult"}}}}}}},"/test/i18n":{"post":{"tags":["Testing"],"summary":"Test internationalization","description":"Test language switching and localization","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["testType"],"properties":{"testType":{"type":"string","enum":["language-switch","translation-completeness","currency-format","date-format"]},"locales":{"type":"array","items":{"type":"string"},"default":["en","zh-HK"]}}}}}},"responses":{"200":{"description":"i18n test results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestResult"}}}}}}}},"components":{"securitySchemes":{"sessionAuth":{"type":"http","scheme":"bearer","description":"Session-based authentication using NextAuth.js"}},"schemas":{"Company":{"type":"object","properties":{"_id":{"type":"string","format":"mongodb-objectid","example":"507f1f77bcf86cd799439011"},"userId":{"type":"string","description":"Owner user ID"},"name":{"type":"string","example":"ABC Tech Limited"},"address":{"type":"string","example":"123 Business Street\nHong Kong"},"logoBase64":{"type":"string","description":"Base64 encoded company logo","nullable":true},"businessRegistrationNo":{"type":"string","example":"12345678","nullable":true},"bankAccount":{"type":"string","example":"HSBC: 123-456789-001","nullable":true},"defaultCurrency":{"type":"string","enum":["USD","HKD","EUR","GBP","CNY"],"default":"HKD"},"locale":{"type":"string","enum":["en-US","zh-HK"],"default":"zh-HK"},"defaultTemplate":{"type":"string","enum":["classic-hk","modern-minimal","corporate-blue","minimalist-gray","elegant-serif","tech-modern"],"default":"classic-hk"},"invoiceNumberPrefix":{"type":"string","default":"INV","example":"INV"},"defaultPaymentTerms":{"type":"string","example":"Payment due within 30 days","nullable":true},"footerText":{"type":"string","example":"Thank you for your business!","nullable":true},"adminWhatsAppNumbers":{"type":"array","items":{"type":"string","pattern":"^\\+\\d{10,15}$"},"example":["+85212345678"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"CompanyCreate":{"type":"object","required":["name","address"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200,"example":"ABC Tech Limited"},"address":{"type":"string","minLength":1,"maxLength":500,"example":"123 Business Street\nHong Kong"},"logoBase64":{"type":"string","description":"Base64 encoded logo (max 100KB)"},"businessRegistrationNo":{"type":"string","maxLength":50},"bankAccount":{"type":"string","maxLength":200},"defaultCurrency":{"type":"string","enum":["USD","HKD","EUR","GBP","CNY"],"default":"HKD"},"locale":{"type":"string","enum":["en-US","zh-HK"],"default":"zh-HK"},"defaultTemplate":{"type":"string","enum":["classic-hk","modern-minimal","corporate-blue","minimalist-gray","elegant-serif","tech-modern"],"default":"classic-hk"},"invoiceNumberPrefix":{"type":"string","maxLength":10,"default":"INV"},"defaultPaymentTerms":{"type":"string","maxLength":200},"footerText":{"type":"string","maxLength":500},"adminWhatsAppNumbers":{"type":"array","items":{"type":"string","pattern":"^\\+\\d{10,15}$"}}}},"CompanyUpdate":{"allOf":[{"$ref":"#/components/schemas/CompanyCreate"},{"type":"object","description":"All fields are optional for updates"}]},"Invoice":{"type":"object","properties":{"_id":{"type":"string","format":"mongodb-objectid"},"companyId":{"type":"string","format":"mongodb-objectid"},"number":{"type":"string","example":"INV-2024-001"},"recipient":{"$ref":"#/components/schemas/Recipient"},"items":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceItem"}},"currency":{"type":"string","enum":["USD","HKD","EUR","GBP","CNY"]},"subtotalMinorUnits":{"type":"integer","description":"Subtotal in minor currency units (cents)","example":280000},"taxAmountMinorUnits":{"type":"integer","description":"Tax amount in minor currency units","example":28000},"totalMinorUnits":{"type":"integer","description":"Total amount in minor currency units","example":308000},"taxSettings":{"$ref":"#/components/schemas/TaxSettings"},"issueDate":{"type":"string","format":"date-time"},"dueDate":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["draft","sent","paid","overdue"],"default":"draft"},"createdVia":{"type":"string","enum":["whatsapp","web","ai","manual","api"],"default":"web"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"InvoiceCreate":{"type":"object","required":["companyId","recipient","items","currency","dueDate"],"properties":{"companyId":{"type":"string","format":"mongodb-objectid"},"recipient":{"$ref":"#/components/schemas/RecipientInput"},"items":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/InvoiceItemInput"}},"currency":{"type":"string","enum":["USD","HKD","EUR","GBP","CNY"]},"taxSettings":{"$ref":"#/components/schemas/TaxSettings"},"issueDate":{"type":"string","format":"date-time","description":"Optional, defaults to current date"},"dueDate":{"type":"string","description":"Due date (any format, will be parsed)"},"notes":{"type":"string","maxLength":1000},"createdVia":{"type":"string","enum":["whatsapp","web","ai","manual","api"],"default":"web"}}},"InvoiceUpdate":{"allOf":[{"$ref":"#/components/schemas/InvoiceCreate"},{"type":"object","description":"All fields are optional for updates","properties":{"status":{"type":"string","enum":["draft","sent","paid","overdue"]}}}]},"Recipient":{"type":"object","properties":{"name":{"type":"string","example":"John Smith"},"email":{"type":"string","format":"email","example":"john@example.com","nullable":true},"phone":{"type":"string","example":"+85212345678","nullable":true},"address":{"type":"string","example":"123 Customer Street\nHong Kong","nullable":true},"company":{"type":"string","example":"Customer Corp","nullable":true}}},"RecipientInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"email":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","maxLength":20,"nullable":true},"address":{"type":"string","maxLength":500,"nullable":true},"company":{"type":"string","maxLength":200,"nullable":true}}},"InvoiceItem":{"type":"object","properties":{"description":{"type":"string","example":"Website Development"},"quantity":{"type":"number","minimum":0.01,"example":1},"unitPrice":{"type":"number","minimum":0,"example":2000},"amount":{"type":"number","minimum":0,"example":2000,"description":"Calculated as quantity * unitPrice"}}},"InvoiceItemInput":{"type":"object","required":["description","quantity","unitPrice"],"properties":{"description":{"type":"string","minLength":1,"maxLength":500},"quantity":{"type":"number","minimum":0.01},"unitPrice":{"type":"number","minimum":0}}},"TaxSettings":{"type":"object","properties":{"enabled":{"type":"boolean","default":false},"name":{"type":"string","example":"VAT","default":"Tax"},"rate":{"type":"number","minimum":0,"maximum":100,"example":10},"taxNumber":{"type":"string","example":"TAX123456","nullable":true}}},"WhatsAppWebhook":{"type":"object","properties":{"object":{"type":"string","example":"whatsapp_business_account"},"entry":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"changes":{"type":"array","items":{"type":"object","properties":{"value":{"type":"object","properties":{"messaging_product":{"type":"string","example":"whatsapp"},"metadata":{"type":"object"},"contacts":{"type":"array"},"messages":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"id":{"type":"string"},"timestamp":{"type":"string"},"text":{"type":"object","properties":{"body":{"type":"string"}}},"type":{"type":"string"}}}}}}}}}}}}}},"TestResult":{"type":"object","properties":{"success":{"type":"boolean"},"duration":{"type":"integer","description":"Test execution time in milliseconds"},"details":{"type":"object","description":"Test-specific result details"},"error":{"type":"string","nullable":true,"description":"Error message if test failed"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer","example":1},"limit":{"type":"integer","example":10},"total":{"type":"integer","example":100},"totalPages":{"type":"integer","example":10},"hasNext":{"type":"boolean","example":true},"hasPrev":{"type":"boolean","example":false}}},"Error":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found"}}}},"responses":{"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}