• NAME
• VERSION
• SYNOPSIS
• DESCRIPTION
• EXCEPTIONS
• METHODS
  • new ( params )
  • last_response
  • get(path, params)
  • delete(path)
  • put(path, json)
  • post(path, params, options)
  • Notes
• PREREQS
• SUPPORT
• AUTHOR
• LEGAL

NAME

WebService::TaxJar - A simple client to TaxJar's REST API.

VERSION

version 0.0002

SYNOPSIS

 use WebService::TaxJar;

 my $tj = WebService::TaxJar->new(api_key => 'XXXXXXXXXXxxxxxxxxxxxx', version => 'v2');

 my $categories = $tj->get('categories');

DESCRIPTION

A light-weight wrapper for TaxJar's RESTful API (an example of which can be found at: https://https://developers.taxjar.com/api/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:

Host selection

Based on the value of the sandbox flag, the module will either send requests to the production environment sandbox => 0 or the sandbox environment sandbox => 1.

Adding authentication headers

WebService::TaxJar adds an authentication header of the type "Authorization: Bearer $tj->api_key" to each request.

Adding api version number to URLs

WebService::TaxJar prepends the $tj->version to each URL you submit.

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>.

Response data is deserialized from JSON and returned from each call.

EXCEPTIONS

All exceptions in WebService::TaxJar are handled by Ouch. A 500 exception "Server returned unparsable content." is returned if TaxJar'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.

api_key

Your key for accessing TaxJar's API. Required.

version

The version of the API that you are using, like 'v1', 'v2', etc. Optional, defaults to 'v2'.

api_version

Tax Jar decided to move away from a numbered scheme where the version is in the URL to a date based version in the HTTP headers. This flag is optional, and defaults to '2022-01-24', which is the default date as of May 2022. The date must be in the version of 'YYYY-MM-DD' to be accepted by TaxJar, but this module will not validate your date flag.

sandbox

A boolean that, if true, will send all requests to TaxJar's sandbox environment for testing instead of to production. Defaults to 0.

debug_flag

Just a spare, writable flag so that users of the object should log debug information, since TaxJar will likely ask for request/response pairs when you're having problems.

    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->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::TaxJar 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 Tax Jar. 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 Tax Jar. 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 'v2'. There is no default value for the version parameter, so please provide this when creating a WebService::TaxJar object.

TaxJar does not provide a free sandbox for prototyping your code, it is part of their premium service level.

TaxJar's sandbox mode does not implement all API endpoints.

PREREQS

HTTP::Thin Ouch HTTP::Request::Common HTTP::CookieJar JSON URI Moo

SUPPORT

Repository

https://github.com/perldreamer/WebService-TaxJar

Bug Reports

https://github.com/perldreamer/WebService-TaxJar/issues

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.

cpanm WebService::TaxJar

perl -MCPAN -e shell
install WebService::TaxJar