API Documentation
This documentation will help you understand how to utilize our Ninja Van's API and customize every process and full automation experience!
Embedded Files
Make sure you follow all our steps for granting access
approval to Ninja Van Integration!
Audit Verification Process Timeline
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 week. It depends on the shipper as well as they need to make changes if there are any issues with the integration
- Read our API Docs
Every Ninja Pro account comes with an API feature for you to build your 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 documentation!
or click here ninjaAPI
Please take note of our integration requirements!
We will need to check on your sandbox integration before approving your move to production. We require 3 orders to be generated for every audit of the Create Order API and the Waybill API
OAuth Access Token API requirement
To set up client API credentials, you can view them here
Attach the access token as a bearer token with every API request to the Ninja Van API.
Store it in persistent storage (database) or cache, and also store the expiration timestamp.
Only generate the token if it is 5 minutes before it expires, or if the API request responded with an HTTP 401 error
Create Order API requirement
You are encouraged to retry order creation requests IF an HTTP 5xx error is returned from our API.
If an HTTP 4xx error is returned, please log the response for your debugging purposes, and DO NOT retry the same order creation request without fixing the error specified in the response.
Generate Waybill API requirement
You must cache the waybill upon generation and avoid excessive calls to the waybill API.
If you are generating your waybill, a Waybill API audit is not necessary.
For the custom waybill, our only requirement is that it contains a QR Code of the Tracking Number generated
Webhooks API requirement
Ninja Van Integration Process
Before you start the integration, kindly ensure that you use the right Environment
Sandbox: https://api-sandbox.ninjavan.co/SG
Production: https://api.ninjavan.co/MY
The integration requires you to go through the Sandbox Audit Process for your Production Account to be able to get permission to create an Order and generate a Waybill (Optional).
If you require to use of the Waybill API, do let us know beforehand so that we’ll grant access to the Sandbox Waybill API.
2. Request Sandbox Account
2. 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 it exists): _______________.
This is my email (if I don't have an 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}}
3. Get access to NV Sandbox Dashboard
3. Get access to NV Sandbox Dashboard
To log in to our shipper Sandbox dashboard
Head over to https://dashboard-sandbox.ninjavan.co/login-v2
Log in to the email with the password provided in the last email.
Go to Settings > IT Settings
API Key Name (Shipper Name)
IF there's no Client ID and Key shown, please click "Regenerate Client ID & Key"
Copy both and paste them into your system
4. Get Audited
4. Get Audited
THIS STEP IS COMPULSORY AND IT IS THE DEFAULT SCENARIO
SCENARIO CAN CHANGE AFTER THE AUDIT PROCESS IS APPROVED
We will send 2 another emails (Integration Audit Request: AUD000XX-INT000XX),
one for Order Creation Production API and one for Sandbox Waybill Sandbox,
including the link to proceed with the audit integration request.
Please follow the test scenario below when creating the test orders for integration audit purposes:
* Make sure that you follow the test scenario exactly as in the example below. This is to ensure that you pass our automated system requirements smoothly.
There will be 3 test scenarios for you to test.
You will need to put the 1 tracking number for each test scenario..
Example email :
First email, we will include the Integration Audit Request Link, click it, and then you will go to our audit integration portal.
2. Click Yes for both questions and get started. You will need to put 3 test orders in separate 3 scenarios.
3. Once all good you will got this email, we will grant the access by the end of the day.
**
if you got the error such as no api calls//token error//etc
please make an amendment first, and then repeat the first step.
4. Once granted, we will send this email
**Repeat the process for WAYBILL API if you have already settled the first link email.
5. [PLUGIN API] - for platform use only
5. [PLUGIN API] - for platform use only
Getting Started
Getting Started
integrating party, you are required to prepare the following to provide to the 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 a Sample)
API Sequence Diagram of how the general flow works. (Click here for a Sample)
Once you have all this information, 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
List of APIS
List of APIS
Production base URL
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
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
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.
Extra Resources
Extra Resources
If you want an idea or guideline for ui/ux please click here!
Page updated
Report abuse