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:

{
  "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):

{
  "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

Date,Description,Amount
2024-01-15,Office Supplies,150.50
2024-01-16,Client Payment,2500.00

Format 2: Date, Description, Debit, Credit

Date,Description,Debit,Credit
2024-01-15,Office Supplies,150.50,0
2024-01-16,Client Payment,0,2500.00

Response (200 OK):

{
  "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):

{
  "error": "CSV must have 'Date' and 'Description' columns"
}

---

Payment Recording API

Endpoint: POST /api/payments

Record a payment against an invoice.

Request Body:

{
  "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):

{
  "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

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

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:

{
  "error": "Missing required fields: bankAccountId, transactions"
}