[carrier-integration] Upgrade outdated DPDHL integration

bxschmidt commented 1 year ago

Hi all, the current dpdhl integration links to an api provided by https://entwickler.dhl.de/ The documentation for the api the karrio calls are directed to states that new users are no longer accepted and redirects users to https://developer.dhl.com/api-reference/parcel-de-shipping-post-parcel-germany-v2#get-started-section/ which uses json instead of xml and has a different endpoint. It is still possible to get access to the legacy api by contacting support but the current karrio implementation is not a long term solution. Great project!

Best regards Sebastian

danh91 commented 1 year ago

Hi @bxschmidt , Thanks for opening the issue. You are correct we need to migrate to the new API for DPDHL. I will add this issue to the roadmap to keep track of it with the other upgrades in progress (FedEx, DHL Express...)

MarcoWel commented 1 year ago

It is good DHL is migrating their outdated APIs. The JSON API you mention is very new, and it is replacing the XML SOAP API more or less 1:1. Migration should be quite straight forward.

MarcoWel commented 8 months ago

Is there a timeline for this update yet? Here is a short overview.

New REST API

Reading the DHL API docs, this is how a CreateShipmentOrderRequest should look like with the new API.

Some things to note:

There is a Postman test collection available here.
XML authentication header of the old API is replaced by a BASIC AUTH on the POST request explained in the docs here.
country code is now 3-letter according to ISO 3166-1 alpha-3. Details like this are shown in the docs when clicking "Show Data Schema" in the "Request body" section.
billingNumber still includes the DHL product in the last digits as per #333.

POST https://api-eu.dhl.com/parcel/de/shipping/v2/orders

{
  "profile": "STANDARD_GRUPPENPROFIL",
  "shipments": [
    {
      "product": "V01PAK",
      "billingNumber": "22222222220102",
      "refNo": "",
      "shipper": {
        "name1": "Deut",
        "addressStreet": "Römerberg 23",
        "additionalAddressInformation1": "",
        "postalCode": "60311",
        "city": "Frankfurt",
        "country": "DEU",
        "email": "",
        "phone": ""
      },
      "consignee": {
        "name1": "Ana",
        "addressStreet": "Am Wall 207",
        "additionalAddressInformation1": "",
        "postalCode": "28195",
        "city": "Bremen",
        "country": "DEU",
        "email": "",
        "phone": ""
      },
      "details": {
        "dim": {
          "uom": "cm",
          "height": 18,
          "length": 10,
          "width": 33
        },
        "weight": {
          "uom": "kg",
          "value": 1
        }
      }
    }
  ]
}

Old SOAP API

This was a CreateShipmentOrderRequest to the old API (taken from here):

POST https://cig.dhl.de/services/production/soap

<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:cis="http://dhl.de/webservice/cisbase"
    xmlns:ns="http://dhl.de/webservices/businesscustomershipping/3.0">
    <soapenv:Header>
        <cis:Authentification>
            <cis:user>2222222222_01</cis:user>
            <cis:signature>pass</cis:signature>
        </cis:Authentification>
    </soapenv:Header>
    <soapenv:Body>
        <ns:CreateShipmentOrderRequest>
            <ns:Version>
                <majorRelease>3</majorRelease>
                <minorRelease>4</minorRelease>
            </ns:Version>
            <ShipmentOrder>
                <sequenceNumber>1</sequenceNumber>
                <Shipment>
                    <ShipmentDetails>
                        <product>V01PAK</product>
                        <cis:accountNumber>22222222220102</cis:accountNumber>
                                                <ShipmentItem>
                            <weightInKG>1</weightInKG>
                            <lengthInCM>10</lengthInCM>
                            <widthInCM>33</widthInCM>
                            <heightInCM>18</heightInCM>
                        </ShipmentItem>
                        <Notification/>
                    </ShipmentDetails>
                    <Shipper>
                        <Name>
                            <cis:name1>Deut</cis:name1>
                            <cis:name2></cis:name2>
                        </Name>
                        <Address>
                            <cis:streetName>Römerberg</cis:streetName>
                            <cis:streetNumber>23</cis:streetNumber>
                            <cis:zip>60311</cis:zip>
                            <cis:city>Frankfurt</cis:city>
                            <cis:Origin>
                                <cis:country>Germany</cis:country>
                                <cis:countryISOCode>DE</cis:countryISOCode>
                            </cis:Origin>
                        </Address>
                        <Communication>
                            <cis:contactPerson>Deut</cis:contactPerson>
                        </Communication>
                    </Shipper>
                    <ShipperReference></ShipperReference>
                    <Receiver>
                        <cis:name1>Ana</cis:name1>
                        <Address>
                            <cis:streetName>Am Wall</cis:streetName>
                            <cis:streetNumber>207</cis:streetNumber>
                            <cis:zip>28195</cis:zip>
                            <cis:city>Bremen</cis:city>
                            <cis:Origin>
                                <cis:country>Germany</cis:country>
                                <cis:countryISOCode>DE</cis:countryISOCode>
                            </cis:Origin>
                        </Address>
                        <Communication>
                            <cis:contactPerson>Ana</cis:contactPerson>
                        </Communication>
                    </Receiver>
                </Shipment>
            </ShipmentOrder>
            <labelResponseType>B64</labelResponseType>
            <combinedPrinting>0</combinedPrinting>
        </ns:CreateShipmentOrderRequest>
    </soapenv:Body>
</soapenv:Envelope>

MarcoWel commented 8 months ago

How to test DHL REST API in Postman

Create App in DHL Developer Portal

For API testing, it is required to register on the DHL Developer Portal and request sandbox credentials by clicking on the "Get Access" button on the API page:

We need the following APIs for "Customer (Integration) Testing":

Parcel DE Shipping (Post & Parcel Germany)
Parcel DE Tracking (Post & Parcel Germany)

Now the app should appear as "approved" in the Developer Portal straight away. Click "Show key" to get the required API key for testing in Postman:

Run Postman Collection

Download the DHL Postman Collection, import it into Postman, enter the Sandbox API key to the variables and press save.

Now you can run any of the collection requests successfully straight away.

This is much better documented and much better to use than the old SOAP API.

danh91 commented 8 months ago

@MarcoWel,

Thanks for the details. I am hoping to close these final tasks for the official release of 2024.2 in the second week of February.

https://github.com/orgs/karrioapi/projects/12/views/1

karrioapi / karrio