NAME
WebService::GoShippo - A simple client to Shippo's REST API.
VERSION
version 0.0002
SYNOPSIS
use WebService::GoShippo;
my $shippo = WebService::GoShippo->new(token => 'XXXXXXXXXXxxxxxxxxxxxx', version => '2018-08-28');
my $addresses = $shippo->get('addresses');DESCRIPTION
A light-weight wrapper for Shippo's RESTful API (an example of which can be found at: https://goshippo.com/docs/reference). This wrapper basically hides the request cycle from you so that you can get down to the business of using the API. It doesn't attempt to manage the data structures or objects the web service interfaces with.
The module takes care of all of these things for you:
- Adding authentication headers
-
WebService::GoShippoadds an authentication header of the type "Authorization:$tj->token" to each request. - Adding api version number to request header.
-
WebService::GoShippocan optionally add a header selecting a particular version of the API$tj->versionto each request you submit. If you do not request a particular API version, then Shippo will use the version specified in your account settings. - PUT/POST data translated to JSON
-
When making a request like:
$tj->post('customers', { customer_id => '27', exemption_type => 'non_exempt', name => 'Andy Dufresne', });The data in POST request will be translated to JSON using <JSON::to_json> and encoded to UTF8.
- Response data is deserialized from JSON and returned from each call.
EXCEPTIONS
All exceptions in WebService::GoShippo are handled by Ouch. A 500 exception "Server returned unparsable content." is returned if Shippo's server returns something that isn't JSON. If the request isn't successful, then an exception with the code and response and string will be thrown.
METHODS
The following methods are available.
new ( params )
Constructor.
- params
-
A hash of parameters.
- token
-
Your token for accessing Shippo's API. Required.
- version
-
The version of the API that you are using, like '2018-02-08', '2017-08-01', etc. Optional. If this is left off, then the version setup in your account will be used.
- debug_flag
-
Just a spare, writable flag so that users of the object should log debug information, since GoShippo will likely ask for request/response pairs when you're having problems. Hint hint.
my $sales_tax = $taxjar->get('taxes', $order_information); if ($taxjar->debug_flag) { $log->info($taxjar->last_response->request->as_string); $log->info($taxjar->last_response->decoded_content); } - agent
-
A LWP::UserAgent compliant object used to keep a persistent cookie_jar across requests. By default this module uses HTTP::Thin, but you can supply another object when creating a WebService::GoShippo object.
last_response
The HTTP::Response object from the last request/reponse pair that was sent, for debugging purposes.
get(path, params)
Performs a GET request, which is used for reading data from the service.
- path
-
The path to the REST interface you wish to call.
- params
-
A hash reference of parameters you wish to pass to the web service. These parameters will be added as query parameters to the URL for you.
delete(path)
Performs a DELETE request, deleting data from the service.
- path
-
The path to the REST interface you wish to call.
- params
-
A hash reference of parameters you wish to pass to the web service. These parameters will be added as query parameters to the URL for you.
put(path, json)
Performs a PUT request, which is used for updating data in the service.
- path
-
The path to the REST interface you wish to call.
- params
-
A hash reference of parameters you wish to pass to Shippo. This will be translated to JSON.
post(path, params, options)
Performs a POST request, which is used for creating data in the service.
- path
-
The path to the REST interface you wish to call.
- params
-
A hash reference of parameters you wish to pass to Shippo. They will be encoded as JSON.
Notes
The path you provide as arguments to the request methods get, post, put delete should not have a leading slash.
As of early 2019:
The current version of their API is '2018-02-08'. There is no default value for the version parameter, so please provide this when creating a WebService::GoShippo object.
Shippo provides a free testing mode for prototyping your code but it is not feature complete. The test mode is accessed by passing a separate token from your regular production token. Please visit their website for details as to what works in test mode, and what works.
PREREQS
HTTP::Thin Ouch HTTP::Request::Common HTTP::CookieJar JSON URI Moo
SUPPORT
AUTHOR
Colin Kuskie <colink_at_plainblack_dot_com>
LEGAL
This module is Copyright 2019 Plain Black Corporation. It is distributed under the same terms as Perl itself.