# Receipt Entry API - cURL Example with Response

## Endpoint
```
POST /receipt
```

## cURL Command

### Basic Example (JSON) - Without Receipt Number (Auto-generated)
```bash
curl -X POST http://localhost:3000/receipt \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "loan_id": "DL2025001",
    "receipt_date": "2025-12-05",
    "cust_id": 8,
    "cus_name": "Pavithra",
    "cus_mobile": "5346876764",
    "no_of_dues": 60,
    "due_amt": 100.00,
    "paid_amt": 100.00,
    "paid_dues": 1,
    "balance_dues": 59,
    "pending_dues": 59,
    "next_date": "2025-12-06",
    "remark": "Payment received",
    "agent": "Raja",
    "ledgerName": "Cash A/c",
    "principal_per_due": 83.33,
    "interest_per_due": 16.67,
    "account_close": "",
    "latitude": 11.3410,
    "longitude": 77.7172,
    "accuracy": 10.5,
    "altitude": 920.5,
    "heading": 45.0,
    "speed": 0.0,
    "address": "Erode, Tamil Nadu"
  }'
```

### With Location Tracking (Complete Example) - Auto-generated Receipt Number
```bash
curl -X POST http://localhost:3000/receipt \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 20d2297a5514be0b1febc28571af468d66319c1758f3dcf8bf718e5680d1cf2f" \
  -d '{
    "loan_id": "DL2025001",
    "receipt_date": "2025-12-05",
    "cust_id": 8,
    "cus_name": "Pavithra",
    "cus_mobile": "5346876764",
    "no_of_dues": 60,
    "due_amt": 92.00,
    "paid_amt": 92.00,
    "paid_dues": 1,
    "balance_dues": 59,
    "pending_dues": 59,
    "next_date": "2025-12-06",
    "remark": "Daily collection payment",
    "agent": "Raja",
    "ledgerName": "Cash A/c",
    "principal_per_due": 83.33,
    "interest_per_due": 8.67,
    "account_close": "",
    "latitude": 11.3410,
    "longitude": 77.7172,
    "accuracy": 10.5,
    "altitude": 920.5,
    "heading": 45.0,
    "speed": 0.0,
    "address": "Erode, Tamil Nadu, India"
  }'
```

### Form Data Format (Alternative) - Receipt Number Optional
```bash
curl -X POST http://localhost:3000/receipt \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d "loan_id=DL2025001" \
  -d "receipt_date=2025-12-05" \
  -d "cust_id=8" \
  -d "cus_name=Pavithra" \
  -d "cus_mobile=5346876764" \
  -d "no_of_dues=60" \
  -d "due_amt=92.00" \
  -d "paid_amt=92.00" \
  -d "paid_dues=1" \
  -d "balance_dues=59" \
  -d "pending_dues=59" \
  -d "next_date=2025-12-06" \
  -d "remark=Payment received" \
  -d "agent=Raja" \
  -d "ledgerName=Cash A/c" \
  -d "principal_per_due=83.33" \
  -d "interest_per_due=8.67" \
  -d "account_close=" \
  -d "latitude=11.3410" \
  -d "longitude=77.7172" \
  -d "address=Erode, Tamil Nadu"
```

---

## Success Response

```json
{
  "success": true,
  "message": "Loan inserted successfully",
  "loan_id": "DL2025001",
  "customer_id": 8,
  "receipt_no": "REC1764932744675",
  "receipt_id": 45,
  "location_tracked": true,
  "location_track_id": 12
}
```

### Response Fields Explanation:
- `success`: `true` if receipt was created successfully
- `message`: Success message
- `loan_id`: The loan ID for which receipt was created
- `customer_id`: Customer ID
- `receipt_no`: Receipt number (auto-generated if not provided in request)
- `receipt_id`: Auto-generated receipt ID from database
- `location_tracked`: `true` if location data was provided and tracked
- `location_track_id`: ID of the location tracking entry (if location was provided)

---

## Error Responses

### 1. Missing Authorization Header
```json
{
  "success": false,
  "message": "Authorization header missing"
}
```

### 2. Invalid JWT Token
```json
{
  "success": false,
  "message": "JWT Error: invalid token"
}
```

### 3. Expired JWT Token
```json
{
  "success": false,
  "message": "Token expired: jwt expired"
}
```

### 4. Missing Required Fields
```json
{
  "success": false,
  "message": "loan_id is required"
}
```

### 5. Database Error
```json
{
  "success": false,
  "message": "Failed to insert receipt",
  "error": "Duplicate entry 'REC001' for key 'rec_no'"
}
```

---

## Required Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `loan_id` | string | ✅ Yes | Loan ID |
| `receipt_no` | string | ❌ No | Unique receipt number (auto-generated if not provided) |
| `receipt_date` | date | ✅ Yes | Receipt date (YYYY-MM-DD) |
| `cust_id` | integer | ✅ Yes | Customer ID |
| `cus_name` | string | ✅ Yes | Customer name |
| `cus_mobile` | string | Optional | Customer mobile number |
| `no_of_dues` | integer | Optional | Total number of dues |
| `due_amt` | decimal | Optional | Due amount |
| `paid_amt` | decimal | Optional | Paid amount |
| `paid_dues` | integer | Optional | Number of dues paid |
| `balance_dues` | integer | Optional | Balance dues |
| `pending_dues` | integer | Optional | Pending dues |
| `next_date` | date | Optional | Next due date |
| `remark` | string | Optional | Remarks |
| `agent` | string | Optional | Agent name |
| `ledgerName` | string | Optional | Ledger account name |
| `principal_per_due` | decimal | Optional | Principal amount per due |
| `interest_per_due` | decimal | Optional | Interest amount per due |
| `account_close` | string | Optional | Set to "Closed" to close account |
| `latitude` | decimal | Optional | GPS latitude |
| `longitude` | decimal | Optional | GPS longitude |
| `accuracy` | decimal | Optional | GPS accuracy |
| `altitude` | decimal | Optional | GPS altitude |
| `heading` | decimal | Optional | GPS heading |
| `speed` | decimal | Optional | GPS speed |
| `address` | string | Optional | Address string |

---

## Quick Test Command (Auto-generated Receipt Number)

```bash
# Replace YOUR_JWT_TOKEN with actual token
# Note: receipt_no is optional - will be auto-generated if not provided
curl -X POST http://localhost:3000/receipt \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "loan_id": "DL2025001",
    "receipt_date": "'$(date +%Y-%m-%d)'",
    "cust_id": 8,
    "cus_name": "Test Customer",
    "due_amt": 92.00,
    "paid_amt": 92.00,
    "paid_dues": 1,
    "principal_per_due": 83.33,
    "interest_per_due": 8.67
  }' | jq '.'
```

---

## Notes

1. **JWT Token**: The JWT token must contain `companyId` (or `company_id`) and `uid` in the payload:
   ```json
   {
     "data": {
       "companyId": 15,
       "uid": 5
     }
   }
   ```

2. **Receipt Number**: 
   - **Optional**: If not provided, the system will automatically generate a unique receipt number in the format `REC{timestamp}` (e.g., `REC1764932744675`)
   - **Auto-generation**: The system gets the latest receipt number for the company and generates the next one
   - **Format**: Uses timestamp-based format to ensure uniqueness
   - **Manual override**: You can still provide your own receipt number if needed

3. **Location Tracking**: If `latitude` and `longitude` are provided, a location tracking entry will be automatically created.

4. **Ledger Entries**: Principal and Interest ledger entries are automatically created in `ledger_day_wise` table.

5. **Transaction**: All operations are wrapped in a database transaction for data integrity.

6. **Account Closing**: Set `account_close` to `"Closed"` to automatically close the loan account.