Support Portal

Subscribing to shipment events via SQS

Overview

If you want to subscribe in real time to events happening on your shipments, the solution is to subscribe to our Amazon SQS Queue.

Whenever an event should be created for a shipment, we will send a message to SQS corresponding to this event.

Activation/Deactivation

If you'd like to activate or deactivate the SQS Queue please contact either your key account manager or write an email to service@sevensenders.com.

Connection

Use the SDK from Amazon Web Services. You will need your API-KEY to connect.

API KEY: This information was given to you when you created your Seven Senders account.

PHP Example

This example uses the AWS PHP SDK. For a complete sample see: github.com/SevenSenders/sqs-sample-php

<?php
 
require_once __DIR__.'/vendor/autoload.php';
 
$credentials = [
    'region' => 'eu-central-1',
    'version' => 'latest',
    'endpoint' => 'https://analytics-api.7senders.com/queue.xml',
    'credentials' => [
        'key'    => '<API-KEY>',
        'secret' => '',
   ]
];
 
$client = new \Aws\Sqs\SqsClient($credentials);
 
$result = $client->receiveMessage(['QueueUrl' => '']);

$messages = $result->get('Messages') ?: [];

echo sprintf("Messages in Queue: %d\n", count($messages));

foreach($messages as $message) {
    echo $message['MessageId'] . "\n";
    echo $message['Body'] . "\n";
}

Java Example

This example uses the AWS Java SDK. For a complete sample see: github.com/SevenSenders/sqs-sample-java

package com.sevensenders.samples;

import java.util.List;

import com.amazonaws.AmazonClientException;
import com.amazonaws.AmazonServiceException;
import com.amazonaws.auth.AWSStaticCredentialsProvider;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.client.builder.AwsClientBuilder.EndpointConfiguration;
import com.amazonaws.services.sqs.AmazonSQS;
import com.amazonaws.services.sqs.AmazonSQSClientBuilder;
import com.amazonaws.services.sqs.model.Message;

public class SQSSample {

    public static void main(String[] args) {
        BasicAWSCredentials awsCredentials = new BasicAWSCredentials("your-sevensenders-api-key", "");
        AmazonSQS sqs = AmazonSQSClientBuilder.standard()
                .withCredentials(new AWSStaticCredentialsProvider(awsCredentials))
                .withEndpointConfiguration(new EndpointConfiguration("https://analytics-api.7senders.com.queue.xml", ""))
                .build();

        try {
            System.out.println("Getting Queue URL");
            String queue_url = sqs.getQueueUrl("").getQueueUrl();
            System.out.println("Result: " + queue_url);

            System.out.println("Receiving messages...\n");

            List<Message> messages = sqs.receiveMessage("").getMessages();

            for (Message m : messages) {
                System.out.println(m.getMessageId() + ":");
                System.out.println(m.getBody());
            }

        } catch (AmazonServiceException ase) {
            System.out.println("AmazonServiceException: Your request made it to SQS Proxy, but was rejected");
            System.out.println("Error Message:    " + ase.getMessage());
            System.out.println("HTTP Status Code: " + ase.getStatusCode());
            System.out.println("AWS Error Code:   " + ase.getErrorCode());
            System.out.println("Error Type:       " + ase.getErrorType());
            System.out.println("Request ID:       " + ase.getRequestId());
        } catch (AmazonClientException ace) {
            System.out.println("AmazonClientException: Request failed.");
            System.out.println("Error Message: " + ace.getMessage());
        }
    }
}


Message format

Each message contains a JSON object with properties described below.

Field
Type
Description
id
string
Seven Senders shipment identifier
order_id
string
The order reference inside your system
tracking_code
string
The shipment tracking number from the carrier
carrier
string
Selected carrier to ship the parcel
carrier_country
string
Country where the parcel is handed over to selected carrier / scanned for the first time by the selected carrier
status
string
Current shipment status. Possible values are:
"" (empty string)
New
Info
Pickup
In transit
Out for delivery
Delivery attempt failed
Delivered
Lost
Delivered to pickup point
Hub scan at LMC
Postal return
First scan at LMC

status_time
date (dd.mm.yyyy hh:mm:ss)
Date and time when the current shipment status was set
tickets
array of ticket objects
Deprecated - A list of tickets, related to this milestone:
Field
Type
id
string
name
string
creation_time
date (dd.mm.yyyy hh:mm:ss)
This property will be removed, please use the events property.
events
array of event objects
A list of events, related to this milestone:
Field
Type
name
string
creation_time
date (dd.mm.yyyy hh:mm:ss)

Example Response Body

{
    "id": "s3030665",
    "order_id": "818213398889282",
    "tracking_code": "394024NRETZ7OMZJ4C02XN",
    "carrier": "dhl",
    "carrier_country": "de",
    "status": "Delivered",
    "status_time": "06.08.2017 12:01:08",
    "tickets": [{
        "id": "123456789",
        "name": "Light damage",
        "creation_time": "04.08.2017 10:01:09"
    }],
    "events": [{
        "name": "Light damage",
        "creation_time": "04.08.2017 10:01:09"
    }]
}