Quotation API (Entrega Expressa) Developer Guide

This channel allows the seller to use their own logistics for quoting and shipping instant orders.

• The shipping quote is made from the quote URL provided by the seller.
• Shipping price and delivery time are provided by the seller.
• Order tracking is simplified, with the seller being responsible for sending “dispatched”, “delivered” or “delivery failed” events via OpenAPI.

Note: This channel will be made available to specific sellers whose products are not supported by Shopee's own logistics due to dimensions and weight, in accordance with the rules established by Shopee's sales team.

This tool allows sellers to send Shopee estimated shipping costs and delivery times, which will be displayed to buyers at the time of purchase. To use this feature, sellers must meet the pre-established approval requirements.

*The seller has the option to integrate directly with Shopee to connect their quote URL or connect via an Integrator-HUB.

Unlike other integration types, the quotation and order status update API integration (from Entrega Expressa channel) requires review and approval from the Shopee team before it can go live. To be approved by the Shopee team, you must:

• Freight Quote API Contract Compliance:Configure and make the URL available via the HTTP POST method.Each request must contain only one item from one seller.The URL has no specific structure, providing flexibility in configuration.
• Default payload for quote request and response (and validation with Shopee URL)
• Response time limit of 200ms.
• Contingency table registered directly through the Seller Center.
• Error monitoring (and development of requested messages)
• Status update API development (“update_tracking_status);Note: The above requirements must be met by the seller's "own system" or their ERP/HUB/Integration. It's worth noting that without them, orders will be canceled, as the flow cannot be performed manually via Seller Central.Note 2: Anyone who develops the quote API must also develop the status update API;Note 3: The Entrega Expressa APP is only used for quotation URLs. To use any API, it is necessary to create a second APP;
• Send confirmation email and approval from the Shopee team via ticket(involving all the criteria above).

To be able to perform the integration and tests above, it is also necessary:

a) Create a new Entrega Expressa APP on the Open Platform and authorize sellers to this APP

b) Have an APP that is capable of calling OpenAPI to update status (and also authorize sellers to this APP)

Once all these steps have been completed, it will be necessary to create at least 2 test orders, which will need to be processed to the delivered and canceled statuses, to release the HUB as an approved channel.

Shopee will be calling Quotation API in 2 scenarios, which have different request and response parameters.

• Quotation API Request and Response (Default)
• Quotation API Request and Response (Fallback)

Quotation API Request and Response (Default)

Request parameters (query)

URL Request Parameters:

Body Request Parameters:

Response Parameters / Quote Response (error):

Response Parameters / Quote Response (success):

Default response for errors not mapped in the error table

Use HTTP status code 500

{

"request_id": "65e9e26dd9d2565e9e26dd9d64",

"error": "Internal system error",

"message": "internal system error"

}

Expected error codes

Quotation API Request and Response (Fallback)

Request Parameters (Body)

Response Parameters (Body)

Response validation (with Shopee URL)

• To ensure the response is in the expected format, we have a URL that should be used to validate and report any necessary corrections.
• URL: "https://seller-quotation-api.uat.shps-br-services.com/validate_quotation_endpoint"
• Within the "x-quotation-id" parameter, you must use the URL that will be registered with Shopee.
• Here is an example payload showing how to use the response format validation URL:

• Considering that checkout is the most critical moment in the user experience during the purchase, it is essential to ensure the best possible experience for the buyer.
• The response time limit is 200ms. A load test is required to ensure this requirement is met.
• Response times longer than 200ms will not be permitted, making integration impossible. Therefore, optimizing this parameter is crucial to providing the best possible customer experience.

• This feature is intended to support freight calculation, in case there is a problem with freight quotation via API (timeout or return 500 for requests).

Shipping Value Settings for Contingency

• For the contingency to work, the seller must register the shipping values ​​and enable the Entrega Expressa channel , according to the steps described below.
• In Seller Centre, go to Shipping Settings and click the Channel Settings button:

Filling in the contingency freight value

Next, the screen will load to enter the shipping cost. Shipping costs can be entered by state (single value) or by city. This setting can only be done by mart shops (which will automatically apply for all outlet shops) and normal shops (shops that are not on mart-outlet structure). We strongly encourage setting this up before toggling on Entrega Expressa channel.

Single shipping cost per state

• Select states
• Fill in the shipping cost field
• Click Save

Single shipping cost per city

• Select states
• Disable the Flat rate button for this area
• Uncheck the Select All Cities option and select the cities you want to inform the shipping cost.
• Fill in the Rate field for the respective cities
• Click Save

This feature is intended to support seller’s serviceable area settings, to identify if the buyer’s address is within seller’s serviceable settings. This setting should be done by outlet shops / normal shops (not on mart-outlet structure). Please note that this setting is mandatory before toggling on Entrega Expressa channel. Without serviceable area settings set, channel will always display as unsupported to buyer. To upload serviceable settings:

• Seller to upload serviceable area settings via /api/v2/logistics/upload_polygonIf you upload 2 KML files, we will take the latest file upload
• Once uploaded, seller can check the status of serviceable area settings upload via /api/v2/logistics/check_polygon_update_status

Seller will arrange shipment via ship_order API. Please note that order_status will be updated to PROCESSED status after arranging shipment, and will be returned in get_package_detail API. get_order_detail order_status will still return READY_TO_SHIP.

Here are the links to the API documentation:

• /api/v2/logistics/ship_order
• /api/v2/order/get_order_detail
• /api/v2/order/get_package_detail

Order status and tracking updates will be performed via the Tracking Update API and will be based on the order number created in Shopee (Order ID, also known as OrderSN). The tracking number will also be required.

To update the tracking number and order status, use the v2.logistics.update_tracking_status (OpenAPI) endpoint. The possible statuses are:

• Order Sent (logistics_pickup_done)The URL and tracking number can be sent when updating the order status to Shipped.
• Order Delivered (logistics_delivery_done)The Delivered status will only be received if the order already has the Shipped status.OTP code verification: For Entrega Expressa channel, it is mandatory to have OTP code verification. Shopee will be generating the OTP code after seller arranges shipment. When seller is delivering the parcel to buyer, it is mandatory for seller to retrieve OTP code from buyer, and send it in API request when attempting to update tracking_status to logistics_delivery_done.
• Delivery Failure (logistics_delivery_failed)The Delivery Failure status will only be received if the order already has the Shipped status.Failed reason: For Entrega Expressa channel, it is mandatory for seller to send failed_reason when updating tracking_status to logistics_delivery_failed.

IMPORTANT : after sending the Order Delivered or Delivery Failed statuses, no further status updates will be allowed, as both are finalizing statuses;

*the tracking_number and tracking_url parameters should only be sent when updating the status to logistics_pickup_done .

Here is a link to the API documentation “ /api/v2/logistics/update_tracking_status”.