Ujuzi Kilimo API Documentation

Base URL

Authentication

Most endpoints require authentication. Use the login endpoint to obtain an access token:

POST https://farmsuitedev.ujuzikilimo.com/api/login
Content-Type: application/json

{
    "email": "[email protected]",
    "password": "your-password"
}

Response Format

All API responses are returned in JSON format:

{
    "success": true,
    "data": {
        // Response data here
    },
    "message": "Success message"
}

Error Handling

Error responses include appropriate HTTP status codes and error messages:

{
    "success": false,
    "error": "Error description",
    "code": 400
}

PHP Example

<?php
// Generate authentication token
$apiKey = 'mobile_your_api_key_here';
$baseUrl = 'https://farmsuitedev.ujuzikilimo.com/api/v1/auth';

$data = [
    'api_key' => $apiKey,
    'email' => '[email protected]',
    'password' => 'userpassword',
    'device_name' => 'My Mobile App',
    'expires_in' => 3600 // 1 hour (optional)
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/generate-token');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $result = json_decode($response, true);
    $token = $result['data']['token'];
    echo "Token: " . $token;
} else {
    echo "Error: " . $response;
}
?>

Expected Response

{
    "success": true,
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "token_type": "Bearer",
        "expires_at": "2024-01-01T12:00:00.000000Z",
        "api_key": "mobile_your_api_key_here"
    },
    "message": "Token generated successfully"
}

PHP Example - Making API Calls

<?php
// Use token for API requests
$token = 'your_generated_token_here';
$baseUrl = 'https://farmsuitedev.ujuzikilimo.com/api';

function makeApiRequest($endpoint, $token, $method = 'GET', $data = null) {
    global $baseUrl;
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $baseUrl . $endpoint);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json',
        'Accept: application/json'
    ]);
    
    if ($method === 'POST' && $data) {
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    }
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    return [
        'status_code' => $httpCode,
        'response' => json_decode($response, true)
    ];
}

// Example: Get farmers list
$result = makeApiRequest('/farmers', $token);
if ($result['status_code'] === 200) {
    $farmers = $result['response']['data'];
    foreach ($farmers as $farmer) {
        echo "Farmer: " . $farmer['name'] . "\n";
    }
} else {
    echo "Error: " . $result['response']['error'];
}
?>

Complete Integration Class

<?php
class UjuziKilimoAPI {
    private $baseUrl;
    private $apiKey;
    private $token;
    
    public function __construct($apiKey, $baseUrl = 'https://farmsuitedev.ujuzikilimo.com/api') {
        $this->apiKey = $apiKey;
        $this->baseUrl = $baseUrl;
    }
    
    public function generateToken($deviceName = 'Mobile App', $expiresIn = 3600) {
        $data = [
            'api_key' => $this->apiKey,
            'device_name' => $deviceName,
            'expires_in' => $expiresIn
        ];
        
        $response = $this->makeRequest('/v1/auth/generate-token', 'POST', $data, false);
        
        if ($response['status_code'] === 200) {
            $this->token = $response['response']['data']['token'];
            return $this->token;
        }
        
        throw new Exception('Failed to generate token: ' . $response['response']['error']);
    }
    
    public function getFarmers() {
        return $this->makeRequest('/farmers');
    }
    
    public function getFarms($farmerId = null) {
        $endpoint = $farmerId ? "/farmers/{$farmerId}/farms" : '/farms';
        return $this->makeRequest($endpoint);
    }
    
    public function getSoilTests($farmId = null) {
        $endpoint = $farmId ? "/farms/{$farmId}/soil-tests" : '/soil-tests';
        return $this->makeRequest($endpoint);
    }
    
    private function makeRequest($endpoint, $method = 'GET', $data = null, $requiresAuth = true) {
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $this->baseUrl . $endpoint);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        
        $headers = [
            'Content-Type: application/json',
            'Accept: application/json'
        ];
        
        if ($requiresAuth && $this->token) {
            $headers[] = 'Authorization: Bearer ' . $this->token;
        }
        
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        
        if ($method === 'POST' && $data) {
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        }
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        return [
            'status_code' => $httpCode,
            'response' => json_decode($response, true)
        ];
    }
}

// Usage example
try {
    $api = new UjuziKilimoAPI('mobile_your_api_key_here');
    $token = $api->generateToken('My Mobile App');
    
    $farmers = $api->getFarmers();
    if ($farmers['status_code'] === 200) {
        foreach ($farmers['response']['data'] as $farmer) {
            echo "Farmer: " . $farmer['name'] . "\n";
        }
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}
?>

Refresh Token

<?php
// Refresh existing token
$data = [
    'api_key' => $apiKey,
    'device_name' => 'My Mobile App',
    'expires_in' => 7200 // 2 hours
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/v1/auth/refresh-token');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $currentToken,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);
?>

Revoke Token

<?php
// Revoke token when done
$data = ['revoke_all' => true]; // or specific token_id

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/v1/auth/revoke-token');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);
?>