Shipment Flows

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

This parameter indicates which credentials should be used for multi-account management. It is an optional parameter, and even if not sent, a default set of credentials should be defined:

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.	Mandatory
x-akinon-api-version	Akinon Customer API version.	Mandatory
x-akinon-credentials-identifier	Unique id specifying the credentials for multiple account	Optional
Authorization	Basic [BASE64_encoded(username:password)]	Mandatory

Request Body raw (json)

{
   "shipmentId": "", - Akinon unique id
   "orderNumber": "", - Akinon unique order number
   "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": ""
   }
}

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. This originId must be the same as the addressId in the response of the generate address service.

 …,
"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. Keys in the hashMap may change depending on the availability of product attributes.

…,
"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
    "paymentType": "", - This parameter is the type of pay on delivery. Card/Cash
    "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.	Mandatory
x-akinon-api-version	Akinon Customer API version.	Mandatory
x-akinon-credentials-identifier	Unique id specifying the credentials for multiple account	Optional
Authorization	Basic [BASE64_encoded(username:password)]	Mandatory

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.	Mandatory
x-akinon-api-version	Akinon Customer API version.	Mandatory
x-akinon-credentials-identifier	Unique id specifying the credentials for multiple account	Optional
Authorization	Basic [BASE64_encoded(username:password)]	Mandatory

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.	Mandatory
x-akinon-api-version	Akinon Customer API version.	Mandatory
x-akinon-credentials-identifier	Unique id specifying the credentials for multiple account	Optional
Authorization	Basic [BASE64_encoded(username:password)]	Mandatory

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.	Mandatory
x-akinon-api-version	Akinon Customer API version.	Mandatory
x-akinon-credentials-identifier	Unique id specifying the credentials for multiple account	Optional
Authorization	Basic [BASE64_encoded(username:password)]	Mandatory

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?labelFormat

Request Headers

x-akinon-request-id	Unique ID for problem solving & tracing.	Mandatory
x-akinon-api-version	Akinon Customer API version.	Mandatory
x-akinon-credentials-identifier	Unique id specifying the credentials for multiple account	Optional
Authorization	Basic [BASE64_encoded(username:password)]	Mandatory

Request Parameters

labelFormats(optional): PNG, ZPL, HTML, PDF

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-returns

Request Headers

x-akinon-request-id	Unique ID for problem solving & tracing.	Mandatory
x-akinon-api-version	Akinon Customer API version.	Mandatory
x-akinon-credentials-identifier	Unique id specifying the credentials for multiple account	Optional
Authorization	Basic [BASE64_encoded(username:password)]	Mandatory

Request Body raw (json)

{
 "returnId": "", -akinon unique id
 "orderNumber": "", -akinon unique order number
}  

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 destination address has a predefined addressId it can be used instead of detailed open address above. This destinationId must be the same as the addressId in the response of the generate address service.

 "destinationId":"",

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": ""
   }

If your service needs product information, these will be filled from product attributes in addition to the above request as a hashMap. Keys in the hashMap may change depending on the availability of product attributes.

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

If your service needs pickup date, the following part will be sent in addition to the above request. Available pickup dates can be obtained from search-appointment-dates service.

"pickupDate": {
    "date": "", -ISO 8601 Date, (yyyy-MM-dd)
    "hourRange": {
        "start": "", - HH:MM
        "end": ""    - HH:MM
    }
}

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-returns/{easyReturnId}

Request Headers

x-akinon-request-id	Unique ID for problem solving & tracing.	Mandatory
x-akinon-api-version	Akinon Customer API version.	Mandatory
x-akinon-credentials-identifier	Unique id specifying the credentials for multiple account	Optional
Authorization	Basic [BASE64_encoded(username:password)]	Mandatory

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

^^/easy-returns/{easyReturnId}

Request Headers

x-akinon-request-id	Unique ID for problem solving & tracing.	Mandatory
x-akinon-api-version	Akinon Customer API version.	Mandatory
x-akinon-credentials-identifier	Unique id specifying the credentials for multiple account	Optional
Authorization	Basic [BASE64_encoded(username:password)]	Mandatory

Request Body

none

Response Body raw 204

none

search-appointment-dates (POST)

This service is used to get available appointment dates. It can be used for expected date of delivery when ordering or pickup date for easy return.

URL

^^/search-appointment-dates

Request Headers

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

Request Body

{
    "address": {
        "country": {
            "id": 0, -Omnitron country id
            "code": "", -ISO code
            "name": ""
        },
        "city": {
            "id": 0, -Omnitron city id
            "name": ""
        },
        "township": {
            "id": 0, -Omnitron township id
            "name": ""
        },
        "district": {
            "id": 0, -Omnitron district id
            "name": ""
        },
        "zipcode": "",
        "addressLine": "",
    },
    "startDate": "", -ISO 8601 Date for Beginning of the desired date range
    "endDate": "" -ISO 8601 Date for End of the desired date range
}

Response Body raw 200 (json)

[
    {
        "date": "", -ISO 8601 Date, (yyyy-MM-dd)
        "hourRanges": [
            {
                "start": "", -HH:MM
                "end": "" -HH:MM
            },
            {
                "start": "", -HH:MM
                "end": "" -HH:MM
            },
            ...
        ]
    },
    ...
]

generate-address (POST)

This service is used to generate a new predefined shipping address.

URL

^^/addresses

Request Headers

x-akinon-request-id	Unique ID for problem solving & tracing.	Mandatory
x-akinon-api-version	Akinon Customer API version.	Mandatory
x-akinon-credentials-identifier	Unique id specifying the credentials for multiple account	Optional
Authorization	Basic [BASE64_encoded(username:password)]	Mandatory

Request Body

{
    "id": "", - Akinon unique address id for all domains(omnitron, oms etc)
    "addressName": "",
    "addressDescription": "",
    "phone": "",
    "email": "",
    "address": {
        "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": ""
    },
    "type": "" -optional address type; values: CUSTOMER, DISTRIBUTION_POINT(default), PICK_UP_LOCATION
}

If your service requires coordinates of address, the following part is sent in addition to the above request.

{
    ...,
    "address": {
        ...,
        "coordinates": {
            "latitude": 0.000000, - Decimal degrees (DD) with 6 decimal places
            "longitude": 0.000000 - Decimal degrees (DD) with 6 decimal places
        }
    }
}

If your service requires hours the location is open, the following part is sent in addition to the above request.

{
    ...,
    "workingHours": [
        {
            "day": "", -values: 1(Monday), 2(Tuesday), ..., 7(Sunday)
            "hourRanges": [
                {
                    "start": "", -HH:MM
                    "end": "" -HH:MM
                },
                {
                    "start": "", -HH:MM
                    "end": "" -HH:MM
                }
            ]
        }
    ]
}

Response Body raw 201 (json)

{
    "addressId": "", -unique addressId for shipment company. This info will be logged in Akinon systems.
}

get-addresses (POST)

This service is used to get predefined shipping addresses.

URL

^^/addresses/info

Request Headers

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

Request Body

{
    "locale": "",
    "type": "", -CUSTOMER, DISTRIBUTION_POINT, PICK_UP_LOCATION
    "address": {
        "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": ""
    }
}

If your service needs product information, these will be filled from product attributes in addition to the above request as a hashMap. Keys in the hashMap may change depending on the availability of product attributes.

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

Response Body raw 200 (json)

[
    {
        "id": "",
        "addressName": "",
        "addressDescription": "",
        "type": "PICK_UP_LOCATION",
        "phone": "",
        "email": "",
        "address": {
            "country": {
                "id": 0,
                "code": "",
                "name": ""
            },
            "city": {
                "id": 0,
                "name": ""
            },
            "district": {
                "id": 0,
                "name": ""
            },
            "township": {
                "id": 0,
                "name": ""
            },
            "zipcode": "",
            "addressLine": "",
            "coordinates": { -optional if coordinates provided
                "latitude": 0.000000,
                "longitude": 0.000000
            }
        },
        "workingHours": [ -optional if working hours provided
            {
                "day": "", -values: 1(Monday), 2(Tuesday), ..., 7(Sunday)
                "hourRanges": [
                    {
                        "start": "", -HH:MM
                        "end": "" -HH:MM
                    },
                    {
                        "start": "", -HH:MM
                        "end": "" -HH:MM
                    }
                ]
            }
        ]
    },
    ...
]

get-address-detail (GET)

This service is used to get details of predefined delivery addresses.

URL

^^/addresses/{id}

Request Headers

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

Request Body

none

Response Body raw 200 (json)

{
    "id": "",
    "addressName": "",
    "addressDescription": "",
    "type": "PICK_UP_LOCATION",
    "phone": "",
    "email": "",
    "address": {
        "country": {
            "id": 0,
            "code": "",
            "name": ""
        },
        "city": {
            "id": 0,
            "name": ""
        },
        "district": {
            "id": 0,
            "name": ""
        },
        "township": {
            "id": 0,
            "name": ""
        },
        "zipcode": "",
        "addressLine": "",
        "coordinates": { -optional if coordinates provided
            "latitude": 0.000000,
            "longitude": 0.000000
        }
    },
    "workingHours": [ -optional if working hours provided
        {
            "day": "", -values: 1(Monday), 2(Tuesday), ..., 7(Sunday)
            "hourRanges": [
                {
                    "start": "", -HH:MM
                    "end": "" -HH:MM
                },
                {
                    "start": "", -HH:MM
                    "end": "" -HH:MM
                }
            ]
        }
    ]
}

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": ""
       }
   ]
}