الخدمات
سواء كنت متجراً يرسل الطلبات يومياً أو شخصاً يرسل طرداً واحداً، عندنا طريقة واضحة لإيصال شحنتك.
01
نستلم طلبات متجرك من داخل بغداد ونوصلها إلى زبائنك في بغداد وجميع المحافظات، مع متابعة كل طلب.
02
عندك طرد لأهلك أو غرض تريد إيصاله لمحافظة أخرى؟ تواصل معنا ونستلمه منك داخل بغداد ونوصله.
03
ننسّق الإرجاع والاستبدال مع التاجر بوضوح، ولدينا سياسة تعويض وخدمات استرداد نقدي (كاش باك).
04
لدينا نظام خاص للتجار وواجهة برمجية (API) لربط المتاجر الإلكترونية بنا، والتفاصيل متاحة عند الطلب.
كيف نعمل
التاجر ينشئ الطلب من نظام التجار أو من متجره مباشرة، والفرد يتواصل معنا.
نستلم الشحنة منك من داخل بغداد وتُجهَّز للانطلاق.
تنطلق الشحنة إلى المستلم في بغداد أو أي محافظة.
يستلم زبونك طلبه ويدفع نقداً عند الاستلام أو بماستركارد.
سعر واحد واضح
أسعار مخصصة للتجار بعد التواصل.
API
كل ما يحتاجه مطوّر متجرك لربطه مباشرة بنظام التوصيل: تسجيل الدخول، إنشاء الطلبات وتعديلها وحذفها، متابعة الحالات، الفواتير، والإشعارات الفورية (Webhooks). المرجع بالإنجليزية كما هو شائع في توثيق الـAPI.
المصدر: نظام التشغيل الذي تعمل عليه الشركة - agg-iq.net/apiDoc - V1.11.4 - 2026/9/19. عند أي اختلاف يُعتمد التوثيق في الرابط الأصلي. لطلب حساب تاجر للبدء تواصل معنا.
Welcome to our API Documentation!
We’re thrilled to have you here. Our API is designed to provide seamless integration and powerful functionality to help you achieve your goals. Whether you’re building a new application, integrating an existing one, or just exploring what our API can do, you’ll find everything you need right here.
A new endpoint — Retrieve Order Story — returns the chronological snapshots of a single merchant order from the order log.
Use this API when you need the full status and data history of one order, rather than the current order list returned by Retrieve Orders.
A new endpoint — Retrieve Active Orders — returns the merchant's currently relevant orders while excluding stale completed or returned orders that have not been updated in the last month.
Use this API when you need an up-to-date order list without loading the full order history returned by Retrieve Orders.
In the following APIs — Retrieve Orders, Retrieve Specific Orders by IDs (Batch), Get Orders With Issues, and Manage Invoices-Get Orders for an Invoice — a new variable has been added ("old_price") to indicate whether the price has changed.
This field shows the OLD order price including delivery fee. If it is set to -1, then the price did not change.
In the Order Status Update Webhook, a new variable has been added ("old_price") to indicate whether the price has changed.
In the following APIs — Retrieve Specific Orders by IDs (Batch), Retrieve Orders, and the Order Status Update Webhook — a new variable has been introduced to indicate the state of a returning order when status_id = 23 (Returning to Returned Warehouse).
To see how this variable is used, refer to the Response Sample section in the Retrieve Specific Orders by IDs (Batch) or Retrieve Orders APIs, or the Request Samples section in the Order Status Update Webhook.
A new API enabling merchants to resend orders once they have been returned to the designated returns warehouse.
check the new api here
Added new api that allows you to request returned orders on behalf of the merchant.
check the new api here
Added a new api that allows you to get orders with issue on behalf of the merchant.
check the new api here
Added a new api that allows you to resend a returned order to a new or the same customer.
check the new api here
Added support for company-specific order ID prefixes to improve system integration and order tracking.
check the registrations process here
Now you can receive returned orders on behalf of the merchant using the new API.
check it out
Your merchants may want to resolve order issues on their own. With this new API, you can enable them to do so.
check it out
We’ve added a new deliver_done flag to the following APIs and webhook 'Retrieve Orders' API, 'Retrieve Orders by IDs' API and the webhook.
This flag enables you to filter orders by their delivery status.
We’ve updated the webhook by adding new flags. The following flags have been introduced
'merchant_invoice_id', 'deliver_confirmed_fin' and 'has_merchant_fin_record' flags have been added to the webhook.
For more details, please refer to the Flags in the 'Request Sample' in the webhook section.
We’ve introduced a powerful new API that allows you to create multiple orders in a single, streamlined request.
This update simplifies the order creation process, enhancing efficiency and saving valuable time when managing large volumes of orders.
check it out.
We've added a new webhook specifically for order status updates.
Now, you can automatically receive real-time updates whenever the status of an order changes in our system.
check it out.
In the 'Create Order', 'Edit Order', 'Retrieve All Orders', and 'Retrieve Orders by IDs' APIs,
a 'Company Order ID' field has been added. This allows you to track which order ID in our system corresponds to the order ID in your system.
Renamed the "Create Order" API to "Order Creation".
Note : The functionality of the API remains unchanged.
With this API, you can delete specific orders.
username and password are submitted to the endpoint, merchant token is returned.
Note: all the API communication depends on the auth-token.
https://agg-iq.net/operation/v1/merchant/login POST
multipart/form-data
To authenticate a merchant and receive a token.
"username":"username"
"Password":"password"{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": {
"token": "@@d71480ycdmp9....", the login token (string)
}
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
} To create an order in our API, couple of parameters have to be specified (region-id, city-id, package-size).
Each of these values has its own API as shown below:
Several endpoints are used to get necessary data before creating an order :
https://agg-iq.net/operation/v1/merchant/cities GET
Response : A list of cities in the format [{id: 1, city_name: 'name'}].
{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"id": "1", the id of the city (string)
"city_name": "name" the text of the city (string)
}
]
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
}https://agg-iq.net/operation/v1/merchant/regions?city_id=ID GET
Parameter : city_id (int) [Required] : Specifies the city for which regions are retrieved.
Response : A list of regions within the specified city in the format [{id: 1, region_name: 'name'}].
"city_id":"ID"{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"id": "1", the id of the region (string)
"region_name": "name" the text of the region (string)
}
]
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
}https://agg-iq.net/operation/v1/merchant/package-sizes GET
Response : A list of available package sizes in the format [{id: 1 ,size: 'name'}].
{
"status": true,
"errNum": "S000", // On success "S000" will be returned "msg": "ok", // Success message
"data": [
{
"id": "1", the id of the package size (string)
"size": "name" the text of the package size (string)
}
]
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
}After preparing all the order info (city-id, region-id, package-size, customer-phone, price, client-name, location description etc.) you can proceed and submit your order-creation info to the API.
https://agg-iq.net/operation/v1/merchant/create-order?token=loginToken POST
multipart/form-data
* Note: This parameter is [Required] if a Company Order ID prefix is activated for the company. The provided Order ID must begin with the registered prefix and must include the full prefix as defined.
If you don't have a registered prefix and would like to add your own, please check this section.
"token":"token""client_name":"name",
"client_mobile":"+964700000000",
"client_mobile2":"+964700000000",
"city_id":ID,
"region_id":ID,
"location":"text",
"type_name":"text",
"items_number":number,
"price":number,
"package_size":ID,
"merchant_notes":"text",
"replacement ":0 or 1,
"company_order_id":"123"{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"client_name":"محمد" (the name of the client),
"client_mobile":"+9647704723599" (client phone number),
"client_mobile2":"+9647704723599"(client second phone number),
"city_id":"5" (the city id of the client),
"region_id":"2" (the region id of the client),
"merchant_mobile":"07704723599" (set from merchant info),
"items_number":"1" (number of items in the order),
"price":"25000" (price of the order including delivery fee),
"package_size":"1" (the size of the order),
"cash_fee":0 (set if order price exceeds 1'000'000 IQD),
"location":"market" (client delivery location description),
"merchant_id":"5" (set from merchant info),
"current_city":"1" (set automatically by the system),
"merchant_city":"1" (set from merchant info),
"company_price":4000 (the delivery fee of this order),
"city_fees":0 (set automatically by the system),
"merchant_price":21000 (the order price without delivery fee),
"type_name":"ملابس" (orders goods type),
"merchant_created_at":"2024-08-10 16:30:10" (set automatically by the system),
"merchant_notes":"عدم فتح القطعة" (set by the merchant),
"qr_id": 38799216 (the QR id of this order, thi will be the main identifier of the order),
"pickup_id": "1" (the pickup drier assigned to this order),
"pickup_created_at": "2024-08-10 04:30:10pm" (set automatically by the system),
"id": 38799216 (set automatically by the system),
"company_order_id":"123", (The order ID from the company's system.),
"qr_link": "https://agg-iq.net/operation/merchant/print-single-tcpdf?id=orderQr&token=merchantToken" (the receipt PDF link)
}
]
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
}In scenarios where the order info needs to be updated and the order is still at the merchant possession, this endpoint provides the ability to do so:
https://agg-iq.net/operation/v1/merchant/edit-order?token=loginToken POST
multipart/form-data
* Note: This parameter is [Required] if a Company Order ID prefix is activated for the company. The provided Order ID must begin with the registered prefix and must include the full prefix as defined.
If you don't have a registered prefix and would like to add your own, please check this section.
"token":"token""qr_id":"6942069",
"client_name":"name",
"client_mobile":"+964700000000",
"client_mobile2":"+964700000000",
"city_id":ID,
"region_id":ID,
"location":"text",
"type_name":"text",
"items_number":number,
"price":number,
"package_size":ID,
"merchant_notes":"text",
"replacement ":0 or 1,
"company_order_id":"123"{
"status": true,
"errNum": "",
"msg": "ok", // Success message
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
} In scenarios where the order needs to be deleted and the order is still in the merchant's possession, this endpoint provides the ability to do so.
Note : Order status must be equal to 1 (new order) to be deleted.
https://agg-iq.net/operation/v1/merchant/delete-orders?token=loginToken POST
multipart/form-data
"token":"token""qr_id":"6942069"{
"status": true,
"errNum": "",
"msg": "ok", // Success message
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
} Now with your order being alive in our system. You might want to inquire about order details/status.
To do so, the APIs below have been provided (basically returns a list of order(s) with their status). Use Retrieve Active Orders for a lighter list that excludes old completed or returned orders.
https://agg-iq.net/operation/v1/merchant/merchant-orders?token=loginToken GET
A list of orders related to the merchant.
"token":"token"{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"client_name":"محمد", (name of the client)
"client_mobile":"+9647704723599", (client mobile number)
"items_number":"1", (number of items in this order)
"created_at":"2023-08-13 22:12:18", (the date and time of when the order was created)
"city_name":"بغداد", (city name of client)
"region_name":"شارع فلسطین", (region name of the client)
"status_id":"2", (the status id of the order)
"send_to_store": (0 OR 1 OR 2),
This flag is relevant when status_id = 23 (Returning to Returned Warehouse). It indicates the current stage of the return process:
0 – The order is still in the city warehouse.
1 – The order is in transit to the Baghdad warehouse.
2 – The order has been received at the Baghdad warehouse.
This flag is primarily used in the Resolve Returned Order API.
"deliver_done":(0 OR 1), (if 1 then the order has been delivered)
"status":"تم استلام الطلب من قبل المندوب", (the status text of the order)
"price":"20000", (the order price including delivery fee)
"old_price":"18000" OR -1, (the OLD order price including delivery fee, if it is set to -1 then the price did not change)
"location":"market", (the description of the client location)
"issue_notes":"لا یوجد", (a note written by the delivery driver when there is an issue with the order)
"merchant_notes":"لا یوجد", (a note written by the merchant)
"client_mobile2":"07", (client second mobile number)
"updated_at":"2024-06-22 11:28:53", (the last date and time the order data was updated)
"city_id":"13", (client city number)
"region_id":"1043", (client region number)
"replacement":"0", (indicate if the order is a replacement or not, 1 for replacement 0 for not)
"type_name":"ملابس", (order goodes type)
"id":"103", (order id)
"company_order_id": "123", (The order ID from the company's system.),
"has_merchant_fin_record": 0 OR 1, (indicates whether the merchant has requested accounting for the invoice this order is included in, 1 if the merchant has requsted accounting.)
"deliver_confirmed_fin":0 OR 1, (if 1 then the order has been delivered, and the company has received payment from the delivery driver. At this stage, the merchant is eligible to request accounting for this order.)
"delivery_price":"9000", (the delivery fee of this order)
"package_size":"عادي", (the order size)
"merchant_invoice_id":"-1" (the merchant invoice number, if the value is "-1" then this order is not included in a merchant invoice and the merchant can not request accounting for this order.)
}
]
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
} Returns the merchant's currently relevant orders. Unlike merchant-orders in Retrieve Orders, which returns the full order history, this endpoint excludes stale final-state orders — delivered orders and orders returned to the merchant — that have not been updated in the last month.
All in-progress orders are always included, and recently completed or returned orders (updated within the last month) are also included.
https://agg-iq.net/operation/v1/merchant/current-active-merchant-orders?token=loginToken GET
A filtered list of the merchant's active and recently updated orders.
"token":"token"Same structure as Retrieve Orders above.
{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"client_name":"محمد", (name of the client)
"client_mobile":"+9647704723599", (client mobile number)
"items_number":"1", (number of items in this order)
"created_at":"2023-08-13 22:12:18", (the date and time of when the order was created)
"city_name":"بغداد", (city name of client)
"region_name":"شارع فلسطین", (region name of the client)
"status_id":"2", (the status id of the order)
"send_to_store": (0 OR 1 OR 2),
"deliver_done":(0 OR 1), (if 1 then the order has been delivered)
"status":"تم استلام الطلب من قبل المندوب", (the status text of the order)
"price":"20000", (the order price including delivery fee)
"old_price":"18000" OR -1, (the OLD order price including delivery fee, if it is set to -1 then the price did not change)
"location":"market", (the description of the client location)
"issue_notes":"لا یوجد", (a note written by the delivery driver when there is an issue with the order)
"merchant_notes":"لا یوجد", (a note written by the merchant)
"client_mobile2":"07", (client second mobile number)
"updated_at":"2024-06-22 11:28:53", (the last date and time the order data was updated)
"city_id":"13", (client city number)
"region_id":"1043", (client region number)
"replacement":"0", (indicate if the order is a replacement or not, 1 for replacement 0 for not)
"type_name":"ملابس", (order goodes type)
"id":"103", (order id)
"company_order_id": "123", (The order ID from the company's system.),
"has_merchant_fin_record": 0 OR 1, (indicates whether the merchant has requested accounting for the invoice this order is included in, 1 if the merchant has requsted accounting.)
"deliver_confirmed_fin":0 OR 1, (if 1 then the order has been delivered, and the company has received payment from the delivery driver. At this stage, the merchant is eligible to request accounting for this order.)
"delivery_price":"9000", (the delivery fee of this order)
"package_size":"عادي", (the order size)
"merchant_invoice_id":"-1" (the merchant invoice number, if the value is "-1" then this order is not included in a merchant invoice and the merchant can not request accounting for this order.)
}
]
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
}This API provides a list of order statuses, each associated with a unique status ID and a descriptive status text.
https://agg-iq.net/operation/v1/merchant/statuses?token=loginToken GET
Response : A list of order statuses in the format [{id: 1, status: 'status text'}].
"token":"token"{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"id": "1",
"تم الاستلام من قبل المندوب" :"status"
}
]
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
} Retrieve Specific Orders by IDs (batch)
Unlike the "Retrieve Orders" endpoint with returned all the orders, this endpoint allows you to inquire about a specific id(s) by specifying them into a comma-separated string of order IDs to retrieved.
The maximum number of ids to be retrieved is 25.
https://agg-iq.net/operation/v1/merchant/get-orders-by-ids-bulk?token=loginToken POST
multipart/form-data
(string)
A comma-separated string of order IDs to retrieve. A maximum of 25 IDs is allowed—any additional IDs beyond this limit will be discarded.
Details of the selected orders.
"token":"token""ids":"11,23,75,29" (string of comma separated values, max 25 ids){
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"client_name":"محمد", (name of the client)
"client_mobile":"+9647704723599", (client mobile number)
"items_number":"1", (number of items in this order)
"created_at":"2023-08-13 22:12:18", (the date and time of when the order was created)
"city_name":"بغداد", (city name of client)
"region_name":"شارع فلسطین", (region name of the client)
"status_id":"2", (the status id of the order)
"send_to_store": (0 OR 1 OR 2),
This flag is relevant when status_id = 23 (Returning to Returned Warehouse). It indicates the current stage of the return process:
0 – The order is still in the city warehouse.
1 – The order is in transit to the Baghdad warehouse.
2 – The order has been received at the Baghdad warehouse.
This flag is primarily used in the Resolve Returned Order API.
"deliver_done":(0 OR 1), (if 1 then the order has been delivered)
"status":"تم استلام الطلب من قبل المندوب", (the status text of the order)
"price":"20000", (the order price including delivery fee)
"old_price":"18000" OR -1, (the OLD order price including delivery fee, if it is set to -1 then the price did not change)
"location":"market", (the description of the client location)
"issue_notes":"لا یوجد", (a note written by the delivery driver when there is an issue with the order)
"merchant_notes":"لا یوجد", (a note written by the merchant)
"client_mobile2":"07", (client second mobile number)
"updated_at":"2024-06-22 11:28:53", (the last date and time the order data was updated)
"city_id":"13", (client city number)
"region_id":"1043", (client region number)
"replacement":"0", (indicate if the order is a replacement or not, 1 for replacement 0 for not)
"type_name":"ملابس", (order goodes type)
"id":"103", (order id)
"company_order_id": "123", (The order ID from the company's system.),
"has_merchant_fin_record": 0 OR 1, (indicates whether the merchant has requested accounting for the invoice this order is included in, 1 if the merchant has requsted accounting.)
"deliver_confirmed_fin":0 OR 1, (if 1 then the order has been delivered, and the company has received payment from the delivery driver. At this stage, the merchant is eligible to request accounting for this order.)
"delivery_price":"9000", (the delivery fee of this order)
"package_size":"عادي", (the order size)
"merchant_invoice_id":"-1" (the merchant invoice number, if the value is "-1" then this order is not included in a merchant invoice and the merchant can not request accounting for this order.)
}
]
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
} Returns the chronological snapshots of a single merchant order from the order log. Each item in the list is a saved copy of the order at a given point in time (oldest first).
Unlike Retrieve Orders, which returns the current state of many orders, this endpoint is for one order identified by qr_id. Archived orders are included. If the order has no log entries, an empty list is returned.
https://agg-iq.net/operation/v1/merchant/order-story?token=loginToken&qr_id=103 GET
A chronological list of order-log snapshots for the requested order.
"token":"token"
"qr_id":"103"Same order fields as Retrieve Orders. updated_at is the time of that snapshot, not the current order update time.
{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "تم", // Success message
"data": [
{
"client_name":"محمد", (name of the client)
"client_mobile":"+9647704723599", (client mobile number)
"items_number":"1", (number of items in this order)
"created_at":"2023-08-13 22:12:18", (the date and time of when the order was created)
"city_name":"بغداد", (city name of client)
"region_name":"شارع فلسطین", (region name of the client)
"status_id":"2", (the status id of the order at this snapshot)
"send_to_store": (0 OR 1 OR 2),
"deliver_done":(0 OR 1), (if 1 then the order has been delivered)
"status":"تم استلام الطلب من قبل المندوب", (the status text of the order at this snapshot)
"price":"20000", (the order price including delivery fee)
"old_price":"18000" OR -1, (the OLD order price including delivery fee, if it is set to -1 then the price did not change)
"location":"market", (the description of the client location)
"issue_notes":"لا یوجد", (a note written by the delivery driver when there is an issue with the order)
"merchant_notes":"لا یوجد", (a note written by the merchant)
"client_mobile2":"07", (client second mobile number)
"updated_at":"2024-06-22 11:28:53", (the date and time of this snapshot)
"city_id":"13", (client city number)
"region_id":"1043", (client region number)
"replacement":"0", (indicate if the order is a replacement or not, 1 for replacement 0 for not)
"type_name":"ملابس", (order goodes type)
"id":"103", (order id)
"company_order_id": "123", (The order ID from the company's system.),
"has_merchant_fin_record": 0 OR 1, (indicates whether the merchant has requested accounting for the invoice this order is included in, 1 if the merchant has requsted accounting.)
"deliver_confirmed_fin":0 OR 1, (if 1 then the order has been delivered, and the company has received payment from the delivery driver. At this stage, the merchant is eligible to request accounting for this order.)
"delivery_price":"9000", (the delivery fee of this order)
"package_size":"عادي", (the order size)
"merchant_invoice_id":"-1" (the merchant invoice number, if the value is "-1" then this order is not included in a merchant invoice and the merchant can not request accounting for this order.)
}
]
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
}In some cases, orders may encounter issues during delivery. These orders are handled by our team, but you can retrieve a list of them using this API. If you prefer to resolve the issues yourself, you can use the Resolve Order API.
https://agg-iq.net/operation/v1/merchant/orders-with-issue?token=merchant-token GET
Returns all orders that have a reported issue.
"token":"merchant-token"{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"client_name": "cutomer name",
"client_mobile": "+9647700000000",
"items_number": "2",
"created_at": "2025-12-30 23:59:59",
"city_name": "بغداد",
"region_name": "شارع فلسطين",
"status": "مغلق",
"package_size": "متوسط",
"status_id": "35",
"price": "15000",
"old_price": "18000" OR -1, (the OLD order price including delivery fee, if it is set to -1 then the price did not change)
"location": "location discription",
"issue_notes": "لا يوجد",
"deliver_done": "0",
"merchant_notes": "merhcant note",
"client_mobile2": "+9647700000000",
"updated_at": "2025-12-30 23:59:59",
"city_id": "1",
"region_id": "1",
"replacement": "1",
"type_name": "ملابس",
"id": "102",
"company_order_id": "AGG_12345",
"has_merchant_fin_record": "0",
"deliver_confirmed_fin": "0",
"delivery_price": "6750",
"merchant_invoice_id": "-1"
}
]
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
} Your merchants can now resolve order issues using the following API.
This API allows them to provide an order ID and the new customer phone number, and it will reset the order status to 'On its way to the client'.
Note: The issue can only be resolved once the order is with the delivery driver. If the order is returned to the warehouse, it cannot be resolved.
https://agg-iq.net/operation/v1/merchant/resolve-order?token=merchant-token&order-id=123&client-mobile=+9647700000000¬e=merchant-note GET
Response :
"token":"merchant-login-token"
"order-id":123
"client-mobile":"+9647700000000"
"note":"merchant-note"{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
}
https://agg-iq.net/operation/v1/merchant/request-returned-orders?token=merchant-token POST
multipart/form-data
(string)
A comma-separated list of order IDs. A maximum of 25 IDs is allowed. If more than 25 are provided, an error will be returned.
Response : A JSON object containing the IDs of successfully retrieved orders and those that failed.
"token":"token""ids":"11,33,55,77" (string of comma separated values, max 25 ids){
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": {
"succeededOrders": [
"11,55"
],
"filedOrders": [
"33,77"
],
}
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
}Instead of returning the order to the original merchant, you can use this API to resend the order to a new or the same client. This endpoint functions similarly to the Edit Order API, with the key difference being that it only supports orders currently in specific statuses. Allowed Status IDs:
Ensure the order is in one of the above statuses before attempting to use this API.
https://agg-iq.net/operation/v1/merchant/resend-order-to-client?token=merchant-token POST
multipart/form-data
* Note: This parameter is [Required] if a Company Order ID prefix is activated for the company. The provided Order ID must begin with the registered prefix and must include the full prefix as defined.
If you don't have a registered prefix and would like to add your own, please check this section.
"token":"merchant-token""qr_id":"6942069",
"client_name":"name",
"client_mobile":"+964700000000",
"client_mobile2":"+964700000000",
"city_id":ID,
"region_id":ID,
"location":"text",
"type_name":"text",
"items_number":number,
"price":number,
"package_size":ID,
"merchant_notes":"text",
"replacement ":0 or 1,
"company_order_id":"123"{
"status": true,
"errNum": "",
"msg": "ok", // Success message
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
}Several APIs are available for managing merchant invoices:
Authentication Requirements for Invoice APIs
To use the Invoice APIs, only the Merchant token is accepted for authentication. If a Merchant user token is used instead, an authentication error will be returned. Please ensure that the correct token is used to avoid authentication issues.
To inquire about invoices, you can use the get merchant invoices API and retrieve invoices. Then get invoice orders from the following APIs.
https://agg-iq.net/operation/v1/merchant/get-merchant-invoices?token=loginToken GET
Returns all invoices related to the merchant.
"token":"token"{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"id": "3", (invoice id)
"merchant_price": "170000", (total price to be received from this invoice)
"delivered_orders_count": "7", (number of delivered orders for this invoice)
"replacement_delivered_orders_count": "0", (number of replacement delivered orders)
"status": "تم الاستلام من قبل التاجر", (invoice status text)
"merchant_id": "5", (merchant id)
"updated_at": "2023-12-20 17:01:46" (last date and time the invoice was updated)
}
]
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
} https://agg-iq.net/operation/v1/merchant/request-new-invoice?token=loginToken POST
multipart/form-data
Creates a new invoice for the merchant with the cuutently deliverd orders.
"token":"token""accounting_by_rep": 0 OR 1 // send merchant invoice by pickup driver (1) or receive the merchant invoice in person (0){
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
}https://agg-iq.net/operation/v1/merchant/get-merchant-invoice-orders?token=loginToken&invoice_id=invoiceID GET
Returns all orders associated with a particular invoice.
"token":"token"
"invoice_id":"ID"{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data":
"invoice" : [
{
"id": "3", (invoice id)
"merchant_price": "170000", (total price to be received from this invoice)
"delivered_orders_count": "7", (number of delivered orders for this invoice)
"replacement_delivered_orders_count": "0", (number of replacement delivered orders)
"status": "تم الاستلام من قبل التاجر", (invoice status text)
"merchant_id": "5", (merchant id)
"updated_at": "2023-12-20 17:01:46" (last date and time the invoice was updated)
}
]
"orders" : [
{
"client_name":"محمد", (name of the client)
"client_mobile":"+9647704723599", (client mobile number)
"items_number":"1", (number of items in this order)
"created_at":"2023-08-13 22:12:18", (the date and time of when the order was created)
"city_name":"بغداد", (city name of client)
"region_name":"شارع فلسطین", (region name of the client)
"status_id":"2", (the status id of the order)
"status":"تم استلام الطلب من قبل المندوب", (the status text of the order)
"price":"20000", (the order price including delivery fee)
"old_price":"18000" OR -1, (the OLD order price including delivery fee, if it is set to -1 then the price did not change)
"location":"market", (the description of the client location)
"issue_notes":"لا یوجد", (a note written by the delivery driver when there is an issue with the order)
"merchant_notes":"لا یوجد", (a note written by the merchant)
"client_mobile2":"07", (client second mobile number)
"updated_at":"2024-06-22 11:28:53", (the last date and time the order data was updated)
"city_id":"13", (client city number)
"region_id":"1043", (client region number)
"replacement":"0", (indicate if the order is a replacement or not, 1 for replacement 0 for not)
"type_name":"ملابس", (order goodes type)
"id":"103", (order id)
"delivery_price":"9000", (the delivery fee of this order)
"package_size":"عادي", (the order size)
"merchant_invoice_id":"8" (the merchant invoice number)
}
]
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
} When the invoice is sent to the merchant he has to confirm the receipt by scanning the invoice's QR-code via the merchant-app.
Alternatively, the invoice can be confirmed (received) by the API below.
https://agg-iq.net/operation/v1/merchant/receive-merchant-invoice?token=loginToken&invoice_id=invoiceID GET
Marks the invoice as received.
"token":"token"
"invoice_id":"ID"{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
} This API allows the merchant to resend a returning order with a new customer phone number. The order status must be Send to Returns Warehouse (status ID = 23) AND the send_to_store = 0 to be eligible for resending. Only the customer phone number can be changed — the destination address must remain the same.
Note: For more information on the send_to_store value, refer to the Response Sample section in the Retrieve Specific Orders by IDs (Batch) or Retrieve Orders APIs, or the Request Samples section in the Order Status Update Webhook.
https://agg-iq.net/operation/v1/merchant/resolve-order-in-return-store?token=Merchant-Token POST
multipart/form-data
Response :
"qr_id":123
"client_mobile":"+9647700000000"
"client_mobile2":"+9647700000000"{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
}In case of an error, the API will return a response with the following structure :
{
"status": false,
"errNum": "999", // Error code
"msg": "error message" // Error message
}A successful response typically looks like this :
{
"status": true,
"errNum": "S000", // Success code
"msg": "ok", // Success message
"data": [ ... ] // Relevant data
}While the previous endpoints were designed to handle the orders on the merchant level, this set of API endpoints is designed to provided merchant(s) management i.e., to enable the aggregator to handle his merchant(s).
All aggre APIs requier an authentication token to be included in the request parameters,
username and password are submitted to the endpoint, aggregator token is returned.
https://agg-iq.net/operation/v1/aggre/login POST
multipart/form-data
To authenticate the comapny account and receive a token.
"username":"username"
"Password":"password"{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": {
"token": "aggre-token", // the login token (string)
"user-data": { // company information
"name": "company name",
"username": "company username",
"mobile": "company mobile"
}
}
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
}With this API you can get all merchant(s) that belongs to your company.
https://agg-iq.net/operation/v1/aggre/get-merchants?token=aggreLoginToken GET
Returns all merchants
"token":"token"{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"id": "123",
"username": "merchant username",
"token": "merchant token",
"mobile": "merchant mobile",
"name": "merchant name",
"city_id": "merchant city id"
}
]
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
}In situations where you need to add a new merchant to our system, you can use this API.
https://agg-iq.net/operation/v1/aggre/add-merchant?token=aggreLoginToken POST
multipart/form-data
"token":"aggre-token""name":"Merchant"
"username":"merchant244"
"password":"12345678"
"mobile":"+96477xxxxxxxx"
"city":"1"
"region":"1"
"location":"قرب زيونة"
"goods_type":"ملابس"
"page_name":"Merchant Businees"{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "Done Successfully.", // Success message
"data": {
"merchant_id": 123 // the created merchant ID (int)
"token": "merchantToken" // the created merchant token (string)
}
}{
"status": false,
"errNum": 1, // Error code
"msg": "error message" // Error message
} In certain situations, you may need to quickly create multiple orders for different merchants.
With this API, you can send a JSON array string containing the orders data, and you'll receive a response that provides success and error messages for each individual order.
You will need the data from the Supplementary Data for Order Creation API(s) to create the orders.
https://agg-iq.net/operation/v1/aggre/create-bulk-orders?token=aggreLoginToken POST
multipart/form-data
* Note: This parameter is [Required] if a Company Order ID prefix is activated for the company. The provided Order ID must begin with the registered prefix and must include the full prefix as defined.
If you don't have a registered prefix and would like to add your own, please check this section.
"token":"aggre-token""data":"[ // JSON array
{
"client_name":"name",
"client_mobile":"+964700000000",
"client_mobile2":"+964700000000",
"city_id":ID,
"region_id":ID,
"location":"text",
"type_name":"text",
"items_number":number,
"price":number,
"package_size":ID,
"merchant_notes":"text",
"replacement":0 or 1,
"merchant_id":ID,
"company_order_id":ID,
"metadata":"text",
}
]"{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "Done Successfully.", // Success message
"data": {
"succeed": [], // an array with all the successfuly created orders
"failed": [] // an array with all the filed orders with an error message for each order
}
}{
"status": false,
"errNum": 1, // Error code
"msg": "error message" // Error message
}To print stickers for your orders, you can send the order ID(s) to this endpoint, and it will generate a PDF file containing the stickers for the order(s) and return a link to that file.
https://agg-iq.net/operation/v1/aggre/print-orders?token=aggreLoginToken&orders-ids=1,2,3 GET
You can submit a maximum of 100 orders per request.
A link to printed orders file
"token":"aggre-token",
"orders-ids":"1,2,3" // comma separated values of orders IDs we want to print{
"status": true,
"errNum": "S000",
"msg": "Done Successfully.",
"data": {
"filePath": "file path link"
}
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
}If you need to retrieve previously created PDF files, you can do so using this API.
https://agg-iq.net/operation/v1/aggre/get-printed-orders?token=aggreLoginToken GET
A list of printed orders files
"token":"aggre-token"{
"status": true,
"errNum": "S000",
"msg": "Done Successfully.",
"data": [
{
"fileName": "file name",
"filePath": "file path link",
"fileType": "file",
"fileSize": "file size"
},
{
"fileName": "file name",
"filePath": "file path link",
"fileType": "file",
"fileSize": "file size"
}
]
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
}To verify if an order is already created with the same company system order number.
https://agg-iq.net/operation/v1/aggre/check-order-exists-by-company-order-number?token=aggreLoginToken&company-order-id=1 GET
"token":"aggre-token",
"company-order-id":"1" // company system order number{
"status": true,
"errNum": "S000",
"msg": "Done Successfully.",
"data": {
"order": "[{orderData}]" OR "[]"
}
}To receive a merchant's returned order, you can use this API to update the order status to "Returned To Merchant".
https://agg-iq.net/operation/v1/aggre/receive-returned-order?token=aggreLoginToken POST
multipart/form-data
"token":"aggre-token""merchant-token":"merchant-token",
"order-id":123{
"status": true,
"errNum": "S000",
"msg": "Done Successfully.",
}{
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
}At our company, we understand the importance of real-time updates and seamless integration between systems. That's why we offer webhooks as a powerful feature to keep your system automatically in sync with key events in our platform.
With webhooks, you no longer need to constantly check for updates. Instead, we’ll send real-time updates directly to your system whenever specific events occur, such as changes to an order’s status. This allows your system to react immediately, whether it’s updating databases, triggering workflows, or sending notifications, all without manual intervention.
By leveraging webhooks, you can streamline your processes, reduce overhead, and ensure that your system stays up-to-date with minimal effort. In this section, we’ll walk you through how to configure and use our webhooks to receive order status updates, so you can take advantage of this feature for a more efficient and automated experience.
This web Hook sends updates regarding order status changes to the API endpoint you provide. The updates are triggered whenever an order transitions through different stages.
You'll need to provide the API endpoint URL where we should send the order status update data. The webhook will send a POST request with the status update data to this URL.
URL : The order status update information will be sent to the API endpoint that you provided.
POST
application/json
Purpose : To automatically send updates about order status changes to your system.
"auth-key-name:token" {
"client_name":"محمد", (name of the client)
"client_mobile":"+9647712345678", (client mobile number)
"items_number":"1", (number of items in this order)
"created_at":"2023-08-13 22:12:18", (the date and time of when the order was created)
"city_name":"بغداد", (city name of client)
"region_name":"شارع فلسطین", (region name of the client)
"status_id":"2", (the status id of the order)
"send_to_store": (0 OR 1 OR 2),
This flag is relevant when status_id = 23 (Returning to Returned Warehouse). It indicates the current stage of the return process:
0 – The order is still in the city warehouse.
1 – The order is in transit to the Baghdad warehouse.
2 – The order has been received at the Baghdad warehouse.
This flag is primarily used in the Resolve Returned Order API.
"deliver_done":(0 OR 1), (if 1 then the order has been delivered)
"status":"تم استلام الطلب من قبل المندوب", (the status text of the order)
"price":"20000", (the order price including delivery fee)
"old_price":"18000" OR -1, (the OLD order price including delivery fee, if it is set to -1 then the price did not change)
"location":"market", (the description of the client location)
"issue_notes":"لا یوجد", (a note written by the delivery driver when there is an issue with the order)
"merchant_notes":"لا یوجد", (a note written by the merchant)
"client_mobile2":"+9647712345678", (client second mobile number)
"updated_at":"2024-06-22 11:28:53", (the last date and time the order data was updated)
"city_id":"13", (client city number)
"region_id":"1043", (client region number)
"replacement":"0", (indicate if the order is a replacement or not, 1 for replacement 0 for not)
"type_name":"ملابس", (order goodes type)
"id":"103", (order id)
"company_order_id": "123", (The order ID from the company's system.)
"has_merchant_fin_record": 0 OR 1, (indicates whether the merchant has requested accounting for the invoice this order is included in, 1 if the merchant has requsted accounting.)
"deliver_confirmed_fin":0 OR 1, (if 1 then the order has been delivered, and the company has received payment from the delivery driver. At this stage, the merchant is eligible to request accounting for this order.)
"delivery_price":"9000", (the delivery fee of this order)
"package_size":"عادي" (the order size)
"merchant_invoice_id":"-1" (the merchant invoice number, if the value is "-1" then this order is not included in a merchant invoice and the merchant can not request accounting for this order.)
} You can now use your own company-specific order IDs within our system, subject to certain conditions. This feature enables better alignment between your internal systems and our order processing workflow. It also allows your company to use its own order manifest (order information sticker) when delivering orders.
Requirements for Order ID Prefix: To enable this feature, you must first register a unique order ID prefix that adheres to the following rules:
تاجراً كنت أو فرداً، تواصل معنا ونوصل شحنتك إلى بغداد وجميع المحافظات.