ninefleet - fleet management software logo

Ninefleet Partners API

Version: v 2.0.15

For help or assistance, please contact at info@ninefleet.com

TABLE OF CONTENTS

Introduction

The Ninefleet Partners API is aimed at developers from POS systems that want to programmatically manage stores, keep their content updated and handle orders with the purpose of improving efficiency and keeping data in sync with their business.

API Credentials

To operate with this API you will be provided of a single static token that will work for all of the Stores under your control. This token is secret and should be kept in a secure place.

Unique identifier of the Partner

Since you could be operating with multiple stores, identifying each one in every operation is be essential. It’s important that you hold and share with us an unique identifier for every store integrated through this API.

This identifier will be requested for every endpoint call as a path parameter:

/stores/YOUR-STORE-ID/...

We will also make sure that you receive it as part all notifications we will be sending to your webhooks:

{
  ...
  "store_id": "YOUR-STORE-ID",
  ...
}

Description of Server Responses

200 (Ok): The request was successful.

400 (Bad Request):  The request could not be understood or was missing required parameters.

401 (Unauthorized): Authentication failed or user does not have permissions for requested operation.

403 (Forbidden): Access denied.404 (Not Found): Resource was not found.

Voucher Model Description

A voucher contains all the necessary information about a courier order.

				
					{
    _id: string, // Unique Voucher ID
    voucherCreationDate: number, // Creation Date Of Voucher
    bulkRouteType: string, // (deprecated) Route Type (acceptable values): oneWay, multiWay, multiDropoff, multiPickup
    bulkPickupDate: number, // Voucher Pickup Date (Timestamp)
    bulkDropOffDate: string, // Courier Service Type (for example Next-Day)
    generalBulkInfoOfMerchant: string, // General comment of merchant applied on every voucher in the group
    shopid: string, // Partner ID
    originName: string, // Pickup Name
    originEmail: string, // Pickup Email
    originMobile: string, // Pickup Mobile Phone
    originExtraDetails: string, // Pickup Extra Details
    originAddress: { // Pickup Address as object contains address name and details, lat and lon
        text: string,
	    lat: string,
        lon: string,
    }
    originPostalCode: number, // Origin Postal Code to assign zone
    clientName: string, // Dropoff Name
    clientEmail: string, // Dropoff Email
    clientMobile: string, // Dropoff Mobile
    clientExtraDetails: string, // Dropoff Extra Details
    clientAddress: { // Dropoff Address as object contains address name and details, lat and lon
        text: string,
	    lat: string,
        lon: string,
    }
    clientPostalCode: number, // Client Postal Code to assign zone
    needPayment: boolean, // Voucher need payment
    paymentAmount: number, // Voucher payment amount
    merchantRef: string, // Merchant comment applied per voucher
    packageVolumetricWeight: number, // Volumetric Weight Of Package
    packageWeight: number, // Physical Weight Of Package
    optimization: { // Optimization Details
	    isOptimal: boolean,
	    idBeforeOptim: string,
        estimatedArrival: string,
        estimatedDeparture: string,
        cluster: string,
        queueClusterNumber: number,
        startingRouteDateTime: number,
    }
    completed: boolean, // If voucher is completed
    cancelled: boolean, // If voucher is canceled
    returned: boolean, // If voucher is returned
    riderCannotScan: boolean, // If rider cannot pickup
    notDelivered: boolean, // If rider cannot dropoff
    currentStatus: string, // The current status of voucher
    nextStatus: string, // The future/next status of voucher
    deliveryDate: number, // The date of voucher completion
    returnFromUserToMerchant: boolean, // If merchant wants to pickup also a package from the same client  as return the value must be true
    hasMultiplePackages: boolean // If a package has same client details and same client address with other packages and exists in the same bulk import, this field must be true, in order to create a group
}
				
			

Headers

apiKey: string (required)

(Authentication with partner apiKey on Headers)

Notes

  1. All the fields are mandatory except “originExtraDetails”, “clientExtraDetails”, “generalBulkInfoOfMerchant”, ”merchantRef”.
  2. If the field “paymentAmount” has null or 0 as value the “needPayment” field must be false. If the field paymentAmount’s  value is over 0 must be true.
  3. OriginAddress text, lat & lon fields must be fixed with the pickup text, lat & lon.  ClientAddress Lat Lon fields must be null, we will geocode the ClientAddress text.
  4. For “clientMobile” the “30” before the phone number is mandatory, in order to send the informational sms.
  5. For the field “hasMultiplePackages”, in order to group them successfully, vouchers must be created in the same create-voucher API call.

Example Body (simple vouchers): 

				
					{
  "vouchers": [
    {
      "originName": "testOriginName",
      "originEmail": "test@hotmail.com",
      "originMobile": "6977777777",
      "originExtraDetails": "test",
      "originAddress": {
        "text": "Agias paraskevis 12, Chalandri",
        "lat": "18.2323",
        "lon": "34.2342"
      },
      "originPostalCode": 15127,
      "clientName": "testClientName",
      "clientAddress": {
        "text": "Agiou artemiou 1, Athina",
        "lat": null,
        "lon": null
      },
      "clientPostalCode": 15127,
      "clientExtraDetails": "TEST-DETS",
      "bulkPickupDate": "1617888086811",
      "bulkDropOffDate": "Next-Day",
      "generalBulkInfoOfMerchant": "test bulk info",
      "clientEmail": "test@ninefleet.com",
      "merchantRef": "parcelCode",
      "clientMobile": "306977777777",
      "packageVolumetricWeight": 23.1,
      "packageWeight": 12.1,
      "needPayment": true,
      "paymentAmount": 12,
      "returnFromUserToMerchant": false,
      "hasMultiplePackages": false
    }
  ]
}
				
			

Success Example (200):

				
					{
    "status": "ok",
    "created": "1 vouchers",
    "data": ["60a26c9d7d79432acdd628b6"],
    "message": "Everything went good!"
}

				
			

Invalid body Error Example

				
					{
    "status": "error",
    "message": "Cannot create vouchers. Possible null values on required items!"
}
				
			

Validation Error Example

				
					{
  "error": [
    {
      "errors": {
        "originEmail": {
          "message": "Validator failed for path `originEmail` with value `ter`",
          "name": "ValidatorError",
          "properties": {
            "message": "Validator failed for path `originEmail` with value `ter`",
            "type": "user defined",
            "path": "originEmail",
            "value": "ter"
          },
          "kind": "user defined",
          "path": "originEmail",
          "value": "ter"
        }
      },
      "_message": "vouchers validation failed",
      "message": "vouchers validation failed: originEmail: Validator failed for path `originEmail` with value `ter`",
      "name": "ValidationError"
    }
  ]
}
				
			

Error After Reaching Daily limit

By default create-vouchers service has an upper limit of 2300 requests daily.

				
					{
    "status": "error",
    "message": "You have reached the daily requests limit. Please contact Ninefleet’s Team to resolve the issue."
}

				
			

Get Voucher Details By ID

Method: GET

Headers

apiKey: string (required)

(Authentication with partner apiKey on Headers)

Path Parameters

idOfVoucher: string (required)

Success Example (200):

				
					{
    "status": "ok",
    "message": "Everything went good!",
    "data": {
        "originAddress": {
            "text": "Agias paraskevis 12, Chalandri",
            "lon": "34.2342",
            "lat": "18.2323"
        },
        "clientAddress": {
            "text": "Agiou Artemiou 1, Athina 116 32, Greece 15127",
            "lon": "23.7432048",
            "lat": "37.9607482"
        },
        "optimization": {
            "isOptimal": false,
            "cluster": null,
            "queueClusterNumber": null,
            "estimatedArrival": null,
            "estimatedDeparture": null,
            "riderToComplete": null,
            "startingRouteDateTime": null,
            "idBeforeOptim": "JJG8298304"
        },
        "paymentStatus": {
            "isPaid": false,
            "riderId": null,
            "paymentTime": null,
            "paymentResponse": null,
            "paymentMethod": null,
            "cashReceived": null,
            "cashChange": null
        },
        "originExtraDetails": "test",
        "clientExtraDetails": "TEST-DETS",
        "cancelled": false,
        "returned": false,
        "completed": false,
        "notDelivered": false,
        "generalBulkInfoOfMerchant": "test bulk info",
        "isInStorage": false,
        "needPayment": true,
        "paymentAmount": 12,
        "_id": "6308bdbb180f2eb12c56295b",
        "voucherCreationDate": 1661517243899,
        "originName": "testOriginName",
        "originEmail": "test@hotmail.com",
        "originMobile": "6977777777",
        "clientName": "testClientName",
        "clientEmail": "test@ninefleet.com",
        "clientMobile": "306977777777",
        "mainHistory": [],
        "merchantRef": "parcelCode"
    }
}
				
			

Get active vouchers

Method: GET

(Get-active-vouchers getmethod production and development urls.)

Headers

apiKey: string (required)

(Authentication with partner apiKey on Headers.)

Notes

Success Example (200):

				
					{
  "status": "ok",
  "message": "Everything went good!",
  "data": [
    {
      "originAddress": {
        "text": "Agias paraskevis 12, Chalandri",
        "lon": "34.2342",
        "lat": "18.2323"
      },
      "clientAddress": {
        "text": "Agiou Artemiou 1, Athina 116 32, Greece 15127",
        "lon": "23.7432048",
        "lat": "37.9607482"
      },
      "optimization": {
        "isOptimal": false,
        "cluster": null,
        "queueClusterNumber": null,
        "estimatedArrival": null,
        "estimatedDeparture": null,
        "riderToComplete": null,
        "startingRouteDateTime": null,
        "idBeforeOptim": "JJG8298304"
      },
      "originExtraDetails": "test",
      "clientExtraDetails": "TEST-DETS",
      "generalBulkInfoOfMerchant": "test bulk info",
      "needPayment": true,
      "paymentAmount": 12,
      "_id": "6308bdbb180f2eb12c56295b",
      "voucherCreationDate": 1661517243899,
      "originName": "testOriginName",
      "originEmail": "test@hotmail.com",
      "originMobile": "6977777777",
      "clientName": "testClientName",
      "clientEmail": "test@ninefleet.com",
      "clientMobile": "306977777777",
      "merchantRef": "parcelCode"
    }
  ],
  "results": 1
}
				
			

Edit voucher

Method: POST

(Edit-vouchers post method production and development urls.)

Headers

apiKey: string (required)

(Authentication with partner apiKey on Headers.)

Notes

Example Body:

				
					{
    "voucherId": "6308bdbb180f2eb12c56295b",
    "voucher": {
      "originName": "testOriginNameEdited",
      "originEmail": "test@hotmail.com",
      "originMobile": "6977777777",
      "originExtraDetails": "test",
      "originAddress": {
        "text": "Agias paraskevis 2, Chalandri",
        "lat": "18.2323",
        "lon": "34.2342"
      },
      "originPostalCode": 15127,
      "clientName": "testClientNameEdited",
      "clientAddress": {
        "text": "Agiou artemiou 4, Athina",
        "lat": "12.34",
        "lon": "23.1"
      },
      "clientPostalCode": 15127,
      "clientExtraDetails": "TEST-DETS",
      "bulkPickupDate": "1617888086811",
      "bulkDropOffDate": "Next-Day",
      "generalBulkInfoOfMerchant": "test bulk info",
      "clientEmail": "test@ninefleet.com",
      "merchantRef": "parcelCode",
      "clientMobile": "306977777777",
      "packageVolumetricWeight": 23.1,
      "packageWeight": 12.1,
      "needPayment": true,
      "paymentAmount": 12
    }
}
				
			

Success Example (200):

				
					{
    "status": "ok",
    "message": "Voucher Changed Successfully"
}
				
			

Cancel vouchers

Method: POST

(Cancel-vouchers post method production and development urls.)

Headers

apiKey: string (required)

(Authentication with partner apiKey on Headers.)

Example Body:

*Multiple vouchers cancel is accepted.

				
					{
    "voucherIds": [
        "60740838e9b540019541f3ca",
        "60740838e9b540019541f3cb"
    ],
    "reason": "Client canceled!"
}
				
			

Success Example (200):

				
					{
    "status": "ok",
    "message": "The selected vouchers canceled successfully!",
    "canceled": 2
}
				
			

Get Voucher History (per day)

Method: POST

(Vouchers History per day post method production and development urls.)

Headers

apiKey: string (required)

(Authentication with partner apiKey on Headers.)

Example Body:

				
					{
    "day": 23,
    "month": 1,
    "year": 2021
}
				
			

Success Example (200):

				
					{
    "status": "ok",
    "message": "Everything went good!",
    "data": [
        {
            "originAddress": {
                "text": "Melissia, Greece",
                "lon": "23.8336016",
                "lat": "38.0572295"
            },
            "clientAddress": {
                "text": "Αγίας Παρασκευής, Λεμεσός, Κύπρος",
                "lon": "33.0527222",
                "lat": "34.6923439"
            },
            "optimization": {
                "isOptimal": false,
                "cluster": null,
                "queueClusterNumber": null,
                "estimatedArrival": null,
                "estimatedDeparture": null,
                "riderToComplete": "62b0b8ce41e8fb2ea95e40c9",
                "startingRouteDateTime": null,
                "idBeforeOptim": "JJG0462374"
            },
            "paymentStatus": {
                "isPaid": true,
                "riderId": "62b0b8ce41e8fb2ea95e40c9",
                "paymentTime": 1661615847370,
                "paymentResponse": "",
                "paymentMethod": "Cash",
                "cashReceived": 3,
                "cashChange": 1
            },
            "originExtraDetails": null,
            "clientExtraDetails": "3434",
            "cancelled": false,
            "returned": false,
            "completed": true,
            "notDelivered": false,
            "generalBulkInfoOfMerchant": null,
            "isInStorage": false,
            "needPayment": true,
            "paymentAmount": 2,
            "_id": "6307a839c63e11aff81191e2",
            "voucherCreationDate": 1661446201136,
            "originName": "testio shopy",
            "originEmail": "test@ninefleet.com",
            "originMobile": "3572100000",
            "clientName": "inkos",
            "clientEmail": "test@ninefleet.com",
            "clientMobile": "35721000000",
            "mainHistory": [
                {
                    "location": {
                        "coordinates": {
                            "lon": 0,
                            "lat": 0
                        },
                        "type": "Point"
                    },
                    "person": {
                        "id": "62b0a31b96e5322e20d20aa4",
                        "role": "Admin",
                        "fullName": "nikos kouus"
                    },
                    "_id": "630a3ee7659990d0bf60a462",
                    "timestamp": "1661615847374",
                    "action": "Completed"
                }
            ]
        }
    ],
    "results": 1
}
				
			

Print active vouchers methods

Partners can print vouchers by using five different ways:

  1.  Partners can print all active vouchers from their panel at the link partner.ninefleet.com/courier/activevouchers


  2. By using the /get-active-vouchers service (section 6) partners can get the information foreach active voucher and generate their own vouchers.

    Each voucher must always include the following fields:
    • QR code generated from _id of the voucher
    • Courier Company Logo (Check link here for graphic assets)
    • 5-digit number (voucher field under optimization → idBeforeOptim)
    • Origin Details: name, mobile, address text, extra details
    • Client Details: name, mobile, address text, extra details
    • Courier Company Legal paragraph, example below:
      “ΑΜ-ΕΕΤΤ 20-034 | Γενική Άδεια Παροχής Ταχυδρομικών Υπηρεσιών / Ταχυμετοφορών – Courier Όροι & Προϋποθέσεις: www.stoferno.gr/terms-of-use

  3. By using the /get-voucher-pdf service (section 11) partners can receive a PDF array buffer, decode it into .pdf file and print it.

  4. By using the /print-wtr-vouchers (section 12 print vouchers with redirect).

  5. By using the /pdf-voucher-file service (section 13) partners can download a PDF file from a web url.

Get Voucher PDF (buffer array)

Method: POST

(Get Voucher PDF as array buffer encode post method production and development urls.)

Headers

apiKey: string (required)

(Authentication with partner apiKey on Headers.)

Example Body:

				
					{
    "voucherId": “605a1662a8dcc154fe545a22”,
    "width": “10cm”,
    "height": “17cm”
}
				
			

Success Example (200):

				
					{
    "status": "ok",
    "message": "Everything went good!",
    "pdf": {
        "type": "Buffer",
        "data": [37,80,68,70,45,43,46,52,10,37,211,235]
    }
}
				
			

Print Vouchers With Redirect

Method: POST

(Get redirect url to print PDF from your browser.)

Headers

apiKey: string (required)

(Authentication with partner apiKey on Headers.)

Example Body:

				
					{
    "voucherIds": [
        "606f217eb376b8552ce5ae48",
        "606f217eb376b8552ce5ae45"
        ],
    "noOfPagesPerPage": 3
}
				
			

Success Example (200):

				
					{
    "status": "ok",
    "url":"partner-dev.ninefleet.com/vouchers/print/606f217eb376b8552ce5ae48,606f217eb376b8552ce5ae45,1"
}
				
			

Download Vouchers PDF (from web url)

Method: POST

(Get url to download pdf with selected vouchers.)

Headers

apiKey: string (required)

(Authentication with partner apiKey on Headers.)

Example Body:

				
					{
    "voucherIds": [
        “61a4f2a9640741076ac79f83”, 
        “61bc9770bc8ff7491eede5b8”]
}
				
			

Success Example (200):

				
					{
    "status": "ok",
    "url": "partner-dev.ninefleet.com/vouchers/download-pdf/61a4f2a9640741076ac79f83,61bc9770bc8ff7491eede5b8"
}
				
			

Voucher Tracking API

Method: POST

(Get tracking info of Voucher.)

Headers

apiKey: string (required)

(Authentication with partner apiKey on Headers.)

Example Body:

				
					{
    "voucherId": “61a4f2a9640741076ac79f83”
}
				
			

Success Example (200):

				
					{
  "status": "ok",
  "voucher": {
    "_id": "61a4f2a9640741076ac79f83",
    "trackingHistory": [
      {
        "_id": "61a4f2a9640741076ac79f84",
        "status": "Request from partner",
        "timestamp": 1638199977564,
        "title": "Μόλις λάβαμε αίτημα διανομής από την εταιρεία Jumbo-dev.",
        "subTitle": "Σύντομα θα ενημερωθείτε ξανά για το επόμενο στάδιο διανομής."
      },
      {
        "_id": "61e6ce791bd26616f70d8fb6",
        "status": "Rider scanned - Deliver to Hub Μεταμόρφωση",
        "timestamp": 1642516089967,
        "title": "Μόλις παρέλαβε ο/η Nikolaos για διακίνηση προς την αποθήκη μας στη διεύθυνση Sintagmatarchou Davaki 24, Metamorfosi 144 51, Greece.",
        "subTitle": "Αν επιθυμείτε να παραλάβετε το δέμα απευθείας από εμάς, μπορείτε να μας ενημερώσετε μέσω Live Chat. Ειδάλλως, θα λάβετε νέα ενημέρωση διανομής."
      }
    ]
  }
}