NAME

WebService::DPD::API

WARNING

This module is depreciated. It will be replaced by WebService::GeoPost::DPD, this is allow expanding the namespace to accomodate other API services provided by GeoPost.

SYNOPSIS

    $dpd = WebService::DPD::API->new(
                                        username => $username,
                                        password => $password,
                                        geoClient => "account/$customer_id",
                                        );

DESCRIPTION

This module provides a simple wrapper around DPD 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

        $dpd->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 = $dpd->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 = $dpd->get_services( $shipping );

get_service( geoServiceCode )

Retrieves the supported countries for a geoServiceCode

        $service = $dpd->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 = $dpd->create_shipment( $shipment_data_example );

list_countries

Provides a full list of available shipping countries

        $countries = $dpd->list_countries;

get_labels( $shipment_id, $format )

Get label for given shipment id, available in multiple formats

        $label = $dpd->get_labels( $shipment_id, 'application/pdf' );

FUTURE METHODS

These methods are implemented as documented in the DPD 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 = $dpd->request_jobid;

get_labels_for_job( $id, $format )

Retrieves all labels for a given job id

        $labels = $dpd->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 = $dpd->get_shipment( $id );

get_international_invoice( $shipment_id )

Creates and returns an international invoice associated with the given shipment id.

        $invoice = $dpd->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 = $dpd->get_unprinted_labels( $date, $format );

delete_shipment( $id )

        Delete a shipment

        $dpd->delete_shipment( $id );

change_collection_date( $id, $date )

Update collection date for a shipment

        $dpd->change_collection_date( $id, $date );

void_shipment

Update status of shipment to void.

        $dpd->void_shipment( $id );

create_manifest

Tag all non manifested shipments for a collection date with a new generated manifest id.

        $manifest = $dpd->create_manifest( $date );

get_manifest_by_date( $date )

Retrieves all the manifests and the core manifest information for a particular collection date.

        $manifests = $dpd->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 = $dpd->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-DPD-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