What is the function of Zid Shipping APIs?
Zid Shipping APIs enable the integration between Zid and the logistic systems of shipping companies. As a shipping company, you can manage and automate all your operations seamlessly with Zid Merchants through the Shipping APIs.
How does it work?
Merchants who have activated your shipping application on their store could place new orders, choose a payment method, track shipments, check supported countries and cities, and generate AWB.
To create a new application, follow these steps:
Open your partner dashboard
Navigate to My Apps
Click the Create Application button.
Choose the Shipping Application
Fill in the general data:
company name: The name of your App that will appear to the merchant."make sure to write the App name in Arabic and English Language"
company URL: Your main company website. started with "http://"
Technical support email: The responsible email to receive and reply to merchant issues.
Mobile number: The responsible phone number to receive and reply to merchant issues. "don't write a random number as it'll appear on your page and be seen by the merchants"
Type of shipping and storage company: you can choose your service type category, either:
Shipping and fulfillment company
Shipping company only
About your company: Write a brief introduction about your company and the nature of the service provided to merchants.
"make sure to write it in Arabic and English Language"
Company logo
Use this template to fit the requirements. Here
Services provided by the company: if you're providing refrigerated Shipping or Heavy Shipping, this would help in identifying your services.
Click the Create App button to move to the next step.
2. Implement OAuth
In this section, you can set up your OAuth. You'll be provided with your OAUTH 2.0 ENDPOINT, CLIENT ID, and CLIENT SECRET, to set up three requirements:
Redirect URL (Ask for merchant permission)
Callback URL (Get the tokens)
Refresh tokens
OAUTH 2.0
If you are not familiar with OAuth 2.0 or you need more information about OAuth 2.0, redirection, or Callback, please check our Authorization Documentation
After this, you can start integrating your system using our APIs. Check the below links.
3. Explore our APIs
4. Shipping option details
In this section, you can set up your shipping option details to appear in your App page and be seen by the merchants.
Delivery/Pickup coverage: Select the countries and cities covered by your company
Collection of money: Expected time to collect shipment amounts "In Arabic and English languages"
Dates for receiving and delivering orders: "In Arabic and English languages"
Developed by: write the name of the developer that will appear in the application card when it is published on the Zid app market. "In Arabic and English languages"
Short description: Briefly explain to merchants how your app and the features of the app will help them. "In Arabic and English languages"
Shipping Weight: Indicate the maximum weight for each shipment and the price increases for each weight gain. "In Arabic and English languages"
App photos &screenshots "In Arabic and English languages" Add photos and screenshots from the application.
Click on Save & Continue
This is how your information will be presented
5. Set your Activation and pricing mechanism:
Based on the contract
Based on the contract
The merchant needs to request an activation and prices are according to the contract.
Note that the merchant will need to set up the shipping option manually from his dashboard.
Fixed price
Fixed price
By using this model, the merchant account will activate immediately and the prices are fixed
Add customization
Customization name
Added countries and cities
Activate cash on delivery
shipping price
Fixed price
By weight
6. Webhook Management
The next step is to add a webhook. Through this, you can add new webhooks, and delete or edit your added ones. You can perform this action while creating your application.
For each webhook, there are 3 fields:
1. Actions list:
2. Target URL: "mandatory" is a URL used to receive the actions when occurred.
You can have a single URL for both actions, or you can have a different URLs for each one
Same URL for both: Choose both of them from the action list field, then add your URL
Different URLs: Choose the needed one and add its URL then click on the Save button. Then Choose the other one and add its URL then click on the Save button.
3. Header: any information you need to pass or identify.
Webhooks
For more information about webhooks, check our technical references Section.
Shipping system webhooks
Shipping system webhooks
These webhooks are for companies that provide only Shipping services. As a shipping system, you're required to subscribe in 4 webhooks. 2 for order updates, and 2 for App updates
Create webhooks for Order updates:
order.ready "mandatory"
order.canceled "mandatory"
2. Create Webhooks For Activation Updates
app.market.application.install: To be notified when your App is installed in the store
app.market.application.uninstall: To be notified when your App is un-installed in the store
Shipping and fulfillment webhooks
Shipping and fulfillment webhooks
These webhooks are for companies that provide Shipping and Fulfillment services, such as Storage, Order processing, packaging, etc..
As a Shipping and Fulfillment company, you're required to subscribe to 13 webhooks. 3 for order updates, 2 for App updates, 4 for products updates, and 4 for Fulfillment options
1. Create webhooks for Orders updates:
order.create "New" "mandatory"
order.ready "mandatory"
order.canceled "mandatory"
2. Create Webhooks For Activation Updates
app.market.application.install "mandatory" : To be notified when your App is installed in the store
app.market.application.uninstall*"mandatory"*: To be notified when your App is un-installed in the store
3. Create webhooks for Products updates
product.create "mandatory": when a new product is created in the store
product.delete "mandatory": when a product is deleted from the store
product.update "mandatory": when a product is updated in the store
product.publish "mandatory": when a product is published in the store
4. Create Webhook For Fulfilment Options
Merchant has the ability to enable or disable "auto-dispatching of orders and auto-syncing of products", so you'll be notified in each event if occurs. You need to subscribe in these Webhooks:
app.market.dispatch_orders.activate "mandatory"
app.market.dispatch_orders.deactivate "mandatory"
app.market.sync_product.activate "mandatory"
app.market.sync_product.deactivate "mandatory"
Here is a clear explanation about order statuses in Zid
ORDER STATUS | DESCRIPTION | RESPONSIBILITY |
New | Order has just been placed by merchant | Merchant |
Preparing | This status is between the merchant and the customer | Merchant |
Ready | Once the merchant changes the status to ready, a request should be sent to the shipping company. You should subscribe to Order List webhook to receive the order in a specific status and send the shipping information (waybill and tracking information) | Merchant |
Indelivery | Once your driver arrives at the merchant and picks up the shipment the order status should be updated to Indelivery. |
|
Delivered | Once the order arrives at the customer, the order status changes to Delivered | Partner |
Canceled | In case the customer didn't receive the shipment or returned the order status should be Canceled | Merchant, Partner |