README

这个非官方库封装了一些DHL SOAP API的函数，以便轻松创建/删除运输和标签。

请注意，这是一个Petschko/DHL-PHP-SDK的分支

安装

您可以使用Composer将包安装到项目中

composer require daniellarusso/dhl-php-sdk

然后类会自动添加到自动加载器中。

要求

• 您需要一个DHL开发者账户，如果您想在生产系统中使用API，还需要一个DHL Intraship账户。
• PHP-SOAP-Client已安装并在您的服务器上启用

兼容性

本项目是为DHL-SOAP-API 版本2或更高版本编写的。

它几乎支持版本1，您可以自由地完善版本1缺失的函数。它们的命名通常是{functionname}_v1。如果它们尚未实现，也会标记为"todo"。

我找不到版本1的文档了，所以很难正确实现它们...

用法

1. 您需要通过包含\DanielLarusso\DHL\BusinessShipment.php文件来引入SDK，它会为您引入其余部分。

2. 您需要设置您的DHL凭据

测试凭据

// You can initial the Credentials-Object with true to pre-set the Test-Account
$credentials = new \DanielLarusso\DHL\Credentials(/* Optional: Test-Modus */ true);

// Now you just need to set your DHL-Developer-Data to it
$credentials
    ->setApiUser('myuser')        // Set the USERNAME (not E-Mail!) of your DHL-Dev-Account
    ->setApiPassword('myPasswd'); // Set the Password of your DHL-Dev-Account

实时凭据

// Just create the Credentials-Object
$credentials = new \DanielLarusso\DHL\Credentials();

// Setup these Infos: (ALL Infos are Case-Sensitive!)
$credentials
    ->setUser('Your-DHL-Account')               // DHL-Account (Same as if you Login with then to create Manual-Labels)
    ->setSignature('Your-DHL-Account-Password') // DHL-Account-Password
    ->setEpk('EPK-Account-Number')              // Number of your Account (Provide at least the first 10 digits)
    ->setApiUser('appId')                       // Your Applications-ID (You can find it in your DHL-Dev-Account)
    ->setApiPassword('appToken');               // Your Applications-Token (You can find it also where you found the App-Id) 

到目前为止，您已经设置了所有必要的信息。现在您可以进行多个操作。

创建运输

请注意，您需要使用具有有效登录信息的\DanielLarusso\DHL\Credentials对象来执行此操作。

使用的类

• \DanielLarusso\DHL\Credentials (必需) - 登录信息
• \DanielLarusso\DHL\ShipmentDetails (必需) - 运输详情
• \DanielLarusso\DHL\Sender (必需) - 发件人详情
  • \DanielLarusso\DHL\SendPerson (父)
    • \DanielLarusso\DHL\Address (父)
• \DanielLarusso\DHL\ReturnReceiver (可选) - 退回接收者详情
  • \DanielLarusso\DHL\SendPerson (父)
    • \DanielLarusso\DHL\Address (父)
• \DanielLarusso\DHL\Service (可选) - 服务详情（运输的许多配置）
• \DanielLarusso\DHL\IdentCheck (非常可选) - 身份验证详情，仅在服务中启用时需要
• \DanielLarusso\DHL\BankData (可选) - 银行信息
• \DanielLarusso\DHL\BusinessShipment (必需) - 管理所有操作和信息
  • \DanielLarusso\DHL\Version (父)
• \DanielLarusso\DHL\Response (必需|自动) - 响应信息
  • \DanielLarusso\DHL\Version (父)

其中之一

• \DanielLarusso\DHL\Receiver (必需) - 接收者详情
  • \DanielLarusso\DHL\SendPerson (父)
    • \DanielLarusso\DHL\Address (父)
• \DanielLarusso\DHL\Filial (可选) - 接收者详情（后分支）
  • \DanielLarusso\DHL\Receiver (必需|父) - 接收者详情
    • \DanielLarusso\DHL\SendPerson (父)
      • \DanielLarusso\DHL\Address (父)
• \DanielLarusso\DHL\PackStation (可选) - 接收者详情（包装站）
  • \DanielLarusso\DHL\Receiver (必需|父) - 接收者详情
    • \DanielLarusso\DHL\SendPerson (父)
      • \DanielLarusso\DHL\Address (父)

如何创建

\DanielLarusso\DHL\ShipmentDetails 对象

您需要为运输设置运输详情（如尺寸/重量等）。您可以使用\DanielLarusso\DHL\ShipmentDetails对象来完成此操作。

// Create the Object with the first 10 Digits of your Account-Number (EPK).
// You can use the \DanielLarusso\DHL\Credentials function "->getEko((int) amount)" to get just the first 10 digits if longer
$shipmentDetails = new \DanielLarusso\DHL\ShipmentDetails((string) $credentials->getEpk(10) . '0101'); // Ensure the 0101 at the end

如果您需要，可以设置详细信息。如果您不设置它们，它将使用默认值（这部分是可选的）

// Setup details

// -- Product
/* Setup the Product-Type that you need. Possible Values are:
* PRODUCT_TYPE_NATIONAL_PACKAGE = 'V01PAK';
* PRODUCT_TYPE_INTERNATIONAL_PACKAGE = 'V53WPAK';
* PRODUCT_TYPE_EUROPA_PACKAGE = 'V54EPAK';
* PRODUCT_TYPE_SAME_DAY_PACKAGE = 'V06PAK';
* PRODUCT_TYPE_SAME_DAY_MESSENGER = 'V06TG';
* PRODUCT_TYPE_WISH_TIME_MESSENGER = 'V06WZ';
* PRODUCT_TYPE_AUSTRIA_PACKAGE = 'V86PARCEL';
* PRODUCT_TYPE_AUSTRIA_INTERNATIONAL_PACKAGE = 'V82PARCEL';
* PRODUCT_TYPE_CONNECT_PACKAGE = 'V87PARCEL';
*/
$shipmentDetails->setProduct((string) \DanielLarusso\DHL\ShipmentDetails::{ProductType}); // Default: PRODUCT_TYPE_NATIONAL_PACKAGE

// Example:
$shipmentDetails->setProduct((string) \DanielLarusso\DHL\ShipmentDetails::PRODUCT_TYPE_INTERNATIONAL_PACKAGE);
// or (the same)
$shipmentDetails->setProduct((string) 'V53WPAK');

// -- Date
// You can set a Shipment-Date you have to provide it in this Format: YYYY-MM-DD
// -> The Date MUST be Today or in the future AND NOT a Sunday
$shipmentDetails->setShipmentDate((string) '2017-01-30'); // Default: Today or 1 day higher if Today is a Sunday
// You can also use a timestamp as value, just set the 2nd param to true (Default is false)
$shipmentDetails->setShipmentDate((int) time(), /* useTimeStamp = false */ true);

// -- Return Account-Number (EPK)
// Provide your Return-Account-Number here. If not needed don't set it!
// Its usually the same Account-Number like your DHL-Account, just set the end to 0701
$shipmentDetails->setReturnAccountNumber((string) $credentials->getEpk(10) . 0701); // Default: null -> Disabled

// -- References
$shipmentDetails->setCustomerReference((string) 'freetext 35 len'); // Default: null -> Disabled
// Only used if return receiver is used (ONLY if you want to print a return label)
$shipmentDetails->setReturnReference((string) 'freetext 35 len'); // Default: null -> Disabled

// Sizes/Weight
$shipmentDetails->setWeight((float) $weightInKG); // Default: 5.0 (KG)
$shipmentDetails->setLength((int) $lengthInCM); // Default: null -> Unset
$shipmentDetails->setWidth((int) $widthInCM); // Default: null -> Unset
$shipmentDetails->setHeight((int) $heightInCM); // Default: null -> Unset

// -- Package-Type (ONLY NEEDED IN VERSION 1)
/* Sets the Type of the Package. Possible Values:
* PALETTE = 'PL';
* PACKAGE = 'PK';
*/
$shipmentDetails->setPackageType((string) \DanielLarusso\DHL\ShipmentDetails::{type}); // Default: PACKAGE

\DanielLarusso\DHL\Sender, \DanielLarusso\DHL\Receiver + \DanielLarusso\DHL\ReturnReceiver 对象

现在您必须创建一个发件人和一个接收者。它们的设置相似，只是XML的创建不同，因此您必须使用不同的对象来完成此操作。

如果您想查找所有值，您可以通过\DanielLarusso\DHL\SendPerson + \DanielLarusso\DHL\Address类来搜索。

我们从发送者开始，在大多数情况下你 =)。创建一个 \DanielLarusso\DHL\Sender 对象

$sender = new \DanielLarusso\DHL\Sender();

设置所有 必需 信息

$sender->setName((string) 'Organisation DanielLarusso'); // Can be a Person-Name or Company Name

// You can add the whole address with that setter if you want
$sender->setFullStreet((string) 'Oberer Landweg 12a');

// If you want to set the elements on your own use the setter for them
$sender->setStreetName((string) 'Oberer Landweg');
$sender->setStreetNumber((string) '12a');

$sender->setZip((string) '21035');
$sender->setCity((string) 'Hamburg');
$sender->setCountry((string) 'Germany');
$sender->setCountryISOCode((string) 'DE'); // 2 Chars ONLY

你还可以添加更多信息，但它们是 可选 的

// You can specify the delivery location
$sender->setAddressAddition((string) 'Etage 1'); // Default: null -> Disabled
$sender->setDispatchingInfo((string) 'Additional dispatching info'); // Default: null -> Disabled
$sender->setState((string) 'State'); // Default: null -> Disabled

// You can add more Personal-Info
$sender->setName2((string) 'Name Line 2'); // Default: null -> Disabled
$sender->setName3((string) 'Name Line 3'); // Default: null -> Disabled
$sender->setPhone((string) '04073409677'); // Default: null -> Disabled
$sender->setEmail((string) 'peter-91@hotmail.de'); // Default: null -> Disabled

// Mostly used in bigger Companies
$sender->setContactPerson((string) 'Peter Dragicevic'); // Default: null -> Disabled

这是发送者对象，你可以使用 \DanielLarusso\DHL\Receiver + \DanielLarusso\DHL\ReturnReceiver 类设置所有相同的信息。

注意：你也可以使用 \DanielLarusso\DHL\PackStation 或 \DanielLarusso\DHL\Filial 替代 \DanielLarusso\DHL\Receiver。请注意，它们需要一些额外信息。

如果你不想要退货标签，不需要创建 \DanielLarusso\DHL\ReturnReceiver 对象。

\DanielLarusso\DHL\Service 对象

你也可以通过使用 \DanielLarusso\DHL\Service 对象来设置更多关于你的运输的详细信息。这是一个可选对象，但你可能应该看看你可以为这个对象设置什么。

我将不会解释服务对象，因为设置太多。请自己查看服务-PHP-文件。字段有很好的文档。

\DanielLarusso\DHL\BankData 对象

你还可以使用 \DanielLarusso\DHL\BankData 对象。银行数据可以用于不同的目的。例如，如果COD作为服务预订，则必须由DHL客户（强制服务器逻辑）提供银行数据。收集到的钱将转账到指定的银行账户。

你可以查看 \DanielLarusso\DHL\BankData-对象的PHP文件，并查看你可以设置什么。这里不会解释它。

\DanielLarusso\DHL\BusinessShipment 对象

最后你可以把它们全部添加在一起。你必须创建 \DanielLarusso\DHL\BusinessShipment 对象

/* Creates the Object:
* - 1st param is the \DanielLarusso\DHL\Credentials Object
* - 2nd param (Optional - Default: false) is a bool value if the testmodus is used. (true uses testmodus, false live)
* - 3rd param (Optional - Default: null -> newest) is a float value, that assigns the Version to use
*/
$dhl = new \DanielLarusso\DHL\BusinessShipment($credentials);

如果你想使用特定的WSDL文件（或远程），你可以设置它：（否则你不需要这部分）

$dhl->setCustomAPIURL('http://myserver.com/myAPIFile.wsdl');

在这里你可以添加之前创建的类

// Add all Required (For a CREATE-Shipment-Request) Classes
$dhl->setShipmentDetails($shipmentDetails); // \DanielLarusso\DHL\ShipmentDetails Object
$dhl->setSender($sender); // \DanielLarusso\DHL\Sender Object
$dhl->setReceiver($receiver); // \DanielLarusso\DHL\Receiver Object

// Add Optional-Classes (Drop the line if you don't need/set it)
$dhl->setReturnReceiver($returnReceiver); // \DanielLarusso\DHL\ReturnReceiver Object - Default: null - Disabled
$dhl->setService($service); // \DanielLarusso\DHL\Service Object - Default: null -> All is default
$dhl->setBank($bankObj); // \DanielLarusso\DHL\BankData Object - Default: null -> Disabled

现在你可以设置标签应该如何返回以及一些其他东西

// You can enable Logging if you want
$dhl->setLog((bool) true);

// Set a Sequence-Number if you need a referrence when you get the response
$dhl->setSequenceNumber((string) '1'); // Default: '1'

// You can let DHL send a Mail to the Receiver, if you want that set the Mail
$dhl->setReceiverEmail((string) 'receiver@mail.com'); // Default: null -> Disabled

/* You can get the Label as URL or as Base64-Data-String - set it how you want to have it
* Possible Values:
* RESPONSE_TYPE_URL = 'URL';
* RESPONSE_TYPE_B64 = 'B64';
*/
$dhl->setLabelResponseType((string) \DanielLarusso\DHL\BusinessShipment::RESPONSE_TYPE_URL); // Default: null -> Uses DHL-Default

创建请求

一切设置好了？很好，现在你最终可以创建运输订单请求。将响应保存到变量中

// Returns false if the Request failed or \DanielLarusso\DHL\Response on success
$response = $dhl->createShipment();

处理响应

首先你必须检查值不是false

if($response === false) {
    // Do your Error-Handling here
    
    // Just to show all Errors
    var_dump($dhl->getErrors()); // Get the Error-Array
} else {
    // Handle the Response here
    
    // Just to show the whole Response-Object
    var_dump($response);
}

你可以从 \DanielLarusso\DHL\Response 对象中获得多个信息。请向下查看，我描述了 \DanielLarusso\DHL\Response 类。

删除运输

请注意，您需要使用具有有效登录信息的\DanielLarusso\DHL\Credentials对象来执行此操作。

你还需要运输号，这是你想要取消/删除的运输。

使用的类

• \DanielLarusso\DHL\Credentials (必需) - 登录信息
• \DanielLarusso\DHL\BusinessShipment (必需) - 管理所有操作和信息
  • \DanielLarusso\DHL\Version (父)
• \DanielLarusso\DHL\Response (必需|自动) - 响应信息
  • \DanielLarusso\DHL\Version (父)

如何创建

删除运输并不难，它只是这样工作的

// Create a \DanielLarusso\DHL\BusinessShipment Object with your credentials
$dhl = new \DanielLarusso\DHL\BusinessShipment($credentials);

// Send a deletetion Request
$response = $dhl->deleteShipment((string) 'shipment_number');

与创建运输订单一样，如果请求失败，响应是 false。有关响应的更多信息，请向下查看我描述的 \DanielLarusso\DHL\Response 类。

重新获取标签

请注意，您需要使用具有有效登录信息的\DanielLarusso\DHL\Credentials对象来执行此操作。

你还需要运输号，这是你想要重新获取标签的运输。

使用的类

• \DanielLarusso\DHL\Credentials (必需) - 登录信息
• \DanielLarusso\DHL\BusinessShipment (必需) - 管理所有操作和信息
  • \DanielLarusso\DHL\Version (父)
• \DanielLarusso\DHL\Response (必需|自动) - 响应信息
  • \DanielLarusso\DHL\Version (父)

如何创建

与删除类似，重新获取标签并不难。你可以简单地重新获取标签

// As usual create a \DanielLarusso\DHL\BusinessShipment Object with your Credentials
$dhl = new \DanielLarusso\DHL\BusinessShipment($credentials);

// This is the only setting you can do here: (Change Label-Response Type) - Optional
$dhl->setLabelResponseType((string) \DanielLarusso\DHL\BusinessShipment::RESPONSE_TYPE_B64); // Default: null -> DHL-Default

// And here comes the Request
$response = $dhl->getShipmentLabel((string) 'shipmentNumber');

如果请求失败，你通常会得到 false，否则得到一个 \DanielLarusso\DHL\Response 对象。

执行Manifest

请注意，您需要使用具有有效登录信息的\DanielLarusso\DHL\Credentials对象来执行此操作。

你需要运输号来执行Manifest （如果你需要，你会知道如何使用它）。

我个人不知道这是为什么，但它可以工作！

使用的类

• \DanielLarusso\DHL\Credentials (必需) - 登录信息
• \DanielLarusso\DHL\BusinessShipment (必需) - 管理所有操作和信息
  • \DanielLarusso\DHL\Version (父)
• \DanielLarusso\DHL\Response (必需|自动) - 响应信息
  • \DanielLarusso\DHL\Version (父)

如何创建

它就像删除运输一样工作

// Create a \DanielLarusso\DHL\BusinessShipment Object with your credentials
$dhl = new \DanielLarusso\DHL\BusinessShipment($credentials);

// Do the Manifest-Request
$dhl->doManifest((string) 'shipment_number');

如果请求失败，你会得到 false，否则得到一个 \DanielLarusso\DHL\Response 对象。

\DanielLarusso\DHL\Response 对象

如果你得到一个不是 false 的响应，你必须与 \DanielLarusso\DHL\Response 对象打交道。

此对象可以帮助你更容易地达到目标。你可以通过使用getter轻松获取所需的值。（IDE会自动检测它们）

我将解释你可以从响应对象中获取哪些值

(string) $response->getShipmentNumber(); // Returns the Shipment-Number of the Request or null
(string) $response->getLabel(); // Returns the Label URL or Base64-Label-String or null
(string) $response->getReturnLabel(); // Returns the ReturnLabel (URL/B64) or null
(string) $response->getSequenceNumber(); // Returns your provided sequence number or null
(int) $response->getStatusCode(); // Returns the Status-Code (Difference to DHL - Weak-Validation is 1 not 0)
(string) $response->getStatusText(); // Returns the Status-Text or null
(string) $response->getStatusMessage(); // Returns the Status-Message (More details) or null

如果值未设置，通常会得到 null 作为结果。不是每个操作都会填写这些值！

您还可以查看“类常量”，它们可以帮助您识别状态码。

const \DanielLarusso\DHL\ERROR_NOT_SET = -1;
const \DanielLarusso\DHL\ERROR_NO_ERROR = 0;
const \DanielLarusso\DHL\ERROR_WEAK_WARNING = 1;
const \DanielLarusso\DHL\ERROR_SERVICE_TMP_NOT_AVAILABLE = 500;
const \DanielLarusso\DHL\ERROR_GENERAL = 1000;
const \DanielLarusso\DHL\ERROR_AUTH_FAILED = 1001;
const \DanielLarusso\DHL\ERROR_HARD_VAL_ERROR = 1101;
const \DanielLarusso\DHL\ERROR_UNKNOWN_SHIPMENT_NUMBER = 2000;

目前就这么多。

联系方式

• 如果您有任何问题或任何其他事情，可以给我发送电子邮件（请不要报告错误！）：daniel.pogodda@googlemail.com
• 您可以在项目的"问题”部分报告错误。
  • 当然，您也可以在那里提出任何问题，请随意。
  • 如果您想使用德语，您可以这样做。请记住，并不是每个人都讲德语，所以最好使用英语 =)