NAME

Shipment::Base

VERSION

version 3.05

SYNOPSIS

This module does not DO anything, but can be extended to create a real interface for a shipping service.

  package Shipment::SomeShippingService;

  use Moose;

  extends 'Shipment::Base';

  sub ship {
    # routine to ship something somewhere via some shipping service
  }

  no Moose;

which can then be used to actually DO stuff:

  use Shipment::SomeShippingService;
  use Shipment::Address;
  use Shipment::Package;

  my $shipment = Shipment::SomeShippingService->new(
    from_address => Shipment::Address->new( ... ),
    to_address => Shipment::Address->new( ... ),
    packages => [ Shipment::Package->new( ... ), ],
  );

  $shipment->ship( 'ground' );

NAME

Shipment::Base - base class for a shipping module

ABOUT

This is a base class for a shipping service such as UPS or FedEx.

Class Attributes

from_address, to_address

Where the shipment is being shipped from and to

type: Shipment::Address

account

The shipper's account number

type: String

bill_account

The billing account number

type: String

defaults to the account

bill_address

The billing address (typically not needed)

type: Shipment::Address

bill_type

Who to bill for the shipment (sender, recipient, third_party)

type: BillingOptions

default: sender

pickup_type

Whether the shipment will be picked up or dropped off (most shipping services have multiple pickup options)

type: PickupOptions

default: pickup

printer_type

Defines the kind of label that will be generated (i.e. pdf, thermal, image)

type: Str

default: pdf

signature_type

Whether a signature confirmation is required, and what type (default, required, not_required, adult)

type: SignatureOptions

default: default (the default setting for the chosen service)

package_type

The type of packaging used (custom, envelope, tube, box, pack)

type: PackageOptions

default: custom

packages

The list of individual packages being shipped

type: ArrayRef[Shipment::Package]

methods handled: all_packages # returns a list of Shipment::Package get_package(index) # returns a Shipment::Package add_package(Shipment::Package) count_packages # returns the number of packages

weight_unit, dim_unit

What units we're dealing with for weight and dimensions (lb, kg and in, cm)

default: lb, in (pounds and inches)

currency

What currency we're dealing with (USD,CAD, etc)

default: USD

insured_value

The total value of the shipment to be insured

type: Data::Currency

goods_value

The total value of the shipment

type: Data::Currency

pickup_date

When the shipment will be ready for pickup

type: DateAndTime

services

The available services

type: HashRef[Shipment::Service]

methods handled: all_services # returns a list of Shipment::Service

service

Details of what was returned from a call to rate

type: Shipment::Service

tracking_id

The tracking_id returned from a call to ship OR the tracking_id to be used in a call to cancel or track

type: String

activities

The tracking activities returned from a call to track

status, ship_date

most recent tracking status

ship_date is when the shipment was passed off to the carrier, set by a call to track

documents

All documents for a shipment including all labels

type: Shipment::Label

manifest

The manifest document (usually generated by an end of day close, but may also be generated on a per shipment basis)

type: Shipment::Label

debug

  turn debugging on
    1 == warnings for notices and errors
    >1 == warnings for raw response xml

error

The last error generated by a method. Should only be non-empty if a method was unsuccessful.

type: String

notice

The last warning/alert/notice generated by a method.

type: String

references

The references for the shipment

type: ArrayRef[String]

methods handled: all_references get_reference(index) add_reference($reference) count_references # returns the number of reference strings

special_instructions

Special Delivery Instructions

type: String

carbon_offset

If available, add a carbon offset charge for the shipment

type: Bool

Class Methods

_build_services

The routine which compiles a list of available shipping services for from and to addresses.

  foreach my $service ( $shipment->all_services ) {
    print $service->name . "\n";
  }

Standard services - ground, express, priority - can be mapped to actual service id's

  print $shipment->services->{ground}->id . "\n";

rate

The routine that fetches a detailed rate for a given service type

  $shipment->rate( 'ground' );
  print $shipment->service->cost . "\n";
  print $shipment->service->etd . "\n";

ship

The routine that creates a shipment/label

  $shipment->ship( 'ground' );
  $shipment->get_package(0)->label->save;

return

The routine that creates a return shipment

  $shipment->return( 'ground' );

cancel

The routine that cancels a shipment

  $shipment->tracking_id( '12345' );
  $shipment->cancel;

end_of_day

The routine that runs end of day close

  $shipment->end_of_day;

track

The routine that fetches tracking information

  $shipment->tracking_id( '12345' );
  $shipment->track;

coerce_datetime

In the pre-Moo era Shipment used MooseX::Types::DateTime::ButMaintained for DateTime types but now we use MooX::Types::MooseLike::DateTime which does not do coercion for us.

This method provides coercion for DateTime/DateAndTime types in the way existing code expects it to work so we don't break anything.

AUTHOR

Andrew Baerg @ <andrew at pullingshots dot ca>

http://pullingshots.ca/

BUGS

Issues can be submitted at https://github.com/pullingshots/Shipment/issues

COPYRIGHT

Copyright (C) 2016 Andrew J Baerg, All Rights Reserved

NO WARRANTY

Absolutely, positively NO WARRANTY, neither express or implied, is offered with this software. You use this software at your own risk. In case of loss, no person or entity owes you anything whatsoever. You have been warned.

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Andrew Baerg <baergaj@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by Andrew Baerg.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.