Support Portal

Welcome
Login

Subscribing to shipment events via SQS

Overview

If you want to subscribe in real time to status and events happening during the life-cycle of your shipments, the solution is to subscribe to our Amazon SQS Queue.

Whenever an event/status is created for a shipment, we will send a message to SQS corresponding to this event.

A status describes a state in which the order /shipment is on a high level. It displays the key information for the customer. Events are happening on a more detailed level. Multiple events can happen meanwhile the order/ shipment is in a certain status. There are events initiating a status switch and some that do not come with a status change. Consequently, the status field is not necessarily be completed.

A detailed list with all events and status can be found here

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());
        }
    }
}


Python Example

This example uses Boto3. For a complete sample see: github.com/SevenSenders/sqs-sample-python.
import boto3

sqs = boto3.client(
    'sqs',
    region_name='eu-central-1',
    endpoint_url='https://analytics-api.7senders.com/queue.xml',
    aws_access_key_id='your-7s-api-key-here', # 7S Shop API Key
    aws_secret_access_key='', # Keep it blank
)

queue_url = sqs.get_queue_url(QueueName='').get('QueueUrl')
print('Queue URL: {}'.format(queue_url))

response = sqs.receive_message(QueueUrl='')
messages = response.get('Messages')
print('Messages in Queue: {}'.format(len(messages)))

for message in messages:
    message_id = message.get('MessageId')
    body = message.get('Body')

    print('{}: {}'.format(message_id, body))

.NET Example

This example uses the AWS .NET SDK. For a complete sample see: https://github.com/SevenSenders/sqs-sample-dotnet

Task.Run(async () => {
    var credentials = new BasicAWSCredentials("<API-KEY>", "---");
    var config = new AmazonSQSConfig {
        ServiceURL = "https://analytics-api.7senders.com"
    };

    var client = new AmazonSQSClient(credentials, config);

    var receiveMessageRequest = new ReceiveMessageRequest {
        QueueUrl = "https://analytics-api.7senders.com/queue.xml",
        MaxNumberOfMessages = 10
    };

    var response = await client.ReceiveMessageAsync(receiveMessageRequest);
    var messages = response.HttpStatusCode == HttpStatusCode.OK ? response.Messages : new List<Message>();
    
    foreach (var message in messages) {
        Console.WriteLine("Message ID: " + message.MessageId);
        Console.WriteLine(message.Body + "\n\n");
        
    }
})
.GetAwaiter()
.GetResult();



Message format

Each message contains a JSON object with the properties described below.

FieldTypeDescription
idstringSeven Senders shipment identifier
order_idstringThe order reference inside your system
tracking_codestringThe shipment tracking number from the carrier
carrierstringSelected carrier to ship the parcel
carrier_countrystringCountry where the parcel is handed over to selected carrier / scanned for the first time by the selected carrier
statusstringCurrent 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_timedate (dd.mm.yyyy hh:mm:ss)Date and time when the current shipment status was set
ticketsarray of ticket objectsDeprecated - A list of tickets, related to this milestone:
FieldType
idstring
namestring
creation_timedate (dd.mm.yyyy hh:mm:ss)
This property will be removed, please use the events property.
eventsarray of event objectsA list of events, related to this milestone:
FieldType
namestring
creation_timedate (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"
    }]
}