Business::Shipping - API for shipping-related tasks

- NAME
- SYNOPSIS
- ABSTRACT

- Shipping Tasks Implemented at this time
- Shipping Vendors Implemented at this time

- REQUIRED MODULES
- INSTALLATION

- Online::UPS Example

- ERROR/DEBUG HANDLING
- CLASS METHODS

- `rate_request()`

- AUTHOR
- COPYRIGHT AND LICENCE

# NAME

Business::Shipping - API for shipping-related tasks

# SYNOPSIS

Example rate request:

            use Business::Shipping;

            my $rate_request = Business::Shipping->rate_request(
                    shipper         => 'Offline::UPS',
                    service         => 'GNDRES',
                    from_zip        => '98682',
                    to_zip          => '98270',
                    weight          =>  5.00,
            );

            $rate_request->submit() or die $rate_request->error();

            print $rate_request->total_charges();

# ABSTRACT

Business::Shipping is an API for shipping-related tasks.

## Shipping Tasks Implemented at this time

     * Shipping cost calculation
     * Tracking, availability, and other services are planned for future addition.

## Shipping Vendors Implemented at this time

     * Online UPS (using the Internet and UPS servers)
     * Offline UPS (using tables stored locally)
     * Online USPS

Offline FedEX and USPS are planned for support in the future.

# REQUIRED MODULES

     Archive::Zip (any)
     Bundle::DBD::CSV (any)
     Cache::FileCache (any)
     Class::MethodMaker (any)
     Config::IniFiles (any)
     Crypt::SSLeay (any)
     Data::Dumper (any)
     Devel::Required (0.03)
     Error (any)
     Getopt::Mixed (any)
     LWP::UserAgent (any)
     Math::BaseCnv (any)
     Scalar::Util (1.10)
     XML::DOM (any)
     XML::Simple (2.05)

# INSTALLATION

`perl -MCPAN -e 'install Bundle::Business::Shipping'`

    =head1 MULTI-PACKAGE API

## Online::UPS Example

     use Business::Shipping;
     use Business::Shipping::Shipment::UPS;

     my $shipment = Business::Shipping::Shipment::UPS->new();

     $shipment->init(
            from_zip        => '98682',
            to_zip          => '98270',
            service         => 'GNDRES',
            #
            # user_id, etc. needed here.
            #
     );

     $shipment->add_package(
            id              => '0',
            weight          => 5,
     );

     $shipment->add_package(
            id              => '1',
            weight          => 3,
     );

     my $rate_request = Business::Shipping::rate_request( shipper => 'Online::UPS' );
     #
     # Add the shipment to the rate request.
     #
     $rate_request->shipment( $shipment );
     $rate_request->submit() or ie $rate_request->error();

     print $rate_request->package('0')->get_charges( 'GNDRES' );
     print $rate_request->package('1')->get_charges( 'GNDRES' );
     print $rate_request->get_total_price( 'GNDRES' );

# ERROR/DEBUG HANDLING

The 'event_handlers' argument takes a hashref telling Business::Shipping what to do for error, debug, trace, and the like. The value can be one of four options:

     * 'STDERR'
     * 'STDOUT'
     * 'carp'
     * 'croak'

For example:

     $rate_request->event_handlers(
            {
                    'error' => 'STDERR',
                    'debug' => 'STDERR',
                    'trace' => undef,
                    'debug3' => undef,
            }
     );

    The default is 'STDERR' for error handling, and nothing for debug/trace
    handling.  The option 'debug3' adds additional debugging messages that are not
    included in the normal 'debug'.  Note that you can still access error messages
    even without an 'error' handler, by accessing the return values of methods.  For
    example:

     $rate_request->init( %values ) or print $rate_request->error();

    However, if you don't save the error value before the next call, it could be
    overwritten by a new error.

# CLASS METHODS

## `rate_request()`

This method is used to request shipping rate information from online providers or offline tables. A hash is accepted as input with the following key values:

- shipper
The name of the shipper to use. Must correspond to a module by the name of: `Business::Shipping::RateRequest::SHIPPER`. For example, `Offline::UPS`.

- user_id
A user_id, if required by the provider. Online::USPS and Online::UPS require this, while Offline::UPS does not.

- password
A password, if required by the provider. Online::USPS and Online::UPS require this, while Offline::UPS does not.

- service
A valid service name for the provider. See the corresponding module documentation for a list of services compatible with the shipper.

- from_zip
The origin zipcode.

- from_state
The origin state. Required for Offline::UPS.

- to_zip
The destination zipcode.

- to_country
The destination country. Required for international shipments only.

- weight
Weight of the shipment, in pounds, as a decimal number.

# AUTHOR

     Dan Browning         <db@kavod.com>
     Kavod Technologies   http://www.kavod.com

# COPYRIGHT AND LICENCE

Copyright (c) 2003-2004 Kavod Technologies, Dan Browning. All rights reserved. Licensed under the GNU Public Licnese (GPL). See COPYING for more info.