Plugin API Guidelines
- For Enabler
This Documentation will help you to understand how to understand how to utilised our Plugin API to built Ninja Van Integration for your plugins or platform
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.
Introduction
This document should help you understand the implementation of our oAuth web grant flow, we will outline what parameters need to be passed to our Public APIs with an example for each API. This documentation consist of:
Getting Started
As an integrating party, you are required to prepare the following to provide to Ninja Van Team:
Your Plugin or Platform Name
Redirect URI (For your Staging or Sandbox Environment)
Permission Scope Required
C4 Panel Flow Diagram with minimum Level 2 Diagram. (Click here for Sample)
API Sequence Diagram of how the general flow are working. (Click here for Sample)
Once you have all these informations, kindly reach out to your Ninja Van Dev Support personnel that been liaising for us to provide you the Ninja Van Sandbox Credential for Plugin Type Integration
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): ________________
This is the Platform Name : ________________________
This is the redirect URI : ___________________________
C4 Panel & API Sequence are attached below.
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}}
List of APIS
Production base URL
URL for OAuth Token API: https://aaa.ninjavan.co/{countryCode}
URL with country code: https://api.ninjavan.co/{countryCode}
Sandbox base URL
URL for OAuth Token API: https://aaa-sandbox.ninjavan.co/{countryCode}
URL with country code: https://api-sandbox.ninjavan.co/{countryCode}
Note: Always send your sandbox requests to the Singapore sandbox API. However, you can send localised addresses for the countries that you are testing for. In other words, you can craft the API request as you would for the production environment. The only difference is the URL.
Initiating the Flow
The flow chart below illustrates the plugin integration normal flow
The plugin client should show a button that directs the shipper to connect their Ninja Van account at the plugin client site.
When the shipper clicks on the button to connect to Ninja Van, the plugin client should redirect the shipper to the Ninja Dash login page and provide the following in the URL parameters:
Client ID
Scopes: we expect them to be space separated. (please make sure to encode this parameter using encodeURIComponent)
State
3. The login page will be displayed by Ninja Dash.
4. The shipper should log in using the Ninja Van shipper credentials.
5. Ninja Van authorization server checks and authorizes shipper login into Ninja Dash.
6. The permission grant form is for the shipper to give permission to the plugin client to act on behalf of their Ninja Van account with the scopes listed.
7. The shipper clicks `Allow` to give permission to the plugin client to act on behalf, `Deny` if otherwise.
8. Ninja Van authorization server then grants permission scopes to the plugin client.
9. After granting the permission, the Ninja Van authorization server redirects back to the plugin client redirect URI adding code and state as URL parameters.
10. The plugin client receives code in the URL parameter.
11. The code received in the previous step should be used along with the client ID and client secret to generate the access token.
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
For User to Input their Pickup Address Details
For User to Select their Preferred Shipping Order Settings
Audit Verification Process Timeline
Once the audit request is received via email, we will be slotting into the sprint and it will be verified by our QA team
The entire audit verification may take 1-3 weeks time. It depends on the shipper as well as they need to make changes if there are any issues with the integration