Report Service Guide May 7, 2013 PUBLIC DISTRIBUTION DST Systems Electronic Solutions Division 333 W 11th St Kansas City, MO 64105 www.dstsystems.com ePriority Development www.epriority.com

Contents

Introduction

Reports created at ePriority.com may be requested by name through an HTTPS query. If the report uses a batch data source, a batch name or id must also be specified. Errors may occur when bad credentials are supplied or incorrect/incomplete data is given in the report query.

If you have not already done so, you should read the «ePriority Service Overview» before going further with this document as it will provide context for all ePriority features.

HTTP Query

To request a report through an HTTPS query, the following parameters must be supplied:

The following parameters are optional:

It is recommended that you URL-Encode your query string prior to submission.

Authentication

All requests must be secure (HTTPS) and contain the three parameters required for authentication:

1. cid (ePriority Client ID)
2. authDate (authentication date - newly created for each request)
3. authHash (HMAC-SHA256 hexidecimal string)

A Keyed-Hash Message Authentication Code (HMAC), the request signature, is calculated using the Web API Password (secret key) for the supplied Client ID and the value of the authDate parameter as input. Your Project Manager or Client Services Liaison will provide your Web API Password.

The Authentication Date must follow the ISO 8601 format: YYYY-MM-DDThh:mm:ss (eg 1997-07-16T19:20:30)

ex: web api password = pass5239900
    authDate = 1997-07-16T19:20:30
    authHash = SHA256.hexValue( "1997-07-16T19:20:30pass5239900" )

Note that your request will expire 24 hours after creation (UTC) and authentication will fail. This ensures that a valid request cannot be stolen and used indefinitely for other API calls.

Using the Report Service

Once you have created a report, it may be requested through the HTTP service at any time.

Note that the Content-type returned to your application (the HTTP response) with be the same as the output method specified in the <xsl:output> 'method' attribute of your report's XSL Stylesheet.

Batch Report Example

https://www.epriority.com/Reports?
  cid=1234&report=XML_bounce_report&version=1&
  bid=1234567&timezone=US/Eastern&authDate=1997-07-16T19:20:30&
  authHash=a19671a63d786d1314b28f2a58e3c4e8

Line breaks and spaces would not be present in an actual query.

Account Report Example

https://www.epriority.com/Reports?version=1&
  cid=1234&report=statements_profile__report&
  start=2003-12-01&stop=2003-12-17&authDate=1997-07-16T19:20:30&
  authHash=a19671a63d786d1314b28f2a58e3c4e8

Line breaks and spaces would not be present in an actual query.

Error Format

When an error occurs due to invalid query data or credentials, the HTTP response Content-type is 'text/plain' and begins with the word 'ERROR', followed by a text message.

Java Example

import java.io.*;
import java.net.URL;
import java.security.MessageDigest;
import java.text.*;
import java.util.*;

public class epriorityReportReader
{
  public static void main(String[] args) throws Exception
  {
    int cid = 1234;
    String report = "batch_status";
    String version = "1";
    String bid = args[0];

    // authentication values
    SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss");
    sdf.setTimeZone(TimeZone.getTimeZone("Universal"));
    String date = sdf.format(new Date());
    String password = getApiPassword();
    String digestString = date + password;
    MessageDigest md = MessageDigest.getInstance("SHA256");
    byte[] hash = md.digest( digestString.getBytes() );
    String hashHex = asHex( hash );

    // URL class provides encoding
    URL epriority = new URL("https://www.epriority.com/" +
        "Reports?cid=" + cid +
        "&report=" + report +
        "&version=" + version +
        "&authDate=" + date +
        "&authHash=" + hashHex +
        "&bid=" + bid);

    BufferedReader in = new BufferedReader(
      new InputStreamReader(epriority.openStream()));

    String inputLine;

    while ((inputLine = in.readLine()) != null)
    {
      if (inputLine.matches("failed"))
      {
        // do something
      }
    }

    in.close();
  }

  public static final String asHex(byte[] data)
  {
    //double size, two bytes (hex range) for one byte
    StringBuffer buf = new StringBuffer(data.length * 2);

    for (int i = 0; i < data.length; i++)
    {
      //don't forget the second hex digit
      if (((int) data[i] & 0xff) < 0x10)
      {
        buf.append("0");
      }

      buf.append(Long.toString((int) data[i] & 0xff, 16));
    }

    return buf.toString();
  }

}

Perl Example

#!/usr/bin/perl

use Net::SSLeay::Handle qw(shutdown);
use URI::Escape;
use Digest::SHA256 qw(hexhash);
use POSIX qw(strftime);

my $cid = "1234";
my $report = "XML_bounce_report";
my $version = "1";
my $timezone = "US/Central";
my $bid = shift;
my $password = shift;
my $datetime = strftime("%Y-%m-%dT%H:%M:%S", gmtime());
my $auth = hexhash("$datetime$password");

my ($host, $port) = ("www.epriority.com", 443);

tie (*SSL, "Net::SSLeay::Handle", $host, $port);

my $location = uri_escape("/Reports?cid=$cid&&authDate=$datetime&authHash=$auth&" .
   "report=$report&version=$version&bid=$bid&timezone=$timezone";

print SSL "GET $location\r\n\r\n";

shutdown(\*SSL, 1);

while (<SSL>)
{
  /<status>([\w\/]+)<\/status>/ or next;
  if ($1 eq "failed")
  {
    # do something ...
  }
}

close SSL;

Time Zones