PozoAccounts/API_DOCUMENTATION.md

# Digital Ledger API Documentation

## Overview
This document outlines all the APIs required for the Digital Ledger Mobile App backend implementation. The APIs are organized by feature modules.

## Base URL
```
https://api.pozo-accounts.com/v1
```

## Authentication
All APIs require Bearer token authentication:
```
Authorization: Bearer <jwt_token>
```

---

## 1. USER MANAGEMENT APIs

### 1.1 User Profile
```http
GET /user/profile
```
**Response:**
```json
{
  "success": true,
  "data": {
    "id": "user_123",
    "name": "Ram Kumar",
    "email": "ram@business.com",
    "phone": "+91 98765 43210",
    "avatar": "RK",
    "businessName": "Ram's Store",
    "role": "Business Owner",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-12-03T14:20:00Z"
  }
}
```

### 1.2 Update User Profile
```http
PUT /user/profile
```
**Request Body:**
```json
{
  "name": "Ram Kumar",
  "email": "ram@business.com",
  "phone": "+91 98765 43210",
  "businessName": "Ram's Store"
}
```

---

## 2. DASHBOARD APIs

### 2.1 Dashboard Summary
```http
GET /dashboard/summary
```
**Response:**
```json
{
  "success": true,
  "data": {
    "transactionSummary": {
      "pendingPayment": {
        "count": 125,
        "change": "+8%",
        "positive": true
      },
      "received": {
        "count": 456,
        "change": "+12%",
        "positive": true
      },
      "paidOut": {
        "count": 234,
        "change": "+5%",
        "positive": true
      },
      "completed": {
        "count": 892,
        "change": "+15%",
        "positive": true
      },
      "cancelled": {
        "count": 23,
        "change": "-3%",
        "positive": false
      }
    },
    "financialOverview": {
      "totalIncome": 328000,
      "totalExpense": 231000,
      "netBalance": 97000,
      "monthlyData": [
        {
          "month": "Jan",
          "income": 45000,
          "expense": 32000
        }
      ]
    },
    "quickStats": {
      "totalCustomers": 248,
      "customerGrowth": "+12%",
      "activeTransactions": 89,
      "pendingApproval": 23,
      "netBalance": 97000,
      "cashflowStatus": "positive"
    }
  }
}
```

---

## 3. CONTACT MANAGEMENT APIs (Customers & Suppliers)

### 3.1 Get All Contacts
```http
GET /contacts?page=1&limit=10&search=&balanceType=all&contactType=all
```
**Query Parameters:**
- `page`: Page number (default: 1)
- `limit`: Items per page (default: 10)
- `search`: Search by name/phone
- `balanceType`: all|credit|debit
- `contactType`: all|C|S (C=Customer, S=Supplier)

**Response:**
```json
{
  "success": true,
  "data": {
    "contacts": [
      {
        "id": "contact_001",
        "name": "Deepa",
        "phone": "98755 43210",
        "email": "deepa@example.com",
        "address": "123 Main St",
        "avatar": "D",
        "balance": 800,
        "balanceType": "credit",
        "contactType": "C",
        "status": "Active",
        "lastTransaction": "Payment received",
        "lastTransactionDate": "2024-12-03T14:30:00Z",
        "totalTransactions": 24,
        "createdAt": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 5,
      "totalItems": 50,
      "hasNext": true,
      "hasPrev": false
    },
    "summary": {
      "customers": {
        "total": 30,
        "totalReceivable": 82000,
        "totalPayable": 16700,
        "active": 28
      },
      "suppliers": {
        "total": 20,
        "totalReceivable": 5000,
        "totalPayable": 62500,
        "active": 18
      }
    }
  }
}
```

### 3.2 Create Contact
```http
POST /contacts
```
**Request Body:**
```json
{
  "name": "John Doe",
  "phone": "+91 98765 43210",
  "email": "john@example.com",
  "address": "123 Main St, City",
  "contactType": "C",
  "initialBalance": 0,
  "balanceType": "credit"
}
```

### 3.3 Get Contact Details
```http
GET /contacts/{contactId}
```
**Response:**
```json
{
  "success": true,
  "data": {
    "id": "contact_001",
    "name": "Deepa",
    "phone": "98755 43210",
    "email": "deepa@example.com",
    "address": "123 Main St",
    "avatar": "D",
    "balance": 800,
    "balanceType": "credit",
    "contactType": "C",
    "status": "Active",
    "createdAt": "2024-01-15T10:30:00Z",
    "transactions": [
      {
        "id": "txn_001",
        "date": "2024-12-02T00:00:00Z",
        "type": "credit",
        "amount": 500,
        "note": "Invoice payment",
        "paymentMethod": "UPI",
        "status": "completed"
      }
    ]
  }
}
```

### 3.4 Update Contact
```http
PUT /contacts/{contactId}
```
**Request Body:**
```json
{
  "name": "John Doe Updated",
  "phone": "+91 98765 43210",
  "email": "john.updated@example.com",
  "address": "456 New St, City"
}
```

### 3.5 Delete Contact
```http
DELETE /contacts/{contactId}
```

---

## 4. TRANSACTION MANAGEMENT APIs

### 4.1 Get All Transactions
```http
GET /transactions?page=1&limit=10&type=all&status=all&dateFrom=&dateTo=
```
**Response:**
```json
{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "txn_001",
        "contactId": "contact_001",
        "contactName": "Rajesh Kumar",
        "contactAvatar": "RK",
        "contactType": "C",
        "category": "Payment",
        "type": "Credit",
        "amount": 45000,
        "date": "2024-05-30T00:00:00Z",
        "status": "Completed",
        "paymentMethod": "UPI",
        "note": "Invoice payment"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 10,
      "totalItems": 100
    },
    "summary": {
      "pendingPayments": 34000,
      "receivedPayments": 550870,
      "statusCounts": {
        "waitingPayment": 435,
        "onProcess": 234,
        "onDelivery": 456,
        "completed": 675,
        "cancelled": 675
      }
    }
  }
}
```

### 4.2 Create Transaction
```http
POST /transactions
```
**Request Body:**
```json
{
  "contactId": "contact_001",
  "type": "credit",
  "amount": 1000,
  "note": "Payment received",
  "paymentMethod": "Cash",
  "date": "2024-12-03T00:00:00Z",
  "category": "Payment"
}
```

### 4.3 Update Transaction
```http
PUT /transactions/{transactionId}
```

### 4.4 Delete Transaction
```http
DELETE /transactions/{transactionId}
```

---

## 5. CASHBOOK APIs

### 5.1 Get Cashbook Entries
```http
GET /cashbook?page=1&limit=10&type=all&dateFrom=&dateTo=
```
**Response:**
```json
{
  "success": true,
  "data": {
    "entries": [
      {
        "id": "cb_001",
        "time": "10:22 AM",
        "date": "2024-12-03T00:00:00Z",
        "type": "out",
        "paymentType": "ONLINE",
        "description": "Office Supplies Purchase",
        "category": "Expenses",
        "amount": 1200,
        "attachments": []
      }
    ],
    "summary": {
      "totalIn": 13500,
      "totalOut": 1550,
      "netBalance": 11950,
      "totalTransactions": 4
    },
    "todaySummary": {
      "todayIn": 5000,
      "todayOut": 1200,
      "netToday": 3800
    }
  }
}
```

### 5.2 Create Cashbook Entry
```http
POST /cashbook
```
**Request Body:**
```json
{
  "type": "in",
  "amount": 5000,
  "description": "Sales Revenue",
  "category": "Income",
  "paymentType": "CASH",
  "date": "2024-12-03T00:00:00Z",
  "attachments": ["file_url_1", "file_url_2"]
}
```

### 5.3 Update Cashbook Entry
```http
PUT /cashbook/{entryId}
```

### 5.4 Delete Cashbook Entry
```http
DELETE /cashbook/{entryId}
```

---

## 6. EXPENSE MANAGEMENT APIs

### 6.1 Get All Expenses
```http
GET /expenses?page=1&limit=10&category=&status=&dateFrom=&dateTo=
```
**Response:**
```json
{
  "success": true,
  "data": {
    "expenses": [
      {
        "id": "exp_001",
        "title": "Inventory Restock",
        "vendor": "Fresh Farm Wholesale",
        "category": "Inventory",
        "date": "2024-12-03T00:00:00Z",
        "paymentType": "UPI",
        "amount": 18500,
        "status": "Settled",
        "isFixedCommitment": false,
        "attachments": []
      }
    ],
    "summary": {
      "totalSpent": 65000,
      "recurringExpenses": 37400,
      "pendingAmount": 37650,
      "totalExpenses": 5
    },
    "categories": ["Inventory", "Fixed Cost", "Logistics", "Utilities", "Supplies"]
  }
}
```

### 6.2 Create Expense
```http
POST /expenses
```
**Request Body:**
```json
{
  "title": "Office Rent",
  "vendor": "Property Owner",
  "category": "Fixed Cost",
  "amount": 25000,
  "paymentType": "Bank Transfer",
  "date": "2024-12-01T00:00:00Z",
  "status": "Scheduled",
  "isFixedCommitment": true,
  "attachments": []
}
```

### 6.3 Update Expense
```http
PUT /expenses/{expenseId}
```

### 6.4 Delete Expense
```http
DELETE /expenses/{expenseId}
```

---

## 7. LEDGER APIs

### 7.1 Get Ledger Summary
```http
GET /ledger/summary
```
**Response:**
```json
{
  "success": true,
  "data": {
    "customers": {
      "totalReceivable": 4800,
      "totalPayable": 1700,
      "count": 6
    },
    "suppliers": {
      "totalReceivable": 5000,
      "totalPayable": 62500,
      "count": 5
    },
    "netBalance": -54400,
    "recentActivity": [
      {
        "id": "act_001",
        "type": "payment_received",
        "description": "₹800 from Deepa",
        "time": "2 hours ago",
        "status": "completed"
      }
    ]
  }
}
```

---

## 8. REPORTS APIs

### 8.1 Get Cashbook Report
```http
GET /reports/cashbook?dateFrom=2024-11-01&dateTo=2024-12-31
```
**Response:**
```json
{
  "success": true,
  "data": {
    "period": "1 Nov - 31 Dec 2024",
    "summary": {
      "totalIn": 125000,
      "totalOut": 87000,
      "netBalance": 38000,
      "totalTransactions": 156
    },
    "chartData": [
      {
        "name": "Week 1",
        "moneyIn": 25000,
        "moneyOut": 18000
      }
    ],
    "categoryBreakdown": [
      {
        "category": "Income",
        "amount": 125000,
        "percentage": 58.9
      }
    ]
  }
}
```

### 8.2 Get Transaction Report
```http
GET /reports/transactions?dateFrom=2024-11-01&dateTo=2024-12-31
```
**Response:**
```json
{
  "success": true,
  "data": {
    "period": "1 Nov - 31 Dec 2024",
    "customers": {
      "totalReceivable": 59550,
      "totalReceived": 13500,
      "pending": 46050,
      "count": 6
    },
    "suppliers": {
      "totalPayable": 9800,
      "totalPaid": 1550,
      "pending": 8250,
      "count": 5
    },
    "chartData": [
      {
        "name": "Customers",
        "receivable": 59550,
        "received": 13500,
        "pending": 46050
      }
    ]
  }
}
```

---

## 9. FILE UPLOAD APIs

### 9.1 Upload File
```http
POST /files/upload
```
**Request:** Multipart form data
**Response:**
```json
{
  "success": true,
  "data": {
    "fileId": "file_123",
    "fileName": "receipt.jpg",
    "fileUrl": "https://cdn.pozo-accounts.com/files/file_123.jpg",
    "fileSize": 2048,
    "mimeType": "image/jpeg"
  }
}
```

---

## 10. NOTIFICATION APIs

### 10.1 Get Notifications
```http
GET /notifications?page=1&limit=10&unreadOnly=false
```
**Response:**
```json
{
  "success": true,
  "data": {
    "notifications": [
      {
        "id": "notif_001",
        "title": "Payment Received",
        "message": "₹800 received from Deepa",
        "type": "payment",
        "isRead": false,
        "createdAt": "2024-12-03T14:30:00Z"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 3,
      "totalItems": 25,
      "unreadCount": 5
    }
  }
}
```

### 10.2 Mark as Read
```http
PUT /notifications/{notificationId}/read
```

---

## Error Response Format
All APIs return errors in this format:
```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "field": "email",
      "message": "Invalid email format"
    }
  }
}
```

## API Summary
**Total APIs: 35+ endpoints**
- User Management: 2 APIs
- Dashboard: 1 API
- Contact Management (Customers & Suppliers): 5 APIs
- Transaction Management: 4 APIs
- Cashbook: 4 APIs
- Expense Management: 4 APIs
- Ledger: 1 API
- Reports: 2 APIs
- File Upload: 1 API
- Notifications: 2 APIs

## Key Benefits of Unified Contact API
- **Simplified Backend**: Single table/model for customers and suppliers
- **Consistent Data Structure**: Same fields and operations for both types
- **Easier Maintenance**: One set of CRUD operations instead of two
- **Flexible Filtering**: Can filter by contactType ('C'/'S') or get all contacts
- **Unified Search**: Search across both customers and suppliers simultaneously

## Common HTTP Status Codes
- `200` - Success
- `201` - Created
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not Found
- `422` - Validation Error
- `500` - Internal Server Error

## Rate Limiting
- 1000 requests per hour per user
- 100 requests per minute per endpoint

## Pagination
All list APIs support pagination with these query parameters:
- `page`: Page number (default: 1)
- `limit`: Items per page (default: 10, max: 100)

## Date Format
All dates should be in ISO 8601 format: `2024-12-03T14:30:00Z`

## File Upload Constraints
- Maximum file size: 10MB
- Supported formats: JPG, PNG, PDF
- Files are automatically compressed and optimized