TamilSelvan
/
PozoAccounts
0
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
PozoAccounts/API_DOCUMENTATION.md

13 KiB
Raw Permalink Blame History

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

GET /user/profile

Response:

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

PUT /user/profile

Request Body:

{
  "name": "Ram Kumar",
  "email": "ram@business.com",
  "phone": "+91 98765 43210",
  "businessName": "Ram's Store"
}

2. DASHBOARD APIs

2.1 Dashboard Summary

GET /dashboard/summary

Response:

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

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:

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

POST /contacts

Request Body:

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

GET /contacts/{contactId}

Response:

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

PUT /contacts/{contactId}

Request Body:

{
  "name": "John Doe Updated",
  "phone": "+91 98765 43210",
  "email": "john.updated@example.com",
  "address": "456 New St, City"
}

3.5 Delete Contact

DELETE /contacts/{contactId}

4. TRANSACTION MANAGEMENT APIs

4.1 Get All Transactions

GET /transactions?page=1&limit=10&type=all&status=all&dateFrom=&dateTo=

Response:

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

POST /transactions

Request Body:

{
  "contactId": "contact_001",
  "type": "credit",
  "amount": 1000,
  "note": "Payment received",
  "paymentMethod": "Cash",
  "date": "2024-12-03T00:00:00Z",
  "category": "Payment"
}

4.3 Update Transaction

PUT /transactions/{transactionId}

4.4 Delete Transaction

DELETE /transactions/{transactionId}

5. CASHBOOK APIs

5.1 Get Cashbook Entries

GET /cashbook?page=1&limit=10&type=all&dateFrom=&dateTo=

Response:

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

POST /cashbook

Request Body:

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

PUT /cashbook/{entryId}

5.4 Delete Cashbook Entry

DELETE /cashbook/{entryId}

6. EXPENSE MANAGEMENT APIs

6.1 Get All Expenses

GET /expenses?page=1&limit=10&category=&status=&dateFrom=&dateTo=

Response:

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

POST /expenses

Request Body:

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

PUT /expenses/{expenseId}

6.4 Delete Expense

DELETE /expenses/{expenseId}

7. LEDGER APIs

7.1 Get Ledger Summary

GET /ledger/summary

Response:

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

GET /reports/cashbook?dateFrom=2024-11-01&dateTo=2024-12-31

Response:

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

GET /reports/transactions?dateFrom=2024-11-01&dateTo=2024-12-31

Response:

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

POST /files/upload

Request: Multipart form data Response:

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

GET /notifications?page=1&limit=10&unreadOnly=false

Response:

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

PUT /notifications/{notificationId}/read

Error Response Format

All APIs return errors in this format:

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