Shipment API

API change history

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
ShipmentStatus Int Status of a shipment
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


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

Try it

Request URL

Request parameters

string

Either GUID received when submitting a shipment or submitted Reference

(optional)
number

Desired language of response if applicable. 1: German
2: English
3: French

(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

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

Request body

Response 200

Returned in case of success. Status is returned in ShipmentStatus field. 

{  
   "ShipmentStatus":10,
   "ErrorString":null,
   "Signature": null,
   "Picture": null,
   "DriverComment": null,
   "ProblemCode": null,
   "Latitude": null,
   "Longitude": null,
   "DriverName": null,
   "DriverPicture": null,
   "DeliveryDate": "2016-07-15",
   "DeliveryTimeFrom": "18:20:00Z",
   "DeliveryTimeTo": "18:30:00Z",
   "ExternalReference": "BBF0429D92544CFCABD4",
   "Fee": 4.90
}

Response 404

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

{  
   "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
}

Response 500

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