A Shippo Perl API wrapper
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
lib/WebService
scripts
t
.gitignore
.travis.yml
Changes
Makefile.PL
README.md
README.txt
build_log.txt
dist.ini
sample.png

README.md

Build Status Coverage Status

Shippo API Perl Client

The Shippo API can be used to automate and customize shipping capabilities for your e-commerce store or marketplace, enabling you to retrieve shipping rates, create and purchase shipping labels, track packages, and much more.

Shippo connects you with multiple shipping providers (USPS, UPS and Fedex, for example) through one interface, offering you great discounts on a selection of shipping rates.

You can sign-up for an account at https://goshippo.com/.

While Shippo do offer official API clients for a bevy of major languages, the venerable Perl is not among them. This client is a community offering that attempts to fill that void.

###PRE-RELEASE SOFTWARE

Though functional, this software is still very much in the process of being documented and should therefore be considered a work in progress.

Version

  • 0.0.21 (2015-11-14) on CPAN

Requirements

Perl 5.8.8 minimum.

Build tests have been conducted successfully on all later versions of Perl.

Dependencies

Implementation Testing
boolean
Clone
File::HomeDir
JSON::XS
LWP
LWP::Protocol::https
MRO::Compat
Params::Callbacks
Path::Class
Sub::Util
Time::HiRes
URI::Encode
YAML::XS
Data::Dumper::Concise
Test::Deep

The Shippo API Perl Client depends on the non-core modules listed in the table above.

Testing

Testing is standard operating procedure when installing Perl modules, since test suites must normally complete successfully before a distribution can be installed.

Be aware that, if you attempt to install this distribution without first taking steps to configure Shippo API authentication, the testing phase of installation will be skipped rather than fail. It may still fail if there are more fundamental problems with your Perl environment, but in all likelihood the installation will complete without running all of its tests.

You should probably run those tests.

Before installing the distribution, you should be in possession of a set of Shippo API Authentication Tokens. You can get these by registering for an account—go to https://goshippo.com/register. Once you have your tokens, simply define the SHIPPO_TOKEN environment variable using the Private Auth Token as the value.

For example:

export SHIPPO_TOKEN="1a2b3c4d5e6ff7e8d9c0b1a21a2b3c4d5e6ff7e8"

Now, if you install the module, the tests should run.

Installation

The Shippo API Perl Client is distributed on CPAN:

It is installed like the majority of Perl modules. If you have never installed a Perl module before then I recommend using cpanminus because it's super easy!

If you have never used cpanminus before then you can install this package by running one of the following commands:

sudo -s 'curl -L cpanmin.us | perl - WebService::Shippo'

# If you're developing under PerlBrew then you probably don't want
# to use sudo...

curl -L cpanmin.us | perl - WebService::Shippo

If you have used cpanminus before then one of the following commands will do the job:

sudo -s cpanm WebService::Shippo

# If you're developing under PerlBrew then you probably don't want
# to use sudo...

cpanm WebService::Shippo

Installing from GitHub

Clone this repository only if you need to make changes. The distribution is managed using Dist::Zilla, which will have dependency requirements of its own.

Using the Shippo API Perl Client

use strict;
use WebService::Shippo;

# If it hasn't already done outside of the script, you
# must set your API key...
Shippo->api_key( 'PASTE YOUR PRIVATE AUTH TOKEN HERE' )
    unless Shippo->api_key;

my $address = Shippo::Address->create(
    object_purpose => 'PURCHASE',
    name           => 'John Smith',
    street1        => '6512 Greene Rd.',
    street2        => '',
    company        => 'Initech',
    phone          => '+1 234 346 7333',
    city           => 'Woodridge',
    state          => 'IL',
    zip            => '60517',
    country        => 'US',
    email          => 'user@gmail.com',
    metadata       => 'Customer ID 123456'
);

print 'Success with Address 1 : ', $address

All being well, you should see something like the following output:

Success with Address 1 : {
   "city" : "Woodridge",
   "company" : "Initech",
   "country" : "US",
   "email" : "user@gmail.com",
   "ip" : null,
   "is_residential" : null,
   "messages" : [],
   "metadata" : "Customer ID 123456",
   "name" : "John Smith",
   "object_created" : "2015-10-16T16:14:16.296Z",
   "object_id" : "475bb05d72b74a08a1d44b40ac85d635",
   "object_owner" : "******@*********.***",
   "object_purpose" : "PURCHASE",
   "object_source" : "FULLY_ENTERED",
   "object_state" : "VALID",
   "object_updated" : "2015-10-16T16:14:16.296Z",
   "phone" : "0012343467333",
   "state" : "IL",
   "street1" : "6512 Greene Rd.",
   "street2" : "",
   "street_no" : "",
   "zip" : "60517"
}

For additional integration notes, visit the project wiki pages.

Full API documentation

ACKNOWLEDGEMENTS

Thanks to Ali Saheli and the wonderful folks at Shippo for assistance rendered.

COPYRIGHT

This software is copyright © 2015 by Iain Campbell.

You may distribute this software under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

SUPPORT / WARRANTY

The Shippo API Perl Client is free Open Source software; it comes without warranty of any kind.