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
addressRecipientformat. It is passed to DPD unchanged and not validated. - parcels
-
Required. Array reference of DPD parcel hashes, for example
[{weight => 2.5}]. Sent asparcels => {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 asproduct.
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
successwas 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
createblindly: that registers a second shipment. The failure happens after the shipment is registered and the parcels andmsidare lost to the caller.