Guides
Log In

Shipping API

Suggest Edits

What is Shipping API :

Shipping service, is an added value service that allows you simply to sell and ship your product through MyFatoorah platform with one payment for your customer. You just need to share your products information to our API with the exact dimensions and weight, then we take care of the rest.

You can create your shipping invoice to your customer directly without having your products predefined MyFatoorah account. Currently we support both DHL and Aramex

351
  • To use this feature, you have to get your account approved for it, please contact your account manager for more details about this feature

Prerequisites:

  • Having an API user created and activated
  • Having the shipping feature enabled and activated

From MyFatoorah portal, the main account login should setup the needed settings from the profile page.

Demo Account:

Kindly, use demo information found here.

Steps to use Shipping API:

  1. Create your API Token
    POST /Token API to authorize the API user ,this API take username and password and return Token.

Note: This token will be used in all the next steps to authorize the requests. Add this header to all the requests : "Authorization": "Bearer { token}"

2.Call GET ApiShipping/GetCountries API

Note: Add this header to the request: "Authorization": "Bearer {token from step 1} after calling the API you will get an array of all countries available for shipping.

3.Call GET ApiShipping/GetCities?shippingMethod=1&countryCode=US API with Token.

ShippingMethods : 1 – HDL, 2 – Aramex
Country Code : Please take the code from step 2 response.

Note: Add this header to the request: "Authorization": "Bearer {token from step 1} after calling the API you will get an array of all Cities for the selected country available for shipping.

4.Call Post ApiShipping/CalculateShippingCharge API with ShippingChargeModel.

Note: Add this header to the request: "Authorization": "Bearer {token from step 1} after calling the API you will get the shipping charge and the currency type.

{
  "ShippingMethod": 1,
  "Items": [
    {
      "ProductName": "test",
      "Description": "test",
      "Weight": 1.0,
      "Width": 1.0,
      "Height": 1.0,
      "Depth": 1.0,
      "Quantity": 1.0,
      "UnitPrice": 1.0
    }
  ],
  "CityName": "kuwait",
  "PostalCode": "1200",
  "CountryCode": "1"
}

5.Call Post ApiShipping/CreateShippingInvoiceAPI API with ShippingInvoiceModel.

Note: Add this header to the request: "Authorization": "Bearer {token from step 1} after calling the API you will get RedirectUrl and available payment methods URLs.

{
  "ShippingMethod": 1,
  "Items": [


   {
      "ProductName": "car 88 ",
      "Description": "TEST ",
      "Weight": 1,
      "Width": 1,
      "Height": 1,
      "Depth": 1,
      "Quantity": 1,
      "UnitPrice": 190,
      "UseExist":true
    }
  ],
  "Consignee": {
    "PersonName": "Dina ",
    "Mobile": "12345678",
    "EmailAddress": "[email protected]",
    "LineAddress": "test ",
    "CityName": "CAIRO",
    "CountryCode": "EG"
  },
  "DisplayCurrencyId": 1,
  "SendInvoiceOption": 4,
  "Language": 1,
  "CallBackUrl":"http://www.google.com",
  "ErrorUrl":"http://www.microsoft.com"
 }

{
  "Id": 41681,
  "IsSuccess": true,
  "Message": "Record Created Successfully!",
  "RedirectUrl": "https://demo.myfatoorah.com/ia/03051474168141",
  "FieldsErrors": null,
  "PaymentMethods": [
    {
      "PaymentMethodName": "اميكس",
      "PaymentMethodUrl": "https://demo.myfatoorah.com/Ar/PayInvoice/Checkout?invoiceKey=03051474168141&paymentGatewayId=3",
      "PaymentMethodCode": "ae"
    },
    {
      "PaymentMethodName": "سداد",
      "PaymentMethodUrl": "https://demo.myfatoorah.com/Ar/PayInvoice/Checkout?invoiceKey=03051474168141&paymentGatewayId=4",
      "PaymentMethodCode": "s"
    },
    {
      "PaymentMethodName": "بنفت",
      "PaymentMethodUrl": "https://demo.myfatoorah.com/Ar/PayInvoice/Checkout?invoiceKey=03051474168141&paymentGatewayId=5",
      "PaymentMethodCode": "b"
    },
    {
      "PaymentMethodName": "فيزا / ماستر",
      "PaymentMethodUrl": "https://demo.myfatoorah.com/Ar/PayInvoice/Checkout?invoiceKey=03051474168141&paymentGatewayId=6",
      "PaymentMethodCode": "vm"
    },
    {
      "PaymentMethodName": "البطاقات المدينة - الامارات",
      "PaymentMethodUrl": "https://demo.myfatoorah.com/Ar/PayInvoice/Checkout?invoiceKey=03051474168141&paymentGatewayId=7",
      "PaymentMethodCode": "uaecc"
    },
    {
      "PaymentMethodName": "مدى",
      "PaymentMethodUrl": "https://demo.myfatoorah.com/Ar/PayInvoice/Checkout?invoiceKey=03051474168141&paymentGatewayId=10",
      "PaymentMethodCode": "md"
    },
    {
      "PaymentMethodName": "كي فاست",
      "PaymentMethodUrl": "https://demo.myfatoorah.com/Ar/PayInvoice/Checkout?invoiceKey=03051474168141&paymentGatewayId=13",
      "PaymentMethodCode": "kf"
    },
    {
      "PaymentMethodName": "كي نت",
      "PaymentMethodUrl": "https://demo.myfatoorah.com/Ar/PayInvoice/Checkout?invoiceKey=03051474168141&paymentGatewayId=20",
      "PaymentMethodCode": "kn"
    },
    {
      "PaymentMethodName": "أبل الدفع",
      "PaymentMethodUrl": "https://demo.myfatoorah.com/Ar/PayInvoice/Checkout?invoiceKey=03051474168141&paymentGatewayId=21",
      "PaymentMethodCode": "ap"
    },
    {
      "PaymentMethodName": "AFS",
      "PaymentMethodUrl": "https://demo.myfatoorah.com/Ar/PayInvoice/Checkout?invoiceKey=03051474168141&paymentGatewayId=23",
      "PaymentMethodCode": "af"
    }
  ],
  "ApiCustomFileds": null
}

6.Use the RedirectURL from step 5 to do the payment

7.Once the payment is done successfully, you will be able to download DHL/Aramex AWBl as PDF in the download section of the receipt

8.Call GET ApiShipping/GetShippingOrderList?shippingMethod=1&orderStatus=0 API

Note: Add this header to the request: "Authorization": "Bearer {token from step 1} after calling the API you will get list of orders in the given order status & shipping method.

ShippingMethods:
DHL=1,
Aramex=2

OrderStatus:
Pending = 0,
Prepared = 1,
RequestPickup = 2,
Picked = 3,
Delivered = 4

?shippingMethod=1&orderStatus=0

{
    "IsSuccess": true,
    "Message": null,
    "FieldsErrors": null,
    "Data": {
        "ShippingMethod": "DHL",
        "OrderStatus": "Pending",
        "TotalOrders": 10,
        "OrderNumbers": [
            40481,
            40480,
        ],
        "ShippingOrders": [
            {
                "OrderNumber": 40481,
                "OrderType": "Shipping",
                "OrderStatus": "Pending",
                "CustomerName": "XYZ",
                "ShippingMethod": "DHL",
                "ShippingValue": 13.464
            },
            {
                "OrderNumber": 40480,
                "OrderType": "Shipping",
                "OrderStatus": "Pending",
                "CustomerName": "XYZ",
                "ShippingMethod": "DHL",
                "ShippingValue": 13.464
            }
        ]
    }
}
  1. We have to change the order shipping status to “Prepared” to initiate shipping

Call Post ApiShipping/UpdateShippingStatus API with Token and ShippingStatusModel
Note: Add this header to the request: "Authorization": "Bearer {Token}" from step 1 after calling the API you will get the details about updated orders number with status.

ShippingMethods:
DHL=1,
Aramex=2

OrderStatus:
Pending = 0,
Prepared = 1,
RequestPickup = 2,
Picked = 3,
Delivered = 4

{
  "ShippingMethod":1,
  "InvoiceNumbers": [
  	40481,40480
  ],
  "OrderStatusChangedTo": 1
}

{
    "IsSuccess": true,
    "Message": null,
    "FieldsErrors": null,
    "Data": {
        "ShippingOrder": [
            {
                "OrderNumber": 40480,
                "OrderStatus": "Prepared"
            },
            {
                "OrderNumber": 40481,
                "OrderStatus": "Prepared"
            }
        ]
    }
}

Here you can’t change status to RequestPickup in this API call. If you want to change RequestPickup please follow the step 10

10.Call Post ApiShipping/RequestPickup?shippingMethod=1

Note: Add this header to the request: "Authorization": "Bearer {Token}" from step 1, after calling the API you will get the details about updated orders number with status. Now it's ready for order status changing.

ShippingMethods:
DHL=1,
Aramex=2

?shippingMethod=1

{
    "IsSuccess": true,
    "Message": null,
    "FieldsErrors": null,
    "Data": [
        {
            "OrderNumber": 40430,
            "OrderStatus": "RequestPickup"
        },
        {
            "OrderNumber": 40476,
            "OrderStatus": "RequestPickup"
        },
        {
            "OrderNumber": 40479,
            "OrderStatus": "RequestPickup"
        },
        {
            "OrderNumber": 40484,
            "OrderStatus": "RequestPickup"
        }
    ]
}

11.Next use the step 9 to change other status like “Picked/ Delivered”.

Call Post ApiShipping/UpdateShippingStatus API

ShippingMethods:
DHL=1,
Aramex=2

OrderStatus:
Pending = 0,
Prepared = 1,
RequestPickup = 2,
Picked = 3,
Delivered = 4

{
  "ShippingMethod":1,
  "InvoiceNumbers": [
  	40481,40480
  ],
  "OrderStatusChangedTo": 3
}

{
    "IsSuccess": true,
    "Message": null,
    "FieldsErrors": null,
    "Data": {
        "ShippingOrder": [
            {
                "OrderNumber": 40480,
                "OrderStatus": "Picked"
            },
            {
                "OrderNumber": 40481,
                "OrderStatus": "Picked"
            }
        ]
    }
}

Updated over 3 years ago