> For the complete documentation index, see [llms.txt](https://qbits-organization.gitbook.io/buildwise-doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://qbits-organization.gitbook.io/buildwise-doc/accounting/transaction/business-document-document-flow/invoice.md). # Invoice ### Create Invoice Creates a new invoice for the specified organisation. The authenticated user must have the ACCOUNTANT, OWNER, or PROJECT\_MANAGER role in the project. #### Endpoint ``` POST /api/v1/org-accounting/{organisationId}/doc-invoices ``` #### Path Parameters * `organisationId` (UUID) - The organisation identifier where the invoice will be created #### Request Body ```json { "projectId": "123e4567-e89b-12d3-a456-426614174000", "clientId": "987fcdeb-51a2-43d1-9c4f-123456789abc", "invoiceType": "STANDARD", "dateOfIssue": "2025-06-11", "dueDate": "2025-07-11", "reference": "Project milestone 1", "discountAmount": 500.00, "taxAmount": 1200.00, "currency": "USD", "lineItems": [ { "description": "Construction materials", "rate": 150.00, "quantity": 10, "taxType": "VAT", "taxRate": 18.0, "unitOfMeasure": "units", "lineOrder": 1 }, { "description": "Labor costs", "rate": 50.00, "quantity": 40, "taxType": "VAT", "taxRate": 18.0, "unitOfMeasure": "hours", "lineOrder": 2 } ] } ``` #### Validation Rules * `projectId`: Required, must exist and belong to the organisation * `clientId`: Required, must exist and belong to the organisation * `invoiceType`: Required * `dateOfIssue`: Required * `dueDate`: Required * `lineItems`: Required, must contain at least one item * The authenticated user must have ACCOUNTANT, OWNER, or PROJECT\_MANAGER role in the project * User must be an active member of the organisation #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Invoice created successfully", "action_time": "2025-06-11T14:30:15.123456", "data": { "invoiceId": "456e7890-e89b-12d3-a456-426614174111", "invoiceNumber": "PROJ0001-25-0001", "status": "DRAFT", "totalAmount": 4200.00, "projectName": "Downtown Office Complex", "lineItemCount": 2, "clientName": "ABC Construction Corp" } } ``` #### Error Responses * `404` - Organisation not found, project not found, client not found, or insufficient permissions * `403` - Access denied (insufficient role permissions) * `400` - Missing required fields or invalid data provided * `401` - Unauthorized (invalid token) * `500` - An unexpected error occurred while creating the invoice *** ### Preview Invoice Number Generates a preview of the next invoice number for a specific project and client combination without creating an invoice. #### Endpoint ``` POST /api/v1/org-accounting/{organisationId}/doc-invoices/preview-invoice-number ``` #### Path Parameters * `organisationId` (UUID) - The organisation identifier #### Request Body ```json { "projectId": "123e4567-e89b-12d3-a456-426614174000", "clientId": "987fcdeb-51a2-43d1-9c4f-123456789abc" } ``` #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Invoice number preview generated successfully", "action_time": "2025-06-11T14:25:10.123456", "data": { "nextInvoiceNumber": "PROJ0001-25-0002", "organisationName": "BuildWise Construction Ltd", "projectName": "Downtown Office Complex", "clientName": "ABC Construction Corp", "projectCode": "PROJ0001" } } ``` #### Error Responses * `404` - Organisation not found, project not found, client not found, or insufficient permissions * `403` - Access denied (insufficient role permissions) * `401` - Unauthorized (invalid token) *** ### Get Invoice By ID Retrieves a specific invoice by its ID. The authenticated user must have ACCOUNTANT, OWNER, or PROJECT\_MANAGER role in the project. #### Endpoint ``` GET /api/v1/org-accounting/{organisationId}/doc-invoices/{invoiceId} ``` #### Path Parameters * `organisationId` (UUID) - The organisation identifier * `invoiceId` (UUID) - The invoice identifier #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Invoice retrieved successfully", "action_time": "2025-06-11T14:35:20.654321", "data": { "id": "456e7890-e89b-12d3-a456-426614174111", "invoiceNumber": "PROJ0001-25-0001", "projectId": "123e4567-e89b-12d3-a456-426614174000", "projectName": "Downtown Office Complex", "clientId": "987fcdeb-51a2-43d1-9c4f-123456789abc", "clientName": "ABC Construction Corp", "invoiceType": "STANDARD", "invoiceStatus": "DRAFT", "dateOfIssue": "2025-06-11", "dueDate": "2025-07-11", "reference": "Project milestone 1", "organisationId": "789e0123-e89b-12d3-a456-426614174222", "organisationName": "BuildWise Construction Ltd", "subtotal": 3500.00, "discountAmount": 500.00, "taxAmount": 1200.00, "totalAmount": 4200.00, "amountPaid": 0.00, "creditApplied": 0.00, "amountDue": 4200.00, "currency": "USD", "createdAt": "2025-06-11T14:30:15.123456", "updatedAt": "2025-06-11T14:30:15.123456", "createdByUserName": "john.doe", "lineItems": [ { "id": "111e2222-e89b-12d3-a456-426614174333", "description": "Construction materials", "rate": 150.00, "quantity": 10, "lineTotal": 1500.00, "taxType": "VAT", "taxRate": 18.0, "taxAmount": 270.00, "unitOfMeasure": "units", "lineOrder": 1 }, { "id": "222e3333-e89b-12d3-a456-426614174444", "description": "Labor costs", "rate": 50.00, "quantity": 40, "lineTotal": 2000.00, "taxType": "VAT", "taxRate": 18.0, "taxAmount": 360.00, "unitOfMeasure": "hours", "lineOrder": 2 } ] } } ``` #### Error Responses * `404` - Invoice not found, organisation not found, or insufficient permissions * `403` - Access denied (insufficient role permissions) * `401` - Unauthorized (invalid token) *** ### Get Invoice By Number Retrieves a specific invoice by its invoice number. The authenticated user must have the ACCOUNTANT, OWNER, or PROJECT\_MANAGER role in the project. #### Endpoint ``` GET /api/v1/org-accounting/{organisationId}/doc-invoices/invoice-number/{invoiceNumber} ``` #### Path Parameters * `organisationId` (UUID) - The organisation identifier * `invoiceNumber` (String) - The invoice number (e.g., "PROJ0001-25-0001") #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Invoice retrieved successfully", "action_time": "2025-06-11T14:35:20.654321", "data": { "id": "456e7890-e89b-12d3-a456-426614174111", "invoiceNumber": "PROJ0001-25-0001", "projectId": "123e4567-e89b-12d3-a456-426614174000", "projectName": "Downtown Office Complex", "clientId": "987fcdeb-51a2-43d1-9c4f-123456789abc", "clientName": "ABC Construction Corp", "invoiceType": "STANDARD", "invoiceStatus": "DRAFT", "dateOfIssue": "2025-06-11", "dueDate": "2025-07-11", "reference": "Project milestone 1", "organisationId": "789e0123-e89b-12d3-a456-426614174222", "organisationName": "BuildWise Construction Ltd", "subtotal": 3500.00, "discountAmount": 500.00, "taxAmount": 1200.00, "totalAmount": 4200.00, "amountPaid": 0.00, "creditApplied": 0.00, "amountDue": 4200.00, "currency": "USD", "createdAt": "2025-06-11T14:30:15.123456", "updatedAt": "2025-06-11T14:30:15.123456", "createdByUserName": "john.doe", "lineItems": [ { "id": "111e2222-e89b-12d3-a456-426614174333", "description": "Construction materials", "rate": 150.00, "quantity": 10, "lineTotal": 1500.00, "taxType": "VAT", "taxRate": 18.0, "taxAmount": 270.00, "unitOfMeasure": "units", "lineOrder": 1 }, { "id": "222e3333-e89b-12d3-a456-426614174444", "description": "Labor costs", "rate": 50.00, "quantity": 40, "lineTotal": 2000.00, "taxType": "VAT", "taxRate": 18.0, "taxAmount": 360.00, "unitOfMeasure": "hours", "lineOrder": 2 } ] } } ``` #### Error Responses * `404` - Invoice not found, organisation not found, or insufficient permissions * `403` - Access denied (insufficient role permissions) * `401` - Unauthorized (invalid token) *** ### Get Project Invoices Retrieves all invoices for a specific project. The authenticated user must have the ACCOUNTANT, OWNER, or PROJECT\_MANAGER role in the project. #### Endpoint ``` GET /api/v1/org-accounting/{organisationId}/doc-invoices/project/{projectId} ``` #### Path Parameters * `organisationId` (UUID) - The organisation identifier * `projectId` (UUID) - The project identifier #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Project invoices retrieved successfully", "action_time": "2025-06-11T15:15:45.234567", "data": [ { "invoiceId": "456e7890-e89b-12d3-a456-426614174111", "invoiceNumber": "PROJ0001-25-0001", "status": "DRAFT", "totalAmount": 4200.00, "projectName": "Downtown Office Complex", "lineItemCount": 2, "clientName": "ABC Construction Corp" }, { "invoiceId": "567e8901-e89b-12d3-a456-426614174222", "invoiceNumber": "PROJ0001-25-0002", "status": "SENT", "totalAmount": 2850.00, "projectName": "Downtown Office Complex", "lineItemCount": 3, "clientName": "ABC Construction Corp" } ] } ``` #### Error Responses * `404` - Project not found, organisation not found, or insufficient permissions * `403` - Access denied (insufficient role permissions) * `401` - Unauthorized (invalid token) *** ### Get Client Invoices Retrieves all invoices for a specific client. The authenticated user must be an active member of the organisation. #### Endpoint ``` GET /api/v1/org-accounting/{organisationId}/doc-invoices/client/{clientId} ``` #### Path Parameters * `organisationId` (UUID) - The organisation identifier * `clientId` (UUID) - The client identifier #### Success Response ```json { "success": true, "httpStatus": "OK", "message": "Client invoices retrieved successfully", "action_time": "2025-06-11T15:20:30.345678", "data": [ { "invoiceId": "456e7890-e89b-12d3-a456-426614174111", "invoiceNumber": "PROJ0001-25-0001", "status": "DRAFT", "totalAmount": 4200.00, "projectName": "Downtown Office Complex", "lineItemCount": 2, "clientName": "ABC Construction Corp" }, { "invoiceId": "678e9012-e89b-12d3-a456-426614174333", "invoiceNumber": "PROJ0002-25-0001", "status": "APPROVED", "totalAmount": 7500.00, "projectName": "Residential Complex Phase 1", "lineItemCount": 4, "clientName": "ABC Construction Corp" } ] } ``` #### Error Responses * `404` - Client not found, organisation not found, or insufficient permissions * `401` - Unauthorized (invalid token) *** ### Authentication & Authorization #### General Rules * All endpoints require authentication via a JWT token * Users must be active members of the relevant organisation * Invoice creation and operations require specific project roles: * **ACCOUNTANT** - Full access to all invoice operations * **OWNER** - Full access to all invoice operations * **PROJECT\_MANAGER** - Full access to invoices for their projects * Client invoice retrieval requires any active membership (OWNER, ADMIN, MEMBER, ACCOUNTANT, PROJECT\_MANAGER) #### Common Error Responses All endpoints may return: * `401 Unauthorized` - Invalid or missing authentication token * `500 Internal Server Error` - Unexpected server error *** ### Response Format All successful responses follow this structure: ```json { "success": true, "httpStatus": "OK", "message": "Description of the operation", "action_time": "2025-06-11T15:45:30.123456", "data": { /* Response data or null */ } } ``` *** ### Additional Notes #### Invoice Numbering System Invoices use a structured numbering format: `[PROJECT-CODE]-[YEAR]-[CLIENT-SEQUENCE]` * **Project Code**: Format like PROJ0001, PROJ0002, etc. * **Year**: 2-digit format (25 for 2025) * **Client Sequence**: 4-digit sequential number per client (0001, 0002, etc.) * **Example**: PROJ0001-25-0001 #### Invoice Types Invoices can have different types, such as: * `STANDARD` * `MILESTONE` * `PROGRESS` * `FINAL` #### Invoice Status Flow Invoices progress through these statuses: * `DRAFT` - Initial creation state * `PENDING_APPROVAL` - Awaiting approval * `APPROVED` - Approved and ready to send * `SENT` - Sent to client with accounting entries created * `PAID` - Payment received * `OVERDUE` - Past due date * `CANCELLED` - Cancelled invoice #### Tax Calculations * Line items support individual tax rates and types * Tax amounts are calculated per line item * Total tax amount is sum of all line item taxes plus invoice-level tax * Supports various tax types (VAT, GST, etc.) #### Currency Support Invoices support multiple currencies with proper formatting and calculations. #### Line Item Structure Each invoice line item contains: * Description and quantity * Unit rate and total amount * Tax information (type, rate, amount) * Unit of measure * Display order #### Project Team Validation The system validates that users have appropriate roles within the project team before allowing invoice operations, ensuring proper access control at the project level.