{ "info": { "name": "V2 Integration API", "description": "Complete Postman Collection for V2 Integration API - Modern, Smart, and Standardized Integration for Delivery Management", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "_postman_id": "v2-integration-api", "version": "2.0.0" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "// Auto-inject token from collection variables if not set", "if (!pm.request.headers.has('Authorization') && pm.collectionVariables.get('token')) {", " pm.request.headers.add({", " key: 'Authorization',", " value: 'Bearer ' + pm.collectionVariables.get('token')", " });", "}" ] } } ], "variable": [ { "key": "baseUrl", "value": "https://jenni.alzaeemexp.com/api", "type": "string" }, { "key": "yourServerBaseUrl", "value": "https://yourstore.com", "type": "string" }, { "key": "systemCode", "value": "YOUR_SYSTEM_CODE", "type": "string" }, { "key": "username", "value": "your_username", "type": "string" }, { "key": "password", "value": "your_password", "type": "string" }, { "key": "outboundAuthMethod", "value": "TOKEN", "type": "string" }, { "key": "outboundStaticToken", "value": "", "type": "string" }, { "key": "outboundUsername", "value": "", "type": "string" }, { "key": "outboundPassword", "value": "", "type": "string" }, { "key": "yourServerInboundToken", "value": "", "type": "string" }, { "key": "token", "value": "", "type": "string" }, { "key": "refreshToken", "value": "", "type": "string" }, { "key": "lastShipmentId", "value": "12345", "type": "string" } ], "item": [ { "name": "Authentication", "item": [ { "name": "Login", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.token) {", " var token = jsonData.token;", " if (typeof token === 'string' && token.toLowerCase().startsWith('bearer ')) {", " token = token.substring(7);", " }", " pm.collectionVariables.set('token', token);", " console.log('✅ Token saved to collection variables');", " }", " if (jsonData.refreshToken) {", " var refreshToken = jsonData.refreshToken;", " if (typeof refreshToken === 'string' && refreshToken.toLowerCase().startsWith('bearer ')) {", " refreshToken = refreshToken.substring(7);", " }", " pm.collectionVariables.set('refreshToken', refreshToken);", " console.log('✅ Refresh token saved to collection variables');", " }", "}" ], "type": "text/javascript" } } ], "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"username\": \"{{username}}\",\n \"password\": \"{{password}}\"\n}" }, "url": { "raw": "{{baseUrl}}/v2/auth/login", "host": ["{{baseUrl}}"], "path": ["v2", "auth", "login"] }, "description": "Authenticate and get JWT token" } }, { "name": "Refresh Token", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.token) {", " var token = jsonData.token;", " if (typeof token === 'string' && token.toLowerCase().startsWith('bearer ')) {", " token = token.substring(7);", " }", " pm.collectionVariables.set('token', token);", " console.log('✅ New token saved to collection variables');", " }", " if (jsonData.refreshToken) {", " var refreshToken = jsonData.refreshToken;", " if (typeof refreshToken === 'string' && refreshToken.toLowerCase().startsWith('bearer ')) {", " refreshToken = refreshToken.substring(7);", " }", " pm.collectionVariables.set('refreshToken', refreshToken);", " console.log('✅ New refresh token saved to collection variables');", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{refreshToken}}" } ], "url": { "raw": "{{baseUrl}}/v2/auth/refresh", "host": ["{{baseUrl}}"], "path": ["v2", "auth", "refresh"] }, "description": "Refresh your JWT token before it expires. This endpoint extends your session by providing a new access token and refresh token. Both tokens are automatically saved to environment variables." } } ] }, { "name": "Shipments", "item": [ { "name": "Create Shipments", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData && jsonData.accepted_shipments && jsonData.accepted_shipments.length > 0) {", " var sid = jsonData.accepted_shipments[0].shipment_id;", " if (sid) {", " pm.collectionVariables.set('lastShipmentId', String(sid));", " console.log('✅ Saved lastShipmentId=' + sid);", " }", " }", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"system_code\": \"{{systemCode}}\",\n \"shipments\": [\n {\n \"shipment_number\": \"SHIP001\",\n \"external_shipment_id\": \"12345\",\n \"airway_bill_number\": null,\n \"merchant_id\": null,\n \"store_id\": null,\n \"receiver_name\": null,\n \"receiver_phone_1\": \"07901234567\",\n \"receiver_phone_2\": null,\n \"governorate_code\": \"BGD\",\n \"city\": \"Al-Karrada\",\n \"address\": null,\n \"amount_iqd\": 50000.0,\n \"amount_usd\": null,\n \"quantity\": 1,\n \"is_proof_of_delivery\": false,\n \"is_fragile\": false,\n \"have_return_item\": false,\n \"is_special_case\": false,\n \"product_info\": null,\n \"note\": null,\n \"receiver_latitude\": null,\n \"receiver_longitude\": null\n }\n ]\n}" }, "url": { "raw": "{{baseUrl}}/v2/shipments/create", "host": ["{{baseUrl}}"], "path": ["v2", "shipments", "create"] }, "description": "Create new shipments in bulk (max 100 per request). REQUIRED FIELDS: system_code, shipment_number, external_shipment_id (sender's ID for tracking), receiver_phone_1, governorate_code, city, amount_iqd. Fields shown as null are optional and can be removed. OPTIONAL: airway_bill_number, merchant_id, store_id, receiver_name, receiver_phone_2, address, amount_usd, quantity, is_proof_of_delivery, is_fragile, have_return_item (used for reverse logistics), is_special_case, product_info, note, GPS coordinates. Jenni generates shipment_id in the response; do not send shipment_id in the create request. Use merchant_id for AGGREGATOR role, store_id for MERCHANT role." } }, { "name": "Query by Shipment Numbers", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"shipment_numbers\": [\"SHIP001\", \"SHIP002\", \"SHIP003\"]\n}" }, "url": { "raw": "{{baseUrl}}/v2/shipments/query", "host": ["{{baseUrl}}"], "path": ["v2", "shipments", "query"] }, "description": "Query specific shipments by tracking numbers (max 100). Returns only shipments owned by authenticated user. Not found list includes both non-existent shipments and access denied ones for security." } }, { "name": "Query by Shipment IDs", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"shipment_ids\": [12345, 12346, 12347]\n}" }, "url": { "raw": "{{baseUrl}}/v2/shipments/query", "host": ["{{baseUrl}}"], "path": ["v2", "shipments", "query"] }, "description": "Query specific shipments by IDs (Case IDs) - max 100. More precise than shipment_numbers. Returns only shipments owned by authenticated user." } }, { "name": "Get All Shipments (Paginated)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"page\": 0,\n \"page_size\": 20\n}" }, "url": { "raw": "{{baseUrl}}/v2/shipments/query", "host": ["{{baseUrl}}"], "path": ["v2", "shipments", "query"] }, "description": "Get all shipments owned by the authenticated user with pagination. Page is 0-indexed. Max page_size is 100. Response includes pagination metadata (total_records, total_pages, has_next_page, etc.). If no params provided, returns first 100 shipments." } }, { "name": "Direct Shipment Update Status", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"shipment_id\": {{lastShipmentId}},\n \"action\": \"SUCCESSFUL_DELIVERY\"\n}" }, "url": { "raw": "{{baseUrl}}/v2/shipments/update-status", "host": ["{{baseUrl}}"], "path": ["v2", "shipments", "update-status"] }, "description": "Direct Jenni shipment update API. Uses action in the request body and updates a shipment directly inside Jenni." } }, { "name": "Edit Shipment", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"shipment_id\": 12345,\n \"receiver_name\": \"أحمد محمد\",\n \"receiver_phone_1\": \"07901234567\"\n}" }, "url": { "raw": "{{baseUrl}}/v2/shipments/edit", "host": ["{{baseUrl}}"], "path": ["v2", "shipments", "edit"] }, "description": "Edit shipment details (partial update)" } }, { "name": "Generate Stickers", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"shipment_numbers\": [\"SHIP001\", \"SHIP002\"],\n \"width_mm\": 100,\n \"height_mm\": 150\n}" }, "url": { "raw": "{{baseUrl}}/v2/shipments/stickers", "host": ["{{baseUrl}}"], "path": ["v2", "shipments", "stickers"] }, "description": "Generate PDF stickers (max 100)" } } ] }, { "name": "Push Out Mode APIs", "description": "APIs for Integration Mode 1 (Push Out) - When Jenni sends shipments to your system", "item": [ { "name": "Push Shipments to External System", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"system_code\": \"{{systemCode}}\",\n \"auth_method\": \"{{outboundAuthMethod}}\",\n \"static_token\": \"{{outboundStaticToken}}\",\n \"username\": \"{{outboundUsername}}\",\n \"password\": \"{{outboundPassword}}\",\n \"shipments\": [\n {\n \"shipment_number\": \"SHIP001\",\n \"receiver_name\": \"Ahmed Ali\",\n \"receiver_phone_1\": \"07901234567\",\n \"receiver_phone_2\": \"07801234567\",\n \"governorate_code\": \"BGD\",\n \"city\": \"Al-Karrada\",\n \"address\": \"Street 10, Building 5\",\n \"amount_iqd\": 50000.0,\n \"quantity\": 1,\n \"product_info\": \"Mobile Phone\",\n \"note\": \"Call before delivery\"\n }\n ]\n}" }, "url": { "raw": "{{baseUrl}}/v2/push/send-shipments", "host": ["{{baseUrl}}"], "path": ["v2", "push", "send-shipments"] }, "description": "Internal/ops API: triggers pushing shipments to the configured external system (Push Out Mode). Typically used by Jenni-side automation; integrators usually DO NOT call this manually." } }, { "name": "Update Status from External System", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"system_code\": \"{{systemCode}}\",\n \"updates\": [\n {\n \"shipment_id\": {{lastShipmentId}},\n \"action_code\": \"SUCCESSFUL_DELIVERY\",\n \"timestamp\": \"2024-01-15T10:30:00Z\",\n \"note\": \"Delivered successfully\",\n \"proof_image_url\": \"https://cdn.example.com/proof/12345.jpg\",\n \"received_by_name\": \"Ahmed Mohammed\",\n \"delivery_latitude\": 33.3152,\n \"delivery_longitude\": 44.3661\n }\n ]\n}" }, "url": { "raw": "{{baseUrl}}/v2/push/update-status", "host": ["{{baseUrl}}"], "path": ["v2", "push", "update-status"] }, "description": "External system calls this API to send delivery status updates back to Jenni. Use shipment_id (recommended), action_code, and required fields per action." } } ] }, { "name": "Reference Data", "item": [ { "name": "Get Governorates", "request": { "auth": { "type": "noauth" }, "method": "GET", "url": { "raw": "{{baseUrl}}/v2/reference/governorates", "host": ["{{baseUrl}}"], "path": ["v2", "reference", "governorates"] }, "description": "List all governorates (Public)" } }, { "name": "Get Cities (Paginated)", "request": { "auth": { "type": "noauth" }, "method": "GET", "url": { "raw": "{{baseUrl}}/v2/reference/cities?page=1&size=50&governorate_code=BGD&search=", "host": ["{{baseUrl}}"], "path": ["v2", "reference", "cities"], "query": [ {"key": "page", "value": "1"}, {"key": "size", "value": "50"}, {"key": "governorate_code", "value": "BGD", "description": "Optional: Filter by governorate"}, {"key": "search", "value": "", "description": "Optional: Search city name"} ] }, "description": "List cities with pagination. All parameters are optional. (Public API - No authentication required)" } }, { "name": "Download Cities (Excel)", "request": { "auth": { "type": "noauth" }, "method": "GET", "url": { "raw": "{{baseUrl}}/v2/reference/cities?download=excel&governorate_code=&search=", "host": ["{{baseUrl}}"], "path": ["v2", "reference", "cities"], "query": [ {"key": "download", "value": "excel"}, {"key": "governorate_code", "value": "", "description": "Optional: Filter by governorate"}, {"key": "search", "value": "", "description": "Optional: Search city name"} ] }, "description": "Download all cities as Excel file with optional filters (Public API - No authentication required)" } }, { "name": "Download Cities (JSON)", "request": { "auth": { "type": "noauth" }, "method": "GET", "url": { "raw": "{{baseUrl}}/v2/reference/cities?download=json&governorate_code=&search=", "host": ["{{baseUrl}}"], "path": ["v2", "reference", "cities"], "query": [ {"key": "download", "value": "json"}, {"key": "governorate_code", "value": "", "description": "Optional: Filter by governorate"}, {"key": "search", "value": "", "description": "Optional: Search city name"} ] }, "description": "Download all cities as JSON file with optional filters (Public API - No authentication required)" } }, { "name": "Get Return Reasons", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v2/reference/return-reasons", "host": ["{{baseUrl}}"], "path": ["v2", "reference", "return-reasons"] }, "description": "List of return reasons" } }, { "name": "Get Postponed Reasons", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v2/reference/postponed-reasons", "host": ["{{baseUrl}}"], "path": ["v2", "reference", "postponed-reasons"] }, "description": "List of postponed reasons" } }, { "name": "Get Action Codes", "request": { "auth": { "type": "noauth" }, "method": "GET", "url": { "raw": "{{baseUrl}}/v2/reference/action-codes", "host": ["{{baseUrl}}"], "path": ["v2", "reference", "action-codes"] }, "description": "Complete list of action codes (Public)" } }, { "name": "Get Available Actions (by shipment_number)", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v2/reference/available-actions?shipment_number=SHIP001", "host": ["{{baseUrl}}"], "path": ["v2", "reference", "available-actions"], "query": [ {"key": "shipment_number", "value": "SHIP001"} ] }, "description": "Get available actions for a shipment using shipment_number (receipt number). Note: shipment_id is more accurate as receipt numbers can be duplicated." } }, { "name": "Get Available Actions (by shipment_id)", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v2/reference/available-actions?shipment_id=12345", "host": ["{{baseUrl}}"], "path": ["v2", "reference", "available-actions"], "query": [ {"key": "shipment_id", "value": "12345"} ] }, "description": "Get available actions for a shipment using shipment_id (case ID). This is the recommended approach as shipment_id is always unique, unlike shipment_number which can be duplicated across different customers." } }, { "name": "Get Countries", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v2/reference/countries", "host": ["{{baseUrl}}"], "path": ["v2", "reference", "countries"] }, "description": "List all countries" } } ] }, { "name": "Statistics", "item": [ { "name": "Order Statistics", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v2/statistics/orders-by-status", "host": ["{{baseUrl}}"], "path": ["v2", "statistics", "orders-by-status"] }, "description": "Count of orders grouped by status" } } ] }, { "name": "Orders", "item": [ { "name": "Orders in Process", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v2/orders/in-process?page=0&size=20", "host": ["{{baseUrl}}"], "path": ["v2", "orders", "in-process"], "query": [ {"key": "page", "value": "0"}, {"key": "size", "value": "20"} ] }, "description": "List all in-process orders" } }, { "name": "Delete Shipment", "request": { "method": "DELETE", "url": { "raw": "{{baseUrl}}/v2/orders/12345", "host": ["{{baseUrl}}"], "path": ["v2", "orders", "12345"] }, "description": "Delete shipment by shipment_id (case ID). Only shipments in initial stages (SORTING_CENTER, NEW_CUSTOMER_SHIPMENTS) and initial steps (NEW_ORDER_TO_PRINT, NEW_ORDER_TO_PICKUP, NEW_WITH_PA) can be deleted. Ownership is verified based on user rank." } }, { "name": "Get Orders by Step", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v2/orders/by-step?step_code=OFD&page=0&size=20", "host": ["{{baseUrl}}"], "path": ["v2", "orders", "by-step"], "query": [ {"key": "step_code", "value": "OFD"}, {"key": "page", "value": "0"}, {"key": "size", "value": "20"} ] }, "description": "Get orders filtered by step status" } } ] }, { "name": "Tickets", "item": [ { "name": "Create Ticket", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"message\": \"لدي مشكلة في التوصيل\",\n \"ticket_cause_name\": \"Delivery Issue\",\n \"ticket_department_name\": \"Operations\"\n}" }, "url": { "raw": "{{baseUrl}}/v2/tickets/create", "host": ["{{baseUrl}}"], "path": ["v2", "tickets", "create"] }, "description": "Create support ticket" } }, { "name": "Get My Tickets", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v2/tickets/by-user?page=1&size=20", "host": ["{{baseUrl}}"], "path": ["v2", "tickets", "by-user"], "query": [ {"key": "page", "value": "1"}, {"key": "size", "value": "20"} ] }, "description": "Get user tickets with pagination" } }, { "name": "Search Tickets", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"page\": 1,\n \"size\": 20\n}" }, "url": { "raw": "{{baseUrl}}/v2/tickets/search", "host": ["{{baseUrl}}"], "path": ["v2", "tickets", "search"] }, "description": "Search tickets with filters" } }, { "name": "Get Ticket Statuses", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v2/tickets/statuses", "host": ["{{baseUrl}}"], "path": ["v2", "tickets", "statuses"] }, "description": "Get all ticket statuses" } }, { "name": "Get Ticket Departments", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v2/tickets/departments", "host": ["{{baseUrl}}"], "path": ["v2", "tickets", "departments"] }, "description": "Get all ticket departments" } }, { "name": "Get Ticket Causes", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v2/tickets/causes", "host": ["{{baseUrl}}"], "path": ["v2", "tickets", "causes"] }, "description": "Get all ticket causes" } }, { "name": "Get Ticket History", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v2/tickets/550e8400-e29b-41d4-a716-446655440000/history", "host": ["{{baseUrl}}"], "path": ["v2", "tickets", "550e8400-e29b-41d4-a716-446655440000", "history"] }, "description": "Get ticket history by ticket ID" } }, { "name": "Get Initial Ticket Status", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v2/tickets/initial-status", "host": ["{{baseUrl}}"], "path": ["v2", "tickets", "initial-status"] }, "description": "Get initial ticket status for new tickets" } }, { "name": "Upload Ticket Attachment", "request": { "method": "POST", "header": [], "body": { "mode": "formdata", "formdata": [ { "key": "file", "type": "file", "src": [] } ] }, "url": { "raw": "{{baseUrl}}/v2/tickets/550e8400-e29b-41d4-a716-446655440000/attachment", "host": ["{{baseUrl}}"], "path": ["v2", "tickets", "550e8400-e29b-41d4-a716-446655440000", "attachment"] }, "description": "Upload attachment to ticket" } } ] }, { "name": "Payments", "item": [ { "name": "Get Payment Info", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v2/payments/123", "host": ["{{baseUrl}}"], "path": ["v2", "payments", "123"] }, "description": "Get payment manifest details by ID. Returns all shipments in the payment with V2 professional property names (snake_case). Includes mapped stage/step names, governorate mapping, balance information, and status descriptions. Ownership verification applied (MASTERCUSTOMER or PICKUPAGENT)." }, "response": [ { "name": "Success Response Example", "originalRequest": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{token}}" } ], "url": { "raw": "{{baseUrl}}/v2/payments/28578", "host": ["{{baseUrl}}"], "path": ["v2", "payments", "28578"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"message\": \"Payment information retrieved successfully\",\n \"timestamp\": \"2025-11-02T11:00:00Z\",\n \"payment_id\": 28578,\n \"merchant_name\": \"ABC Trading Company\",\n \"store_name\": \"ABC Electronics Branch\",\n \"payment_date\": \"2025-10-30T09:00:00Z\",\n \"note\": \"Monthly payment - October 2025\",\n \"merchant_id\": 100,\n \"store_id\": 3235,\n \"pickup_agent_name\": \"Mohammed Karim\",\n \"pickup_agent_phone\": \"07902222222\",\n \"pickup_agent_task_id\": 567,\n \"total_shipments\": 5,\n \"amount_paid_actually_iqd\": 125000,\n \"amount_paid_actually_usd\": 0,\n \"total_receipt_amount_iqd\": 250000,\n \"total_receipt_amount_usd\": 0,\n \"previous_balance\": {\n \"debit_iqd\": 50000.0,\n \"debit_usd\": 0.0,\n \"credit_iqd\": 0.0,\n \"credit_usd\": 0.0\n },\n \"net_receipt_amount\": {\n \"debit_iqd\": 0.0,\n \"debit_usd\": 0.0,\n \"credit_iqd\": 175000.0,\n \"credit_usd\": 0.0\n },\n \"amount_paid_from_agent\": {\n \"debit_iqd\": 0.0,\n \"debit_usd\": 0.0,\n \"credit_iqd\": 125000.0,\n \"credit_usd\": 0.0\n },\n \"new_balance\": {\n \"debit_iqd\": 0.0,\n \"debit_usd\": 0.0,\n \"credit_iqd\": 0.0,\n \"credit_usd\": 0.0\n },\n \"cases_by_state\": {\n \"BGD\": {\n \"count\": 3,\n \"state_name\": \"BAGHDAD\"\n },\n \"BAS\": {\n \"count\": 2,\n \"state_name\": \"BASRAH\"\n }\n },\n \"shipments\": [\n {\n \"shipment_id\": 12345,\n \"shipment_number\": \"SHIP001\",\n \"receiver_name\": \"أحمد علي\",\n \"receiver_phone\": \"07901234567\",\n \"governorate_name\": \"BAGHDAD\",\n \"address\": \"شارع الرشيد، بناية 10\",\n \"amount_iqd\": 50000.0,\n \"amount_usd\": 0.0,\n \"amount_iqd_before_change\": null,\n \"amount_usd_before_change\": null,\n \"amount_changed\": false,\n \"shipment_cost\": 7500.0,\n \"net_amount_iqd\": 42500.0,\n \"net_amount_usd\": 0.0,\n \"quantity\": 1,\n \"current_stage\": \"DELIVERED\",\n \"current_stage_ar\": \"الواصل\",\n \"current_step\": \"DELIVERED\",\n \"current_step_ar\": \"سلمت بنجاح\",\n \"status_description\": \"Delivered\",\n \"note\": \"تم التسليم بنجاح\",\n \"agent_share\": 2500.0\n },\n {\n \"shipment_id\": 12346,\n \"shipment_number\": \"SHIP002\",\n \"receiver_name\": \"سارة محمد\",\n \"receiver_phone\": \"07803456789\",\n \"governorate_name\": \"BASRAH\",\n \"address\": \"حي الجمهورية، شارع 5\",\n \"amount_iqd\": 75000.0,\n \"amount_usd\": 0.0,\n \"amount_iqd_before_change\": 80000.0,\n \"amount_usd_before_change\": null,\n \"amount_changed\": true,\n \"shipment_cost\": 8000.0,\n \"net_amount_iqd\": 67000.0,\n \"net_amount_usd\": 0.0,\n \"quantity\": 2,\n \"current_stage\": \"DELIVERED\",\n \"current_stage_ar\": \"الواصل\",\n \"current_step\": \"DELIVERED_PRICE_CHANGED\",\n \"current_step_ar\": \"سلمت مع تغيير السعر\",\n \"status_description\": \"Delivered - Amount changed from 80000.00 to 75000.00 IQD\",\n \"note\": \"Price negotiated with customer\",\n \"agent_share\": 3000.0\n }\n ]\n}" } ] }, { "name": "Get Settled Payments", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v2/payments/settled?page=1&size=20", "host": ["{{baseUrl}}"], "path": ["v2", "payments", "settled"], "query": [ {"key": "page", "value": "1"}, {"key": "size", "value": "20"} ] }, "description": "List settled payments with pagination" } } ] }, { "name": "Stores Management", "item": [ { "name": "Get My Stores", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v2/merchants/my-stores", "host": ["{{baseUrl}}"], "path": ["v2", "merchants", "my-stores"] }, "description": "Get merchant stores list (Master Customer role)" } }, { "name": "Create Store", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"store_name\": \"متجر الإلكترونيات\",\n \"store_phone\": \"07901234567\",\n \"governorate_code\": \"BGD\",\n \"address\": \"شارع الرشيد، بناية 10\",\n \"latitude\": 33.3152,\n \"longitude\": 44.3661\n}" }, "url": { "raw": "{{baseUrl}}/v2/stores/create", "host": ["{{baseUrl}}"], "path": ["v2", "stores", "create"] }, "description": "Create a new store under current master customer. System generates a random password for the store. Returns store_id, store_name, and generated_password." } }, { "name": "Get Branch Master Customers (Platform / AGGREGATOR)", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{token}}" } ], "url": { "raw": "{{baseUrl}}/api/kb-master-customers/branch-master-customers", "host": ["{{baseUrl}}"], "path": ["api", "kb-master-customers", "branch-master-customers"] }, "description": "List of merchants (Master Customers) by user branch. For platform and AGGREGATOR role." } }, { "name": "Get Master Customer Name And Id By Branch (Platform / AGGREGATOR)", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{token}}" } ], "url": { "raw": "{{baseUrl}}/api/kb-master-customers/getMasterCustomerNameAndIdByBranch", "host": ["{{baseUrl}}"], "path": ["api", "kb-master-customers", "getMasterCustomerNameAndIdByBranch"] }, "description": "List of merchant id + name for dropdowns. Optional: ?branchId= to specify branch." } } ] }, { "name": "Merchant Management", "item": [ { "name": "List Merchants", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{token}}" } ], "url": { "raw": "{{baseUrl}}/v2/merchant-management/list", "host": ["{{baseUrl}}"], "path": ["v2", "merchant-management", "list"] }, "description": "List merchants for current AGGREGATOR. Returns merchant_id, merchant_name, phone only (no password). Use with Create/Update." } }, { "name": "Create Merchant", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{token}}" } ], "body": { "mode": "raw", "raw": "{\n \"merchant_name\": \"New Merchant\",\n \"phone\": \"07901234567\",\n \"system_code\": \"NEWMERCH001\"\n}" }, "url": { "raw": "{{baseUrl}}/v2/merchant-management/create", "host": ["{{baseUrl}}"], "path": ["v2", "merchant-management", "create"] }, "description": "Create merchant. Minimal: merchant_name, phone, optional system_code. Optional password (else generated and returned). Use List to display." } }, { "name": "Update Merchant", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{token}}" } ], "body": { "mode": "raw", "raw": "{\n \"merchant_id\": 123,\n \"merchant_name\": \"Updated Name\"\n}" }, "url": { "raw": "{{baseUrl}}/v2/merchant-management/update", "host": ["{{baseUrl}}"], "path": ["v2", "merchant-management", "update"] }, "description": "Update merchant by merchant_id. Use List to get current data. AGGREGATOR only." } } ] }, { "name": "Returns", "item": [ { "name": "Get Return Info", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v2/returns/123", "host": ["{{baseUrl}}"], "path": ["v2", "returns", "123"] }, "description": "Get return (RTO) manifest details by ID. Returns all shipments in the manifest with V2 professional property names (snake_case). Includes mapped stage/step names, governorate mapping, and status descriptions. Ownership verification applied (MASTERCUSTOMER or PICKUPAGENT)." }, "response": [ { "name": "Success Response Example", "originalRequest": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{token}}" } ], "url": { "raw": "{{baseUrl}}/v2/returns/456", "host": ["{{baseUrl}}"], "path": ["v2", "returns", "456"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"message\": \"Return information retrieved successfully\",\n \"timestamp\": \"2025-11-02T10:00:00Z\",\n \"return_id\": 456,\n \"merchant_name\": \"ABC Trading Company\",\n \"created_date\": \"2025-10-28T08:30:00Z\",\n \"note\": \"Monthly RTO manifest - October 2025\",\n \"merchant_id\": 100,\n \"total_shipments\": 3,\n \"shipments\": [\n {\n \"shipment_id\": 12345,\n \"shipment_number\": \"SHIP001\",\n \"receiver_name\": \"أحمد علي\",\n \"receiver_phone\": \"07901234567\",\n \"governorate_name\": \"BAGHDAD\",\n \"address\": \"شارع الرشيد، بناية 10\",\n \"amount_iqd\": 50000.0,\n \"amount_usd\": 0.0,\n \"amount_iqd_before_change\": null,\n \"amount_usd_before_change\": null,\n \"amount_changed\": false,\n \"shipment_cost\": 7500.0,\n \"net_amount_iqd\": 42500.0,\n \"net_amount_usd\": 0.0,\n \"quantity\": 1,\n \"current_stage\": \"RTO\",\n \"current_stage_ar\": \"الراجع\",\n \"current_step\": \"RTO_WH\",\n \"current_step_ar\": \"راجع كلي في المخزن\",\n \"status_description\": \"Returned to warehouse\",\n \"note\": \"Customer refused\"\n },\n {\n \"shipment_id\": 12346,\n \"shipment_number\": \"SHIP002\",\n \"receiver_name\": \"سارة محمد\",\n \"receiver_phone\": \"07803456789\",\n \"governorate_name\": \"BASRAH\",\n \"address\": \"حي الجمهورية، شارع 5\",\n \"amount_iqd\": 75000.0,\n \"amount_usd\": 0.0,\n \"amount_iqd_before_change\": 80000.0,\n \"amount_usd_before_change\": null,\n \"amount_changed\": true,\n \"shipment_cost\": 8000.0,\n \"net_amount_iqd\": 67000.0,\n \"net_amount_usd\": 0.0,\n \"quantity\": 2,\n \"current_stage\": \"DELIVERED\",\n \"current_stage_ar\": \"الواصل\",\n \"current_step\": \"PARTIAL_DELIVERY\",\n \"current_step_ar\": \"تسليم جزئي\",\n \"status_description\": \"Partial delivery - Amount changed from 80000.00 to 75000.00 IQD\",\n \"note\": \"1 item returned\",\n \"paid_in_advance\": true,\n \"advance_payment_id\": 789\n },\n {\n \"shipment_id\": 12347,\n \"shipment_number\": \"SHIP003\",\n \"receiver_name\": \"علي حسن\",\n \"receiver_phone\": \"07705551234\",\n \"governorate_name\": \"NINEVEH\",\n \"address\": \"الموصل، حي الزهراء\",\n \"amount_iqd\": 0.0,\n \"amount_usd\": 0.0,\n \"amount_iqd_before_change\": 60000.0,\n \"amount_usd_before_change\": null,\n \"amount_changed\": true,\n \"shipment_cost\": 9000.0,\n \"net_amount_iqd\": -9000.0,\n \"net_amount_usd\": 0.0,\n \"quantity\": 1,\n \"current_stage\": \"DELIVERED\",\n \"current_stage_ar\": \"الواصل\",\n \"current_step\": \"REPLACEMENT\",\n \"current_step_ar\": \"استبدال\",\n \"status_description\": \"Replacement\",\n \"note\": \"Product replaced\",\n \"agent_share\": 3000.0\n }\n ]\n}" } ] }, { "name": "Get Settled Returns", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/v2/returns/settled?page=1&size=20", "host": ["{{baseUrl}}"], "path": ["v2", "returns", "settled"], "query": [ {"key": "page", "value": "1"}, {"key": "size", "value": "20"} ] }, "description": "List settled returns with pagination" } } ] }, { "name": "Push & Status Update", "item": [ { "name": "Push Shipments", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"system_code\": \"{{systemCode}}\",\n \"auth_method\": \"{{outboundAuthMethod}}\",\n \"static_token\": \"{{outboundStaticToken}}\",\n \"username\": \"{{outboundUsername}}\",\n \"password\": \"{{outboundPassword}}\",\n \"shipments\": [\n {\n \"shipment_id\": 12345,\n \"shipment_number\": \"SHIP001\",\n \"receiver_name\": \"أحمد علي محمد\",\n \"receiver_phone_1\": \"07901234567\",\n \"governorate_code\": \"BGD\",\n \"city_name\": \"الكرادة\",\n \"address\": \"شارع الرشيد، بناية 10\",\n \"amount_iqd\": 50000.0,\n \"quantity\": 2,\n \"note\": \"يفضل الاتصال قبل التوصيل\",\n \"sender_name\": \"متجر ABC\",\n \"sender_phone\": \"07801234567\"\n }\n ]\n}" }, "url": { "raw": "{{baseUrl}}/v2/push/send-shipments", "host": ["{{baseUrl}}"], "path": ["v2", "push", "send-shipments"] }, "description": "Authenticated Jenni-side operation that pushes shipments to the configured external system in Push Out mode." } }, { "name": "Integration Update Status (Push Out -> Jenni)", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"system_code\": \"{{systemCode}}\",\n \"updates\": [\n {\n \"shipment_id\": 12345,\n \"action_code\": \"POSTPONED\",\n \"postponed_reason\": \"العميل غير متواجد\",\n \"postponed_reason_en\": \"Customer not available\",\n \"postponed_reason_ku\": \"کڕیار بەردەست نییە\",\n \"postponed_date_id\": 1,\n \"timestamp\": \"2024-01-15T10:30:00Z\",\n \"note\": \"سيتم التواصل غداً\"\n },\n {\n \"shipment_id\": 12346,\n \"action_code\": \"RETURNED_WITH_AGENT\",\n \"return_reason\": \"رفض الاستلام\",\n \"return_reason_en\": \"Customer refused\",\n \"return_reason_ku\": \"کڕیار ڕەتکردەوە\",\n \"timestamp\": \"2024-01-15T10:30:00Z\",\n \"note\": \"العميل رفض المنتج\"\n },\n {\n \"shipment_id\": 12347,\n \"action_code\": \"TREATED\",\n \"treated_message\": \"تم التواصل مع العميل وتحديد موعد جديد - سيتم التوصيل غداً الساعة 3 مساءً\",\n \"timestamp\": \"2024-01-15T10:30:00Z\",\n \"note\": \"Follow-up completed\"\n },\n {\n \"shipment_id\": 12348,\n \"action_code\": \"PARTIAL_DELIVERY\",\n \"is_partial\": true,\n \"quantity_delivered\": 3,\n \"quantity_returned\": 2,\n \"partial_has_returned\": true,\n \"partial_return_action\": \"RETURN_TO_STORE\",\n \"proof_image_url\": \"https://cdn.example.com/proof.jpg\",\n \"received_by_name\": \"أحمد علي\",\n \"timestamp\": \"2024-01-15T10:30:00Z\",\n \"note\": \"Partial delivery recorded\"\n }\n ]\n}" }, "url": { "raw": "{{baseUrl}}/v2/push/update-status", "host": ["{{baseUrl}}"], "path": ["v2", "push", "update-status"] }, "description": "Integration status endpoint used when your external system sends Push Out updates back to Jenni. Uses updates[] + action_code. IMPORTANT: Use shipment_id (recommended). POSTPONED requires postponed_reason + postponed_date_id. TREATED requires treated_message." } } ] }, { "name": "On YOUR Server Examples", "description": "Illustrative receiver endpoints that YOU implement on your own domain. These examples are not sent to Jenni baseUrl; update yourServerBaseUrl and yourServerInboundToken before testing them.", "item": [ { "name": "Receive Shipments on YOUR Server (Push Out)", "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{yourServerInboundToken}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"system_code\": \"{{systemCode}}\",\n \"shipments\": [\n {\n \"shipment_id\": 12345,\n \"shipment_number\": \"SHIP001\",\n \"external_shipment_id\": \"12345\",\n \"receiver_name\": \"Ahmed Ali\",\n \"receiver_phone_1\": \"07901234567\",\n \"governorate_code\": \"BGD\",\n \"city_name\": \"Al-Karrada\",\n \"city\": \"Al-Karrada\",\n \"address\": \"Street 10, Building 5\",\n \"amount_iqd\": 50000.0,\n \"quantity\": 1,\n \"note\": \"Please call before delivery\",\n \"sender_name\": \"ABC Store\",\n \"sender_phone\": \"07801234567\",\n \"is_proof_of_delivery\": false,\n \"is_fragile\": false\n }\n ]\n}" }, "url": { "raw": "{{yourServerBaseUrl}}/v2/shipments/create", "host": ["{{yourServerBaseUrl}}"], "path": ["v2", "shipments", "create"] }, "description": "Example inbound request that Jenni sends to YOUR server in Push Out mode. Jenni calls this endpoint with Authorization: Bearer {token}; the token may be static (TOKEN mode) or obtained by Jenni from your login flow (LOGIN mode). Implement this endpoint on your own domain and return accepted_shipments / rejected_shipments in the documented format. For each accepted shipment, return external_id as your internal shipment/order ID so Jenni can keep it for later matching and sync." } }, { "name": "Receive Status Updates on YOUR Server (Receive In Webhook / Push Out Follow-up)", "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{yourServerInboundToken}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"system_code\": \"{{systemCode}}\",\n \"username\": \"your_login_username_if_configured\",\n \"password\": \"your_login_password_if_configured\",\n \"updates\": [\n {\n \"shipment_number\": \"ORD-2024-001\",\n \"shipment_id\": 98765,\n \"external_id\": \"MYSTORE-ORDER-12345\",\n \"action_code\": \"SUCCESSFUL_DELIVERY\",\n \"current_step\": \"DELIVERED\",\n \"current_step_ar\": \"سلمت بنجاح\",\n \"current_stage\": \"DELIVERED\",\n \"current_stage_ar\": \"الواصل\",\n \"governorate_code\": \"BGD\",\n \"governorate_name\": \"BAGHDAD\",\n \"note\": \"Delivered successfully to customer\",\n \"agent_latitude\": 33.3152,\n \"agent_longitude\": 44.3661,\n \"amount_iqd\": 50000,\n \"amount_usd\": 0,\n \"quantity_delivered\": 1,\n \"quantity_returned\": 0,\n \"postponed_reason\": null,\n \"postponed_reason_en\": null,\n \"postponed_reason_ku\": null,\n \"postponed_date_id\": null,\n \"return_reason\": null,\n \"return_reason_en\": null,\n \"return_reason_ku\": null\n }\n ]\n}" }, "url": { "raw": "{{yourServerBaseUrl}}/v2/push/update-status", "host": ["{{yourServerBaseUrl}}"], "path": ["v2", "push", "update-status"] }, "description": "Example webhook request that Jenni sends to YOUR server when status changes. This is used in Receive In mode and can also be used for Push Out follow-up callbacks such as TREATED, POSTPONEMENT_APPROVED, and RETURN_APPROVED. For TOKEN mode Jenni may send Authorization: Bearer {token}; for LOGIN mode Jenni may include username/password in the request body." } } ] } ] }