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.

Click on the Logo Button to read through our Documentations!

or click here ninjaAPI

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:

API documentation

Getting Started

Request Sandbox Account

[Suggested] Ninja Van Settings Module

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

You are all done!

If you bump into any errors or inquiries feel free to email us at

my-sales-enablers@ninjavan.co and cc to my-devsupport@ninjavan.co

Page updated

Report abuse