1. Integration Specification


1.1     Overview

This document specifies the integration of nuDeliverIt with external systems. The intention of the document is to provide the understanding, methods and data mapping required to integrate nuDeliverIt (https://www.nudeliverit.com) with external systems.

1.2     Document Terminology

The document assumes native nuDeliverIt field-naming conventions. nuDeliverIt can be used in a wide variety of business delivery application and the field names represented here may not directly represent the use of these fields in your specific application.

It is recommended to read this document along with the understanding of integration of inbound interfaces.

Document Terminology nuDeliverIt Use Associated Industry Terminology
Stop Destination for performing work activities such as delivery, pickup, service, field work etc. Customer location, destination, site.
Load A sequence of stops combined and assigned to a person. The load contains all the stops in the sequence. Work schedule, Route, truck path, delivery run, service run.
Driver Represents the personnel deployed for the Load Driver, trucker, delivery man, technician
Comments Set of instructions sent to the driver. Comments can be associated with the stop or the load. Note: Only specific comment types are sent to the driver. Special instructions, delivery instructions, Customer request.
Product Identifier Used to uniquely identify the product during delivery/ pickup or use. This could represent the barcode if scanning is used in the system. SKU barcode, Package barcode, Item barcode, service number, part, pickup tracking number, delivery tracking number.
Host This indicates your server from which orders or routes will be sent to nuDeliverIt server Server


2.  Integration Overview


This document covers the use of Events and Stops that are generated by nuDeliverIt.

2.1     Integration Protocols

Integration protocols used are HTTPS, FTP and SFTP. External systems can send orders to nuDeliverIt using webservice. The stop/order tracking information files are created in nuDeliverIt. External systems can fetch the XML from nuDeliverIt over FTP. nuDeliverIt can also post Stop/Order data using a customer created webservice on a secure server on the interfacing system.

Interface Protocols Data Format
Host to nuDeliverIt Stop/ Order HTTPS/ SFTP/ FTP XML
nuDeliverIt to Host Stop/Order Delivery HTTPS/SFTP/ FTP XML

2.2     Integration Format

Integration format is developed for the most common use. The most commonly used format (XML) is provided as default.

2.3     File Name

If a file-based protocol is used (FTP/ SFTP/FILE), if is recommended that the following file naming convention is used. This will allow the files to be processed in sequence. The file name will be prefixed as follows

  • <stopnumber>_CCYYMMDD_HHMMSS.xml (all filenames are in lowercase notation)


3.   Host to nuDeliverIt Stop/ Order Integration (From your server to nuDeliverIt)


3.1     Stop integration Overview

Here “Host” refers to your server from which orders/routes will be sent via XML to nuDeliverIt server. Stop integration is achieved through either a REST based web services over HTTPS connection or using SFTP/FTP. The stops are interfaced using XML. The schema definition is defined in nuDeliverItStops.xsd.

3.2     Stop XML Structure

The stop information is a hierarchical structure. The high-level schematics are shown as below. The fields under each of the tags and their description are provided in the integration spreadsheet. A sample XML document and XSD for the XML is provided at the end of this page.


3.3     Function node

XML has a node “Function” within the tag “Stop”. The value of this node “Function” determines the action to be taken.

Function Description
01 Create or update the Stop.
02 Delete the Stop.
03 Create or update the stop and assign/ un-assign it to Business Partner carrier.

3.4     Web Services

Upon signup with nuDeliverIt, the URL for web services will be provided along with the company code. Web services utilizes basic authentication over HTTPS. An integration user with integration role should be created to authenticate with the web services. An example of the web service URL is


3.5     Web Service Response

The web service request is processed synchronously and a response XML is sent back. The response XML consists of any error information and updates performed in the system. The response must be captured and analyzed for any errors.

Code Response Status
10 Success
99 Failure

3.6     XML Special Characters

XML data must be well formed and must conform to the XML standards and the XSD. Care should be taken to ensure that special characters are escaped properly in the data. The following are the special characters used in the XML and their corresponding escaped format. Replace any special characters in the data with the escaped format to prevent failure of the interface.

Special Character Escaped Format
& &amp;

4.  nuDeliverIt to Host Stop/ Order Integration (From nuDeliverIt to your server)


For every stop/order, when the stop/order is completed in nuDeliverIt, nuDeliverIt creates an XML file with all the execution data. The XML format is very similar to the stop/order data coming from host to nuDeliverIt except additional attributes for actual start date/time of the order delivery, date/time of order completion, actual items delivered, signature if captured etc. Host systems can get these XML files over FTP/SFTP or if the customer can expose a webservice, nuDeliverIt will POST the XML over HTTPS using customer created REST based webservice. The XML file includes the stop/order events and the event definition is explained below.

5. Event Overview


5.1     Events

Events are recorded steps that occur on the nuDeliverIt mobile application and sent to the portal in real-time. If there is loss of connectivity between the device and portal, the events are reported on the first available data connection. All nuDeliverIt event data (loads & stops) can be reported with date, time and location where the event occurred.

The following provide the list of events that are reported by nuDeliverIt.

Load Level Events

Event Code Event Name Description
7000 LOAD CREATED Event to indicate when the load was created.
7001 LOAD ASSIGNED Event to indicate a driver has been assigned to a load.
7002 LOAD UNASSIGNED Event to indicate the load was unassigned from a driver.
7004 LOAD INITIATED Event to indicate the driver has checked into the load using the nuDeliverIt mobile app.
7005 LOAD COMPLETED Event to indicate that load was completed.
7015 LOAD SUSPENDED Event to indicate when the load was suspended.
7024 LOAD UPDATED Event to indicate when the load was updated.
7033 LOAD CANCELLATION Event to indicate when the route was cancelled.

Stop Level Events

Event Code Event Name Description
7006 STOP GF ENTERED Event to indicate the driver has entered into the stop geo-fence of one of the stops on their load. The data provided gives the associated load number and stop number.
7007 STOP ARRIVAL Event to indicate the drivers arrival at the stop (pick or delivery)
7008 STOP DEPARTURE Event to indicate the driver’s departure from the stop
7009 STOP DELIVERY Event to indicate the confirmation of pickup/delivery at the stop
7014 DOCUMENT CAPTURE Event to indicate, if any PDF documents are involved or camera capture of photos at the stop
7021 STOP CLOSED Event to indicate when the stop was closed
7028 STOP PLANNED Event to indicate when the stop was planned into a route
7044 STOP REOPENED Event to indicate the when the stop was reopened
7053 STOP UPDATED Event to indicate when the stop was updated
7059 STOP CANCELLED Event to indicate when the stop was cancelled
8100 Stop Received Event to indicate of the stop was physically received at the warehouse/depot location
8101 Stop Scheduling Initiated Event to indicate customer has been notified to select an appointment date for a pickup/delivery
8102 Stop Scheduling Confirmed Event to indicate customer has been confirmed an appointment date for a pickup/delivery
8103 Stop Scheduling Cancelled Event to indicate customer has been cancelled an appointment date for a pickup/delivery

Sample nuDeliverIt event flow
  • Step 1: Event: Stop Received
    Shipment is received at the distribution center or warehouse. The dispatchers can mark the stops as received.
  • Step 2: Event: Stop Scheduling Initiated
    Dispatcher/customer support person requests for a delivery window from a customer.
  • Step 3: Event: Stop Scheduling Confirmed
    Dispatcher/customer support person or actual end customer can confirm the appointment window. The rescheduling of the delivery window fires the same event (stop scheduling confirmed)
  • Step 4: Event: Stop Scheduling Cancelled
    Dispatcher/customer support person or actual end customer can cancel the appointment window
  • Step 5: Event: Load Created/Stop-Planned
    Shipment is added to a route/load
  • Step 6: Event: Load Initiated
    The driver loads the truck and departs the warehouse/distribution center and is now out for delivery
  • Step 7: Event:  Stop Arrival
    Driver arrives at the customer location for a delivery/pickup
  • Step 8: Event: Stop Close
    Driver arrives but the customer is not available. Driver closes the stop and leaves. This stop can be reopened later and added to a new route
  • Step 8: Event: Stop Delivery/Stop Confirmation
    Driver arrives at the stop and performs delivery/pickup with or without exceptions
  • Step 9: Event: Signature/Document Capture
    Driver has performed the delivery and captures ePODs such as pictures or signatures
  • Step 10: Event: Stop Departure
    The driver has performed the delivery/pickup and leaves the customer location
  • Step 11: Event:  Load Complete
    Driver has finished all stops on the route/load

6.  Web Service Integration


6.1     Introduction

This section describes in detail the process involved on how a user can make requests to the nuDeliverIt Portal and retrieve the necessary data using Web Services API Calls(s). nuDeliverIt provides a very clean and easy mechanism for any customer to send a custom specific request to retrieve any data that they need for their custom use. All of the Web Services Requests are very secure, as any request to the nuDeliverIt portal requires authentication using the username and password that’s registered with the nuDeliverIt portal application for a specific company/customer. Not only the Authentication, the user must also have the appropriate role assigned in nuDeliverIt to make request to the Web Services API, even if one has access to the portal if Role (DI_Integration) is not assigned to the user, he/she will not be able to make the request.

There are many ways one can use to send requests to nuDeliverIt Web Service API(s), some of them are for example through PHP, CURL or JAVA. Whichever technology one is most familiar with can use that to make request to nuDeliverIt Web Service API(s) and get the required information needed. Following are the two Web Services API(s) available that are most frequently used.

  • https://www.nuvizzapps.com/nuDeliverIt/webservices/api/<ENTITY>/<COMPANY_CODE>
  • https://www.nuvizzapps.com/nuDeliverIt/webservices/api/document/<FILE_GUID>/<COMPANY_CODE>

In the above, the first Web Service API is used to retrieve Load/Route or Stop/Order information and the second Web Service API is used to retrieve the associated Document/Image with a Load/Stop. <ENTITY> can be either Loador Stop(entity name is case insensitive), <FILE_GUID> specifies that actual unique alpha-numeric encoded string that represents the name of the Document, and <COMPANY_CODE> is the unique Company Code assigned to the customer which is used while logging into the portal.

To explain in detail how to use nuDeliverIt Web Service API(s) to retrieve information, CURL is used which is a Command Tool used for sending and getting files/data using URL syntax. It’s an open source tool and is available on most of the operating systems or if it is not available then it can be downloaded and installed from (http://curl.haxx.se). Usage of this tool is very simple and curl –helpprovides detailed information about all available command line parameters. CURL supports many commonly used protocols (including FTP, HTTP, HTTPS etc.).

6.2     Route/Stop Detail Retrieval

To obtain detailed Stop Information for a company say DEMO following curl command can be used to make the Web Service API call as follows:

> curl -X GET -H "Content-Type:application/json" -k -u admin:password 'https://www.nuvizzapps.com/nuDeliverIt/webservices/api/stop/DEMO?stopNbr=69794200&&stopSealNbr=JEFF'

The above command makes a Web Service API call to retrieve details of a STOP having Stop Number as 69794200 and Seal Number being JEFF for the company code DEMO. The username/password for authentication is admin/password and the expected result is of JSON object type. Below is the result returned executing the above command. The highlighted fields in BOLD in the result below shows the parameters passed to retrieve the exact STOP information. You can create your own query using below available fields to obtain STOP or LOAD information which could be very generic say at Company Level or very specific like above.

"loadId": {
"loadHeader": {
"loadId": 3145,
"loadNbr": "DEMO000006",
"status": "30",
"origin": "Demo Facility",
"originName": "Demo Delivery",
"originAddr1": "5855 Mountain View Pkwy",
"originAddr2": "",
"originCity": "Norcross",
"originState": "GA",
"originZip": "30093",
"originCountry": "USA",
"totalStops": 4,
"reference": "",
"weight": {
"value": 0
"volume": {
"value": 0
"companyId": {
"companyId": 138,
"companyName": "Demo Company",
"address1": "5855 Mountain View Pkwy",
"address2": "",
"city": "Norcross",
"state": "GA",
"zip": "30093"
"assignedDriver": "David Shawn"
"stopNbr": "69794200",
"status": "00",
"stopSeq": 1,
"shipmentNbr": "69794200",
"bol": "002480748",
"signatureRequired": false,
"shipToName": "RENEW COMPUTER AS",
"shipToAddr1": "STE 1200",
"shipToAddr2": "5060 AVALON RIDGE PKWY",
"shipToCity": "NORCROSS",
"shipToState": "GA",
"shipToZip": "30071",
"billToAddr1": "1770 SATELLITE BLVD",
"billToCity": "BUFORD",
"billToState": "GA",
"billToZip": "30518",
"billToCountry": "US",
"earliestStartDttm": "Mar 5, 2015 7:00:00 AM",
"latestStartDttm": "Mar 5, 2015 7:00:00 AM",
"totalPallets": 1,
"totalCartons": 1,
"sealNbr": "JEFF",
"documents": [],
"stopDetails": [
"product": "KNIVES",
"productIdentifier": "011110-00-2401",
"quantity": {
"uom": "CTN",
"value": 1
"weight": {
"uom": "LBS",
"value": 1
"volume": {
"value": 0
"product": "CORR BOXES KDF 12 # PER C",
"productIdentifier": "029275-04-2400",
"quantity": {
"uom": "BDL",
"value": 40
"weight": {
"uom": "LBS",
"value": 340
"volume": {
"value": 0
"product": "FLASHLIGHT",
"productIdentifier": "109800-02-2404",
"quantity": {
"uom": "CTN",
"value": 1
"weight": {
"uom": "LBS",
"value": 1
"volume": {
"value": 0
"product": "LABELS",
"productIdentifier": "153500-02-2402",
"quantity": {
"uom": "CTN",
"value": 6
"weight": {
"uom": "LBS",
"value": 79
"volume": {
"value": 0
"productIdentifier": "156830-00-2403",
"quantity": {
"uom": "CTN",
"value": 1
"weight": {
"uom": "LBS",
"value": 37
"volume": {
"value": 0

If any incorrect parameter value is specified, then nothing is returned. For example, if the stopSealNbrparameter value is changed from JEFFto JEFFSthen nothing or [] is returned as there is no stopSealNbr with JEFFS present in the company DEMO.

6.3     Document Retrieval using File GUID

nuDeliverIt Mobile App allows the Carrier/Driver to capture Signature, Image or Signed Documents (BOLs) as part of Load Execution/Delivery of products/goods at Stop(s). A Web Service API is available that can be called to retrieve a specific document for any company by providing the unique identifier assigned to the document by nuDeliverIt and Company Code. Below example demonstrates how to retrieve a sample document and again here for simplicity CURL tool is used to send request and retrieve document information.

> curl –X GET -H "Content-Type:application/octet-stream" -k -u admin:password 'https://www.nuvizzapps.com/nuDeliverIt/webservices/api/document/3cd11644-db8c-4d26-8371-743949573db6/DEMO'

The above command retrieves document associated with the <FILE_GUID> highlighted as bold in above parameter for the company DEMO. Since the result returned is not in a readable format (octet-stream) and the returned value may contain control/special characters that’s not readable the result is not displayed. If the <FILE_GUID> passed is incorrect or not a valid value present in nuDeliverIt portal application, then error message is returned.

6.4     Sample PHP Program

The below sample PHP program gives an idea on how to use PHP program/script to make request to Web Service API(s) call.  Necessary comments have been provided to help one understand the entire flow how to program in PHP. Eventually it calls CURL API to send the Web Service Request and retrieve the result as depicted above in previous 2 sections.

* A sample simple PHP program to make WEB SERVICE Request to
* nuDeliverIt Application
// config.ini file contains necessary configuration information
// like username, password, baseurl, company code etc. the
// fill should be protected and the content may contain as
// follows:
// base.url = "https://nuvizzapps.com"
// company.code = "DEMO"
// username = "admin"
// password = "password"
$configFile = "config.ini";
// Ensure that the file exists, if so parse the file and extract
// all variable name and associated values into configInfo array
if (file_exists($configFile))
$configInfo = parse_ini_file($configFile);
// Assign the Company Code, Base URL, User Name and Password
// what was specified and read from the config.ini file.
$companyCode = $configInfo['company.code'];
$baseUrl = $configInfo["base.url"];
$userName = $configInfo["username"];
$password = $configInfo["password"];
// URL Parameters to be passed to the Web Service API as part
// of the request.
$stopNbr = $_GET['stopNbr'];
$stopSealNbr = $_GET['stopSealNbr'];
// Specify the necessary options to be passed to CURL command
$options = array(
CURLOPT_USERPWD => $userName . ":" . $password,
// Form the full URL request.
$json_url = $baseUrl . '/nuDeliverIt/webservices/api/stop/' . $companyCode . '?stopNbr=' . $stopNbr . '&stopSealNbr=' . $stopSealNbr;
// Initialize the CURL
$ch = curl_init($json_url);
// Set All the optional parameters prior to execution
curl_setopt_array($ch, $options);
// Execute the request to process
$result = curl_exec($ch);

7.   Sample XSD File Formats

nuDeliverIt to Host