Direct API
- Self Developed
Connect your system directly with Ninja Van's API and customize every process and full automation experience!
API documentation
Every Ninja Pro account comes with an API feature for you to build your own custom function and module in your system. In our documentation below, we have included all APIs in our repository, integration requirements, sample payloads, webhook subscriptions and error codes.
Request Sandbox Account
You need to use your Ninjavan Account (Sandbox Environment) to test our API, Please follow all the steps below:
Write an Email to my-sales-enablers@ninjavan.co
Subject: Requesting Sandbox Account
Body/Content :
Hi, my company name is _______________,
this is my Ninja Van account email (if exists): _______________
this is my email (if don't have NV account): ________________
Please give me access to Ninja Van's Sandbox Account. Thank You!
**If you need more than one test account, please mention it in the email.
Once the account is ready we will send a separete email looks like this :
Subject : Sandbox Credential for Integration - {{Shipper Name}}
UI/UX Guideline
View our Guideline, Front-end template that you may apply!
This is a proposal based on what you can implement in your system/platform by utilizing Ninja Van’s API. Based on the feedback that Ninja Van gathered from the client base and what features can be implemented to satisfy their needs. In order to ensure all the development of any platform that what we do in the future is standardized.
Here are the 2 main Modules that you can implement in your system:
Order Module
These are basically a proposal from us on what you can implement in your current Order Module. It's an extesion for Creating NV Shipping Order, Generating NV Waybill or Shipping Label and Additional Columns that you can add to your system in order to provide the best experience to your users. It mainly consist of 2 parts:
NV Shipping Order Creation
NV Shipping Label / Waybill
Extension in your Current User Order Module for 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, in order to perform the Bulk-Order Creation, your system may need to implement array action where multiple request 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 processed 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
Extension in your Current User Order Module for NV Shipping Labels / Waybills
The UI we propose below is for Bulk Waybill Generation, whereby the user can just filter the orders they already create the Ninja Van Tracking Numbers "ie: Status = Fulfilled / NV Pewnding 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 respond 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 received are in the format of "1 bill per page in an A4 size". In order to perform the Bulk-Waybill Print with user preferred Waybill Format, your system may need to implement array action where multiple request 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 processed and respond per request
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:
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 basically a proposal from us on what you can implement in your current Order Status Module. What this implementation will do is to create a real-time shipping order status and tracking to your users and their customers. What's needed for this integration is just:
Your URL Endpoint for Ninja Van to triggers the Webhook
Storing and Reflecting the information received from Ninja Van
Extension in your Current User Order Status Module
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 sent the order status information to your endpoint(s). Whenever you received a webhook from Ninja Van, your system can:
Show real-time shipping status update for every order
Display the Status in User's Order Module Page
Display or Send Notifications to User's Customer
*Note: For the Webhook to work, all your users need to Subscribe the Ninja Van Events in their Ninja Van Dashboard. The Subscription Process is just the user need to select the Event and Copy Paste your URL Endpoint(s). Ninja Van team will guide all the users on 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