ninjaAPI Integration - Interface Guideline

Interface Guideline

Proposal documentation that you can implement in your current Order Module. It's an extension that you can add to your system in order to provide the best experience to your users.

NV Shipping Order Creation

The UI we propose below is for Bulk Order Creation, whereby the user can just pre-filter the orders they want to send using Ninja Van and select the orders in bulk. With a single button click, your system will perform 3 things:

Triggers NV Order Creation API
Change the Order Status to "Fulfilled" or "NV Pending Pickup"
Display the Tracking Number generated for easy reference

*Note: NV Order Create API is for Single Order Creation, to perform the Bulk-Order Creation, your system may need to implement an array action where multiple requests will be sent to Ninja Van based on the selected orders. But fret not, since our API will only take around 0.01 seconds to process and respond per request

Multiple Pickup Address (Optional)

This is an optional built if your system support multiple fulfilment or warehouse locations where you can include in the NV Order Create API "parcel_job":"pickup_address"

Ninja Van supports multi-pickup locations for every merchants that uses our service

It is advisable to include this as part of the integration feature as all the users already have this feature in their Ninja Van Dashboard

Fixed Parameter in NV Order Create API

Here are some fields in our Order Create API that you can make the value as a default for all Order Create API Request in order to make it a hassle-free experience for your users

Pickup Date

Based on Order Creation Date

Pre-filled for all Ninja Van Order Create API parameter “parcel_job”: {”pickup_date”} during Order Creation

Service Type

Standardized service type for all users

Pre-filled for all Ninja Van Order Create API parameter {“service_type”: parcel} during Order Creation

Delivery Date

Add one day ahead

Pre-filled for all Ninja Van Order Create API parameter “parcel_job”: {”delivery_start_date”} during Order Creation

Delivery Time Slot

Standardized the delivery time slot for all users

Pre-filled for all Ninja Van Order Create API parameter “parcel_job”: {”delivery_timeslot”} during Order Creation

0900-2200

Parcel Weight

Weight: 1

Prefilled the value for parameter “Weight”

as 1 if the value equals = null.

Only applicable if there is no value for parameter “weight”

Show "Description" on AWB

User can change

Pre-filled for all Ninja Van Order Create API parameter “parcel_job”: {”delivery_instructions”}

either Product with Variation & Quantity OR Notes

NV Shipping Labels / Waybills

The UI we propose below is for Bulk Waybill Generation, whereby the user can just filter the orders they have already created the Ninja Van Tracking Numbers, ie, Status = Fulfilled / NV Pending Pickup, and select the orders in bulk. With a single button click, your system will perform 3 things:

Triggers NV Waybill Generation API
Modify the PDF response received from the calls
Display the generated & consolidated waybills in a new tab

*Note: NV Generate Waybill API is for Single Waybill Generation, and the output you'll receive is in the format of "1 bill per page in an A4 size". In order to perform the Bulk-Waybill Print with the user's preferred Waybill Format, your system may need to implement an array action where multiple requests will be sent to Ninja Van based on the selected orders and modify the output received. But fret not, since our API will only take around 0.01 seconds to process and respond per request

Example of AWB

We allow and encourage you to generate your own Waybills instead of using NV's Generate Waybill API for the Shipping Labels

Since NV Generate Waybill API returns the output in 1 bill per page in A4 size format, it is easier for you to generate the waybill on your own rather than need to modify the output you received from Ninja Van.

You can generate the waybill by using the same method you generate order invoices or you can also refer our sample here copied from our WooCommerce Plugin. Below are the Requirements and Advisable Information that you can include in the Custom Waybill:

Info need on AWB

Compulsory Info

What is required to be included in the generated waybills:

QR Code
Barcode (Code-128 Format)

The value of the QR Code and Barcode should be the same whereas the data or the value must be the generated Tracking Number for the Order

Advisable Info

What is advisable to be included in the generated waybills:

Sender & Receiver Details (Name, Email, Phone, Full Address)
Tracking Number
Ninja Van Logo
Item Description / Comment
Your System's Logo

Optional Info

What can be considered as a bonus and an added-value feature to your user

User's Logo
Order Number or Invoice Number
Marketing Banner (Uploaded by User)
Your Service's (Platform / System) ads or Promo

Status Module

These are a proposal from us on what you can implement in your current Order Status Module. What this implementation will do is create a real-time shipping order status and tracking for your users and their customers. What's needed for this integration is just:

Your URL Endpoint for Ninja Van to trigger the Webhook
Storing and reflecting the information received from Ninja Van

Webhook Event

The UI we propose below is for Real-Time Status Update based on Ninja Van's Webhook Triggers. For every Ninja Van Order Status Change, it will trigger a webhook call to send the order status information to your endpoint(s). Whenever you receive a webhook from Ninja Van, your system can:

Show real-time shipping status updates for every order
Display the Status in the User's Order Module Page
Display or Send Notifications to the User's Customer

*Note: For the Webhook to work, all your users need to subscribe to the Ninja Van Events in their Ninja Van Dashboard. The Subscription Process is just that the user need to select the Event and copy and paste your URL Endpoint(s). The Ninja Van team will guide all the users through the setup tutorial

Suggested Ninja Van Settings Module

These are basically a proposal from us on what you can implement in the Ninja Van Plugin or Extension Module. Settings that your user need to setup for their Account Connection and User's Ninja Van Preference. The setup consist of:

Ninja Van API Credentials
Sender Address
User Shipping Setting Preference

For User to Input their Ninja Van's API Credentials

For User to Input their Pickup Address Details

For User to Select their Preferred Shipping Order Settings

You are all done! Proceed with Audit here!

Auditting