PARTNER INTEGRATION REFERENCE

Store Partner API Documentation

Comprehensive API reference for Store Partners (Managers and Employees). Use these endpoints to create delivery orders with Google Maps location URLs, check customer blacklist status, manage package pickups, and configure employee access.

Base URL: http://127.0.0.1:8000
Authorization Header: Authorization: Bearer <access_token>
Content Type: application/json

Role & Permissions Matrix

Every partner account has a defined role (MANAGER or EMPLOYEE). Managers have unrestricted access to their store, while employees operate under explicit permission flags:

Operation / Area Store Manager Employee Flag Required
View Orders & Details ✓ Allowed can_see_orders = True
Create Orders & Request Pickups ✓ Allowed can_add_orders = True
Update Existing Orders ✓ Allowed can_edit_orders = True
View Blacklisted Numbers ✓ Allowed can_see_blacklisted_numbers = True
Add Numbers to Blacklist ✓ Allowed can_add_blacklisted_numbers = True
Manage Store Info & Employees ✓ Allowed ✕ Store Manager Only

1. Authentication & Profile

POST /api/auth/login/
Public (No Auth Header)

Authenticates a store manager or employee using their registered phone number and password. Returns JWT access and refresh tokens alongside user profile and store association details.

Request Body (JSON)
Field Type Required Description
phone string Required Registered Iraqi phone number (e.g., 07701234567)
password string Required Account password
Request Example 
{
  "phone": "07701234567",
  "password": "storeManagerPassword123"
}
Response: 200 OK 
{
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 5,
    "phone": "07701234567",
    "name": "Ibrahim Store Manager",
    "role": "MANAGER",
    "is_manager": true,
    "partner_id": 2,
    "partner_name": "Al-Nour Electronics",
    "created_at": "2026-09-01T10:00:00Z"
  }
}
POST /api/auth/refresh/
Public (Requires Refresh Token)

Exchanges a valid refresh token for a new short-lived JWT access token when the current access token expires.

Request Example 
{
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Response: 200 OK 
{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
GET /api/profile/detail/
Authenticated User

Retrieves identity, role, and avatar details of the authenticated store user.

Response: 200 OK 
{
  "id": 5,
  "phone": "07701234567",
  "name": "Ibrahim Store Manager",
  "role": "MANAGER",
  "is_admin": false,
  "is_manager": true,
  "is_employee": false,
  "is_delivery": false,
  "created_at": "2026-09-01T10:00:00Z"
}
PATCH /api/profile/update/
Authenticated User

Allows updating personal profile fields (name, phone, or password).

Request Example 
{
  "name": "Ibrahim Store Manager (Updated)",
  "phone": "07709998877"
}
Response: 200 OK 
{
  "id": 5,
  "phone": "07709998877",
  "name": "Ibrahim Store Manager (Updated)",
  "role": "MANAGER",
  "created_at": "2026-09-01T10:00:00Z"
}

2. Store Partner Profile

GET /api/store/partner/detail/
MANAGER / EMPLOYEE

Returns full profile information of the store associated with the logged-in user, including its unique prefix code for QR tracking.

Response: 200 OK 
{
  "id": 2,
  "name": "Al-Nour Electronics",
  "prefix_code": "ALN",
  "phone": "07701234567",
  "address": "الموصل - حي السكر - الفرع التجاري",
  "description": "متجر الكترونيات وأجهزة ذكية",
  "neighbourhood": 3,
  "is_active": true,
  "created_at": "2026-08-15T09:00:00Z"
}
PATCH /api/store/partner/update/
STORE MANAGER ONLY

Updates store contact details, physical address, or description.

Request Example 
{
  "name": "Al-Nour Electronics & Gadgets",
  "phone": "07701234567",
  "address": "الموصل - حي السكر - مقابل مصرف الرشيد"
}
Response: 200 OK 
{
  "id": 2,
  "name": "Al-Nour Electronics & Gadgets",
  "prefix_code": "ALN",
  "phone": "07701234567",
  "address": "الموصل - حي السكر - مقابل مصرف الرشيد",
  "is_active": true
}

3. Store Employee Management

GET /api/store/employees/list/
STORE MANAGER ONLY

Lists all staff accounts created for this store with their assigned permissions.

Response: 200 OK 
[
  {
    "id": 1,
    "partner": 2,
    "account": {
      "id": 12,
      "name": "محمود موظف الاستلام",
      "phone": "07703334455",
      "role": "EMPLOYEE"
    },
    "can_see_dashboard": true,
    "can_see_orders": true,
    "can_add_orders": true,
    "can_edit_orders": false,
    "can_manage_partner_info": false,
    "is_active": true
  }
]
POST /api/store/employees/create/
STORE MANAGER ONLY

Creates an employee user account tied directly to your store and sets their specific permissions.

Request Body (JSON)
Field Type Required Description
account integer Required Account ID of an existing user or newly registered user
can_see_orders boolean Optional (default: true) Can view store orders list and details
can_add_orders boolean Optional (default: false) Can create new delivery orders & courier pickup requests
can_edit_orders boolean Optional (default: false) Can edit existing orders
Request Example 
{
  "account": 14,
  "can_see_orders": true,
  "can_add_orders": true,
  "can_edit_orders": false
}
Response: 201 Created 
{
  "id": 2,
  "partner": 2,
  "account": 14,
  "can_see_orders": true,
  "can_add_orders": true,
  "can_edit_orders": false,
  "is_active": true
}

4. Orders Management

GET /api/store/orders/features/
Authenticated Partner

Returns all active special delivery features (e.g., Fragile, Needs Cooling, Heavy Weight, Special Handling) to populate selection chips/checkboxes in your order creation UI.

Response: 200 OK 
[
  {
    "id": 1,
    "name": "قابل للكسر (Fragile)",
    "code": "fragile",
    "description": "يتطلب عناية خاصة أثناء النقل لتجنب الكسر",
    "extra_charge": 0,
    "is_active": true
  },
  {
    "id": 2,
    "name": "يحتاج تبريد (Needs Cooling)",
    "code": "cooling",
    "description": "يتطلب النقل في حافظة مبردة للحفاظ على جودة المنتج",
    "extra_charge": 0,
    "is_active": true
  },
  {
    "id": 3,
    "name": "وزن ثقيل (Heavy Weight)",
    "code": "heavy",
    "description": "شحنة ذات وزن ثقيل تحتاج إلى وسيلة نقل مناسبة",
    "extra_charge": 0,
    "is_active": true
  },
  {
    "id": 4,
    "name": "معاملة خاصة (Special Handling)",
    "code": "special_delivery",
    "description": "يتطلب تسليم سريع أو إشراف مباشر",
    "extra_charge": 0,
    "is_active": true
  }
]
GET /api/store/orders/list/
can_see_orders

Returns all delivery orders placed by your store. Each item contains full pricing, Google Maps location URL, delivery status, assigned courier details, neighborhood info, and selected delivery features.

Response: 200 OK 
[
  {
    "id": 101,
    "qr_code": "ALN-A1B-26-09-05",
    "partner": 2,
    "delivery_boy": 8,
    "driver": {
      "id": 8,
      "name": "أحمد محمد (Courier)",
      "phone": "07712345678"
    },
    "status": "OUT_FOR_DELIVERY",
    "rejection_reason": null,
    "order_type": "inside_mosul",
    "customer_name": "سارة علي",
    "customer_phone": "07709876543",
    "delivery_address": "حي الزهور - قرب جامع الصبور",
    "location_on_map": "https://maps.app.goo.gl/abc123xyz",
    "neighborhood": 4,
    "neighborhood_details": {
      "id": 4,
      "name": "حي الزهور",
      "city": "Mosul"
    },
    "total_price": 45000,
    "delivery_charge": 5000,
    "is_order_paid": false,
    "is_delivery_charge_paid": false,
    "requires_special_delivery": true,
    "features": [
      {
        "id": 1,
        "name": "قابل للكسر (Fragile)",
        "code": "fragile",
        "description": "يتطلب عناية خاصة أثناء النقل لتجنب الكسر",
        "extra_charge": 0,
        "is_active": true
      }
    ],
    "order_details": "عطور ومستحضرات تجميل",
    "created_at": "2026-09-05T12:30:00Z",
    "updated_at": "2026-09-05T13:00:00Z"
  }
]
POST /api/store/orders/create/
can_add_orders

Creates a new delivery order. Supports saving Google Maps location URLs, delivery fees, selected feature IDs, packaging QR code, and items details.

Request Body (JSON)
Field Type Required Description
customer_name string Required Customer's full name
customer_phone string Required Recipient customer phone number
delivery_address string Required Detailed textual address
location_on_map string (URL) Optional Google Maps location link (e.g. https://maps.app.goo.gl/...)
total_price integer Required Price of items in Iraqi Dinars (IQD)
delivery_charge integer Optional (default: 0) Delivery fee in IQD
order_type string Optional inside_mosul, districts_and_subdistricts, governorates
is_vip_delivery boolean Optional (default: false) VIP priority delivery flag (توصيل VIP سريع)
neighborhood integer (ID) Optional Neighborhood ID from coverage list
feature_ids array of integers Optional List of selected OrderFeature IDs (e.g. [1, 2] for Fragile & Cooling)
order_details string Optional Summary of items ordered
Request Example 
{
  "customer_name": "سارة علي",
  "customer_phone": "07709876543",
  "delivery_address": "حي الزهور - قرب جامع الصبور",
  "location_on_map": "https://maps.app.goo.gl/abc123xyz",
  "total_price": 45000,
  "delivery_charge": 5000,
  "order_type": "inside_mosul",
  "neighborhood": 4,
  "feature_ids": [1, 2],
  "order_details": "عطور ومستحضرات تجميل"
}
Response: 201 Created 
{
  "id": 102,
  "qr_code": null,
  "partner": 2,
  "delivery_boy": null,
  "driver": null,
  "status": "NEW",
  "rejection_reason": null,
  "order_type": "inside_mosul",
  "customer_name": "سارة علي",
  "customer_phone": "07709876543",
  "delivery_address": "حي الزهور - قرب جامع الصبور",
  "location_on_map": "https://maps.app.goo.gl/abc123xyz",
  "neighborhood": 4,
  "neighborhood_details": {
    "id": 4,
    "name": "حي الزهور",
    "city": "Mosul"
  },
  "total_price": 45000,
  "delivery_charge": 5000,
  "is_order_paid": false,
  "is_delivery_charge_paid": false,
  "requires_special_delivery": true,
  "features": [
    {
      "id": 1,
      "name": "قابل للكسر (Fragile)",
      "code": "fragile",
      "description": "يتطلب عناية خاصة أثناء النقل لتجنب الكسر",
      "extra_charge": 0,
      "is_active": true
    },
    {
      "id": 2,
      "name": "يحتاج تبريد (Needs Cooling)",
      "code": "cooling",
      "description": "يتطلب النقل في حافظة مبردة للحفاظ على جودة المنتج",
      "extra_charge": 0,
      "is_active": true
    }
  ],
  "order_details": "عطور ومستحضرات تجميل",
  "created_at": "2026-09-05T14:00:00Z",
  "updated_at": "2026-09-05T14:00:00Z"
}
GET /api/store/orders/{id}/detail/
can_see_orders

Fetches complete order details. If assigned to a courier, the driver block contains their name and contact phone number.

Response: 200 OK 
{
  "id": 102,
  "qr_code": "ALN-K78-26-09-05",
  "partner": 2,
  "delivery_boy": 8,
  "driver": {
    "id": 8,
    "name": "أحمد محمد (Courier)",
    "phone": "07712345678"
  },
  "status": "OUT_FOR_DELIVERY",
  "rejection_reason": null,
  "order_type": "inside_mosul",
  "customer_name": "سارة علي",
  "customer_phone": "07709876543",
  "delivery_address": "حي الزهور - قرب جامع الصبور",
  "location_on_map": "https://maps.app.goo.gl/abc123xyz",
  "neighborhood": 4,
  "neighborhood_details": {
    "id": 4,
    "name": "حي الزهور",
    "city": "Mosul"
  },
  "total_price": 45000,
  "delivery_charge": 5000,
  "is_order_paid": false,
  "is_delivery_charge_paid": false,
  "is_vip_delivery": false,
  "requires_special_delivery": true,
  "features": [
    {
      "id": 1,
      "name": "قابل للكسر (Fragile)",
      "code": "fragile",
      "description": "يتطلب عناية خاصة أثناء النقل لتجنب الكسر",
      "extra_charge": 0,
      "is_active": true
    }
  ],
  "order_details": "عطور ومستحضرات تجميل",
  "created_at": "2026-09-05T14:00:00Z",
  "updated_at": "2026-09-05T14:30:00Z"
}
PATCH /api/store/orders/{id}/update/
can_edit_orders

Updates editable fields of an order (e.g. address, phone number, location URL, price, or details).

Request Example 
{
  "delivery_address": "حي الزهور - خلف جامع الصبور - بيت رقم 12",
  "location_on_map": "https://maps.app.goo.gl/updatedMapLink",
  "total_price": 48000
}
Response: 200 OK 
{
  "id": 102,
  "delivery_address": "حي الزهور - خلف جامع الصبور - بيت رقم 12",
  "location_on_map": "https://maps.app.goo.gl/updatedMapLink",
  "total_price": 48000,
  "updated_at": "2026-09-05T14:45:00Z"
}
POST /api/store/orders/check-qr/
can_add_orders

Checks if a scanned QR code belongs to your store and whether it is already tied to an order.

Request Example 
{
  "qr_code": "ALN-A1B-26-09-05"
}
Response: 200 OK 
{
  "valid": true,
  "exists": false,
  "message": "QR code is valid and available for new order assignment."
}
GET /api/store/orders/customer-by-phone/?phone={phone}
can_see_orders

Autofills past customer information (name, address, neighborhood, Google Maps link) during order entry and verifies whether this customer phone is blacklisted.

Response: 200 OK (Customer Found & Blacklist Status) 
{
  "is_blacklisted": true,
  "blacklist_reason": "Customer refused delivery multiple times without valid reason",
  "customer": {
    "customer_name": "سارة علي",
    "customer_phone": "07709876543",
    "delivery_address": "حي الزهور - قرب جامع الصبور",
    "neighborhood": 4,
    "location_on_map": "https://maps.app.goo.gl/abc123xyz"
  }
}

5. Store Customer Blacklist

GET /api/store/orders/blacklist/
can_see_blacklisted_numbers

Lists all customer phone numbers blacklisted specifically by your store.

Response: 200 OK 
[
  {
    "id": 9,
    "phone": "07709876543",
    "customer_name": "سارة علي",
    "reason": "Repeated order cancellations at doorstep",
    "partner": 2,
    "partner_name": "Al-Nour Electronics",
    "created_by": 5,
    "created_by_name": "Ibrahim Manager",
    "created_at": "2026-09-05T15:20:00Z"
  }
]
POST /api/store/orders/blacklist/
can_add_blacklisted_numbers

Adds a problematic customer phone number to your store's blacklist.

Request Example 
{
  "phone": "07709876543",
  "customer_name": "سارة علي",
  "reason": "Repeated order cancellations at doorstep"
}
Response: 201 Created 
{
  "id": 9,
  "phone": "07709876543",
  "customer_name": "سارة علي",
  "reason": "Repeated order cancellations at doorstep",
  "partner": 2,
  "created_at": "2026-09-05T15:20:00Z"
}
DELETE /api/store/orders/blacklist/{id}/
can_add_blacklisted_numbers

Removes a phone number from your store's blacklist. Returns 204 No Content.

6. Courier Collection Requests (Store Pickups)

Collection Requests allow your store to call for a courier pickup when packages are boxed and ready.
Lifecycle: PENDING (Waiting for courier) → ACCEPTED (Courier assigned & on the way) → COMPLETED (Courier collected packages).

POST /api/store/orders/collection-requests/
can_add_orders

Submits a request for courier pickup. Only 1 active pickup request is allowed at a time for each store.

Request Body (JSON)
Field Type Required Description
packages_count integer Optional (default: 1) Estimated number of packages ready for pickup
notes string Optional Pickup instructions or gate location
Request Example 
{
  "packages_count": 8,
  "notes": "الطلبات مجهزة وجاهزة للاستلام من الباب الخلفي"
}
Response: 201 Created 
{
  "id": 14,
  "partner": 2,
  "partner_name": "Al-Nour Electronics",
  "courier": null,
  "courier_details": null,
  "status": "PENDING",
  "packages_count": 8,
  "notes": "الطلبات مجهزة وجاهزة للاستلام من الباب الخلفي",
  "created_by": 5,
  "created_by_name": "Ibrahim Manager",
  "created_at": "2026-09-05T15:00:00Z",
  "updated_at": "2026-09-05T15:00:00Z"
}
GET /api/store/orders/collection-requests/active/
can_see_orders

Returns the active pickup request. When accepted by a courier, status changes to ACCEPTED and courier_details shows their name and phone number ("Courier on the way").

Response: 200 OK (Courier On The Way) 
{
  "id": 14,
  "partner": 2,
  "partner_name": "Al-Nour Electronics",
  "courier": 8,
  "courier_details": {
    "id": 8,
    "phone": "07712345678",
    "name": "أحمد محمد",
    "role": "DELIVERY"
  },
  "status": "ACCEPTED",
  "packages_count": 8,
  "notes": "الطلبات مجهزة وجاهزة للاستلام من الباب الخلفي",
  "created_at": "2026-09-05T15:00:00Z",
  "updated_at": "2026-09-05T15:10:00Z"
}
DELETE /api/store/orders/collection-requests/{id}/cancel/
can_add_orders

Cancels a pickup request if it is still in PENDING status. (Accepted or Completed requests cannot be cancelled).

Response: 204 No Content

7. Delivery Neighborhoods

GET /api/store/neighborhoods/list/
can_see_orders

Returns all delivery coverage zones/neighborhoods with their IDs to populate address selection dropdowns in store applications.

Response: 200 OK 
[
  {
    "id": 1,
    "name": "حي الزهور",
    "city": "Mosul",
    "delivery_charge": 5000
  },
  {
    "id": 2,
    "name": "حي السكر",
    "city": "Mosul",
    "delivery_charge": 5000
  },
  {
    "id": 3,
    "name": "حي المثنى",
    "city": "Mosul",
    "delivery_charge": 5000
  }
]