NAME

Business::DPD::SK::API - create DPD Slovakia shipments and fetch labels

SYNOPSIS

use Business::DPD::SK::API;

# account settings and endpoint from dpd-sk/api.ini
my $api = Business::DPD::SK::API->new();
my $res = $api->create(
    recipient_address => {...},
    parcels           => [{weight => 2.5}],
    reference         => 'PO-1',
    labels_filename   => '/tmp/labels.pdf',
);
say $res->{msid};

# constructor arguments override the config file
my $other = Business::DPD::SK::API->new(
    config_file => '/etc/dpd-sk/api-other.ini',
    base_url    => 'https://api.dpd.sk/shipment/json',
);

DESCRIPTION

Thin client for the createV3 method of the DPD Slovakia shipment JSON-RPC API. One call to "create" registers one shipment with one or more parcels and saves the label PDF that DPD returns.

Configuration file

The endpoint and the account settings come from the INI file in "config_file", by default dpd-sk/api.ini below "sysconfdir" in Business::DPD::SK::SPc (for example /etc/dpd-sk/api.ini after ./Build install). Its [api] section has one key per attribute:

[api]
; test endpoint
base_url=https://capi.dpd.sk/shipment/json
; production endpoint
;base_url=https://api.dpd.sk/shipment/json
api_email=user@example.com
api_key=secret
delis_id=DELIS_ID
sender_address_id=0

The shipped file selects the test endpoint https://capi.dpd.sk/shipment/json and holds placeholder account values. To create real shipments, switch the base_url lines to the production endpoint and fill in the real account values. DPD may issue separate credentials for the test and production endpoints; keep them matching the active base_url.

Each of the five attributes takes its value from the constructor if given, otherwise from the file. The file is read once, the first time a value is needed that the constructor did not supply. An object built with all five values never reads the file.

The file holds the API key. ./Build install installs it with mode 0640; give the group of the user that runs the client read access.

ATTRIBUTES

All attributes are read-only and can only be set through the constructor. The five API attributes croak with no KEY in FILE on first use when neither the constructor nor the config file supplies them. An empty value in the file, such as api_key=, counts as missing.

config_file

Path of the INI file described in "Configuration file". Defaults to dpd-sk/api.ini below "sysconfdir" in Business::DPD::SK::SPc.

api_config

Hash reference with the [api] section of "config_file", read on first use. Croaks with no [api] section in FILE if the section is missing, and with Config::INI::Reader's error if the file cannot be read.

base_url

URL the JSON-RPC requests are POSTed to. Config key base_url.

api_email

api_key

Credentials sent as DPDSecurity/SecurityToken (Email and ClientKey) in every request. Config keys api_email and api_key.

delis_id

DPD customer (DELIS) identifier, sent as delisId in the shipment. Config key delis_id.

sender_address_id

ID of the sender address registered with DPD, sent as addressSender => {id => ...}. Config key sender_address_id.

METHODS

create

my $res = $api->create(%args);

Creates one shipment and downloads its labels.

Arguments:

recipient_address

Required. Hash reference in DPD's addressRecipient format. It is passed to DPD unchanged and not validated.

parcels

Required. Array reference of DPD parcel hashes, for example [{weight => 2.5}]. Sent as parcels => {parcel => [...]}.

reference

Required. Your own reference for the shipment, such as an order number.

labels_filename

Required. Path of the file the label PDF is written to. An existing file is overwritten.

product_code

Optional, defaults to 1. DPD product, sent as product.

create croaks with need ARGUMENT if a required argument is missing. The shipment is sent without services (services is an empty hash).

The method makes two HTTP requests: the JSON-RPC POST to "base_url", then a plain GET of the label URL from the response, saved straight into labels_filename. The label GET carries no credentials. Both use a 10 second timeout and honour the proxy variables read by "env_proxy" in LWP::UserAgent (http_proxy, https_proxy, no_proxy).

Returns a hash reference:

{
    parcels => [...],   # parcel records from DPD's response, as-is
    msid    => '...',   # DPD's mpsId (multi-parcel shipment ID)
}

parcels is an empty array if DPD returns none.

Dies with one of these messages:

request to DPD failed: STATUS_LINE

The shipment POST returned a non-2xx status or failed at transport level.

unknown response from DPD: ...

The response body was not JSON or did not have the expected result.result[0] structure.

request to DPD was not successful

DPD answered, but success was false. The message does not include DPD's error details.

request to DPD label fetch failed: STATUS_LINE

The shipment exists at DPD, but downloading the label failed. Do not retry create blindly: that registers a second shipment. The failure happens after the shipment is registered and the parcels and msid are lost to the caller.

SEE ALSO

Business::DPD::SK, Business::DPD::SK::SPc