...
This guide assumes basic familiarity with USPS. It also assumes the reader is familiar with SOAP, XML and other related technologies.
| Info |
|---|
This documentation applies to both the Classic and Redesign versions of USPS. Except as noted in the document the Redesign and Classic API's of the SOAP services are compatible. |
Glossary
ITC, Information Technology Centers are regional data processing centers that provide computer services to member school districts. Among the services ITCs provide is hosting of the USPS application for school districts.
...
This document is updated routinely to reflect the current version of the USPS SOAP service.
Links to the latest version of this document can be obtained from the SSDT Public Wiki site at:http https://wikimcoecn.ssdt.oecn.k12.oh.us/index.php?title=USPS_SOAP_Developers_Guideatlassian.net/wiki/x/_AYm
Resources
This document does not represent the complete documentation for the USPS SOAP service. The actual API documentation is contained in the WSDL, the USPS XML Schema and the OECN RPC XML schema. These documents are available from the the actual installation of the USPS SOAP service. Developers can find the current development version of the documents at: http://devel.ssdt.nwoca.org/uspssoap/
...
To view a list of changes made to the USPS XML Schema for version 1.6 onward of the USPS SOAP service, view the Updates to USPS XML Schema page.
usps-42.xsd
UspsWebService.wsdl
Status of the USPS SOAP Service
...
District Database Identification
For Classic USPS a single SOAP service endpoint is used to access all district databases at an ITC. Each unique database is identified by a “district code” "district code" or IRN. Some ITCs ITC's also support the use of NCES codes to identify district databases. After a SOAP client authenticates with the SOAP service, it must declare the district database on which it intends to operate. Alternatively, the SOAP client may query the service for the databases the user has access to and allow the user to select the district code.
SOAP Service Endpoints
Each ITC that supports the USPS SOAP service will provide one or more “SOAP endpoint” URLs For Redesign USAS, a separate endpoint is used for each district. In Redesign implementations of the SOAP service, the setDistrictAccess operation is a NOOP and is not necessary.
SOAP Service Endpoints
Each ITC that supports the Classic USAS SOAP service will provide one “SOAP endpoint” URL's for accessing the service for their districts. In most cases, a single endpoint will be used for all districts hosted by a given ITC Site. However, in some cases, an ITC may provide a different endpoint for specific districts.
Most ITCs For Redesign USAS SOAP, a separate endpoint will be provided for each school district.
ITC's will provide an HTTPS (SSL) end-point can be used to encrypt SOAP messages on the wire. Developers are encouraged required to use HTTPS when available. Each ITC decides whether HTTPS is available or required and may have other local security policies regarding from what networks SOAP connections are available.
...
for production instances.
Authentication and Authorization
When a client connects to the service, it must provide username and password credentials for an account on the ITC server. Usernames and access rights are administered by the ITC on behalf of the member district. Rights granted by the ITC and any USPS security profiles established by the district limit the access rights and functions the account can perform.
...
- Invoke _login _operation with credentials for an account on the USPS server
- Optional: Invoke _getDistrictList _to return a list of districts the user can access
- Optional for Redesign: Invoke _setDistrictAccess _to bind the session to a given district database
...
It is important that the client invoke setDistrictAccess code to establish the district database to which the session is bound. This must be done exactly once after login and prior to any other USPS operation.{{
...
|
|---|
A client must not invoke _setDistrictAccess _more than once for a session. A fault will be returned if such an attempt is made and the session will be left in an indeterminate state. Client applications that need to access more than one district, must establish at least one session for each district. |
...
Session Timeout
Sessions consume resources on both the SOAP server and the back-end USPS server. Therefore, inactivity timeouts apply to the SOAP sessions. The timeout interval is configurable by each ITC and defaults to approximately 45 minutes. If there is no activity for a session during the timeout interval, the session will be deleted from the SOAP service. Any subsequent invocations using an expired sessionId will result in a fault being returned. Client applications that attempt to maintain long running connections, must be prepared to handle such faults.
...
...
Assume the ITC has established a resource archive called "W2" which contains archives of PDF W2 Forms by employee for multiple tax years. The following are valid requests and the like responses:
| Wiki Markup |
|---|
{table:border=1}
{tr}
{th}You type {th}
{th}Looks like{th}
{tr}
{tr}
{td:valign=top}
~UWC| HTML Table |
|---|
|
| Table Row (tr) |
|---|
| Table Head (th) |
|---|
| Looks like |
|
| Table Row (tr) |
|---|
| Table Cell (td) |
|---|
| UWC_TOKEN_START~1292862896731~UWC_TOKEN_ |
|
END~
{td}
{td}
{td}
{tr}
{tr}
{td:valign=top}
Or with line numbering:
~UWC
| Table Row (tr) |
|---|
| Table Cell (td) |
|---|
| Or with line numbering:
UWC_TOKEN_START~1292862896732~UWC_TOKEN_ |
|
END~
{td}
{td}
{table:border=1}
{tr}
{th}Request{th}
{th}Response{th}
{tr}
{tr}
{td}
| Table Cell (td) |
|---|
| /resource/W2?employee.id=EMP0001&tax.year=2008 |
{td}
{td}
| Table Cell (td) |
|---|
| Content-type: |
{td}
{tr}
{tr}
{td}
| Table Cell (td) |
|---|
| /resource/W2?employee.id=EMP0001&tax.year=4008 |
{td}
{td}HTTP 404 Response (not found){td}
{tr}
{tr}
{td:valign=top}
| Table Cell (td) |
|---|
| HTTP 404 Response (not found) |
| Table Cell (td) |
|---|
| | /resource/W2?employee.id=EMP0001&tax.year= |
\{td}
{td}Returns all
| Table Cell (td) |
|---|
Returns all URL's |
{}
[]
[]
.
{panel}
{td}
{tr}
{tr}
{td:valign=top}
| Table Cell (td) |
|---|
| | /resource/W2?employee.id=*&tax.year=2008 |
{td}
{td}Returns all
| Table Cell (td) |
|---|
Returns all URL's |
{}
[]
[]
[]
[]
.
{panel}
{td}
{tr}
{table} |
| Wiki Markup |
|---|
| {table:border=1}
{th}{th}
{th}Footnotes{th}
{tr}
{td}1{td}
{td}WS-I is a trademark of the Web Services-Interoperability Organization in the United States and other countries.{td}
{tr}
{table}
|
| HTML Table |
|---|
|
| Table Row (tr) |
|---|
| Table Cell (td) |
|---|
| WS-I is a trademark of the Web Services-Interoperability Organization in the United States and other countries. |
|
|