Integration API Guide

Complete documentation for IHMS Integration API

Authentication Required

Getting Started

How to Obtain API Access

  1. Contact System Administrator: Request API access credentials by contacting the IHMS system administrator.
  2. Receive Credentials: You will receive a unique Username and Password for your organization.
  3. Generate Token: Use the authentication endpoint to obtain a Bearer token.
  4. Make API Calls: Include the Bearer token in all subsequent API requests.
Important Security Notes:
  • Keep your credentials secure and never share them publicly
  • Tokens expire after 8 hours - you'll need to refresh them
  • All API endpoints require HTTPS in production

Base URL

https://ukffda.in/api/integration

Authentication

POST /auth/token

Obtain a JWT Bearer token for authenticating subsequent API requests.

Request Body

Parameter Type Required Description
username string REQUIRED Your API username provided by admin
password string REQUIRED Your API password provided by admin 
// Using Fetch API
fetch('https://ukffda.in/api/integration/auth/token', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        username: 'your_username',
        password: 'your_password'
    })
})
.then(response => response.json())
.then(data => {
    console.log('Token:', data.token);
    localStorage.setItem('ihms_token', data.token);
})
.catch(error => console.error('Error:', error));
<?php
$url = 'https://ukffda.in/api/integration/auth/token';
$data = array(
    'username' => 'your_username',
    'password' => 'your_password'
);

$options = array(
    'http' => array(
        'header'  => "Content-type: application/json\r\n",
        'method'  => 'POST',
        'content' => json_encode($data)
    )
);

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result);

echo "Token: " . $response->token;
?>
// Using OkHttp (recommended for Android)
OkHttpClient client = new OkHttpClient();
MediaType JSON = MediaType.parse("application/json; charset=utf-8");

JSONObject json = new JSONObject();
json.put("username", "your_username");
json.put("password", "your_password");

RequestBody body = RequestBody.create(JSON, json.toString());
Request request = new Request.Builder()
    .url("https://ukffda.in/api/integration/auth/token")
    .post(body)
    .build();

client.newCall(request).enqueue(new Callback() {
    @Override
    public void onResponse(Call call, Response response) throws IOException {
        String responseData = response.body().string();
        JSONObject jsonResponse = new JSONObject(responseData);
        String token = jsonResponse.getString("token");
        Log.d("IHMS", "Token: " + token);
    }
});

Success Response (200 OK)

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "clientName": "Your Organization Name",
    "expiresAt": "2024-01-15T16:30:00Z"
}
Using the Token: Include the token in the Authorization header of all subsequent requests: Authorization: Bearer {your_token_here}

Get All Hatcheries

GET /data/hatcheries

Retrieve a list of all active hatcheries with their basic information including location details.

fetch('https://ukffda.in/api/integration/data/hatcheries', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer ' + localStorage.getItem('ihms_token')
    }
})
.then(response => response.json())
.then(data => {
    console.log('Hatcheries:', data);
    // Process hatcheries list
})
.catch(error => console.error('Error:', error));
<?php
$token = 'your_jwt_token_here';
$url = 'https://ukffda.in/api/integration/data/hatcheries';

$options = array(
    'http' => array(
        'header'  => "Authorization: Bearer $token\r\n",
        'method'  => 'GET'
    )
);

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$hatcheries = json_decode($result);

foreach($hatcheries as $hatchery) {
    echo $hatchery->hatcheryName . "\n";
}
?>
String token = "your_jwt_token_here";
Request request = new Request.Builder()
    .url("https://ukffda.in/api/integration/data/hatcheries")
    .addHeader("Authorization", "Bearer " + token)
    .get()
    .build();

client.newCall(request).enqueue(new Callback() {
    @Override
    public void onResponse(Call call, Response response) throws IOException {
        String responseData = response.body().string();
        JSONArray hatcheries = new JSONArray(responseData);
        // Process hatcheries data
    }
});

Success Response (200 OK)

[
    {
        "hatcheryId": 1,
        "hatcheryName": "Rishikesh Fish Hatchery",
        "address": "123 Main Street, Rishikesh",
        "districtName": "Dehradun",
        "blockName": "Rishikesh",
        "latitude": 30.0869,
        "longitude": 78.2676,
        "hatcheryEmail": "rishikesh@hatchery.com",
        "isActive": true
    },
    {
        "hatcheryId": 2,
        "hatcheryName": "Haridwar Aquaculture Center",
        "address": "456 River Road, Haridwar",
        "districtName": "Haridwar",
        "blockName": "Haridwar",
        "latitude": 29.9457,
        "longitude": 78.1642,
        "hatcheryEmail": "haridwar@hatchery.com",
        "isActive": true
    }
]

Get Hatchery Profile

GET /data/hatcheries/{id}/profile

Get comprehensive profile information for a specific hatchery including infrastructure, energy/water sources, species, and production stages.

Path Parameters

Parameter Type Description
id integer The unique ID of the hatchery 
const hatcheryId = 1;
fetch(`https://ukffda.in/api/integration/data/hatcheries/${hatcheryId}/profile`, {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer ' + localStorage.getItem('ihms_token')
    }
})
.then(response => response.json())
.then(data => {
    console.log('Hatchery Profile:', data);
    console.log('Infrastructure:', data.infrastructure);
    console.log('Species:', data.speciesAndStages);
});
<?php
$token = 'your_jwt_token_here';
$hatcheryId = 1;
$url = "https://ukffda.in/api/integration/data/hatcheries/$hatcheryId/profile";

$options = array(
    'http' => array(
        'header'  => "Authorization: Bearer $token\r\n",
        'method'  => 'GET'
    )
);

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$profile = json_decode($result);

echo "Hatchery: " . $profile->hatcheryName;
?>
int hatcheryId = 1;
String token = "your_jwt_token_here";
Request request = new Request.Builder()
    .url("https://ukffda.in/api/integration/data/hatcheries/" + hatcheryId + "/profile")
    .addHeader("Authorization", "Bearer " + token)
    .get()
    .build();

client.newCall(request).enqueue(new Callback() {
    @Override
    public void onResponse(Call call, Response response) throws IOException {
        String responseData = response.body().string();
        JSONObject profile = new JSONObject(responseData);
        String name = profile.getString("hatcheryName");
    }
});

Success Response (200 OK)

{
    "hatcheryId": 1,
    "hatcheryName": "Rishikesh Fish Hatchery",
    "address": "123 Main Street",
    "districtName": "Dehradun",
    "blockName": "Rishikesh",
    "latitude": 30.0869,
    "longitude": 78.2676,
    "infrastructure": {
        "overheadTankCapacityLitres": 50000,
        "noOfBreedingTanks": 5,
        "noOfIncubationTanks": 10,
        "noOfNurseryPonds": 8,
        "noOfBroodstockPonds": 3,
        "aerationSystemAvailable": true,
        "noOfAirBlowers": 4,
        "laboratoryAvailable": true,
        "quarantineFacilityAvailable": true
    },
    "energySources": ["Grid Electricity", "Solar"],
    "waterSources": ["River", "Borewell"],
    "speciesAndStages": [
        {
            "speciesId": 1,
            "speciesName": "Rohu",
            "category": "Indian Major Carp",
            "activeStages": [
                { "stageId": 1, "stageName": "Spawn" },
                { "stageId": 2, "stageName": "Fry" },
                { "stageId": 3, "stageName": "Fingerling" }
            ]
        }
    ]
}

Get Production Transactions

GET /data/hatcheries/{id}/production

Retrieve seed production and broodstock transaction records for a specific hatchery with optional date filtering.

Path Parameters

Parameter Type Required Description
id integer REQUIRED The unique ID of the hatchery

Query Parameters

Parameter Type Required Description
from date OPTIONAL Start date (YYYY-MM-DD format)
to date OPTIONAL End date (YYYY-MM-DD format) 
const hatcheryId = 1;
const from = '2024-01-01';
const to = '2024-12-31';
const url = `https://ukffda.in/api/integration/data/hatcheries/${hatcheryId}/production?from=${from}&to=${to}`;

fetch(url, {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer ' + localStorage.getItem('ihms_token')
    }
})
.then(response => response.json())
.then(data => {
    console.log('Seed Production:', data.seedProduction);
    console.log('Broodstock:', data.brooderTransactions);
});
<?php
$token = 'your_jwt_token_here';
$hatcheryId = 1;
$from = '2024-01-01';
$to = '2024-12-31';
$url = "https://ukffda.in/api/integration/data/hatcheries/$hatcheryId/production?from=$from&to=$to";

$options = array(
    'http' => array(
        'header'  => "Authorization: Bearer $token\r\n",
        'method'  => 'GET'
    )
);

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$production = json_decode($result);
?>
int hatcheryId = 1;
String from = "2024-01-01";
String to = "2024-12-31";
String url = "https://ukffda.in/api/integration/data/hatcheries/" + 
             hatcheryId + "/production?from=" + from + "&to=" + to;

Request request = new Request.Builder()
    .url(url)
    .addHeader("Authorization", "Bearer " + token)
    .get()
    .build();

client.newCall(request).enqueue(new Callback() {
    @Override
    public void onResponse(Call call, Response response) throws IOException {
        String responseData = response.body().string();
        JSONObject production = new JSONObject(responseData);
    }
});

Success Response (200 OK)

{
    "hatcheryId": 1,
    "hatcheryName": "Rishikesh Fish Hatchery",
    "seedProduction": [
        {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "speciesName": "Rohu",
            "stageName": "Fry",
            "productionMonth": 3,
            "productionYear": 2024,
            "quantity": 50000,
            "addRemove": "Add",
            "fYear": 2024,
            "remarks": "Good production batch",
            "lastModifiedOn": "2024-03-15T10:30:00Z"
        }
    ],
    "brooderTransactions": [
        {
            "id": "987e6543-e21b-98d3-b654-123456789abc",
            "speciesName": "Catla",
            "maleCount": 10,
            "femaleCount": 15,
            "avgMaleWeightKg": 2.5,
            "avgFemaleWeightKg": 3.0,
            "productionMonth": 2,
            "productionYear": 2024,
            "addRemove": "Add",
            "fYear": 2024,
            "remarks": "Healthy broodstock",
            "lastModifiedOn": "2024-02-20T14:15:00Z"
        }
    ]
}

Get Farmers by Hatchery

GET /data/hatcheries/{id}/farmers

Retrieve all farmers who have active accounts with a specific hatchery.

Path Parameters

Parameter Type Description
id integer The unique ID of the hatchery 
const hatcheryId = 1;
fetch(`https://ukffda.in/api/integration/data/hatcheries/${hatcheryId}/farmers`, {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer ' + localStorage.getItem('ihms_token')
    }
})
.then(response => response.json())
.then(farmers => {
    farmers.forEach(farmer => {
        console.log(`${farmer.name} - Balance: ${farmer.currentBalance}`);
    });
});
<?php
$token = 'your_jwt_token_here';
$hatcheryId = 1;
$url = "https://ukffda.in/api/integration/data/hatcheries/$hatcheryId/farmers";

$options = array(
    'http' => array(
        'header'  => "Authorization: Bearer $token\r\n",
        'method'  => 'GET'
    )
);

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$farmers = json_decode($result);
?>
int hatcheryId = 1;
Request request = new Request.Builder()
    .url("https://ukffda.in/api/integration/data/hatcheries/" + hatcheryId + "/farmers")
    .addHeader("Authorization", "Bearer " + token)
    .get()
    .build();

client.newCall(request).enqueue(new Callback() {
    @Override
    public void onResponse(Call call, Response response) throws IOException {
        String responseData = response.body().string();
        JSONArray farmers = new JSONArray(responseData);
    }
});

Success Response (200 OK)

[
    {
        "farmerId": 101,
        "farmerCode": "F2024001",
        "name": "Ramesh Kumar",
        "mobile": "9876543210",
        "currentBalance": 5000.00,
        "accountActive": true
    },
    {
        "farmerId": 102,
        "farmerCode": "F2024002",
        "name": "Suresh Singh",
        "mobile": "9876543211",
        "currentBalance": -1500.00,
        "accountActive": true
    }
]

Get Sales Orders

GET /data/hatcheries/{id}/sales

Retrieve all sale orders for a specific hatchery with optional date range filtering.

Path Parameters

Parameter Type Required Description
id integer REQUIRED The unique ID of the hatchery

Query Parameters

Parameter Type Required Description
from date OPTIONAL Start date (YYYY-MM-DD format)
to date OPTIONAL End date (YYYY-MM-DD format) 
const hatcheryId = 1;
const from = '2024-01-01';
const to = '2024-12-31';
const url = `https://ukffda.in/api/integration/data/hatcheries/${hatcheryId}/sales?from=${from}&to=${to}`;

fetch(url, {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer ' + localStorage.getItem('ihms_token')
    }
})
.then(response => response.json())
.then(orders => {
    orders.forEach(order => {
        console.log(`Order #${order.saleOrderId} - ${order.farmerName} - ₹${order.totalAmount}`);
    });
});
<?php
$token = 'your_jwt_token_here';
$hatcheryId = 1;
$from = '2024-01-01';
$to = '2024-12-31';
$url = "https://ukffda.in/api/integration/data/hatcheries/$hatcheryId/sales?from=$from&to=$to";

$options = array(
    'http' => array(
        'header'  => "Authorization: Bearer $token\r\n",
        'method'  => 'GET'
    )
);

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$orders = json_decode($result);
?>
int hatcheryId = 1;
String from = "2024-01-01";
String to = "2024-12-31";
String url = "https://ukffda.in/api/integration/data/hatcheries/" + 
             hatcheryId + "/sales?from=" + from + "&to=" + to;

Request request = new Request.Builder()
    .url(url)
    .addHeader("Authorization", "Bearer " + token)
    .get()
    .build();

client.newCall(request).enqueue(new Callback() {
    @Override
    public void onResponse(Call call, Response response) throws IOException {
        String responseData = response.body().string();
        JSONArray orders = new JSONArray(responseData);
    }
});

Success Response (200 OK)

[
    {
        "saleOrderId": 1001,
        "farmerId": 101,
        "farmerCode": "F2024001",
        "farmerName": "Ramesh Kumar",
        "saleDate": "2024-03-15T00:00:00",
        "totalAmount": 15000.00,
        "paymentMode": "Cash",
        "items": [
            {
                "itemId": 1,
                "speciesName": "Rohu",
                "stage": "Fingerling",
                "quantity": 5000,
                "rate": 2.50,
                "amount": 12500.00
            },
            {
                "itemId": 2,
                "speciesName": "Catla",
                "stage": "Fry",
                "quantity": 1000,
                "rate": 2.50,
                "amount": 2500.00
            }
        ]
    }
]

Get All Farmers

GET /data/farmers

Retrieve complete profiles of all active farmers in the system with their mapped species.

fetch('https://ukffda.in/api/integration/data/farmers', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer ' + localStorage.getItem('ihms_token')
    }
})
.then(response => response.json())
.then(farmers => {
    farmers.forEach(farmer => {
        console.log(`${farmer.name} - ${farmer.districtName} - Species: ${farmer.species.join(', ')}`);
    });
});
<?php
$token = 'your_jwt_token_here';
$url = 'https://ukffda.in/api/integration/data/farmers';

$options = array(
    'http' => array(
        'header'  => "Authorization: Bearer $token\r\n",
        'method'  => 'GET'
    )
);

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$farmers = json_decode($result);

foreach($farmers as $farmer) {
    echo $farmer->name . " - " . $farmer->mobile . "\n";
}
?>
Request request = new Request.Builder()
    .url("https://ukffda.in/api/integration/data/farmers")
    .addHeader("Authorization", "Bearer " + token)
    .get()
    .build();

client.newCall(request).enqueue(new Callback() {
    @Override
    public void onResponse(Call call, Response response) throws IOException {
        String responseData = response.body().string();
        JSONArray farmers = new JSONArray(responseData);

        for (int i = 0; i < farmers.length(); i++) {
            JSONObject farmer = farmers.getJSONObject(i);
            String name = farmer.getString("name");
            String mobile = farmer.getString("mobile");
        }
    }
});

Success Response (200 OK)

[
    {
        "farmerId": 101,
        "farmerCode": "F2024001",
        "name": "Ramesh Kumar",
        "fatherName": "Suresh Kumar",
        "mobile": "9876543210",
        "aadhaar": "123456789012",
        "address": "Village Mainpur, Rishikesh",
        "districtName": "Dehradun",
        "blockName": "Rishikesh",
        "isActive": true,
        "createdOn": "2024-01-15T00:00:00",
        "isMobileVerified": true,
        "species": ["Rohu", "Catla", "Mrigal"]
    },
    {
        "farmerId": 102,
        "farmerCode": "F2024002",
        "name": "Suresh Singh",
        "fatherName": "Mahesh Singh",
        "mobile": "9876543211",
        "aadhaar": "123456789013",
        "address": "Village Haridwar Kalan",
        "districtName": "Haridwar",
        "blockName": "Haridwar",
        "isActive": true,
        "createdOn": "2024-01-20T00:00:00",
        "isMobileVerified": true,
        "species": ["Common Carp", "Grass Carp"]
    }
]

Get Farmer Purchase History

GET /data/farmers/{id}/purchases

Retrieve complete purchase history for a specific farmer with optional date filtering.

Path Parameters

Parameter Type Required Description
id integer REQUIRED The unique ID of the farmer

Query Parameters

Parameter Type Required Description
from date OPTIONAL Start date (YYYY-MM-DD format)
to date OPTIONAL End date (YYYY-MM-DD format) 
const farmerId = 101;
const from = '2024-01-01';
const to = '2024-12-31';
const url = `https://ukffda.in/api/integration/data/farmers/${farmerId}/purchases?from=${from}&to=${to}`;

fetch(url, {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer ' + localStorage.getItem('ihms_token')
    }
})
.then(response => response.json())
.then(data => {
    console.log(`Farmer: ${data.farmerName}`);
    console.log(`Total Orders: ${data.orders.length}`);
    data.orders.forEach(order => {
        console.log(`Order #${order.saleOrderId} - ₹${order.totalAmount}`);
    });
});
<?php
$token = 'your_jwt_token_here';
$farmerId = 101;
$from = '2024-01-01';
$to = '2024-12-31';
$url = "https://ukffda.in/api/integration/data/farmers/$farmerId/purchases?from=$from&to=$to";

$options = array(
    'http' => array(
        'header'  => "Authorization: Bearer $token\r\n",
        'method'  => 'GET'
    )
);

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$purchases = json_decode($result);

echo "Farmer: " . $purchases->farmerName;
?>
int farmerId = 101;
String from = "2024-01-01";
String to = "2024-12-31";
String url = "https://ukffda.in/api/integration/data/farmers/" + 
             farmerId + "/purchases?from=" + from + "&to=" + to;

Request request = new Request.Builder()
    .url(url)
    .addHeader("Authorization", "Bearer " + token)
    .get()
    .build();

client.newCall(request).enqueue(new Callback() {
    @Override
    public void onResponse(Call call, Response response) throws IOException {
        String responseData = response.body().string();
        JSONObject purchases = new JSONObject(responseData);
        String farmerName = purchases.getString("farmerName");
        JSONArray orders = purchases.getJSONArray("orders");
    }
});

Success Response (200 OK)

{
    "farmerId": 101,
    "farmerCode": "F2024001",
    "farmerName": "Ramesh Kumar",
    "orders": [
        {
            "saleOrderId": 1001,
            "farmerId": 101,
            "farmerCode": "F2024001",
            "farmerName": "Ramesh Kumar",
            "saleDate": "2024-03-15T00:00:00",
            "totalAmount": 15000.00,
            "paymentMode": "Cash",
            "items": [
                {
                    "itemId": 1,
                    "speciesName": "Rohu",
                    "stage": "Fingerling",
                    "quantity": 5000,
                    "rate": 2.50,
                    "amount": 12500.00
                }
            ]
        }
    ]
}
Need Help?

If you encounter any issues or need additional API endpoints, please contact the IHMS system administrator at admin@ukffda.in