# Smart Khata Book REST APIs - curl Commands

All APIs expect JSON request bodies (except where specified) and use standard HTTP headers. For protected endpoints, replace `<JWT_TOKEN>` with your actual token.

---

## 1. Authentication & Security (2 APIs)

### API 01. Send OTP Request
*   **Method**: `POST`
*   **URL**: `http://localhost:8080/api/v1/auth/request-otp`
*   **curl**:
    ```bash
    curl -X POST http://localhost:8080/api/v1/auth/request-otp \
         -H "Content-Type: application/json" \
         -d '{"phone": "+919876543210"}'
    ```

### API 02. Verify OTP
*   **Method**: `POST`
*   **URL**: `http://localhost:8080/api/v1/auth/verify-otp`
*   **curl**:
    ```bash
    curl -X POST http://localhost:8080/api/v1/auth/verify-otp \
         -H "Content-Type: application/json" \
         -d '{"phone": "+919876543210", "otp": "5582"}'
    ```

---

## 2. Shop & Branding Configuration (3 APIs)

### API 03. Create New Shop
*   **Method**: `POST`
*   **URL**: `http://localhost:8080/api/v1/shops/create`
*   **curl**:
    ```bash
    curl -X POST http://localhost:8080/api/v1/shops/create \
         -H "Authorization: Bearer <JWT_TOKEN>" \
         -H "Content-Type: application/json" \
         -d '{"name": "Sharma General Store", "businessType": "Retail", "city": "Lucknow", "address": "Shop No 14, Grain Market, Lucknow", "gstin": "09AAAAA1111A1Z1"}'
    ```

### API 04. Update Shop Profile Details
*   **Method**: `PUT`
*   **URL**: `http://localhost:8080/api/v1/shops/{shopId}/update`
*   *(Replace `{shopId}` with your shop ID)*
*   **curl**:
    ```bash
    curl -X PUT http://localhost:8080/api/v1/shops/shop_sharma_991/update \
         -H "Authorization: Bearer <JWT_TOKEN>" \
         -H "Content-Type: application/json" \
         -d '{"name": "Sharma & Sons Store", "businessType": "Wholesale", "city": "Kanpur", "address": "Gali No 2, Market, Kanpur", "gstin": "09AAAAA1111A1Z2", "logoUrl": "https://storage.googleapis.com/logos/shop_sharma.png"}'
    ```

### API 05. Fetch Shop Profile
*   **Method**: `GET`
*   **URL**: `http://localhost:8080/api/v1/shops/{shopId}`
*   *(Replace `{shopId}` with your shop ID)*
*   **curl**:
    ```bash
    curl -X GET http://localhost:8080/api/v1/shops/shop_sharma_991 \
         -H "Authorization: Bearer <JWT_TOKEN>"
    ```

---

## 3. Customer Book Ledger (4 APIs)

### API 06. Add New Customer
*   **Method**: `POST`
*   **URL**: `http://localhost:8080/api/v1/customers/add`
*   **curl**:
    ```bash
    curl -X POST http://localhost:8080/api/v1/customers/add \
         -H "Authorization: Bearer <JWT_TOKEN>" \
         -H "Content-Type: application/json" \
         -d '{"shopId": "shop_sharma_991", "name": "Ravi Singh", "phone": "+919876512345"}'
    ```

### API 07. Fetch Customer List
*   **Method**: `GET`
*   **URL**: `http://localhost:8080/api/v1/shops/{shopId}/customers`
*   *(Replace `{shopId}` with your shop ID)*
*   **curl**:
    ```bash
    curl -X GET http://localhost:8080/api/v1/shops/shop_sharma_991/customers \
         -H "Authorization: Bearer <JWT_TOKEN>"
    ```

### API 08. Edit Customer Details
*   **Method**: `PUT`
*   **URL**: `http://localhost:8080/api/v1/customers/{customerId}/edit`
*   *(Replace `{customerId}` with your customer ID)*
*   **curl**:
    ```bash
    curl -X PUT http://localhost:8080/api/v1/customers/cust_ravi_001/edit \
         -H "Authorization: Bearer <JWT_TOKEN>" \
         -H "Content-Type: application/json" \
         -d '{"name": "Ravi Kumar Singh", "phone": "+919876599999"}'
    ```

### API 09. Delete Customer
*   **Method**: `DELETE`
*   **URL**: `http://localhost:8080/api/v1/customers/{customerId}`
*   *(Replace `{customerId}` with your customer ID)*
*   **curl**:
    ```bash
    curl -X DELETE http://localhost:8080/api/v1/customers/cust_ravi_001 \
         -H "Authorization: Bearer <JWT_TOKEN>"
    ```

---

## 4. Customer Transactions (4 APIs)

### API 10. Add Customer Ledger Entry
*   **Method**: `POST`
*   **URL**: `http://localhost:8080/api/v1/transactions/customer/add`
*   **curl**:
    ```bash
    curl -X POST http://localhost:8080/api/v1/transactions/customer/add \
         -H "Authorization: Bearer <JWT_TOKEN>" \
         -H "Content-Type: application/json" \
         -d '{"customerId": "cust_ravi_001", "shopId": "shop_sharma_991", "title": "Aata & Rice packet", "amount": -1200.00, "billNumber": "BILL-4412", "isCredit": false, "dateTime": "2026-06-30 18:30"}'
    ```

### API 11. Fetch Transaction History
*   **Method**: `GET`
*   **URL**: `http://localhost:8080/api/v1/customers/{customerId}/transactions`
*   *(Replace `{customerId}` with your customer ID)*
*   **curl**:
    ```bash
    curl -X GET http://localhost:8080/api/v1/customers/cust_ravi_001/transactions \
         -H "Authorization: Bearer <JWT_TOKEN>"
    ```

### API 12. Modify Customer Entry
*   **Method**: `PUT`
*   **URL**: `http://localhost:8080/api/v1/transactions/customer/{transactionId}/edit`
*   *(Replace `{transactionId}` with your transaction ID)*
*   **curl**:
    ```bash
    curl -X PUT http://localhost:8080/api/v1/transactions/customer/tx_cust_abc001/edit \
         -H "Authorization: Bearer <JWT_TOKEN>" \
         -H "Content-Type: application/json" \
         -d '{"title": "Aata packet only", "amount": -500.00, "billNumber": "BILL-4412"}'
    ```

### API 13. Delete Customer Entry
*   **Method**: `DELETE`
*   **URL**: `http://localhost:8080/api/v1/transactions/customer/{transactionId}`
*   *(Replace `{transactionId}` with your transaction ID)*
*   **curl**:
    ```bash
    curl -X DELETE http://localhost:8080/api/v1/transactions/customer/tx_cust_abc001 \
         -H "Authorization: Bearer <JWT_TOKEN>"
    ```

---

## 5. Supplier Ledger / Wholesalers (4 APIs)

### API 14. Add New Supplier
*   **Method**: `POST`
*   **URL**: `http://localhost:8080/api/v1/suppliers/add`
*   **curl**:
    ```bash
    curl -X POST http://localhost:8080/api/v1/suppliers/add \
         -H "Authorization: Bearer <JWT_TOKEN>" \
         -H "Content-Type: application/json" \
         -d '{"shopId": "shop_sharma_991", "name": "Krishna Wholesalers", "phone": "+919888877777", "address": "42 Grains Market, Delhi"}'
    ```

### API 15. Fetch Suppliers List
*   **Method**: `GET`
*   **URL**: `http://localhost:8080/api/v1/shops/{shopId}/suppliers`
*   *(Replace `{shopId}` with your shop ID)*
*   **curl**:
    ```bash
    curl -X GET http://localhost:8080/api/v1/shops/shop_sharma_991/suppliers \
         -H "Authorization: Bearer <JWT_TOKEN>"
    ```

### API 16. Edit Supplier Details
*   **Method**: `PUT`
*   **URL**: `http://localhost:8080/api/v1/suppliers/{supplierId}/edit`
*   *(Replace `{supplierId}` with your supplier ID)*
*   **curl**:
    ```bash
    curl -X PUT http://localhost:8080/api/v1/suppliers/sup_krish_01/edit \
         -H "Authorization: Bearer <JWT_TOKEN>" \
         -H "Content-Type: application/json" \
         -d '{"name": "Krishna Wholesalers Ltd", "phone": "+919888877777", "address": "Shop 42, Grains Market, Delhi"}'
    ```

### API 17. Delete Supplier
*   **Method**: `DELETE`
*   **URL**: `http://localhost:8080/api/v1/suppliers/{supplierId}`
*   *(Replace `{supplierId}` with your supplier ID)*
*   **curl**:
    ```bash
    curl -X DELETE http://localhost:8080/api/v1/suppliers/sup_krish_01 \
         -H "Authorization: Bearer <JWT_TOKEN>"
    ```

---

## 6. Supplier Transactions (4 APIs)

### API 18. Add Supplier Transaction Entry
*   **Method**: `POST`
*   **URL**: `http://localhost:8080/api/v1/transactions/supplier/add`
*   **curl**:
    ```bash
    curl -X POST http://localhost:8080/api/v1/transactions/supplier/add \
         -H "Authorization: Bearer <JWT_TOKEN>" \
         -H "Content-Type: application/json" \
         -d '{"supplierId": "sup_krish_01", "shopId": "shop_sharma_991", "amount": 15400.00, "isPurchase": true, "billNo": "PUR-992", "photoUrl": "https://storage.googleapis.com/bills/bill_pur_992.jpg", "dateTime": "2026-06-30 14:00"}'
    ```

### API 19. Fetch Supplier Transactions
*   **Method**: `GET`
*   **URL**: `http://localhost:8080/api/v1/suppliers/{supplierId}/transactions`
*   *(Replace `{supplierId}` with your supplier ID)*
*   **curl**:
    ```bash
    curl -X GET http://localhost:8080/api/v1/suppliers/sup_krish_01/transactions \
         -H "Authorization: Bearer <JWT_TOKEN>"
    ```

### API 20. Edit Supplier Entry
*   **Method**: `PUT`
*   **URL**: `http://localhost:8080/api/v1/transactions/supplier/{transactionId}/edit`
*   *(Replace `{transactionId}` with your transaction ID)*
*   **curl**:
    ```bash
    curl -X PUT http://localhost:8080/api/v1/transactions/supplier/tx_sup_009/edit \
         -H "Authorization: Bearer <JWT_TOKEN>" \
         -H "Content-Type: application/json" \
         -d '{"amount": 15000.00, "billNo": "PUR-992-revised"}'
    ```

### API 21. Delete Supplier Entry
*   **Method**: `DELETE`
*   **URL**: `http://localhost:8080/api/v1/transactions/supplier/{transactionId}`
*   *(Replace `{transactionId}` with your transaction ID)*
*   **curl**:
    ```bash
    curl -X DELETE http://localhost:8080/api/v1/transactions/supplier/tx_sup_009 \
         -H "Authorization: Bearer <JWT_TOKEN>"
    ```

---

## 7. Staff & Team Management (3 APIs)

### API 22. Invite Staff Member
*   **Method**: `POST`
*   **URL**: `http://localhost:8080/api/v1/team/invite`
*   **curl**:
    ```bash
    curl -X POST http://localhost:8080/api/v1/team/invite \
         -H "Authorization: Bearer <JWT_TOKEN>" \
         -H "Content-Type: application/json" \
         -d '{"shopId": "shop_sharma_991", "name": "Suresh Kumar", "phone": "+919876598765", "role": "staff"}'
    ```

### API 23. Submit Verification Documents (Staff Login verification)
*   **Method**: `POST`
*   **URL**: `http://localhost:8080/api/v1/team/verify-credentials`
*   *(Note: This is multipart/form-data. It does NOT require a JWT token.)*
*   **curl**:
    ```bash
    curl -X POST http://localhost:8080/api/v1/team/verify-credentials \
         -F "phone=+919876598765" \
         -F "securityCode=SURESH-5582" \
         -F "photo=@/path/to/photo.jpg" \
         -F "document=@/path/to/doc.pdf"
    ```

### API 24. Deactivate Member (Remote Log out)
*   **Method**: `POST`
*   **URL**: `http://localhost:8080/api/v1/team/deactivate`
*   **curl**:
    ```bash
    curl -X POST http://localhost:8080/api/v1/team/deactivate \
         -H "Authorization: Bearer <JWT_TOKEN>" \
         -H "Content-Type: application/json" \
         -d '{"shopId": "shop_sharma_991", "phone": "+919876598765"}'
    ```

---

## 8. Stock & Exports (2 APIs)

### API 25. Fetch Stock Inventory
*   **Method**: `GET`
*   **URL**: `http://localhost:8080/api/v1/shops/{shopId}/inventory`
*   *(Replace `{shopId}` with your shop ID)*
*   **curl**:
    ```bash
    curl -X GET http://localhost:8080/api/v1/shops/shop_sharma_991/inventory \
         -H "Authorization: Bearer <JWT_TOKEN>"
    ```

### API 26. Request Older Report Email (Export Safety Guard)
*   **Method**: `POST`
*   **URL**: `http://localhost:8080/api/v1/reports/export-email`
*   **curl**:
    ```bash
    curl -X POST http://localhost:8080/api/v1/reports/export-email \
         -H "Authorization: Bearer <JWT_TOKEN>" \
         -H "Content-Type: application/json" \
         -d '{"shopId": "shop_sharma_991", "customerName": "Ravi Singh", "email": "ramesh.sharma@gmail.com", "yearRange": "2022-2023"}'
    ```