Create Reverse Pickup Shipping API

• Introduction
• Request and Response

Introduction

This API provides an interface to create a new reverse pickup shipment at Aymakan.

{warning} Only allowed customers can create reverse pickup shipment

Request and Response

This API only accepts POST requests.

Development API End Point URL

https://dev-api.aymakan.com.sa/v2/shipping/create/reverse_pickup

Production API End Point URL

https://api.aymakan.net/v2/shipping/create/reverse_pickup

Headers

The following headers should be sent along with the request

• Accept: application/json
• Authorization: Your account security code / Api Token

Request

Below table list the request parameters which can be sent to Shipping Create API.

{info} The request parameters should be sent in request body using JSON format.

{warning} To be compatible with future API updates and releases, Please use the cities in the Cities API. As of now, Aymakan is not validating the city in the API requests, but it soon it will be implemented.

A sample POST request body is below with only the required data:

{
    "requested_by": "Test3",
    "declared_value": 1,
    "declared_value_currency": "SAR",
    "reference": "",
    "is_cod": 1,
    "cod_amount": 12,
    "currency": "SAR",
    "delivery_name": "Ahmed",
    "delivery_email": "[email protected]",
    "delivery_city": "Riyadh",
    "delivery_address": "Riyadh",
    "delivery_neighbourhood": "Al Sahafa",
    "delivery_postcode": 11543,
    "delivery_country": "SA",
    "delivery_phone": 540000000,
    "delivery_description": "",
    "collection_name": "Ahmed",
    "collection_email": "[email protected]",
    "collection_city": "Riyadh",
    "collection_address": "Al Sahafa",
    "collection_neighbourhood": "Riyadh",
    "collection_postcode": 11543,
    "collection_country": "SA",
    "collection_phone": 540000000,
    "collection_description": "",
    "weight": 38,
    "pieces": 1,
    "items_count": 1,
    "products": [
        {
            "sku": 1212,
            "qty": 1,
            "price":34
        },
        {
            "sku": 1212,
            "qty": 1,
            "price":34
        }
    ]
}

{info} The request parameters should be sent in request body using JSON format.

Response

Success Response

Upon successful request, the following response will be sent back with an HTTP status 200 OK.

{
    "success": true,
    "data": {
        "shipping": {
            "reference": null,
            "tracking_number": "RP47082146",
            "customer_tracking": null,
            "customer_name": null,
            "requested_by": "Test3",
            "price_set_amount": null,
            "price_set_amount_incl_tax": null,
            "tax_amount": null,
            "tax_rate": null,
            "cod_amount": 0,
            "declared_value": 1,
            "declared_value_currency": "SAR",
            "currency": "SAR",
            "delivery_name": "Ahmed",
            "delivery_email": "[email protected]",
            "delivery_city": "Riyadh",
            "delivery_address": "Riyadh",
            "delivery_region": null,
            "delivery_postcode": 11543,
            "delivery_country": "SA",
            "delivery_phone": 540000000,
            "delivery_description": null,
            "collection_name": "Ahmed",
            "collection_email": "[email protected]",
            "collection_city": "Riyadh",
            "collection_address": "Al Sahafa",
            "collection_region": null,
            "collection_postcode": 11543,
            "collection_country": "SA",
            "collection_phone": 540000000,
            "collection_description": null,
            "submission_date": "2021-10-03T08:24:22.206338Z",
            "pickup_date": null,
            "received_at": null,
            "delivery_date": null,
            "weight": 38,
            "pieces": 1,
            "items_count": 1,
            "status": "AWB created at origin",
            "status_label": null,
            "reason_en": null,
            "reason_ar": null,
            "created_at": "2021-10-03T08:24:22.000000Z",
            "is_reverse_pickup": 1,
            "label": "http://localhost/pdf/generate/daad6184-e15c-4e91-a859-913ce888f42c",
            "pdf_label": "http://localhost/pdf/generate/daad6184-e15c-4e91-a859-913ce888f42c"
        }
    }
}

{info} The reverse shipping tracking number starts with the prefix RP

Error Response

If the customer is not allowed to create reverse pickup shipment this error will be returned.

{
    "error": true,
    "message": "The given data was invalid.",
    "errors": {
        "rp": [
            "You are not allowed to create RP shipments. Contact sales team."
        ]
    }
}

In case of an error, the following response can be returned. The error response depends on the validation of request data, make sure all required data is entered correctly.

{
  "message": "The given data was invalid.",
  "errors": {
    "price_set": [
      "The price set field is required."
    ],
    "declared_value": [
      "The declared value field is required."
    ]
  }
}

Also, an HTTP status of 422 Unprocessable Entity will be returned.

In case of invalid credentials 401 Unauthorized, the following response will be returned.

{
    "error": true,
    "response": "Invalid Credentials"
}