Stamps.com API for Python

The Idea

The goal of this API is to provide a thin Python wrapper around the Stamps.com Web Services API. As to why anyone would be generating big W-S APIs in the 21st century? Don't get me started.

This API gives you a flexible configuration mechanism, calls for the more common operations, cached authenticator token, conversation out-of-sync detection, and examples as test cases.

This API depends on Python "Suds" and exerts minimal opinion on the format or results of the Stamps.com operations. In other words, the naming conventions for Suds-based I/O are not Pythonic and are dictated, instead, by the backing WSDL. You'll probably want to extend the API here with your own so you can bury all of the weird syntax under your own version of awesomeness.

The Installation

Simple with pip:

$ pip install stamps.py

Easy with setuptools (but you really shouldn't):

$ easy_install stamps.py

The Interface

These and other public functions are documented in stamps.services.StampsService:

add_postage Add postage to your account so you can start creating labels.

create_* Convenience methods for creating various call objects. In general, these will be bare objects that need to be populated with detail information based on the call you wish to make. See the get_* functions in tests.py for details.

get_account Account information accessor.

get_label Get a shipping label from one address to another based on a given rate.

get_rates Get the available rates for a given shipping object.

get_tracking Get the tracking events for a given label ID.

register_account Register a new account with Stamps.com.

remove_label Cancel a shipping label (triggers a postage refund with Stamps.com).

The Instantiation

The best way to get started is to digest the code in tests.py, which uses a file to initialize a test StampsConfiguration. Below is a simple example that uses the API to retrieve account information. Register with developer.stamps.com to get your own integration ID, username, and password.

from stamps.config import StampsConfiguration
from stamps.services import StampsService

integration_id = "XXXXXXXX-1111-2222-3333-YYYYYYYYYYYY"
username = "stampy"
password = "secret"
configuration = StampsConfiguration(integration_id=integration_id,
    username=username, password=password)
service = StampsService(configuration=configuration)
account = service.get_account()