{"id":25839783,"url":"https://github.com/netresearch/dhl-sdk-api-bcs","last_synced_at":"2025-03-01T04:34:25.491Z","repository":{"id":44449729,"uuid":"228393759","full_name":"netresearch/dhl-sdk-api-bcs","owner":"netresearch","description":"Library package encapsulating API communication to the DHL Geschäftskundenversand 3.0 web service.","archived":false,"fork":false,"pushed_at":"2024-03-30T15:11:29.000Z","size":572,"stargazers_count":3,"open_issues_count":3,"forks_count":6,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-04-14T11:16:22.397Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/netresearch.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2019-12-16T13:30:16.000Z","updated_at":"2024-03-26T00:07:34.000Z","dependencies_parsed_at":"2022-08-21T09:50:43.126Z","dependency_job_id":"24c05615-fce4-4110-b619-0b9af70bdd7b","html_url":"https://github.com/netresearch/dhl-sdk-api-bcs","commit_stats":{"total_commits":44,"total_committers":7,"mean_commits":6.285714285714286,"dds":0.5454545454545454,"last_synced_commit":"705cd6385a9640a2313fb0cc40faa8547e2319af"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netresearch%2Fdhl-sdk-api-bcs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netresearch%2Fdhl-sdk-api-bcs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netresearch%2Fdhl-sdk-api-bcs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netresearch%2Fdhl-sdk-api-bcs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/netresearch","download_url":"https://codeload.github.com/netresearch/dhl-sdk-api-bcs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241317608,"owners_count":19943199,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-01T04:34:25.036Z","updated_at":"2025-03-01T04:34:25.482Z","avatar_url":"https://github.com/netresearch.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DHL BCS API SDK\n\nThe DHL Business Customer Shipping API SDK package offers an interface to the following web services:\n\n- [Geschäftskundenversand 3.1.2](https://entwickler.dhl.de/group/ep/wsapis/geschaeftskundenversand/current)\n- [DHL Parcel DE Shipping 2.1.6](https://developer.dhl.com/api-reference/parcel-de-shipping-post-parcel-germany-v2)\n\n## Requirements\n\n### System Requirements\n\n- PHP 7.2+ with SOAP and JSON extension\n\n### Package Requirements\n\n- `league/openapi-psr7-validator`: Schema validator for JSON request messages\n- `netresearch/jsonmapper`: Mapper for deserialization of JSON response messages into PHP objects\n- `php-http/discovery`: Discovery service for HTTP client and message factory implementations\n- `php-http/httplug`: Pluggable HTTP client abstraction\n- `php-http/logger-plugin`: HTTP client logger plugin for HTTPlug\n- `psr/http-client`: PSR-18 HTTP client interfaces\n- `psr/http-factory`: PSR-7 HTTP message factory interfaces\n- `psr/http-message`: PSR-7 HTTP message interfaces\n- `psr/log`: PSR-3 logger interfaces\n\n### Virtual Package Requirements\n\n- `psr/http-client-implementation`: Any package that provides a PSR-18 compatible HTTP client\n- `psr/http-factory-implementation`: Any package that provides PSR-7 compatible HTTP message factories\n- `psr/http-message-implementation`: Any package that provides PSR-7 HTTP messages\n\n### Development Package Requirements\n\n- `nyholm/psr7`: PSR-7 HTTP message factory \u0026 message implementation\n- `phpunit/phpunit`: Testing framework\n- `php-http/mock-client`: HTTPlug mock client implementation\n- `phpstan/phpstan`: Static analysis tool\n- `squizlabs/php_codesniffer`: Static analysis tool\n\n## Installation\n\n```bash\n$ composer require dhl/sdk-api-bcs\n```\n\n## Uninstallation\n\n```bash\n$ composer remove dhl/sdk-api-bcs\n```\n\n## Testing\n\n```bash\n$ ./vendor/bin/phpunit -c test/phpunit.xml\n```\n\n## Features\n\nThe DHL BCS API SDK is able to connect to the legacy _Business Customer Shipping_ SOAP API\nas well as its successor, the _Parcel DE Shipping_ REST web service.\n\nWhile the connection to the REST API includes some shipping services that were introduced\nafter BCS v3.1.2, both connections share the same high-level functionality:\n\n* Validate Shipment: Validate a shipment order without booking a label\n* Create Shipment Order: Book a shipment label\n* Delete Shipment Order: Cancel a shipment label\n\nPlease note that the _Parcel DE Shipping_ REST API takes different arguments in some cases:\n\n- sandbox credentials and EKP\n- countries must be specified as three-letter codes\n\n## Authentication\n\nBoth APIs require a two-level authentication to identify application and user.\nThe API SDK offers an authentication storage to pass credentials in.\n\n```php\n// BCS\n$authStorage = new \\Dhl\\Sdk\\Paket\\Bcs\\Auth\\AuthenticationStorage('appId', 'appToken', 'user', 'signature');\n\n// Parcel DE Shipping\n$authStorage = new \\Dhl\\Sdk\\Paket\\Bcs\\Auth\\AuthenticationStorage('', 'apiKey', 'user', 'password');\n```\n\n- API user credentials (user and signature/password) are created in the\n  [DHL Business Customer Portal](https://geschaeftskunden.dhl.de/)\n- SOAP access: application ID and token are created in the [Developer Portal](https://entwickler.dhl.de/)\n- REST access: API key is created in the [API Developer Portal](https://developer.dhl.com/user/apps)\n\n## API Selection\n\nBy default, the SDK connects to the legacy _Business Customer Shipping_ SOAP API.\nIn order to switch to the REST web service, pass an additional argument to the\nservice factory:\n\n```php\n$serviceFactory = new \\Dhl\\Sdk\\Paket\\Bcs\\Service\\ServiceFactory(\n    \\Dhl\\Sdk\\Paket\\Bcs\\Api\\ServiceFactoryInterface::API_TYPE_REST\n);\n```\n\nWhen using the request builder to create outgoing messages, then pass the respective\nargument there as well:\n\n```php\n$requestBuilder = new \\Dhl\\Sdk\\Paket\\Bcs\\RequestBuilder\\ShipmentOrderRequestBuilder(\n    \\Dhl\\Sdk\\Paket\\Bcs\\Api\\ShipmentOrderRequestBuilderInterface::REQUEST_TYPE_REST\n);\n```\n\nMore thorough examples on using service factory and request builder can be found in the\nsection about [web service operations](#web-service-operations).\n\n## Web Service Operations\n\n### Validate Shipment\n\nValidate shipments for DHL Paket including the relevant shipping documents.\n\n#### Public API\n\nThe library's components suitable for consumption comprise\n\n* services:\n  * service factory\n  * shipment service\n  * data transfer object builder\n* data transfer objects:\n  * [authentication storage](#Authentication)\n  * order/label settings\n  * validation result with status message\n\n#### Usage\n\n```php\n$logger = new \\Psr\\Log\\NullLogger();\n\n$serviceFactory = new \\Dhl\\Sdk\\Paket\\Bcs\\Service\\ServiceFactory();\n$service = $serviceFactory-\u003ecreateShipmentService($authStorage, $logger, $sandbox = true);\n\n$requestBuilder = new \\Dhl\\Sdk\\Paket\\Bcs\\RequestBuilder\\ShipmentOrderRequestBuilder();\n$requestBuilder-\u003esetShipperAccount($billingNumber = '22222222220101');\n$requestBuilder-\u003esetShipperAddress(\n    $company = 'DHL',\n    $country = 'DE',\n    $postalCode = '53113',\n    $city = 'Bonn',\n    $street = 'Charles-de-Gaulle-Straße',\n    $streetNumber = '20'\n);\n$requestBuilder-\u003esetRecipientAddress(\n    $recipientName = 'Jane Doe',\n    $recipientCountry = 'DE',\n    $recipientPostalCode = '53113',\n    $recipientCity = 'Bonn',\n    $recipientStreet = 'Sträßchensweg',\n    $recipientStreetNumber = '2'\n);\n$requestBuilder-\u003esetShipmentDetails($productCode = 'V01PAK', $shipmentDate = new \\DateTime());\n$requestBuilder-\u003esetPackageDetails($weightInKg = 2.4);\n\n$shipmentOrder = $requestBuilder-\u003ecreate();\n$result = $service-\u003evalidateShipments([$shipmentOrder]);\n```\n### Create Shipment Order\n\nCreate shipments for DHL Paket including the relevant shipping documents. In\naddition to the primary shipment data (shipper, consignee, etc.), further\nsettings can be defined per request via the _order configuration_ object, including\nlabel printing size, profile, and more.\n\n#### Public API\n\nThe library's components suitable for consumption comprise\n\n* services:\n  * service factory\n  * shipment service\n  * data transfer object builder\n* data transfer objects:\n  * [authentication storage](#Authentication)\n  * order/label settings\n  * shipment with shipment/tracking number and label(s)\n\n#### Usage\n\n```php\n$logger = new \\Psr\\Log\\NullLogger();\n\n$serviceFactory = new \\Dhl\\Sdk\\Paket\\Bcs\\Service\\ServiceFactory();\n$service = $serviceFactory-\u003ecreateShipmentService($authStorage, $logger, $sandbox = true);\n\n$orderConfiguration = new \\Dhl\\Sdk\\Paket\\Bcs\\Service\\ShipmentService\\OrderConfiguration(\n    $printOnlyIfCodable = true,\n    $combinedPrinting = null,\n    $docFormat = \\Dhl\\Sdk\\Paket\\Bcs\\Api\\Data\\OrderConfigurationInterface::DOC_FORMAT_PDF,\n    $printFormat = \\Dhl\\Sdk\\Paket\\Bcs\\Api\\Data\\OrderConfigurationInterface::PRINT_FORMAT_A4\n);\n\n$requestBuilder = new \\Dhl\\Sdk\\Paket\\Bcs\\RequestBuilder\\ShipmentOrderRequestBuilder();\n$requestBuilder-\u003esetShipperAccount($billingNumber = '22222222220101');\n$requestBuilder-\u003esetShipperAddress(\n    $company = 'DHL',\n    $country = 'DE',\n    $postalCode = '53113',\n    $city = 'Bonn',\n    $street = 'Charles-de-Gaulle-Straße',\n    $streetNumber = '20'\n);\n$requestBuilder-\u003esetRecipientAddress(\n    $recipientName = 'Jane Doe',\n    $recipientCountry = 'DE',\n    $recipientPostalCode = '53113',\n    $recipientCity = 'Bonn',\n    $recipientStreet = 'Sträßchensweg',\n    $recipientStreetNumber = '2'\n);\n$requestBuilder-\u003esetShipmentDetails($productCode = 'V01PAK', $shipmentDate = new \\DateTime());\n$requestBuilder-\u003esetPackageDetails($weightInKg = 2.4);\n\n$shipmentOrder = $requestBuilder-\u003ecreate();\n$shipments = $service-\u003ecreateShipments([$shipmentOrder], $orderConfiguration);\n```\n\n### Delete Shipment Order\n\nCancel earlier created shipments.\n\n#### Public API\n\nThe library's components suitable for consumption comprise\n\n* services:\n  * service factory\n  * shipment service\n* data transfer objects:\n  * authentication storage\n\n#### Usage\n\n```php\n$logger = new \\Psr\\Log\\NullLogger();\n\n$serviceFactory = new \\Dhl\\Sdk\\Paket\\Bcs\\Service\\ServiceFactory();\n$service = $serviceFactory-\u003ecreateShipmentService($authStorage, $logger, $sandbox = true);\n\n$shipmentNumber = '222201011234567890';\n$cancelled = $service-\u003ecancelShipments([$shipmentNumber]);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetresearch%2Fdhl-sdk-api-bcs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetresearch%2Fdhl-sdk-api-bcs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetresearch%2Fdhl-sdk-api-bcs/lists"}