Colizey - Ship Orders

Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)

The purpose of this page is to describe in details how we ship orders on the Colizey marketplace.

The shipment process is straight forward - we need to push the order id, which we have received in “Order List“ response, the tracking number and tracking URL and also the shipper id.

Before shipping the order, first we should get & store all the available couriers for Colizey because is mandatory when shipping an order to push the shipper ID from the list of Colizey.

To ship the order, order status to be on “Ready For Shipping“ and Is Acknowledge = Yes (i.e. the order to be accepted, using the API call, described here: Colizey - Accept Orders ) & Shipment = Pending (waiting for information to be sent to the MP);

Before we ship the order, we need to download and store all available couriers (shippers) on Colizey.

• Get available shippers

Using this call we are able to retrieve available carriers for Colizey we are able to ship with.

The shippers will be stored into Carriers table - Colizey Couriers table. We would want to map the name but to send the ShipperID to Colizey ONLY if we have a match between the courier we are going to ship with and Colizey couriers' list.

We would want to incorporate a button which update the carrier ad hoc.

If we have a case, where Colizey will update the list of couriers and for example delete some of them or add shipper, we would want to to delete them, respectively add them to Colizey Couriers table.

API Call: GET https://api.colizey.fr/merchant/v2/shippers

Docs: https://apidoc.colizey.fr/?shell#shipping-carriers

Example response:

[
    {
        "id": "940a543d-a3c9-43b2-a10a-80777e514d44",
        "type": "address",
        "name": "Colissimo"
    },
    {
        "id": "e5246b74-04ee-4b6a-9bb2-362a4da9d255",
        "type": "relay",
        "name": "Mondial Relay"
    }
]

Note: Complete list with couriers will follow up soon

• Ship order

To ship the order we should have payment record for the order, order status to be on “Ready For Shipping“ ( Order Acknowledgement = Yes) & Shipment = Pending (waiting for information to be sent to the MP);

If the order is not in the Accepted state (RFS status, Order Acknowledgement = No), then the API will send back an error.

Note: To ship the order we need to send the order ID which is stored in Orders > Marketplace Order ID

We are storing all carriers in a separate table (Colizey Courriers) which we want to become a slave of Couriers where we want to have a dropdown field with all the couriers downloaded from Colizey. We want to display the name and send the Id to the marketplace. Every time we try to ship an order we need to match the Order Shipment > Courier against Couriers > Name and get the get Colizey Couriers > Courier which we need to map and push in the payload.

If we do not match any of the name we want to use the default Courier set in Account Colizey > Default Courier (Dropdown field with all couriers downloaded from Colizey) If there are no records in Colizey Couriers we want to return an error in Order Error table stating: (Error message: There are no couriers into Colizey courier table); If there is no default Carrier set and we do not match any of the Couriers > Name we want to return error (Error: There is no mapped carrier for this order)

The whole flow looks like

Step 1: If we have downloaded Colizey couriers, we need to check if the courier stated into the order appears into Hemi Courier table (1513).

Step2: Then we check the matched value between the Order and the Courier and get from the salve table Colizey Couriers > Courier

Step 3: If there is no mapping (from step 2), we want to use the default courier in Account Colizey > Default Courier

Step 4: If for some reason there is no default courier and nothing is mapped we want to return an error again (Error message: There is no mapped carrier for this order);

API Call: POST https://api.colizey.fr/merchant/orders/{orderId}/ship

Docs: https://apidoc.colizey.fr/?shell#ship-an-accepted-order

Example body:

(Please note into the postman collection, the body is x-www-form-urlencoded)

OR Courier > Courier Url | If Order Shipment > Tracking URL is missing we want to use the Courier > Courier Url. If Courier > Courier Url is missing we push it empty in the payload. | | trackingNumber | string | no | Carrier tracking number | Order Shipment > Tracking Number | | | shipperId | uuid | no | Shipper that will handle the package. | Colizey Courier > Shipper ID | We would want to map the shipper name but to send the shipper id Also, we would want to map the Order Shipment > Courier against Couriers > Name and get the get Colizey Couriers > Courier which we need to map and push in the payload. If we do not match any of the Courier name we want to use the default Courier set in Account Colizey > Default .

In any other cases like: If there are no records in Colizey Couriers we want to return an error in Order Error table.

If there is no default Carrier set and we do not match any of the Couriers > Name we want to return error |

Once we receive success, into the response we will receive updated order information and we need to update the information respectively in Hemi (for example after we send shipping call, and it is successed, the order status will be changed from Accepted to Ship and in Hemi - from RFS status to Shipped status)

Error cases:

As per performed tests, seems that we must use the shippers ID, provided by Colizey.

• If ShipperID=1:

{
    "error": "Could not find Shipper with name #1"
}

(Error message: Could not find Shipper with name #1)

• If ShipperID=other

{
    "error": "Could not find Shipper with name #other"
}

(Error message: Could not find Shipper with name #other)

• If we try to ship order which is not accepted

{
    "error": "Transition \"shipped\" is not enabled for workflow \"merchant_order_line\"."
}

(Error message: The order is not accepted and shipment cannot be completed)

We should store respectively error in Order Error table!