# Farmer ID Service API Documentation

## Overview

The Farmer ID Service API allows users to verify their Farmer ID using their Aadhar number. The service:
- Accepts Aadhar number (12 digits)
- Calls external API to verify Farmer ID
- Deducts service cost (₹25 by default, configurable by admin) from user's wallet
- Returns farmer details including Farmer ID, name, address, land ownership, etc.
- Tracks all service transactions

**Base URL:** `https://api.alldigtalseva.com/api`

---

## Table of Contents

1. [Verify Farmer ID](#verify-farmer-id)
2. [Check Transaction Status](#check-transaction-status)
3. [Service Transaction History](#service-transaction-history)
4. [Admin Service Management (with Cost)](#admin-service-management-with-cost)
5. [Error Responses](#error-responses)
6. [Testing Examples](#testing-examples)

---

## Verify Farmer ID

Verify Farmer ID using Aadhar number. This will deduct the service cost from user's wallet.

**⚠️ Important:** This API may take 1-2 minutes to respond as it calls an external API that processes the request. The timeout is set to 3 minutes. Please keep the connection open and wait for the response.

**Endpoint:** `POST /service/farmer-id/verify`

**Headers:**
```
Authorization: Bearer {user_token}
Content-Type: application/json
```

**Request Body:**
```json
{
    "aadhar": "576109808884"
}
```

**Parameters:**
- `aadhar` (required): String, exactly 12 digits. Aadhar number to verify.

**Note:** The response includes a `transaction_id` which you can use to check the status later using the status endpoint if needed.

**Success Response (200):**
```json
{
    "success": true,
    "message": "Farmer ID verified successfully",
    "data": {
        "farmer_id": "45874742709",
        "farmer_aadhar_number": "576109808884",
        "farmer_dob": "1979-08-05",
        "farmer_name_en": "Bhausaheb Sakharam Dake",
        "farmer_name_local": "भाऊसाहेब सखाराम डाके",
        "farmer_gender": "Male",
        "farmer_pincode": 431130,
        "farmer_address": "Mhalas Pimpalgav",
        "farmer_mobile": "9445760262",
        "farmer_photograph": "[encoded data, 7240 characters]",
        "farmer_land_ownerships": [
            {
                "extentAssignedAreaInHectare": 1.99,
                "villageName": "Mhalas Pimpalgaon",
                "districtName": "BEED",
                "subDistrictName": "Georai",
                "surveyNumber": "75"
            },
            {
                "extentAssignedAreaInHectare": 1.99,
                "villageName": "Mhalas Pimpalgaon",
                "districtName": "BEED",
                "subDistrictName": "Georai",
                "surveyNumber": "1"
            }
        ],
        "amount_deducted": 25.00,
        "remaining_balance": 475.00,
        "transaction_id": 1
    }
}
```

**Note:** The API response time is typically 1-2 minutes. Please wait for the response. If the connection times out, you can use the transaction ID to check the status later.

**Error Responses:**

**400 - Insufficient Balance:**
```json
{
    "success": false,
    "message": "Insufficient wallet balance",
    "data": {
        "required_amount": 25.00,
        "current_balance": 10.00,
        "shortage": 15.00
    }
}
```

**400 - Service Coming Soon:**
```json
{
    "success": false,
    "message": "This service is coming soon."
}
```

**400 - API Error:**
```json
{
    "success": false,
    "message": "Failed to verify Farmer ID. Please try again.",
    "data": {
        "status": 400,
        "message": "Invalid Aadhar number"
    }
}
```

**422 - Validation Error:**
```json
{
    "success": false,
    "message": "Validation error",
    "errors": {
        "aadhar": [
            "The aadhar must be 12 digits.",
            "The aadhar format is invalid."
        ]
    }
}
```

---

## Check Transaction Status

Check the status of a Farmer ID verification transaction. Useful if you want to check the status of a previous request or if the initial request timed out.

**Endpoint:** `GET /service/farmer-id/status/{id}`

**Headers:**
```
Authorization: Bearer {user_token}
```

**Parameters:**
- `id` (required): Transaction ID returned from the verify endpoint

**Success Response (200) - Pending:**
```json
{
    "success": true,
    "data": {
        "id": 1,
        "status": "pending",
        "amount": 25.00,
        "service": {
            "id": 1,
            "name": "Farmer ID",
            "path": "/user/farmerid"
        },
        "created_at": "2025-12-05T12:00:00.000000Z",
        "updated_at": "2025-12-05T12:00:00.000000Z"
    }
}
```

**Success Response (200) - Success:**
```json
{
    "success": true,
    "data": {
        "id": 1,
        "status": "success",
        "amount": 25.00,
        "service": {
            "id": 1,
            "name": "Farmer ID",
            "path": "/user/farmerid"
        },
        "created_at": "2025-12-05T12:00:00.000000Z",
        "updated_at": "2025-12-05T12:01:30.000000Z",
        "farmer_data": {
            "farmer_id": "45874742709",
            "farmer_aadhar_number": "576109808884",
            "farmer_dob": "1979-08-05",
            "farmer_name_en": "Bhausaheb Sakharam Dake",
            "farmer_name_local": "भाऊसाहेब सखाराम डाके",
            "farmer_gender": "Male",
            "farmer_pincode": 431130,
            "farmer_address": "Mhalas Pimpalgav",
            "farmer_mobile": "9445760262",
            "farmer_photograph": "/9j/4AAQSkZJRgABAgAAAQABAAD...",
            "farmer_land_ownerships": [
                {
                    "extentAssignedAreaInHectare": 1.99,
                    "villageName": "Mhalas Pimpalgaon",
                    "districtName": "BEED",
                    "subDistrictName": "Georai",
                    "surveyNumber": "75"
                }
            ]
        }
    }
}
```

**Success Response (200) - Failed:**
```json
{
    "success": true,
    "data": {
        "id": 1,
        "status": "failed",
        "amount": 25.00,
        "service": {
            "id": 1,
            "name": "Farmer ID",
            "path": "/user/farmerid"
        },
        "error_message": "Invalid Aadhar number",
        "created_at": "2025-12-05T12:00:00.000000Z",
        "updated_at": "2025-12-05T12:01:30.000000Z"
    }
}
```

**Error Response (404):**
```json
{
    "success": false,
    "message": "Transaction not found"
}
```

---

## Service Transaction History

Get history of all service transactions for the authenticated user.

**Endpoint:** `GET /service/farmer-id/history`

**Headers:**
```
Authorization: Bearer {user_token}
```

**Query Parameters:**
- `page` (optional): Page number for pagination (default: 1)

**Success Response (200):**
```json
{
    "success": true,
    "data": {
        "current_page": 1,
        "data": [
            {
                "id": 1,
                "user_id": 1,
                "service_id": 1,
                "amount": 25.00,
                "service_type": "farmer_id",
                "request_data": {
                    "aadhar": "576109808884"
                },
                "response_data": {
                    "status": 200,
                    "data": {
                        "farmerID": "45874742709",
                        "farmerAadharNumber": "576109808884"
                    }
                },
                "status": "success",
                "error_message": null,
                "created_at": "2025-12-05T12:00:00.000000Z",
                "service": {
                    "id": 1,
                    "name": "Farmer ID",
                    "path": "/user/farmerid"
                }
            }
        ],
        "per_page": 20,
        "total": 1
    }
}
```

---

## Admin Service Management (with Cost)

### Add Service with Cost

**Endpoint:** `POST /api/admin/service`

**Request Body:**
```json
{
    "name": "Farmer ID",
    "path": "/user/farmerid",
    "is_coming_soon": false,
    "cost": 25.00
}
```

**Parameters:**
- `name` (required): Service name
- `path` (required): Service path (must start with `/`)
- `is_coming_soon` (optional): Boolean, default: false
- `cost` (optional): Decimal, service cost in rupees. Default: 0.00

**Success Response:**
```json
{
    "success": true,
    "message": "Service added successfully",
    "data": {
        "id": 1,
        "name": "Farmer ID",
        "path": "/user/farmerid",
        "is_coming_soon": false,
        "cost": 25.00,
        "created_by": 1,
        "created_at": "2025-12-05T12:00:00.000000Z",
        "updated_at": "2025-12-05T12:00:00.000000Z"
    }
}
```

### Update Service Cost

**Endpoint:** `PUT /api/admin/service/{id}`

**Request Body:**
```json
{
    "cost": 30.00
}
```

---

## Error Responses

### 401 Unauthorized
```json
{
    "success": false,
    "message": "Unauthorized. Please login first."
}
```

### 404 Service Not Found
```json
{
    "success": false,
    "message": "Farmer ID service not found. Please contact admin."
}
```

### 500 Server Error
```json
{
    "success": false,
    "message": "An error occurred while verifying Farmer ID. Please try again later.",
    "error": "Connection timeout"
}
```

---

## Testing Examples

### cURL Examples

**1. Verify Farmer ID:**
```bash
curl -X POST "https://api.alldigtalseva.com/api/service/farmer-id/verify" \
  -H "Authorization: Bearer {user_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "aadhar": "576109808884"
  }'
```

**2. Check Transaction Status:**
```bash
curl -X GET "https://api.alldigtalseva.com/api/service/farmer-id/status/1" \
  -H "Authorization: Bearer {user_token}"
```

**3. Get Transaction History:**
```bash
curl -X GET "https://api.alldigtalseva.com/api/service/farmer-id/history" \
  -H "Authorization: Bearer {user_token}"
```

**4. Add Service with Cost (Admin):**
```bash
curl -X POST "https://api.alldigtalseva.com/api/admin/service" \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Farmer ID",
    "path": "/user/farmerid",
    "is_coming_soon": false,
    "cost": 25.00
  }'
```

---

## Notes

1. **Response Time**: ⚠️ **Important**: The external API (`https://api.farmeridonline.com/api/farmer/verify_card_details`) typically takes 1-2 minutes to respond. The HTTP timeout is set to 3 minutes (180 seconds). Please keep the connection open and wait for the response. If your request times out, you can use the transaction ID to check the status later using the status endpoint.

2. **Service Cost**: The service cost is configurable by admin. If not set, it defaults to ₹25.00 for Farmer ID service.

3. **Wallet Deduction**: The amount is deducted from user's wallet only if:
   - User has sufficient balance
   - External API call is successful (status 200)
   - Farmer data is retrieved successfully

4. **Transaction Tracking**: All service usage is tracked in `service_transactions` table, including:
   - Request parameters
   - Response data
   - Status (success/failed/pending)
   - Error messages (if any)

5. **External API**: The service calls `https://api.farmeridonline.com/api/farmer/verify_card_details` with the Aadhar number as a query parameter. This API may take 1-2 minutes to process.

6. **Aadhar Validation**: Aadhar number must be exactly 12 digits and contain only numbers.

7. **Service Availability**: The service must exist in the database and must not be marked as "coming soon" for the API to work.

8. **Status Checking**: If your initial request times out or you want to check the status of a previous request, use the status endpoint with the transaction ID returned in the response.

---

## Database Schema

### services (updated)
- `id`: Primary key
- `name`: Service name
- `path`: Service path (unique)
- `is_coming_soon`: Boolean
- `cost`: Decimal (10,2) - Service cost in rupees
- `created_by`: Admin ID (foreign key)
- `timestamps`

### service_transactions
- `id`: Primary key
- `user_id`: User ID (foreign key)
- `service_id`: Service ID (foreign key)
- `amount`: Amount deducted
- `service_type`: Type of service (e.g., "farmer_id")
- `request_data`: JSON - Request parameters
- `response_data`: JSON - API response
- `status`: Enum (success, failed, pending)
- `error_message`: Text - Error details if failed
- `timestamps`

---

## Support

For issues or questions, please contact the development team.


