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|
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.
|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.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.
XML has a node “Function” within the tag “Stop”. The value of this node “Function” determines the action to be taken.
|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.|
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
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.
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|
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.
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
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.
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.).
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.
"origin": "Demo Facility",
"originName": "Demo Delivery",
"originAddr1": "5855 Mountain View Pkwy",
"companyName": "Demo Company",
"address1": "5855 Mountain View Pkwy",
"assignedDriver": "David Shawn"
"shipToName": "RENEW COMPUTER AS",
"shipToAddr1": "STE 1200",
"shipToAddr2": "5060 AVALON RIDGE PKWY",
"billToName": "DEMO PARENT COMPANY",
"billToAddr1": "1770 SATELLITE BLVD",
"earliestStartDttm": "Mar 5, 2015 7:00:00 AM",
"latestStartDttm": "Mar 5, 2015 7:00:00 AM",
"product": "CORR BOXES KDF 12 # PER C",
"product": "PALLET STRETCH WRAP 15PCF",
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.
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.
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
// 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
$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_RETURNTRANSFER => true,
CURLOPT_AUTOREFERER => false,
CURLOPT_HEADER => false,
CURLOPT_HTTPGET => true,
CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
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
// Execute the request to process
$result = curl_exec($ch);