V2 Integration API

Step 1: Implement Receive Endpoint (Your Server)

# server.py - Flask Example
from flask import Flask, request, jsonify
from datetime import datetime
import os

app = Flask(__name__)

# ==========================================
# STEP 1: Implement endpoint to receive from Jenni Logistics
# ==========================================
@app.route('/v2/shipments/create', methods=['POST'])
def receive_shipments():
    print('📥 Received shipments from Jenni Logistics')
    
    try:
        # 1. Validate authentication
        auth_header = request.headers.get('Authorization', '')
        token = auth_header.replace('Bearer ', '')
        
        if not token or not is_valid_jenni_token(token):
            return jsonify({
                'success': False,
                'message': 'Invalid authentication token'
            }), 401

        # 2. Extract shipments from request
        data = request.get_json()
        system_code = data.get('system_code')
        shipments = data.get('shipments', [])
        
        print(f'System: {system_code}, Shipments: {len(shipments)}')

        # 3. Process and save shipments
        accepted_shipments = []
        rejected_shipments = []
        
        for shipment in shipments:
            try:
                # Check for duplicates
                if is_duplicate_shipment(shipment['shipment_number'], shipment['shipment_id']):
                    rejected_shipments.append({
                        'shipment_number': shipment['shipment_number'],
                        'shipment_id': shipment['shipment_id'],
                        'airway_bill_number': shipment.get('airway_bill_number'),
                        'reason': 'Shipment number already exists',
                        'error_code': 'DUPLICATE_SHIPMENT',
                        'field': 'shipment_number'
                    })
                    continue
                
                # Save to database
                saved_shipment = save_shipment_to_database(shipment)
                
                # Assign to driver
                assign_to_driver(saved_shipment)
                
                accepted_shipments.append({
                    'shipment_number': shipment['shipment_number'],
                    'shipment_id': shipment['shipment_id'],
                    'external_id': str(saved_shipment['id']),
                    'airway_bill_number': shipment.get('airway_bill_number')
                })
            except Exception as e:
                rejected_shipments.append({
                    'shipment_number': shipment['shipment_number'],
                    'shipment_id': shipment.get('shipment_id'),
                    'airway_bill_number': shipment.get('airway_bill_number'),
                    'reason': str(e),
                    'error_code': 'PROCESSING_ERROR',
                    'field': None
                })

        # 4. Return response (REQUIRED FORMAT)
        return jsonify({
            'success': len(accepted_shipments) > 0,
            'message': f'{len(accepted_shipments)} shipment(s) processed successfully' if accepted_shipments else 'All shipments failed to process',
            'timestamp': datetime.utcnow().isoformat() + 'Z',
            'accepted_shipments': accepted_shipments,
            'rejected_shipments': rejected_shipments,
            'summary': {
                'total_requested': len(shipments),
                'accepted_count': len(accepted_shipments),
                'rejected_count': len(rejected_shipments)
            }
        })

    except Exception as error:
        print(f'❌ Error receiving shipments: {error}')
        return jsonify({
            'success': False,
            'message': 'Internal server error',
            'timestamp': datetime.utcnow().isoformat() + 'Z'
        }), 500

def is_valid_jenni_token(token):
    """Validate token from Jenni Logistics"""
    return token == os.getenv('JENNI_AUTH_TOKEN')

def save_shipment_to_database(shipment):
    """Save shipment to your database"""
    # Your database logic here
    saved = {
        'id': 12345,
        'shipment_number': shipment['shipment_number'],
        'receiver_name': shipment['receiver_name'],
        'status': 'PENDING'
    }
    return saved

def assign_to_driver(shipment):
    """Assign shipment to available driver"""
    # Your assignment logic here
    pass

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=3000)
    print('✅ Server running on port 3000')
    print('📡 Waiting for shipments from Jenni Logistics...')

Step 2: Send Status Updates to Jenni Logistics Server

# status_updater.py - Send updates to Jenni Logistics server
import requests
from datetime import datetime, timedelta

JENNI_API_URL = 'https://jenni-api.com/api'
JENNI_USERNAME = 'your_username'
JENNI_PASSWORD = 'your_password'

auth_token = None
token_expiry = None

# ==========================================
# STEP 2: Login to Jenni Logistics
# ==========================================
def login_to_jenni():
    global auth_token, token_expiry
    
    try:
        response = requests.post(
            f'{JENNI_API_URL}/v2/auth/login',
            json={
                'username': JENNI_USERNAME,
                'password': JENNI_PASSWORD
            }
        )
        response.raise_for_status()
        data = response.json()
        
        auth_token = data['token']
        token_expiry = datetime.now() + timedelta(seconds=data['expires_in'])
        
        print('✅ Logged in to Jenni Logistics successfully')
        return auth_token
    except Exception as error:
        print(f'❌ Login failed: {error}')
        raise

def ensure_valid_token():
    """Ensure token is valid"""
    global auth_token, token_expiry
    if not auth_token or datetime.now() > (token_expiry - timedelta(minutes=5)):
        login_to_jenni()

# ==========================================
# STEP 3: Send status update
# ==========================================
def send_status_update(shipment_number, action, details=None):
    ensure_valid_token()
    
    if details is None:
        details = {}
    
    try:
        payload = {
            'system_code': 'YOUR_SYSTEM_CODE',
            'updates': [{
                'shipment_number': shipment_number,
                'action_code': action,
                'timestamp': datetime.utcnow().isoformat() + 'Z',
                **details
            }]
        }
        
        print(f'📤 Sending {action} update for {shipment_number}')
        
        response = requests.post(
            f'{JENNI_API_URL}/v2/push/update-status',
            json=payload,
            headers={
                'Authorization': f'Bearer {auth_token}',
                'Content-Type': 'application/json'
            }
        )
        response.raise_for_status()
        
        print('✅ Status update sent successfully')
        return response.json()
        
    except Exception as error:
        print(f'❌ Failed to send status update: {error}')
        raise

# ==========================================
# USAGE EXAMPLES
# ==========================================
def mark_as_delivered(shipment_number, driver_name):
    """Mark shipment as delivered"""
    return send_status_update(
        shipment_number,
        'SUCCESSFUL_DELIVERY',
        {
            'location': {
                'latitude': 33.312805,
                'longitude': 44.361488,
                'address': 'Baghdad, Al-Karrada'
            },
            'proof_of_delivery': {
                'images': ['https://your-cdn.com/proof/12345.jpg'],
                'receiver_name': 'Ahmed Mohammed',
                'delivery_time': datetime.utcnow().isoformat() + 'Z'
            },
            'notes': f'Delivered by driver: {driver_name}'
        }
    )

def mark_as_postponed(shipment_number, reason, postponed_date_id):
    """Mark shipment as postponed"""
    return send_status_update(
        shipment_number,
        'POSTPONED',
        {
            'postponed_reason': reason,
            'postponed_reason_en': 'Customer not available',
            'postponed_reason_ku': 'کڕیار بەردەست نییە',
            'postponed_date_id': postponed_date_id,  # ✅ REQUIRED: 1=tomorrow, 2=2 days, 3=3+ days
            'notes': 'Will retry delivery tomorrow'
        }
    )

def mark_as_returned(shipment_number, return_reason):
    """Mark shipment as returned"""
    return send_status_update(
        shipment_number,
        'RETURNED_WITH_AGENT',
        {
            'return_reason': return_reason,
            'return_reason_en': 'Customer refused',
            'return_reason_ku': 'کڕیار ڕەتکردەوە',
            'notes': 'Customer refused to receive'
        }
    )

# Example usage
if __name__ == '__main__':
    # Successful delivery
    mark_as_delivered('SHIP001', 'Driver Ali')
    
    # Postponed delivery
    mark_as_postponed('SHIP002', 'Customer not available')
    
    # Returned delivery
    mark_as_returned('SHIP003', 'Customer refused')

Step 1: Implement Receive Endpoint (Your Server)

<?php
// receive.php - Receive shipments from Jenni Logistics

header('Content-Type: application/json');

// ==========================================
// STEP 1: Implement /receive endpoint
// ==========================================
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    error_log('📥 Received shipments from Jenni Logistics');
    
    try {
        // 1. Validate authentication
        $headers = getallheaders();
        $authHeader = $headers['Authorization'] ?? '';
        $token = str_replace('Bearer ', '', $authHeader);
        
        if (empty($token) || !isValidJenniToken($token)) {
            http_response_code(401);
            echo json_encode([
                'success' => false,
                'message' => 'Invalid authentication token'
            ]);
            exit;
        }

        // 2. Extract shipments
        $data = json_decode(file_get_contents('php://input'), true);
        $systemCode = $data['system_code'] ?? '';
        $shipments = $data['shipments'] ?? [];
        
        error_log("System: $systemCode, Shipments: " . count($shipments));

        // 3. Process shipments
        $acceptedShipments = [];
        $rejectedShipments = [];
        
        foreach ($shipments as $shipment) {
            try {
                // Check if shipment already exists in your database
                if (shipmentExists($shipment['shipment_id'])) {
                    $rejectedShipments[] = [
                        'shipment_number' => $shipment['shipment_number'],
                        'shipment_id' => $shipment['shipment_id'],
                        'airway_bill_number' => $shipment['airway_bill_number'] ?? null,
                        'reason' => 'Shipment already exists in your system',
                        'error_code' => 'DUPLICATE_SHIPMENT',
                        'field' => 'shipment_number'
                    ];
                    continue;
                }
                
                // Save shipment to your database
                $savedShipment = saveToDatabase($shipment);
                
                // Assign shipment to your delivery driver
                assignToYourDriver($savedShipment);
                
                $acceptedShipments[] = [
                    'shipment_number' => $shipment['shipment_number'],
                    'shipment_id' => $shipment['shipment_id'],
                    'external_id' => (string)$savedShipment['id'],
                    'airway_bill_number' => $shipment['airway_bill_number'] ?? null
                ];
            } catch (Exception $e) {
                $rejectedShipments[] = [
                    'shipment_number' => $shipment['shipment_number'],
                    'shipment_id' => $shipment['shipment_id'] ?? null,
                    'airway_bill_number' => $shipment['airway_bill_number'] ?? null,
                    'reason' => $e->getMessage(),
                    'error_code' => 'PROCESSING_ERROR',
                    'field' => null
                ];
            }
        }

        // 4. Return response (REQUIRED FORMAT)
        echo json_encode([
            'success' => count($acceptedShipments) > 0,
            'message' => count($acceptedShipments) > 0 
                ? count($acceptedShipments) . ' shipment(s) processed successfully'
                : 'All shipments failed to process',
            'timestamp' => gmdate('Y-m-d\TH:i:s\Z'),
            'accepted_shipments' => $acceptedShipments,
            'rejected_shipments' => $rejectedShipments,
            'summary' => [
                'total_requested' => count($shipments),
                'accepted_count' => count($acceptedShipments),
                'rejected_count' => count($rejectedShipments)
            ]
        ]);

    } catch (Exception $error) {
        error_log('❌ Error receiving shipments: ' . $error->getMessage());
        http_response_code(500);
        echo json_encode([
            'success' => false,
            'message' => 'Internal server error',
            'timestamp' => gmdate('Y-m-d\TH:i:s\Z')
        ]);
    }
}

function isValidJenniToken($token) {
    return $token === getenv('JENNI_AUTH_TOKEN');
}

function saveToDatabase($shipment) {
    // Save shipment to your database
    // Return saved shipment with ID
    return [
        'id' => 12345,
        'shipment_number' => $shipment['shipment_number'],
        'status' => 'PENDING'
    ];
}

function assignToYourDriver($shipment) {
    // Your logic to assign shipment to your delivery driver
}
?>

Step 2: Send Status Updates to Jenni Logistics Server

<?php
// StatusUpdater.php - Send updates to Jenni Logistics server

class JenniStatusUpdater {
    private $apiUrl = 'https://jenni-api.com/api';  // Jenni Logistics server URL
    private $username;
    private $password;
    private $authToken = null;
    private $tokenExpiry = null;

    public function __construct($username, $password) {
        $this->username = $username;
        $this->password = $password;
    }

    // ==========================================
    // Login to Jenni Logistics server
    // ==========================================
    public function login() {
        $ch = curl_init($this->apiUrl . '/v2/auth/login');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'username' => $this->username,
            'password' => $this->password
        ]));

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

        if ($httpCode !== 200) {
            throw new Exception('Login failed: ' . $response);
        }

        $data = json_decode($response, true);
        $this->authToken = $data['token'];
        $this->tokenExpiry = time() + $data['expires_in'];

        error_log('✅ Logged in to Jenni Logistics successfully');
        return $this->authToken;
    }

    private function ensureValidToken() {
        if (!$this->authToken || time() > ($this->tokenExpiry - 300)) {
            $this->login();
        }
    }

    // ==========================================
    // STEP 3: Send status update
    // ==========================================
    public function sendStatusUpdate($shipmentNumber, $action, $details = []) {
        $this->ensureValidToken();

        $payload = [
            'system_code' => 'YOUR_SYSTEM_CODE',
            'updates' => [[
                'shipment_number' => $shipmentNumber,
                'action_code' => $action,
                'timestamp' => gmdate('Y-m-d\TH:i:s\Z')
            ] + $details]
        ];

        error_log("📤 Sending $action update for $shipmentNumber");

        $ch = curl_init($this->apiUrl . '/v2/push/update-status');
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json',
            'Authorization: Bearer ' . $this->authToken
        ]);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

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

        if ($httpCode !== 200) {
            throw new Exception('Failed to send status update: ' . $response);
        }

        error_log('✅ Status update sent successfully');
        return json_decode($response, true);
    }

    // ==========================================
    // USAGE EXAMPLES
    // ==========================================
    public function markAsDelivered($shipmentNumber, $driverName) {
        return $this->sendStatusUpdate(
            $shipmentNumber,
            'SUCCESSFUL_DELIVERY',
            [
                'location' => [
                    'latitude' => 33.312805,
                    'longitude' => 44.361488,
                    'address' => 'Baghdad, Al-Karrada'
                ],
                'proof_of_delivery' => [
                    'images' => ['https://your-cdn.com/proof/12345.jpg'],
                    'receiver_name' => 'Ahmed Mohammed',
                    'delivery_time' => gmdate('Y-m-d\TH:i:s\Z')
                ],
                'notes' => "Delivered by driver: $driverName"
            ]
        );
    }

    public function markAsPostponed($shipmentNumber, $reason, $postponedDateId) {
        return $this->sendStatusUpdate(
            $shipmentNumber,
            'POSTPONED',
            [
                'postponed_reason' => $reason,
                'postponed_reason_en' => 'Customer not available',
                'postponed_reason_ku' => 'کڕیار بەردەست نییە',
                'postponed_date_id' => $postponedDateId,  // ✅ REQUIRED: 1=tomorrow, 2=2 days, 3=3+ days
                'notes' => 'Will retry delivery tomorrow'
            ]
        );
    }

    public function markAsReturned($shipmentNumber, $returnReason) {
        return $this->sendStatusUpdate(
            $shipmentNumber,
            'RETURNED_WITH_AGENT',
            [
                'return_reason' => $returnReason,
                'return_reason_en' => 'Customer refused',
                'return_reason_ku' => 'کڕیار ڕەتکردەوە',
                'notes' => 'Customer refused to receive'
            ]
        );
    }
}

// Example usage
$updater = new JenniStatusUpdater('your_username', 'your_password');

// Successful delivery
$updater->markAsDelivered('SHIP001', 'Driver Ali');

// Postponed delivery
$updater->markAsPostponed('SHIP002', 'Customer not available');

// Returned delivery
$updater->markAsReturned('SHIP003', 'Customer refused');
?>

Step 1: Implement Receive Endpoint (Your Server)

// ShipmentReceiveController.java - Spring Boot Example
@RestController
@RequestMapping("/v2/shipments")
@Slf4j
public class ShipmentReceiveController {

    @Autowired
    private ShipmentService shipmentService;

    // ==========================================
    // STEP 1: Implement /receive endpoint
    // ==========================================
    @PostMapping("/receive")
    public ResponseEntity<ReceiveResponse> receiveShipments(
            @RequestHeader("Authorization") String authHeader,
            @RequestBody ReceiveRequest request) {
        
        log.info("📥 Received shipments from Jenni Logistics");
        
        try {
            // 1. Validate authentication
            String token = authHeader.replace("Bearer ", "");
            if (!isValidJenniToken(token)) {
                return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
                    .body(ReceiveResponse.error("Invalid authentication token"));
            }

            // 2. Extract shipments
            String systemCode = request.getSystemCode();
            List<Shipment> shipments = request.getShipments();
            log.info("System: {}, Shipments: {}", systemCode, shipments.size());

            // 3. Process shipments
            List<Map<String, Object>> acceptedShipments = new ArrayList<>();
            List<Map<String, Object>> rejectedShipments = new ArrayList<>();
            
            for (Shipment shipment : shipments) {
                try {
                    // Check if shipment already exists in your database
                    if (shipmentService.shipmentExists(
                            shipment.getShipmentId())) {
                        Map<String, Object> rejected = new HashMap<>();
                        rejected.put("shipment_number", shipment.getShipmentNumber());
                        rejected.put("shipment_id", shipment.getShipmentId());
                        rejected.put("airway_bill_number", shipment.getAirwayBillNumber());
                        rejected.put("reason", "Shipment number already exists");
                        rejected.put("error_code", "DUPLICATE_SHIPMENT");
                        rejected.put("field", "shipment_number");
                        rejectedShipments.add(rejected);
                        continue;
                    }
                    
                    // Save to database
                    Shipment saved = shipmentService.saveShipment(shipment);
                    
                    // Assign shipment to your delivery driver
                    shipmentService.assignToYourDriver(saved);
                    
                    // Add to accepted
                    Map<String, Object> accepted = new HashMap<>();
                    accepted.put("shipment_number", shipment.getShipmentNumber());
                    accepted.put("shipment_id", shipment.getShipmentId());
                    accepted.put("external_id", String.valueOf(saved.getId()));
                    accepted.put("airway_bill_number", shipment.getAirwayBillNumber());
                    acceptedShipments.add(accepted);
                    
                } catch (Exception e) {
                    Map<String, Object> rejected = new HashMap<>();
                    rejected.put("shipment_number", shipment.getShipmentNumber());
                    rejected.put("shipment_id", shipment.getShipmentId());
                    rejected.put("airway_bill_number", shipment.getAirwayBillNumber());
                    rejected.put("reason", e.getMessage());
                    rejected.put("error_code", "PROCESSING_ERROR");
                    rejected.put("field", null);
                    rejectedShipments.add(rejected);
                }
            }

            // 4. Return response (REQUIRED FORMAT)
            Map<String, Object> response = new HashMap<>();
            response.put("success", !acceptedShipments.isEmpty());
            response.put("message", !acceptedShipments.isEmpty() 
                ? String.format("%d shipment(s) processed successfully", acceptedShipments.size())
                : "All shipments failed to process");
            response.put("timestamp", Instant.now().toString());
            response.put("accepted_shipments", acceptedShipments);
            response.put("rejected_shipments", rejectedShipments);
            response.put("summary", Map.of(
                "total_requested", shipments.size(),
                "accepted_count", acceptedShipments.size(),
                "rejected_count", rejectedShipments.size()
            ));
                
            return ResponseEntity.ok(response);

        } catch (Exception error) {
            log.error("❌ Error receiving shipments", error);
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(ReceiveResponse.error("Internal server error"));
        }
    }

    private boolean isValidJenniToken(String token) {
        String expectedToken = System.getenv("JENNI_AUTH_TOKEN");
        return token != null && token.equals(expectedToken);
    }
}

Step 2: Send Status Updates to Jenni Logistics Server

// JenniStatusUpdater.java - Send updates to Jenni Logistics server
@Service
@Slf4j
public class JenniStatusUpdater {

    private static final String JENNI_API_URL = "https://jenni-api.com/api";
    
    @Value("${jenni.username}")
    private String username;
    
    @Value("${jenni.password}")
    private String password;
    
    private String authToken;
    private Instant tokenExpiry;
    
    private final RestTemplate restTemplate;

    public JenniStatusUpdater(RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }

    // ==========================================
    // STEP 2: Login to Jenni Logistics
    // ==========================================
    public void login() {
        try {
            LoginRequest loginRequest = new LoginRequest(username, password);
            
            ResponseEntity<LoginResponse> response = restTemplate.postForEntity(
                JENNI_API_URL + "/v2/auth/login",
                loginRequest,
                LoginResponse.class
            );

            LoginResponse data = response.getBody();
            this.authToken = data.getToken();
            this.tokenExpiry = Instant.now().plusSeconds(data.getExpiresIn());

            log.info("✅ Logged in to Jenni Logistics successfully");
        } catch (Exception e) {
            log.error("❌ Login failed", e);
            throw new RuntimeException("Login failed", e);
        }
    }

    private void ensureValidToken() {
        if (authToken == null || Instant.now().isAfter(tokenExpiry.minusSeconds(300))) {
            login();
        }
    }

    // ==========================================
    // STEP 3: Send status update
    // ==========================================
    public StatusUpdateResponse sendStatusUpdate(
            String shipmentNumber, 
            String action, 
            Map<String, Object> details) {
        
        ensureValidToken();

        try {
            Map<String, Object> update = new HashMap<>();
            update.put("shipment_number", shipmentNumber);
            update.put("action_code", action);
            update.put("timestamp", Instant.now().toString());
            update.putAll(details);

            Map<String, Object> payload = Map.of(
                "system_code", "YOUR_SYSTEM_CODE",
                "updates", List.of(update)
            );

            log.info("📤 Sending {} update for {}", action, shipmentNumber);

            HttpHeaders headers = new HttpHeaders();
            headers.setBearerAuth(authToken);
            headers.setContentType(MediaType.APPLICATION_JSON);

            HttpEntity<Map<String, Object>> request = new HttpEntity<>(payload, headers);

            ResponseEntity<StatusUpdateResponse> response = restTemplate.postForEntity(
                JENNI_API_URL + "/v2/push/update-status",
                request,
                StatusUpdateResponse.class
            );

            log.info("✅ Status update sent successfully");
            return response.getBody();

        } catch (Exception e) {
            log.error("❌ Failed to send status update", e);
            throw new RuntimeException("Failed to send status update", e);
        }
    }

    // ==========================================
    // USAGE EXAMPLES
    // ==========================================
    public StatusUpdateResponse markAsDelivered(String shipmentNumber, String driverName) {
        Map<String, Object> details = Map.of(
            "location", Map.of(
                "latitude", 33.312805,
                "longitude", 44.361488,
                "address", "Baghdad, Al-Karrada"
            ),
            "proof_of_delivery", Map.of(
                "images", List.of("https://your-cdn.com/proof/12345.jpg"),
                "receiver_name", "Ahmed Mohammed",
                "delivery_time", Instant.now().toString()
            ),
            "notes", "Delivered by driver: " + driverName
        );
        
        return sendStatusUpdate(shipmentNumber, "SUCCESSFUL_DELIVERY", details);
    }

    public StatusUpdateResponse markAsPostponed(String shipmentNumber, String reason, Integer postponedDateId) {
        Map<String, Object> details = Map.of(
            "postponed_reason", reason,
            "postponed_reason_en", "Customer not available",
            "postponed_reason_ku", "کڕیار بەردەست نییە",
            "postponed_date_id", postponedDateId,  // ✅ REQUIRED: 1=tomorrow, 2=2 days, 3=3+ days
            "notes", "Will retry delivery tomorrow"
        );
        
        return sendStatusUpdate(shipmentNumber, "POSTPONED", details);
    }

    public StatusUpdateResponse markAsReturned(String shipmentNumber, String returnReason) {
        Map<String, Object> details = Map.of(
            "return_reason", returnReason,
            "return_reason_en", "Customer refused",
            "return_reason_ku", "کڕیار ڕەتکردەوە",
            "notes", "Customer refused to receive"
        );
        
        return sendStatusUpdate(shipmentNumber, "RETURNED_WITH_AGENT", details);
    }
}

Complete Integration Example

# jenni_client.py - Complete Mode 2 Integration
import requests
from datetime import datetime, timedelta
from typing import List, Dict, Optional

JENNI_API_URL = 'https://jenni-api.com/api'
JENNI_USERNAME = 'your_username'
JENNI_PASSWORD = 'your_password'
SYSTEM_CODE = 'YOUR_SYSTEM_CODE'

class JenniClient:
    def __init__(self):
        self.auth_token = None
        self.token_expiry = None

    # ==========================================
    # STEP 1: Authentication
    # ==========================================
    def login(self):
        """Login to Jenni Logistics and get auth token"""
        try:
            response = requests.post(
                f'{JENNI_API_URL}/v2/auth/login',
                json={
                    'username': JENNI_USERNAME,
                    'password': JENNI_PASSWORD
                }
            )
            response.raise_for_status()
            data = response.json()

            self.auth_token = data['token']
            self.token_expiry = datetime.now() + timedelta(seconds=data['expires_in'])

            print('✅ Logged in to Jenni Logistics successfully')
            return self.auth_token
        except Exception as error:
            print(f'❌ Login failed: {error}')
            raise

    def ensure_valid_token(self):
        """Ensure auth token is valid"""
        if not self.auth_token or datetime.now() > (self.token_expiry - timedelta(minutes=5)):
            self.login()

    # ==========================================
    # STEP 2: Create Shipments
    # ==========================================
    def create_shipments(self, shipments: List[Dict]) -> Dict:
        """Create shipments in Jenni"""
        self.ensure_valid_token()

        try:
            print(f'📤 Creating {len(shipments)} shipments in Jenni')

            response = requests.post(
                f'{JENNI_API_URL}/v2/shipments/create',
                json={
                    'system_code': SYSTEM_CODE,
                    'shipments': shipments
                },
                headers={
                    'Authorization': f'Bearer {self.auth_token}',
                    'Content-Type': 'application/json',
                    'Accept-Language': 'en'
                }
            )
            response.raise_for_status()
            data = response.json()

            print(f'✅ Created {data["summary"]["accepted_count"]} shipments')
            print(f'❌ Rejected {data["summary"]["rejected_count"]} shipments')

            # Log rejected shipments
            if data.get('rejected_shipments'):
                for rejected in data['rejected_shipments']:
                    print(f'⚠️ {rejected["shipment_number"]}: {rejected["reason"]}')

            return data
        except Exception as error:
            print(f'❌ Failed to create shipments: {error}')
            raise

    # ==========================================
    # STEP 3: Query Shipments
    # ==========================================
    def query_shipments(self, shipment_numbers: List[str]) -> Dict:
        """Query shipment status"""
        self.ensure_valid_token()

        try:
            print(f'🔍 Querying {len(shipment_numbers)} shipments')

            response = requests.post(
                f'{JENNI_API_URL}/v2/shipments/query',
                json={'shipment_numbers': shipment_numbers},
                headers={
                    'Authorization': f'Bearer {self.auth_token}',
                    'Content-Type': 'application/json'
                }
            )
            response.raise_for_status()
            data = response.json()

            print(f'✅ Found {data["summary"]["found_count"]} shipments')
            print(f'❌ Not found {data["summary"]["not_found_count"]} shipments')

            return data
        except Exception as error:
            print(f'❌ Failed to query shipments: {error}')
            raise

    # ==========================================
    # STEP 4: Edit Shipment
    # ==========================================
    def edit_shipment(self, shipment_number: str, updates: Dict) -> Dict:
        """Edit shipment information"""
        self.ensure_valid_token()

        try:
            print(f'✏️ Editing shipment {shipment_number}')

            response = requests.put(
                f'{JENNI_API_URL}/v2/shipments/edit',
                json={
                    'shipment_number': shipment_number,
                    **updates
                },
                headers={
                    'Authorization': f'Bearer {self.auth_token}',
                    'Content-Type': 'application/json'
                }
            )
            response.raise_for_status()

            print('✅ Shipment edited successfully')
            return response.json()
        except Exception as error:
            print(f'❌ Failed to edit shipment: {error}')
            raise


# ==========================================
# USAGE EXAMPLES - E-commerce Integration
# ==========================================

jenni = JenniClient()

def handle_new_order(order: Dict):
    """Handle new customer order"""
    print(f'\n📦 New order received: {order["order_number"]}')

    try:
        # 1. Create shipment in Jenni
        shipments = [{
            'shipment_number': order['order_number'],
            'external_shipment_id': str(order['id']),  # ✅ REQUIRED: Your internal order ID for tracking
            'receiver_name': order['customer']['name'],
            'receiver_phone_1': order['customer']['phone'],
            'governorate_code': order['delivery_address']['governorate_code'],
            'city': order['delivery_address']['city'],
            'address': order['delivery_address']['street'],
            'amount_iqd': order['total_amount'],
            'quantity': len(order['items']),
            'product_info': ', '.join(item['name'] for item in order['items']),
            'note': order.get('delivery_notes', ''),
            'is_proof_of_delivery': True
        }]

        result = jenni.create_shipments(shipments)

        if result['summary']['accepted_count'] > 0:
            # 2. Save Jenni Logistics shipment ID
            accepted = result['accepted_shipments'][0]
            save_shipment_id_to_database(
                order['order_number'],
                accepted['shipment_id']
            )

            print('✅ Order sent to Jenni Logistics for delivery')

            # 3. Notify customer
            send_customer_notification(
                order['customer']['email'],
                'Your order is on its way!',
                f'Tracking number: {accepted["shipment_id"]}'
            )
        else:
            print('❌ Order rejected by Jenni')

    except Exception as error:
        print(f'Failed to process order: {error}')


def check_order_status(order_number: str):
    """Check order status"""
    print(f'\n🔍 Checking status for order: {order_number}')

    try:
        result = jenni.query_shipments([order_number])

        if result['shipments']:
            shipment = result['shipments'][0]

            print(f'📊 Status: {shipment["current_step"]}')
            print(f'📊 Arabic: {shipment["current_step_ar"]}')

            # Update database
            update_order_status_in_database(
                order_number,
                shipment['current_step'],
                shipment['shipment_history']
            )

            # Notify if delivered
            if shipment['current_step'] == 'Successfully Delivered':
                send_customer_notification(
                    'customer@email.com',
                    'Your order has been delivered!',
                    'Thank you for your order'
                )

            return shipment
        else:
            print('❌ Shipment not found')
            return None

    except Exception as error:
        print(f'Failed to check status: {error}')
        raise


# Helper functions (implement these based on your system)
def save_shipment_id_to_database(order_number, shipment_id):
    pass

def update_order_status_in_database(order_number, status, history):
    pass

def send_customer_notification(email, subject, message):
    pass


# Test example
if __name__ == '__main__':
    sample_order = {
        'id': 12345,  # ✅ Your internal order ID (will be sent as external_shipment_id)
        'order_number': 'ORD-2024-001',
        'customer': {
            'name': 'Ahmed Mohammed',
            'phone': '07901234567',
            'email': 'ahmed@email.com'
        },
        'delivery_address': {
            'governorate_code': 'BGD',
            'city': 'Al-Karrada',
            'street': 'Al-Rabi Street, Building 5'
        },
        'total_amount': 50000,
        'items': [
            {'name': 'Mobile Phone', 'quantity': 1},
            {'name': 'Phone Case', 'quantity': 1}
        ],
        'delivery_notes': 'Please call before delivery'
    }

    # handle_new_order(sample_order)
    # check_order_status('ORD-2024-001')