NeoCom/API_ENDPOINTS.md

# 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"
}
```