SCAN API

 

 

USPS Web Tools™

Application Programming Interface

User’s Guide

 

 

Document Version 2.9 (02/19/2019)

 

 

 

 

 

 

 

 

 


 


Contents

Introduction to Web Tools. 3

Before you get started: 3

USPS SCAN API 3

Overview.. 3

API Signature. 3

Tag Descriptions. 3

Sample Requests. 6

Error Responses. 7

Appendix A – Error Codes. 9

 


Introduction to Web Tools

This document contains a Reference Guide to the SCAN API.  See the Developer’s Guide to Web Tools APIs to learn the administrative process for gaining access to the Web Tools APIs as well as the basic mechanism for calling the APIs and processing the results.  The Developer’s Guide also contains information on testing and trouble-shooting.

 

Note: The Request Parameter sections present the XML input tags for generating live requests along with the restrictions on the values allowed. An error message will be returned if an incorrect value is entered.  Also, be aware of the maximum character amounts allowed for some tags.  If the user enters more than those amounts, an error will not be generated. The Web Tool will simply pass in the characters up to the maximum amount allowed and disregard the rest.  This is important since the resulting value could prevent a correct response.

 

When building the XML request, pay particular attention to the order and case for tags.  An error message will be returned if an incorrect value is entered.  Remember that all data and attribute values in this document are for illustration purposes and are to be replaced by your actual values.  For instance, a line of sample code may be:

 

<ZipDestination>12345</ZipDestination>

 

In this instance, you will replace “12345” with the destination ZIP Code for the domestic-bound package

Before you get started:

Please refer to the Getting Started section of the Web Tools Developer page for instructions on registering with Web Tools at usps.com/webtools

USPS SCAN API

Overview

The SCAN API allows integrators to consolidate multiple domestic and international labels and custom forms through one Electronic File Number (efile).

 

The API operates in two parts:

  1. The SCAN API eligible WebTools user creates valid, live labels using WebTools domestic and international label APIs, setting the HoldForManifest request tag to “Y”.  More information on available label APIs can be found on the WebTools documentation website.
  2. A SCAN API request is submitted. There are several ways the SCAN request may be submitted
    1. With the held PICs populated in the SCAN API request XML.  This will produce a SCAN form with the specified PICs
    2. With the <CloseManifest> tag. The <CloseManifest> tag allows for two options:

                                                               i.      “ALL” – Include all PICs for the USERID submitted regardless of the SHIPDATE on the held PICs.

                                                             ii.      “SHIPDATE” – Include all PICS for the USERID submitted on the request for the specified date in the <MAILDATE> tag.

 

There are some rules to label grouping compatibility in the SCAN API:

  1. The manifested labels must have been previously created and “held” when created.
  2. The label mailing dates must be the same across label and SCAN API requests except for requests with <CloseManifest> tag with the “ALL” value.
  3. The manifest file formats for the labels must be identical.

API Signature

Scheme

Host

Path

API

XML

Test

https://

stg-secure.shippingapis.com

/ShippingAPI.dll

?API=SCAN

Test

https://

stg-secure.shippingapis.com

/ShippingAPI.dll

?API=SCANCertify

Production

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=SCAN

Production

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=SCANCertify

Tag Descriptions

Request Parameters

Tag Name

Occurs

Description

Type

Validation

SCANRequest

required once

API=SCAN

(group)

 

SCANRequest / @USERID

required

This attribute specifies your Web Tools ID. See the Developer's Guide for information on obtaining your USERID. 

NMTOKEN

 

SCANRequest / Option

optional

Groups form information

(group)

 

SCANRequest / Option / Form

optional

Designates desired label option selected by customer.  Enter one of the valid entries:

‘3152’ generates PS Form 3152.

‘5630’ generates PS Form 5630.

For example: <Form>3152</Form>

string

enumeration=3152

enumeration=5630

SCANRequest / Revision

optional

This is for versioning of the API's and for triggering response tags for future versions.  For future use.

string

minLength=0

pattern=\d{1}

SCANRequest / FromName

required once

Name of sender.

For example: <FromName>Joe Smith</FromName>

string

 

SCANRequest / FromFirm

optional

Company name.

For example: <FromFirm>ABC Corp.</FromFirm>

string

 

SCANRequest / FromAddress1

required once

From address line 1.  Denote apartment or suite number.

For example: <FromAddress1>Apt. 3C</FromAddress1>

string

 

SCANRequest / FromAddress2

required once

From address line 2.  Denote street/structure number.

For example: <FromAddress2>475 L’Enfant Plaza SW</FromAddress2>

string

 

SCANRequest / FromCity

required once

From city.

For example: <FromCity>Greenbelt</FromCity>

string

 

SCANRequest / FromState

required once

From state.

For example: <FromState>MD</FromState>

string

 

SCANRequest / FromZip5

required once

From ZIP Code.  Must be a valid ZIP5 Code.

For example: <FromZip5>20770</FromZip5>

string

 

SCANRequest / FromZip4

required once

From ZIP Code+4.

For example: <FromZip4>1234</FromZip4>

string

 

SCANRequest / Shipment

optional, mutually exclusive with the <CloseManifest> tag

Groups shipment information

(group)

 

SCANRequest / Shipment / PackageDetail

optional, repeating up to unbounded times

Groups package detail information

(group)

 

SCANRequest / Shipment / PackageDetail / PkgBarcode

required once

Individual package PICs. Unlimited number of package barcodes can be requested.

For example: <PkgBarcode>42020260910180521390702413570

</PkgBarcode>

string

 

SCANRequest / Shipment / PackageDetail / SpecialService

optional, repeating up to unbounded times

FOR FUTURE USE. Groups extra service information.

(group)

 

SCANRequest / Shipment / PackageDetail / SpecialService / SpcServCode

required once

FOR FUTURE USE. If present, must be <SpcServFee>.  From Extra Service Code table.

For example: <SpcServCode>01</SpcServCode>

string

 

SCANRequest / Shipment / PackageDetail / SpecialService / SpcServFee

required once

FOR FUTURE USE. Fee for Extra Service.

For example: <SpcServFee>00275</SpcServFee>

string

 

SCANRequest / Shipment / PackageDetail / EMail

optional

FOR FUTURE USE. Email address of acceptance scan event recipient.

For example: <EMail>john.smith@abc.com</EMail>

string

 

SCANRequest/CloseManifest

optional, mutually exclusive with the <Shipment> tag

Used to include all PICs for the submitted UserID. There are two values: “ALL” will close all PICs for the submitted USERID. “SHIPDATE” will close all PICs for the submitted USERID that have the Shipdate matching the value in the MAILDATE tag.

 

 

SCANRequest / MailDate

required once

Date of mailing/Carrier Pickup.  This denotes date mail to be tendered to Postal Service.  YYYYMMDD format.

For example: <MailDate>20060103</MailDate>

MailDate may not be submitted in conjunction with the CloseManifest tag.

 

MailDate must be submitted when CloseManifest tag is submitted with the value of “SHIPDATE”.

string

 

SCANRequest / MailTime

required once

Time of mailing/Carrier Pickup.  This is an approximation.  This denotes time of mail to be tendered to Postal Service.  HHMMSS (24 hour) format.

For example: <MailTime>143000</MailTime>

string

 

SCANRequest / EntryFacility

required once

ZIP Code of Postal Service facility.  Populate/required only if different from <FromZip5>.

For example: <EntryFacility>07067</EntryFacility>

string

 

SCANRequest / ImageType

required once

The form image format desired.  Enter one of the valid entries:

"TIF"

"PDF"

“NONE”

For example: <ImageType>TIF</ImageType>

string

enumeration=TIF

enumeration=PDF

enumeration=NONE

SCANRequest / CustomerRefNo

optional

Arbitrary number for customers own tracking or inventory systems, does not print to form or manifest with Product Tracking.  May be any combination of alpha and numeric characters, up to a maximum of 30. 

For example:<CustomerRefNo>123456</CustomerRefNo>

string

 

SCANRequest / CarrierPickup

optional

FOR FUTURE USE.

boolean

Default=false

 

Note: whiteSpace=collapse processing is currently limited to trimming leading and trailing spaces.

 

 


Response Parameters

Tag Name

Occurs

Description

Type

SCANResponse

required once

 

(group)

SCANResponse / SCANFormNumber

required, repeating up to 20 times

Electronic File Number

integer

SCANResponse / SCANFormImage

required, repeating up to 20 times

Encoded image of PS Form 3152 or PS Form 5630.  

base64Binary

 

 

 

Sample Requests

Test XML Request with PICs specified:

http://production.shippingapis.com/ShippingAPITest.dll?API=SCAN&XML=<SCANRequest USERID="xxx">

   <Option>

      <Form>5630</Form>

   </Option>

   <FromName>John Doe</FromName>

   <FromFirm>United States Postal Service</FromFirm>

   <FromAddress1></FromAddress1>

   <FromAddress2>475 L’Enfant Plaza SW, Room 1546</FromAddress2>

   <FromCity>Washington</FromCity>

   <FromState>DC</FromState>

   <FromZip5>20260</FromZip5>

   <FromZip4>1234</FromZip4>

   <Shipment>

      <PackageDetail>

         <PkgBarcode>LJ019027504US</PkgBarcode>

      </PackageDetail>

   </Shipment>

   <MailDate>20120719</MailDate>

   <MailTime>080501</MailTime>

   <EntryFacility>20260</EntryFacility>

   <ImageType>TIF</ImageType>

   <CustomerRefNo>123XYZ</CustomerRefNo>

</SCANRequest>

 

Test XML Response with PICs specified:

<SCANResponse>

     <SCANFormNumber>CS201009141406094670660949S</SCANFormNumber>

     <SCANFormImage>SUkqAAgAAAASAP4ABAABAAAAAAAAAAABBAABAAAArgYAAAEBBA…

      <!--65255 skipped-->

     </SCANFormImage>

</SCANResponse>

Test XML Request with <CloseManifest> tag specified:

 

https://secure.shippingapis.com/ShippingAPITest.dll?API=SCAN&XML=<SCANRequest USERID="xxx">

   <Option>

      <Form>5630</Form>

   </Option>

   <FromName>John Doe</FromName>

   <FromFirm>United States Postal Service</FromFirm>

   <FromAddress1></FromAddress1>

   <FromAddress2>475 L’Enfant Plaza SW, Room 1546</FromAddress2>

   <FromCity>Washington</FromCity>

   <FromState>DC</FromState>

   <FromZip5>20260</FromZip5>

   <FromZip4>1234</FromZip4>

   <CloseManifest>ALL</CloseManifest>

   <MailDate>20120719</MailDate>

   <MailTime>080501</MailTime>

   <EntryFacility>20260</EntryFacility>

   <ImageType>TIF</ImageType>

   <CustomerRefNo>123XYZ</CustomerRefNo>

</SCANRequest>

 

Test XML Response with <CloseManifest> tag specifed:

<SCANResponse>

     <SCANFormNumber ShipDate=”02/07/2012” EntryZipCode=”20260”>CS201009141406094670660949S</SCANFormNumber>

     <SCANFormImage ShipDate=”02/07/2012” EntryZipCode=”20260”>SUkqAAgAAAASAP4ABAABAAAAAAABBAABAAAArgYAAAEBBA…

      <!--65255 skipped-->

     </SCANFormImage>

</SCANResponse>

Error Responses

Error conditions are handled at the main XML document level.  When parsing, it is best to check for an error document first before checking for good data.  Error documents have the following format:

<Error>

<Number></Number>

<Source></Source>

<Description></Description>

<HelpFile></HelpFile>

<HelpContext></HelpContext>

</Error>

Where:

·       Number = the error number generated by the Web Tools server.

·       Source = the component and interface that generated the error on the Web Tools server.

·       Description = the error description.

·       HelpFile = [reserved for future use].

·       HelpContext = [reserved for future use].

Errors that are further down in the hierarchy also follow the above format.

An <Error> element may be returned at the top (response) level if there is a problem with the syntax of the request, or if a system error occurs.

 

Please see Appendix A for a list of error codes.

 

If you need assistance with an error response, contact the Web Tools team at WebTools@usps.com

 


 

 

Tagged PS Form 3152 Diagram

Tagged PS Form 5630 Diagram

Appendix A – Error Codes

Error Code

Error Message

-2147218001

Invalid ImageType.

-2147217991

Invalid value for EntryFacility

-2147217990

Invalid value for FromZip5

-2147217989

Invalid value for FromZip4

-2147217993

Invalid value for MailDate

-2147217992

Invalid value for MailTime

-2147217987

Invalid value for PkgBarcode

-2147217994

Total PackageDetail items exceeded

-2147217995

Must have at least 1 PackageDetail

-2147217999

Missing value for FromCity

-2147218000

Missing value for FromName

-2147217998

Missing value for FromState

-2147218002

Missing value for ImageType

-2147217997

Missing value for MailDate

-2147217996

Missing value for MailTime

-2147217988

Missing value for FromZip5 and EntryFacility

-2147217986

Invalid value for Form.

-2147217985

Invalid value specified for CarrierPickup. If specified, CarrierPickup must be true or false.

-2147217984

Invalid Mix of Packages

-2147217983

Master MID not found for User

-2147217982

Invalid value for CloseManifest. Valid values are 'ALL' and 'SHIPDATE'.

-2147217981

MailDate not allowed when CloseManifest contains 'ALL'.

-2147217979

EntryFacility not allowed with CloseManifest tag.

-2147217978

No Packages found for CloseManifest request.

-2147217977

PkgBarcode(s) specified with EntryZip code(s) that do not match EntryFacility (%ENTRYFACILITY%) in the SCAN request.  Out of %TotalBarcodes% barcode(s) submitted %ErrorBarcodes% did not match EntryFacility in the SCAN request. Failed PkgBarcode (EntryZip) are as follows:

-2147220103

Error generating barcode image.

-2147220102

Error encoding label into base 64

-80040B1A

This API requires the use of SSL