Merchant APIs : Integration Guide
Changelog
2. Supplementary data for order creation
3. Order Creation
4. Edit an Order
5. Retrieve Orders
6. Get Orders Statuses
7. Retrieve Specific Orders by IDs (batch)
8. Manage Invoices
9. Response Handling
Merchant APIs : Integration Guide V2.3
Welcome to our Merchant 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.
What's new in V2.3 - 2025/1/18
1. Changed Get Orders Statuses API :

The Get Orders Statuses API now returns all possible order statuses.

V2.2 - 2024/12/31
1. Changed create order API name :

Renamed the "Create Order" API to "Order Creation".
Note : The functionality of the API remains unchanged.

2. Added clearer explanations for each endpoint :
- Added clearer explanations for each endpoint, providing more detailed information on their usage and expected responses.
- Clarified the authentication requirements for the Invoice API to ensure proper integration.
API Rate Limit :
To ensure fair usage and optimal performance of our API, we have implemented a rate limit of
30 requests per 30 seconds
for each user. This limit is enforced across all endpoints.
Endpoints :
Before delving into our endpoints, please import our collection to your postman via the following URL:
https://documenter.getpostman.com/view/5889333/
2sA3QpCtuw
01
Login Endpoint :

username and password are submitted to the endpoint, merchant token is returned.
Note: all the API communication depends on the auth-token.

URL : https://api.alwaseet-iq.net/v1/merchant/login
Method :

POST

Content-Type :

multipart/form-data

Purpose :

To authenticate a merchant and receive a token.

  • Login token resets after password change
  • Login with merchant account to get merchant token, or with merchant user account to get merchant user token
  • Invoice APIs strictly require Merchant token and will return authentication error if merchant user token is used.
Required Parameters :
  • username
    (string)
    [Required] :
    The merchant's username.
  • password
    (string)
    [Required] :
    The merchant's password.
Response :
  • On success : Returns a token to be used for future API calls.
  • On failure : Provides an error code and message.
Request Samples :
  • Query Parameters : No parameters
  • Request Body :
    • "username":"username"
"Password":"password"
Response Samples :
  • Response body on success :
    • {
 "status": true,
 "errNum": "S000", // On success "S000" will be returned
 "msg": "ok", // Success message
 "data": {
    "token": "@@d71480ycdmp9....", the login token (string)
 }
}
  • Response body on failure:
    • {
 "status": false,
 "errNum": "999", // Error code
 "msg": "error message", // Error message
}
02
Supplementary data for order creation :

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 :

Cities :

Returns a list of cities by name and ID.

  • URL : https://api.alwaseet-iq.net/v1/merchant/citys
  • Method :

    GET

  • Content-Type :

    multipart/form-data

  • Response : A list of cities in the format [{id: 1, city_name: 'name'}].

  • Request Sample :
    • Query Parameters : No parameters
    • Request Body : No body
  • Response Sample :
    • Response body on success :
    {
 "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)
  } 
 ]
}
    • Response body on error :
    {
 "status": false,
 "errNum": "999", // Error code
 "msg": "error message", // Error message
}
Regions :

Returns the list of regions by name and id for a given city-id.

  • URL : https://api.alwaseet-iq.net/v1/merchant/regions?city_id=ID
  • Method :

    GET

  • Content-Type :

    multipart/form-data

  • 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'}].

  • Request Sample :
    • Query Parameters :
      • "city_id":"ID"
    • Request Body: No body
  • Response Sample :
    • Response body on success:
      • {
 "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)
  }
 ] 
}
    • Response body on error :
      • {
 "status": false,
 "errNum": "999", // Error code
 "msg": "error message", // Error message
}
Package Sizes :

Returns a list of supported sizes by name and ID.

  • URL : https://api.alwaseet-iq.net/v1/merchant/package-sizes
  • Method :

    GET

  • Content-Type :

    multipart/form-data

  • Response : A list of available package sizes in the format [{id: 1 ,size: 'name'}].

  • Request Sample :
    • Query Parameters : No parameters
    • QRequest Body : No body
  • Response Sample :
    • Response body on success :
      • {
 "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)
  } 
 ]
}
    • Response body on error :
      • {
 "status": false,
 "errNum": "999", // Error code
 "msg": "error message", // Error message
}
03
Order Creation:

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.

URL : https://api.alwaseet-iq.net/v1/merchant/create-order?token=loginToken
Method :

POST

Content-Type :

multipart/form-data

Required Parameters (in body) :
  • client_name
    (string)
    [Required] :
    Name of the client.
  • client_mobile
    (string)
    [Required] :
    The client’s mobile number. Must be in this format “+9647000000000“, iraq country code followed by 10 numbers
  • client_mobile2
    (string)
    [Optional] :
    The client’s mobile number. Must be in this format “+9647000000000“, iraq country code followed by 10 numbers
  • city_id
    (int)
    [Required] :
    ID of the client’s city (from the Cities API).
  • region_id
    (int)
    [Required] :
    ID of the client’s region (from the Regions API).
  • location
    (string)
    [Required] :
    Description of the client’s location.
  • type_name
    (string)
    [Required] :
    Description of the type of goods in the order.
  • items_number
    (int)
    [Required] :
    Number of items in the order.
  • price
    (int)
    [Required] :
    Total price of the order, including delivery.
  • package_size
    (int)
    [Required] :
    The size of the order package (from the Package Sizes API).
  • merchant_notes
    (string)
    [Optional] :
    A general note or instruction about the order.
  • replacement
    (0 or 1)
    [Required] :
    Specifies if the order is a replacement.
Response :
  • On success : A success message and the order data.
  • On success : A success message and the order data.
Request Sample :
  • Query Parameters :
    • "token":"token"
  • Request Body :
    • 
"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
Response Sample :
  • Response body on success :
    • {
 "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),
    "qr_link": "https://alwaseet-iq.net/merchant/print-single-tcpdf?id=38799216&token=@@827ccb0eea8a706c4c34a16 (the receipt PDF link)
  } 
 ]
}
  • Response body on error :
    • {
"status": false,
"errNum": "999", // Error code
"msg": "error message", // Error message
}
04
Edit an Order :

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:

URL : https://api.alwaseet-iq.net/v1/merchant/edit-order?token=loginToken
Method :

POST

Content-Type :

multipart/form-data

Required Parameters (in body) :
  • qr_id
    (string)
    [Required] :
    Order number
  • client_name
    (string)
    [Required] :
    Name of the client.
  • client_mobile
    (string)
    [Required] :
    The client’s mobile number. Must be in this format “+9647000000000“, iraq country code followed by 10 numbers
  • client_mobile2
    (string)
    [Optional] :
    The client’s mobile number. Must be in this format “+9647000000000“, iraq country code followed by 10 numbers
  • city_id
    (int)
    [Required] :
    ID of the client’s city (from the Cities API).
  • region_id
    (int)
    [Required] :
    ID of the client’s region (from the Regions API).
  • location
    (string)
    [Required] :
    Description of the client’s location.
  • type_name
    (string)
    [Required] :
    Description of the type of goods in the order.
  • items_number
    (int)
    [Required] :
    Number of items in the order.
  • price
    (int)
    [Required] :
    Total price of the order, including delivery.
  • package_size
    (int)
    [Required] :
    The size of the order package (from the Package Sizes API).
  • merchant_notes
    (string)
    [Optional] :
    A general note or instruction about the order.
  • replacement
    (0 or 1)
    [Required] :
    Specifies if the order is a replacement.
Response :
  • On success : A success message.
  • On failure : An error message.
Request Sample :
  • Query Parameters :
    • "token":"token"
  • Request Body :
    • "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
Response Sample :
  • Response body on success :
    • {
 "status": true,
 "errNum": "",
 "msg": "ok", // Success message
}
  • Response body on error :
    • {
 "status": false,
 "errNum": "999", // Error code
 "msg": "error message", // Error message
}
05
Retrieve Orders :

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).

Alternatively you can retrieve orders by their ids using this API (Retrieve Specific Orders by IDs).

URL : https://api.alwaseet-iq.net/v1/merchant/merchant-orders?token=loginToken
Method :

GET

Content-Type :

multipart/form-data

Response :

A list of orders related to the merchant.

Request Sample :
  • Query Parameters : 
    "token":"token"
  • Request Body : no body
Response Sample:
  • Response body on success : 
    {
 "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) 
    "status":"تم استلام الطلب من قبل المندوب", (the status text of the order)
    "price":"20000", (the order price including delivery fee) 
    "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)
    "has_merchant_fin_record":"0", (if 1 then this order is included in a merchant invoice)
    "deliver_confirmed_fin":"0", (if 1 then this order has been delivered and order money has been received by the company from the delivery driver and the merchant can request an invoice for it)
    "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 the merchant hasn't requested an invoice for this order yet)
  }    
 ] 
}
  • Response body on error : 
    {
 "status": false,
 "errNum": "999", // Error code
 "msg": "error message", // Error message
}
06
Get Order Statuses :

This API provides a list of order statuses, each associated with a unique status ID and a descriptive status text.

URL : https://api.alwaseet-iq.net/v1/merchant/statuses?token=loginToken
Method :

GET

Content-Type :

multipart/form-data

Response : A list of order statuses in the format [{id: 1, status: 'status text'}].

Request Sample :
  • Query Parameters : 
    "token":"token"
  • Request Body: No body
Response Sample :
  • Response body on success : 
    {
 "status": true,
 "errNum": "S000", // On success "S000" will be returned
 "msg": "ok", // Success message
 "data": [
  {
    "id": "1",
    "status": "تم الاستلام من قبل المندوب"
  } 
 ]
}
  • Response body on error : 
    {
    "status": false,
    "errNum": "999", // Error code
    "msg": "error message", // Error message
}
07
Retrieve Specific Orders by IDs
(batch)
:

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.

URL : https://api.alwaseet-iq.net/v1/merchant/get-orders-by-ids-bulk?token=loginToken
Method :

POST

Content-Type :

multipart/form-data

Parameter :
ids

(string)

[Required] :

A comma-separated string of order IDs to retrieve, max ids is 25 if more is sent thay will be discarded.

Response :

Details of the selected orders.

Request Sample :
  • Query Parameters : 
    "token":"token"
  • Request Body : 
    "ids":"11,23,75,29" (string of comma separated values, max 25 ids)
Response Sample :
  • Response body on success : 
    {
 "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)
    "status":"تم استلام الطلب من قبل المندوب", (the status text of the order)
    "price":"20000", (the order price including delivery fee)
    "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)
    "has_merchant_fin_record":"0", (if 1 then this order is included in a merchant invoice)
    "deliver_confirmed_fin":"0", (if 1 then this order has been delivered and order money has been received by the company from the delivery driver and the merchant can request an invoice for it)
    "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 the merchant hasn't requested an invoice for this order yet)
  }    
 ] 
}
  • Response body on error : 
    {
 "status": false,
 "errNum": "999", // Error code
 "msg": "error message", // Error message
}
08
Manage Invoices :

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.

OR
receive an invoice using the following APIs.

Get Merchant Invoices :
  • URL : https://api.alwaseet-iq.net/v1/merchant/get_merchant_invoices?token=loginToken
  • Method :

    GET

  • Content-Type :

    multipart/form-data

  • Response :

    Returns all invoices related to the merchant.

  • Request Sample:
    • Query Parameters :
      • "token":"token"
    • Request Body : No body
  • Response Sample :
    • Response body on success :
      • {
 "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)
  }    
 ] 
}
    • Response body on error :
      • {
 "status": false,
 "errNum": "999", // Error code
 "msg": "error message", // Error message
}
Get Orders for an Invoice :
  • URL : https://api.alwaseet-iq.net/v1/merchant/get_merchant_invoice_orders?token=loginToken&invoice_id=invoiceID
  • Method :

    GET

  • Content-Type :

    multipart/form-data

  • Parameter:

    invoice_id
    (string): The ID of the invoice.

  • Response :

    Returns all orders associated with a particular invoice.

  • Request Sample :
    • Query Parameters :
      • "token":"token"
"invoice_id":"ID"
    • Request Body : No body
  • Response Sample :
    • Response body on success :
      • {
 "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)
 "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)
  }
 ]
}
    • Response body on error :
      • {
 "status": false,
 "errNum": "999", // Error code
 "msg": "error message", // Error message
}
Receive an Invoice :

    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.

  • URL : https://api.alwaseet-iq.net/v1/merchant/receive_merchant_invoice?token=loginToken&invoice_id=invoiceID
  • Method :

    GET

  • Content-Type :

    multipart/form-data

  • Parameter:

    invoice_id
    (string): The ID of the invoice.

  • Response :

    Marks the invoice as received.

  • Request Sample :
    • Query Parameters :
      • "token":"token"
"invoice_id":"ID"
    • Request Body : No body
  • Response Sample :
    • Response body on success :
      • {
 "status": true,
 "errNum": "S000", // On success "S000" will be returned
 "msg": "ok", // Success message
}
    • Response body on error :
      • {
 "status": false,
 "errNum": "999", // Error code
 "msg": "error message", // Error message
}
09
Response Handling :

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
}