NAME
WebService::GeoPost::Shipping::API
SYNOPSIS
$geopost = WebService::GeoPost::Shipping::API->new(
username => $username,
password => $password,
geoClient => "account/$customer_id",
);DESCRIPTION
This module provides a simple wrapper around GeoPost delivery service API. This is a work in progress and contains incomplete test code, methods are likely to be refactored, you have been warned.
METHODS
login
Authenticates and establishes api session used by following methods
$geopost->login;get_country( $code )
Retrieves the country details for a provided country code and can be used to determine if a country requires a postcode or if liability is allowed etc.
$country = $geopost->get_country( 'GB' );get_services( \%shipping_information )
Retrieves list of services available for provided shipping information.
my $address = {
countryCode => 'GB',
county => 'West Midlands',
locality => 'Birmingham',
organisation => 'GeoPost',
postcode => 'B661BY',
property => 'GeoPost UK',
street => 'Roebuck Ln',
town => 'Smethwick',
};
my $shipping = {
collectionDetails => {
address => $address,
},
deliveryDetails => {
address => $address,
},
deliveryDirection => 1, # 1 for outbound 2 for inbound
numberOfParcels => 1,
totalWeight => 5,
shipmentType => 0, # 1 or 2 if a collection on delivery or swap it service is required
};
my $services = $geopost->get_services( $shipping );get_service( geoServiceCode )
Retrieves the supported countries for a geoServiceCode
$service = $geopost->get_service(812);create_shipment( \%data )
Creates a shipment object
my $shipment_data = {
jobId => 'null',
collectionOnDelivery => "false",
invoice => "null",
collectionDate => $date,
consolidate => "false",
consignment => [
{
collectionDetails => {
contactDetails => {
contactName => "Mr David Smith",
telephone => "0121 500 2500"
},
address => $address,
},
deliveryDetails => {
contactDetails => {
contactName => "Mr David Smith",
telephone => "0121 500 2500"
},
notificationDetails => {
mobile => "07921 123456",
email => 'david.smith@acme.com',
},
address => {
organisation => "ACME Ltd",
property => "Miles Industrial Estate",
street => "42 Bridge Road",
locality => "",
town => "Birmingham",
county => "West Midlands",
postcode => "B1 1AA",
countryCode => "GB",
}
},
networkCode => "1^12",
numberOfParcels => '1',
totalWeight => '5',
shippingRef1 => "Catalogue Batch 1",
shippingRef2 => "Invoice 231",
shippingRef3 => "",
customsValue => '0',
deliveryInstructions => "Please deliver to industrial gate A",
parcelDescription => "",
liabilityValue => '0',
liability => "false",
parcels => [],
consignmentNumber => "null",
consignmentRef => "null",
}
]
};
$shipment = $geopost->create_shipment( $shipment_data_example );list_countries
Provides a full list of available shipping countries
$countries = $geopost->list_countries;get_labels( $shipment_id, $format )
Get label for given shipment id, available in multiple formats
$label = $geopost->get_labels( $shipment_id, 'application/pdf' );FUTURE METHODS
These methods are implemented as documented in the GeoPost API specification. Although at the time of writing their functionality has not been publicly implemented within the API.
request_job_id
Get a job id to group shipments
$job_id = $geopost->request_jobid;get_labels_for_job( $id, $format )
Retrieves all labels for a given job id
$labels = $geopost->get_labels_for_job( $id, $format );get_shipments( \%search_params )
Retrieves a full list of shipments meeting the search criteria and/or collection date. If no URL parameters are set the default settings brings back the first 100 shipments found.
$shipments = $self->get_shipments( {
collectionDate => $date,
searchCriterea => 'foo',
searchPage => 1,
searchPageSize => 20,
useTemplate => false,
});get_shipment( $id )
Retrieves all shipment information associated with a shipment id
$shipment = $geopost->get_shipment( $id );get_international_invoice( $shipment_id )
Creates and returns an international invoice associated with the given shipment id.
$invoice = $geopost->get_international_invoice( $shipment_id );get_unprinted_labels( $date, $format )
Retrieves all labels that have not already been printed for a particular collection date.
$labels = $geopost->get_unprinted_labels( $date, $format );delete_shipment( $id )
Delete a shipment
$geopost->delete_shipment( $id );change_collection_date( $id, $date )
Update collection date for a shipment
$geopost->change_collection_date( $id, $date );void_shipment
Update status of shipment to void.
$geopost->void_shipment( $id );create_manifest
Tag all non manifested shipments for a collection date with a new generated manifest id.
$manifest = $geopost->create_manifest( $date );get_manifest_by_date( $date )
Retrieves all the manifests and the core manifest information for a particular collection date.
$manifests = $geopost->get_manifest_by_date( $date );get_manifest_by_id( $id )
Get printable manifest by its associated manifest id
$manifest = get_manifest_by_id( $id );INTERNAL METHODS
_to_query_params
Recursively converts hash of hashes into query string for http request
send_request( \%args )
Constructs and sends authenticated HTTP API request
$result = $geopost->send_request( {
type => 'POST', # HTTP request type defaults to GET
path => "/path/to/service", # Path to service
data => { # hashref of data for POST/PUT requests, converted to JSON for sending
key1 => 'value1',
key2 => 'value2',
},
content_type => 'appilcation/json', # defaults to application/json
header => { # hashref of additional headers
Accept => $format,
}
} );SOURCE CODE
The source code for this module is held in a public git repository on Github : https://github.com/pryanet/WebService-GeoPost-Shipping-API
LICENSE AND COPYRIGHT
Copyright (c) 2014 Richard Newsham, Pryanet Ltd
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
BUGS AND LIMITATIONS
See rt.cpan.org for current bugs, if any.
INCOMPATIBILITIES
None known.
DEPENDENCIES
Carp
Moo
LWP::UserAgent
LWP::Protocol::https
HTTP::Request::Common
URI::Escape
Data::Dumper
JSON
MIME::Base64
namespace::clean