Shipment API

REST JSON interface that exposes methods related to:

Submitting a shipment to the notime platfom
Checking a shipment's status
Cancelling a shipment
Updating shipment parameters after submission

2. Get Shipment Status

This method is used in order to retrieve the status of a shipment.
Shipments must be sent to the platform via the method Submit Shipment
On successfully submitting a shipment to our platform the system returns a unique identifier for the shipment (shipment GUID). When asking for the shipment status , use this ID as the first parameter of the call.
In addition to polling for status information via this method, our platform supports the pushing of status and other shipment related information via our in built communication system. Please contact us on info@notime.eu for more information.

The following object is sent back:

Name	Type	Description
Status	Int	Status of a shipment
StatusString	String	Status name
LastStatusUpdate	UTC Date time string (YYYY-MM-DDTHH:MM:SSZ)	When status was changed the last time
ErrorString	String	Error description
Signature	String	The URL of signature in case we have one
Picture	String	The URL of picture from last problem report
DriverComment	String	Text of driver comment from last problem report
ProblemCode	Int	Problem code from last problem report
Latitude	double	Latitude of driver. It's returned if driver is on route (StatusCode equals to either 70 or 90)
Longitude	double	Longitude of driver. It's returned if driver is on route (StatusCode equals to either 70 or 90)
DriverName	String	Name of driver, in case the shipment is already allocated
DriverPicture	String	The URL of the driver picture
DeliveryDate	UTC Date String (YYYY-MM-DD)	Shipment delivery date
DeliveryTimeFrom	UTC time string (HH:MM:SSZ)	Shipment delivery time from
DeliveryTimeTo	UTC time string (HH:MM:SSZ)	Shipment delivery time to
Dropoff	POI	The dropoff location
ExternalReference	String	The customer's Reference which has been provided in the method Submit Shipment
Fee	double	Total fee of the shipment
ClusterPoint	String	Cluster point code, in case the shipment is related to one
TourLetter	String	Tour letter, in case the shipment is allocated to a tour
StopNumber	Int	Stop number, in case the shipment is allocated to a tour

POI

Name	Type	Description
Reference	String	Identier of the object which was provided or autogenerated
Name	String	Name of the organization that is located at this POI, or the name of the person
ContactName	String	Name of the contact person
StreetAddress	String
PostCode	String
City	String
CountryCode	String	Country code e.g. "CH", "DE", "FR", "AT"
Phone	String	Main phone number
Phone2	String	Additional phone number. This number is given to the courier and operation manager in case the POI's contact is not reachable otherwise
Phone3	String	Additional phone number. This number is given to the courier and operation manager in case the POI's contact is not reachable otherwise
ContactEmailAddress	String	Email address under which the recipient can be contacted
Note	String	Freetext message that assist the courier in finding the location

Response example:

Try it

Request

Request URL

https://v1.notimeapi.com/api/shipment/{shipmentId}/status[?languageId][&groupGuid]

Request parameters

shipmentId

string

Either GUID received when submitting a shipment or submitted Reference
languageId (optional)

number

Desired language of response if applicable. 1: German
2: English
3: French
groupGuid (optional)

string

Guid identifying your shipper account. It should be submitted only if shipment reference is passed in shipmentId parameter. For testing purposes use the ID: 28228CFE-12F2-4BFB-B8BF-B7FF87746E96. Your account manager will provide you with your ID before going into production.

Request headers

Ocp-Apim-Subscription-Key

string

Subscription key which provides access to this API. Found in your Profile.

Request body

Responses

200 OK

Returned in case of success. Status is returned in ShipmentStatus field. Response example: </label

Representations

application/json

{
  "ShipmentStatus": 10,
  "ErrorString": null,
  "Signature": null,
  "Picture": null,
  "DriverComment": null,
  "ProblemCode": null,
  "Latitude": null,
  "Longitude": null,
  "DriverName": null,
  "DriverPicture": null,
  "DeliveryDate": "2016-07-15T00:00:00.0000000+00:00",
  "DeliveryTimeFrom": "2020-01-22T18:20:00.0000000+00:00",
  "DeliveryTimeTo": "2020-01-22T18:30:00.0000000+00:00",
  "ExternalReference": "BBF0429D92544CFCABD4",
  "Fee": 4.9,
  "ClusterPoint": "ZH1",
  "TourLetter": "YE",
  "StopNumber": 2
}

404 Not Found

Returned in case if specified shipment is not found. Reason phrase is specified as 'Shipment with id = [guid] not found'. Response example:

Representations

application/json

{
  "ShipmentStatus": null,
  "ErrorString": "Entity not found",
  "Signature": null,
  "Picture": null,
  "DriverComment": null,
  "ProblemCode": null,
  "Latitude": null,
  "Longitude": null,
  "DriverName": null,
  "DriverPicture": null,
  "DeliveryDate": null,
  "DeliveryTimeFrom": null,
  "DeliveryTimeTo": null,
  "ExternalReference": null,
  "Fee": null,
  "ClusterPoint": null,
  "TourLetter": null,
  "StopNumber": null
}

500 Internal Server Error

Returned in case of internal server error. Specific error might be specified in status string. General status string is Internal Server Error

Code samples

@ECHO OFF

curl -v -X GET "https://v1.notimeapi.com/api/shipment/{shipmentId}/status?languageId=1&groupGuid={string}"
-H "Ocp-Apim-Subscription-Key: {subscription key}"

--data-ascii "{body}"

using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;

namespace CSHttpClientSample
{
    static class Program
    {
        static void Main()
        {
            MakeRequest();
            Console.WriteLine("Hit ENTER to exit...");
            Console.ReadLine();
        }
        
        static async void MakeRequest()
        {
            var client = new HttpClient();
            var queryString = HttpUtility.ParseQueryString(string.Empty);

            // Request headers
            client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

            // Request parameters
            queryString["languageId"] = "1";
            queryString["groupGuid"] = "{string}";
            var uri = "https://v1.notimeapi.com/api/shipment/{shipmentId}/status?" + queryString;

            var response = await client.GetAsync(uri);
        }
    }
}

// // This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class JavaSample 
{
    public static void main(String[] args) 
    {
        HttpClient httpclient = HttpClients.createDefault();

        try
        {
            URIBuilder builder = new URIBuilder("https://v1.notimeapi.com/api/shipment/{shipmentId}/status");

            builder.setParameter("languageId", "1");
            builder.setParameter("groupGuid", "{string}");

            URI uri = builder.build();
            HttpGet request = new HttpGet(uri);
            request.setHeader("Ocp-Apim-Subscription-Key", "{subscription key}");


            // Request body
            StringEntity reqEntity = new StringEntity("{body}");
            request.setEntity(reqEntity);

            HttpResponse response = httpclient.execute(request);
            HttpEntity entity = response.getEntity();

            if (entity != null) 
            {
                System.out.println(EntityUtils.toString(entity));
            }
        }
        catch (Exception e)
        {
            System.out.println(e.getMessage());
        }
    }
}

<!DOCTYPE html>
<html>
<head>
    <title>JSSample</title>
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>

<script type="text/javascript">
    $(function() {
        var params = {
            // Request parameters
            "languageId": "1",
            "groupGuid": "{string}",
        };
      
        $.ajax({
            url: "https://v1.notimeapi.com/api/shipment/{shipmentId}/status?" + $.param(params),
            beforeSend: function(xhrObj){
                // Request headers
                xhrObj.setRequestHeader("Ocp-Apim-Subscription-Key","{subscription key}");
            },
            type: "GET",
            // Request body
            data: "{body}",
        })
        .done(function(data) {
            alert("success");
        })
        .fail(function() {
            alert("error");
        });
    });
</script>
</body>
</html>

#import <Foundation/Foundation.h>

int main(int argc, const char * argv[])
{
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
    
    NSString* path = @"https://v1.notimeapi.com/api/shipment/{shipmentId}/status";
    NSArray* array = @[
                         // Request parameters
                         @"entities=true",
                         @"languageId=1",
                         @"groupGuid={string}",
                      ];
    
    NSString* string = [array componentsJoinedByString:@"&"];
    path = [path stringByAppendingFormat:@"?%@", string];

    NSLog(@"%@", path);

    NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
    [_request setHTTPMethod:@"GET"];
    // Request headers
    [_request setValue:@"{subscription key}" forHTTPHeaderField:@"Ocp-Apim-Subscription-Key"];
    // Request body
    [_request setHTTPBody:[@"{body}" dataUsingEncoding:NSUTF8StringEncoding]];
    
    NSURLResponse *response = nil;
    NSError *error = nil;
    NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];

    if (nil != error)
    {
        NSLog(@"Error: %@", error);
    }
    else
    {
        NSError* error = nil;
        NSMutableDictionary* json = nil;
        NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
        NSLog(@"%@", dataString);
        
        if (nil != _connectionData)
        {
            json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
        }
        
        if (error || !json)
        {
            NSLog(@"Could not parse loaded json with error:%@", error);
        }
        
        NSLog(@"%@", json);
        _connectionData = nil;
    }
    
    [pool drain];

    return 0;
}

<?php
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
require_once 'HTTP/Request2.php';

$request = new Http_Request2('https://v1.notimeapi.com/api/shipment/{shipmentId}/status');
$url = $request->getUrl();

$headers = array(
    // Request headers
    'Ocp-Apim-Subscription-Key' => '{subscription key}',
);

$request->setHeader($headers);

$parameters = array(
    // Request parameters
    'languageId' => '1',
    'groupGuid' => '{string}',
);

$url->setQueryVariables($parameters);

$request->setMethod(HTTP_Request2::METHOD_GET);

// Request body
$request->setBody("{body}");

try
{
    $response = $request->send();
    echo $response->getBody();
}
catch (HttpException $ex)
{
    echo $ex;
}

?>

########### Python 2.7 #############
import httplib, urllib, base64

headers = {
    # Request headers
    'Ocp-Apim-Subscription-Key': '{subscription key}',
}

params = urllib.urlencode({
    # Request parameters
    'languageId': '1',
    'groupGuid': '{string}',
})

try:
    conn = httplib.HTTPSConnection('v1.notimeapi.com')
    conn.request("GET", "/api/shipment/{shipmentId}/status?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

headers = {
    # Request headers
    'Ocp-Apim-Subscription-Key': '{subscription key}',
}

params = urllib.parse.urlencode({
    # Request parameters
    'languageId': '1',
    'groupGuid': '{string}',
})

try:
    conn = http.client.HTTPSConnection('v1.notimeapi.com')
    conn.request("GET", "/api/shipment/{shipmentId}/status?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

require 'net/http'

uri = URI('https://v1.notimeapi.com/api/shipment/{shipmentId}/status')

query = URI.encode_www_form({
    # Request parameters
    'languageId' => '1',
    'groupGuid' => '{string}'
})

if uri.query && uri.query.length > 0
    uri.query += '&' + query
else
    uri.query = query
end

request = Net::HTTP::Get.new(uri.request_uri)
# Request headers
request['Ocp-Apim-Subscription-Key'] = '{subscription key}'
# Request body
request.body = "{body}"

response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
    http.request(request)
end

puts response.body