Akwaan Express Merchant API Documentation

Overview

The Akwaan Express Merchant API allows external merchants to integrate with the Akwaan Express delivery system to create, track, and manage orders. This documentation covers all available endpoints for merchant integration.

Base Information

• API Version: 1.0
• Base URL: https://api.akwanexpress.com/
• Content-Type: application/json
• Authentication: API Key based

Authentication

API Key Authentication

All API requests require an API key to be included in the request headers.

ApiKey: your-api-key-here

Getting API Access

1. Contact Akwaan Express support to register your merchant account
2. Provide your integration details:
   • Webhook URL: Your server endpoint to receive order status updates
   • Contact information: Email, phone, company details
3. Receive your unique API key and integration configuration
4. Your webhook URL will be configured in the system to receive status updates
5. No direct access to the admin panel is required - all operations via API

Order Management

1. Create Order (External Merchant)

Creates a new order for external merchants using API key authentication.

Headers:

Content-Type: application/json
ApiKey: your-api-key-here

Request Body:

{
  "code": "ORD-2024-001",
  "customerName": "أحمد حسن علي",
  "customerPhoneNumber": "07901234567",
  "customerSecondPhoneNumber": "07801234567",
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "content": "1x iPhone 15 Pro Max 256GB - أسود",
  "deliveryZoneName": "الزعفرانية",
  "pickupZoneName": "المنصور",
  "pickUpGovernorateId": 1,
  "deliveryGovernorateId": 1,
  "note": "قطعة هشة - تعامل معها بحذر شديد",
  "amount": 40000.00,
  "paidAmount": 0.00,
  "nearestLandmark": "قرب مجمع بغداد التجاري",
  "pickUpLocation": {
    "lat": 33.3152,
    "long": 44.3661
  },
  "deliveryLocation": {
    "lat": 33.3406,
    "long": 44.4009
  }
}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "code": "MERCHANT-001-ORD-2024-001",
  "customerName": "أحمد حسن علي",
  "customerPhoneNumber": "07901234567",
  "customerSecondPhoneNumber": "07801234567",
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "content": "1x iPhone 15 Pro Max 256GB - أسود",
  "deliveryZoneName": "الزعفرانية",
  "pickupZoneName": "المنصور",
  "pickupGovernorate": {
    "id": 1,
    "name": "محافظة بغداد"
  },
  "deliveryGovernorate": {
    "id": 1,
    "name": "محافظة بغداد"
  },
  "note": "قطعة هشة - تعامل معها بحذر شديد",
  "amount": 40000.00,
  "paidAmount": 0.00,
  "nearestLandmark": "قرب مجمع بغداد التجاري",
  "size": "Small",
  "pickUpLocation": {
    "lat": 33.3152,
    "long": 44.3661
  },
  "deliveryLocation": {
    "lat": 33.3406,
    "long": 44.4009
  },
  "status": "Pending"
}

2. Get Order by External ID

Retrieves order details using the external order ID (your system's order ID).

Headers:

ApiKey: your-api-key-here

Example:

GET /api/b2b/external/order/550e8400-e29b-41d4-a716-446655440000

Response:

Same as Create Order response

3. Cancel Order

Cancels an existing order using the internal order ID.

Headers:

Content-Type: application/json
ApiKey: your-api-key-here

Example:

PUT /api/b2b/merchant/order/550e8400-e29b-41d4-a716-446655440000/cancel

Response:

Updated order object with status "Cancelled"

Data Structures

OrderCreationIntegrationForm

Location Object

Order Status Enum

Order Size Enum

Error Handling

Error Response Format

{
  "error": "Error message description",
  "details": "Additional error details if available"
}

Common Error Messages

HTTP Status Codes

Webhooks

The system supports webhooks for real-time order status updates. When you register for API access, you must provide your webhook URL where you want to receive status updates.

Webhook Configuration

During registration, provide your webhook URL in this format:

• Your Webhook URL: https://your-domain.com/api/akwaan/order
• Example: https://merchant-api.example.com/api/akwaan/order

The system will automatically append the external order ID to your URL when sending updates.

Webhook Events

Webhook Payload

The system will send HTTP PUT requests to your configured webhook URL with the following format:

URL Pattern: {YOUR_WEBHOOK_URL}/api/akwaan/order-delivery/webhook

Example URL: https://merchant-api.example.com/api/akwaan/order-delivery/webhook

Headers:

Content-Type: application/json
Authorization: {your-auth-header} (if configured)

Payload:

[
    {
        "eventType": "OrderStatusUpdated",
        "eventData": {
            "orderId" : "02323",
            "status": "InDeliveryProgress"
        }
    }
]

Webhook Event Data

Sample Data for Testing

Governorate IDs (Iraq)

• بغداد: 1
• البصرة: 2
• بابل: 3
• نجف: 4
• المثنى: 5
• ميسان: 6
• كركوك: 7
• كربلاء: 8
• ديالى: 9
• الانبار: 10
• دهوك: 11
• اربيل: 12
• نينوى: 13
• القادسية: 14
• صلاح الدين: 15
• السليمانية: 16
• ذي قار: 17
• واسط: 18

Content Field Examples

The content field should describe the items and quantities being shipped:

• "1x iPhone 15 Pro Max 256GB - أسود"
• "3x Samsung Galaxy S24 Ultra 512GB - أسود تيتانيوم"
• "2x MacBook Pro 16-inch M3 Max - رمادي"
• "5x AirPods Pro 2nd Generation - أبيض"
• "1x iPad Air 11-inch 256GB - أزرق"

Payment Fields Clarification

• amount: The value of the items being shipped ONLY (e.g., 40000.00 for a 40,000 IQD phone) - DO NOT include delivery fee
• deliveryFee: The cost of delivery (calculated automatically by the system based on zones and pricing)
• totalAmount: Order amount + delivery fee (calculated automatically by the system)
• PaidAmount: The paid amount of the order with the delivery fee (Order amount = 40,000, Delivery fee = 5,000,PaidAmount = 45,000,totalAmount = 0)

Example Payment Breakdown:

Item Value (amount): 40,000 IQD
Delivery Fee: 5,000 IQD (calculated by system)
Total Amount: 45,000 IQD (calculated by system)

Integration Checklist

Before integrating with the Akwaan Express API, ensure you have:

• ✅ Contacted Akwaan Express support for API access
• ✅ Provided your webhook URL during registration (format: https://your-domain.com/api/akwaan/orders)
• ✅ Received your unique API key
• ✅ Set up your webhook endpoint to handle PUT requests with the pattern /api/akwaan/orders/{externalId}
• ✅ Tested with sample data using the provided examples
• ✅ Implemented proper error handling
• ✅ Set up monitoring for API responses
• ✅ Verified governorate and zone names are correct

Support

For technical support or questions about the API:

• Website: https://api.akwanexpress.com/
• Email:
• Phone:

Changelog

This documentation is maintained by the Akwaan Express development team. For the most up-to-date information, please refer to the latest version of this document.