initial commit

2026-04-09 20:36:10 -07:00
commit 4681b1a3c8
248 changed files with 97032 additions and 0 deletions
--- a/API_ENDPOINTS.md
+++ b/API_ENDPOINTS.md
@@ -0,0 +1,243 @@
+# Bank Transaction and Payment Recording Endpoints
+
+## Bank Transaction Import API
+
+### Endpoint: POST `/api/bank-transactions/import`
+
+Import multiple bank transactions in bulk.
+
+**Request Body:**
+```json
+{
+  "bankAccountId": "uuid-of-bank-account",
+  "transactions": [
+    {
+      "transactionDate": "2024-01-15",
+      "transactionType": "DEBIT",
+      "amount": 150.50,
+      "description": "Office Supplies Purchase",
+      "referenceNumber": "REF-001",
+      "oppositeParty": "Office Depot"
+    },
+    {
+      "transactionDate": "2024-01-16",
+      "transactionType": "CREDIT",
+      "amount": 2500.00,
+      "description": "Customer Payment - Acme Corp",
+      "referenceNumber": "INV-2024-001",
+      "oppositeParty": "Acme Corp"
+    }
+  ]
+}
+```
+
+**Response (201 Created):**
+```json
+{
+  "success": true,
+  "imported": 2,
+  "message": "Successfully imported 2 transaction(s)"
+}
+```
+
+**Notes:**
+- `transactionType` must be one of: `DEBIT`, `CREDIT`
+- `amount` must be a positive number
+- `referenceNumber` and `oppositeParty` are optional
+- The bank account must exist and belong to the organization
+
+---
+
+## CSV Parser API
+
+### Endpoint: POST `/api/bank-transactions/parse-csv`
+
+Parse a CSV file to extract transactions for preview before import.
+
+**Request:** Form Data with file upload
+```
+Content-Type: multipart/form-data
+
+file: <CSV file>
+```
+
+**Supported CSV Formats:**
+
+#### Format 1: Date, Description, Amount
+```csv
+Date,Description,Amount
+2024-01-15,Office Supplies,150.50
+2024-01-16,Client Payment,2500.00
+```
+
+#### Format 2: Date, Description, Debit, Credit
+```csv
+Date,Description,Debit,Credit
+2024-01-15,Office Supplies,150.50,0
+2024-01-16,Client Payment,0,2500.00
+```
+
+**Response (200 OK):**
+```json
+{
+  "success": true,
+  "count": 2,
+  "transactions": [
+    {
+      "transactionDate": "2024-01-15",
+      "description": "Office Supplies",
+      "transactionType": "DEBIT",
+      "amount": 150.50
+    },
+    {
+      "transactionDate": "2024-01-16",
+      "description": "Client Payment",
+      "transactionType": "CREDIT",
+      "amount": 2500.00
+    }
+  ],
+  "message": "Parsed 2 transaction(s) from CSV"
+}
+```
+
+**Error Response (400 Bad Request):**
+```json
+{
+  "error": "CSV must have 'Date' and 'Description' columns"
+}
+```
+
+---
+
+## Payment Recording API
+
+### Endpoint: POST `/api/payments`
+
+Record a payment against an invoice.
+
+**Request Body:**
+```json
+{
+  "paymentDate": "2024-01-20",
+  "paymentMethod": "ACH",
+  "paymentAmount": 1500.00,
+  "customerId": "uuid-of-customer",
+  "invoiceId": "uuid-of-invoice",
+  "paymentAllocations": [
+    {
+      "invoiceId": "uuid-of-invoice",
+      "allocatedAmount": 1500.00
+    }
+  ]
+}
+```
+
+**Response (201 Created):**
+```json
+{
+  "id": "uuid-of-payment",
+  "paymentNumber": "PAY-2024-0001",
+  "paymentDate": "2024-01-20",
+  "paymentMethod": "ACH",
+  "paymentAmount": 1500.00,
+  "totalPaymentAmount": 1500.00,
+  "status": "COMPLETED",
+  "memo": null,
+  "vendorId": null,
+  "customerId": "uuid-of-customer",
+  "invoiceId": "uuid-of-invoice",
+  "paymentAllocations": [
+    {
+      "id": "uuid-of-allocation",
+      "invoiceId": "uuid-of-invoice",
+      "invoiceNumber": "INV-AR-2024-0001",
+      "allocatedAmount": 1500.00,
+      "allocationDate": "2024-01-20T00:00:00.000Z"
+    }
+  ]
+}
+```
+
+**Supported Payment Methods:**
+- `ACH`
+- `WIRE`
+- `CHECK`
+- `CREDIT_CARD`
+- `BANK_TRANSFER`
+- `CASH`
+- `OTHER`
+
+**Notes:**
+- The payment automatically updates the invoice's `paidAmount` and `balanceDue`
+- Invoice status is updated to `PAID` when balance due reaches 0, or `PARTIALLY_PAID` if there's still a balance
+
+---
+
+## UI Components
+
+### AR Invoice Detail Page
+
+**Location:** `/src/app/(dashboard)/finance/ar/invoice/[invoiceId]/page.tsx`
+
+Features:
+- "Record Payment" button in the Actions section
+- Payment recording modal with form
+- Auto-opens when navigating with query parameter `?action=payment`
+- Displays payment history
+- Updates automatically after successful payment
+
+**Payment Form Fields:**
+- Payment Amount (required, defaults to balance due suggestion)
+- Payment Date (required, defaults to today)
+- Payment Method (required, dropdown with standard methods)
+
+---
+
+## Example Workflow
+
+### 1. Upload and Parse CSV
+
+```bash
+curl -X POST http://localhost:3000/api/bank-transactions/parse-csv \
+  -F "file=@transactions.csv"
+```
+
+### 2. Review Parsed Transactions
+
+The response shows all parsed transactions for preview.
+
+### 3. Import Transactions
+
+```bash
+curl -X POST http://localhost:3000/api/bank-transactions/import \
+  -H "Content-Type: application/json" \
+  -d '{
+    "bankAccountId": "account-uuid",
+    "transactions": [...parsed transactions...]
+  }'
+```
+
+### 4. Record Payment
+
+Navigate to `/finance/ar/invoice/{invoiceId}` and click "Record Payment" button, or directly navigate to `/finance/ar/invoice/{invoiceId}?action=payment` to auto-open the payment modal.
+
+---
+
+## Error Handling
+
+All endpoints return appropriate HTTP status codes:
+
+- `200 OK` - Successful read operation
+- `201 Created` - Successful create operation
+- `400 Bad Request` - Validation error or missing required fields
+- `404 Not Found` - Resource not found (bank account, invoice, etc.)
+- `409 Conflict` - Duplicate record
+- `500 Internal Server Error` - Server error
+
+Error responses include an `error` field with a descriptive message:
+
+```json
+{
+  "error": "Missing required fields: bankAccountId, transactions"
+}
+```