Shipment Flows

Payloads

This part of the document contains the list of services that can be integrated in flows above. 2 configuration parameters will be shared during integration:

username	Username for basic authentication
password	Password for basic authentication

generate-shipment (POST)

This service is used to start a new shipping process.

URL

^^/shipments

Request Headers

x-akinon-request-id	Unique ID for problem solving & tracing.
x-akinon-api-version	Akinon Customer API version.
Authorization	username/password (Basic BASE64_encoded)

Request Body raw (json)

{
   "shipmentId": "", - Akinon unique id
   "locale": "", – IETF BCP 47 language tag
   "deliveryNote":"",
   "type:":"", -CUSTOMER, PICK_UP_LOCATION
   "destination": {
       "name": "",
       "surname": "",
       "tel": "",
       "country": {
           "id": 0, -Omnitron country id
           "code": "",-ISO code
           "name": ""
       },
       "city": {
           "id": 0, -Omnitron city id
           "name": ""
       },
       "district": {
           "id": 0, -Omnitron district id
           "name": ""
       },
       "township": {
           "id": 0, -Omnitron township id
           "name": ""
       },
       "zipcode": "",
       "addressLine": ""
   }
}

Notes

Sender Address Information

If your service requires a sender information ID with a predefined sender address, the following part is sent in addition to the above request.

 …,
"originId":""

Product List Information

If your service needs product information, these will be filled from product attributes in addition to the above request as a hashMap.

…,
"products": [{
      "barcode": "",
      "category": "",
      "deci": "", ...
   }]

Payment Information

If the payment type is pay on delivery, the following information will be sent in addition to the above request.

…,
"payment": {
    "paymentId": "", -Akinon id
    "amount": 0.00,
    "currency": "" -Three-letter ISO 4217 currency code
}

Statuses

CREATED	Shipment information created at the cargo company.
DELETED	The package has not yet been received by the cargo company and the sender canceled and deleted previously created records.
SHIPPING	From the receipt of the package to the first arrival at the customer.
ATTEMPTED_DELIVERY	The package could not be delivered due to the customer.
DELIVERED	Delivered.
DELIVERY_FAILED	The package could not be delivered for any reason.
READY_FOR_PICKUP	The package has arrived at the pickup location.

Response Body raw 200 (json)

{
    "waybillNumber": "", -unique shipment company id, if exist trackingNumber, else unique waybill id
    "trackingNumber":"", -if exists, optional at this step
    "trackingUrl":"", -if exists, optional at this step
    "status":"", CREATED
    "statusDetail":"",
    "labelData":"", - optional, if exists at this step base64 encoded label 
    "labelFormat":"" - optional, label file format. PNG, ZPL, HTML, PDF
}

query-shipment (GET)

This service is used to query the latest status of previously initiated cargo transactions.

URL

^^/shipments/{id}?type={queryType}

Request Headers

x-akinon-request-id	Unique ID for problem solving & tracing.
x-akinon-api-version	Akinon Customer API version.
Authorization	username/password (Basic BASE64_encoded)

Request Parameters

queryType: SHIPMENT_ID(default), WAYBILL_NUMBER, TRACKING_NUMBER

This parameter indicates which value is sent in the ID field. If there is no parameter, the default value should be used.

Request Body

none

Response Body raw 200 (json)

{
    "waybillNumber": "", -shipmentCompanyId
    "trackingNumber":"", -optional if not yet created
    "trackingUrl":"", -optional if not yet created
    "status":"" -CREATED, LABEL_DELETED, SHIPPING, ATTEMPTED_DELIVERY, DELIVERED, DELIVERY_FAILED, READY_FOR_PICKUP
    "statusDetail":""
}

query-shipment-history (GET)

This service is used to inquire in detail the latest status of the cargo transactions that have been initiated before.

URL

^^/shipments/{id}/history?type={queryType}

Request Headers

x-akinon-request-id	Unique ID for problem solving & tracing.
x-akinon-api-version	Akinon Customer API version.
Authorization	username/password (Basic BASE64_encoded)

Request Parameters

queryType: SHIPMENT_ID(default), WAYBILL_NUMBER, TRACKING_NUMBER

This parameter indicates which value is sent in the ID field. If there is no parameter, the default value should be used.

Request Body

none

Response Body raw 200 (json)

{
    "waybillNumber": "", -shipmentCompanyId
    "trackingNumber":"", -optional if not yet created
    "trackingUrl":"", -optional if not yet created
    "status":"" -CREATED, LABEL_DELETED, SHIPPING, ATTEMPTED_DELIVERY, DELIVERED, DELIVERY_FAILED, READY_FOR_PICKUP
    "statusDetail":"",
    "history": [
        { 
          "status":"" -CREATED, LABEL_DELETED, SHIPPING, ATTEMPTED_DELIVERY, DELIVERED, DELIVERY_FAILED, READY_FOR_PICKUP
          "statusDetail":"",
          "timestamp": "" -ISO 8601
        }
   ]

}

delete-shipment (DELETE)

This service is used to cancel the previously initiated cargo transactions before the carrier receives the package.

URL

^^/shipments/{shipmentId}

Request Headers

x-akinon-request-id	Unique ID for problem solving & tracing.
x-akinon-api-version	Akinon Customer API version.
Authorization	username/password (Basic BASE64_encoded)

Request Body

none

Response Body raw 204

none

update-shipment (PATCH)

This service is used to update the address information of the previously created cargo request.

URL

^^/shipments/{shipmentId}

Request Headers

x-akinon-request-id	Unique ID for problem solving & tracing.
x-akinon-api-version	Akinon Customer API version.
Authorization	username/password (Basic BASE64_encoded)

Request Body raw (json)

{
     "destination": {
       "name": "",
       "surname": "",
       "tel": "",
       "country": {
           "id": 0, -Akinon country id
           "code": "",-ISO code
           "name": ""
       },
       "city": {
           "id": 0, -Akinon city id
           "name": ""
       },
       "district": {
           "id": 0, -Akinon district id
           "name": ""
       },
       "township": {
           "id": 0, -Akinon township id
           "name": ""
       },
       "zipcode": "",
       "addressLine": ""
   }
}

Response Body raw 200

none

query-shipment-label (GET)

This service is used to retrieve the label of the previously created cargo request.

URL

^^/shipments/{shipmentId}/label

Request Headers

x-akinon-request-id	Unique ID for problem solving & tracing.
x-akinon-api-version	Akinon Customer API version.
Authorization	username/password (Basic BASE64_encoded)

Request Body

none

Response Body raw 200 (json)

{
    "labelData":"", - base64 encoded label 
    "labelFormat":"", -label file format. PNG, ZPL, HTML, PDF
}

generate-easy-return (POST)

This service is used to initiate the return process of the product that has been delivered.

URL

^^/easy-return

Request Headers

x-akinon-request-id	Unique ID for problem solving & tracing.
x-akinon-api-version	Akinon Customer API version.
Authorization	username/password (Basic BASE64_encoded)

Request Body raw (json)

{
 "returnId": "" -akinon unique id
}  

If target location information and detailed information are required for easy return, the following part will be sent in addition to the above request:

 "destination": { -seller address
       "name": "",
       "surname": "",
       "tel": "",
       "country": {
           "id": 0, -Akinon country id
           "code": "",-ISO code
           "name": ""
       },
       "city": {
           "id": 0, -Akinon city id
           "name": ""
       },
       "district": {
           "id": 0, -Akinon district id
           "name": ""
       },
       "township": {
           "id": 0, -Akinon township id
           "name": ""
       },
       "zipcode": "",
       "addressLine": ""
   },

If the package is to be picked up from the customer's address, the following part will be sent in addition to the above request.

"origin": { -customer address for pick up
       "name": "",
       "surname": "",
       "tel": "",
       "country": {
           "id": 0, -Akinon country id
           "code": "",-ISO code
           "name": ""
       },
       "city": {
           "id": 0, -Akinon city id
           "name": ""
       },
       "district": {
           "id": 0, -Akinon district id
           "name": ""
       },
       "township": {
           "id": 0, -Akinon township id
           "name": ""
       },
       "zipcode": "",
       "addressLine": ""
   }
}

Response Body raw 200 (json)

{
    "waybillNumber": "",
    "trackingNumber":"", -optional 
    "trackingUrl":"", -optional 
    "status":"", -CREATED
    "statusDetail":""
}

query-easy-return (GET)

This service is used to query the latest status of the product whose return process has started.

URL

^^/easy-return/{easyReturnId}

Request Headers

x-akinon-request-id	Unique ID for problem solving & tracing.
x-akinon-api-version	Akinon Customer API version.
Authorization	username/password (Basic BASE64_encoded)

Request Body

none

Response Body raw 200 (json)

{
    "waybillNumber": "", -shipmentCompanyId
    "trackingNumber":"", -optional
    "trackingUrl":"", -optional
    "status":"" -CREATED, LABEL_DELETED, SHIPPING, ATTEMPTED_DELIVERY, DELIVERED, DELIVERY_FAILED, READY_FOR_PICKUP
    "statusDetail":""
}

delete-easy-return (DELETE)

This service is used to cancel the initial return process.

URL

base_url/easy-return/{easyReturnId}

Request Headers

x-akinon-request-id	Unique ID for problem solving & tracing.
x-akinon-api-version	Akinon Customer API version.
Authorization	username/password (Basic BASE64_encoded)

Request Body

none

Response Body raw 204

none

Response Body For Errors (ALL)

If any errors are encountered in the services, these errors should be reported in the format below, and the list of error codes should be shared with Akinon.

Response Body raw 4xx/5xx (json)

{
    "errors": [
       {
           "code": "",
           "field": "",
           "message": ""
       }
   ]
}