karrio-dhl-poland 2025.5rc1__py3-none-any.whl

karrio/mappers/dhl_poland/__init__.py

@@ -0,0 +1,3 @@
+from karrio.mappers.dhl_poland.mapper import Mapper
+from karrio.mappers.dhl_poland.proxy import Proxy
+from karrio.mappers.dhl_poland.settings import Settings

karrio/mappers/dhl_poland/mapper.py

@@ -0,0 +1,51 @@
+"""Karrio DHL Poland client mapper."""
+
+import typing
+import karrio.lib as lib
+import karrio.api.mapper as mapper
+import karrio.core.models as models
+import karrio.universal.providers.rating as universal_provider
+import karrio.providers.dhl_poland as provider
+import karrio.mappers.dhl_poland.settings as provider_settings
+
+
+class Mapper(mapper.Mapper):
+    settings: provider_settings.Settings
+
+    def create_rate_request(self, payload: models.RateRequest) -> lib.Serializable:
+        return universal_provider.rate_request(payload, self.settings)
+
+    def create_tracking_request(
+        self, payload: models.TrackingRequest
+    ) -> lib.Serializable:
+        return provider.tracking_request(payload, self.settings)
+
+    def create_shipment_request(
+        self, payload: models.ShipmentRequest
+    ) -> lib.Serializable:
+        return provider.shipment_request(payload, self.settings)
+
+    def create_cancel_shipment_request(
+        self, payload: models.ShipmentCancelRequest
+    ) -> lib.Serializable:
+        return provider.shipment_cancel_request(payload, self.settings)
+
+    def parse_cancel_shipment_response(
+        self, response: lib.Deserializable
+    ) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+        return provider.parse_shipment_cancel_response(response, self.settings)
+
+    def parse_rate_response(
+        self, response: lib.Deserializable
+    ) -> typing.Tuple[typing.List[models.RateDetails], typing.List[models.Message]]:
+        return universal_provider.parse_rate_response(response, self.settings)
+
+    def parse_shipment_response(
+        self, response: lib.Deserializable
+    ) -> typing.Tuple[models.ShipmentDetails, typing.List[models.Message]]:
+        return provider.parse_shipment_response(response, self.settings)
+
+    def parse_tracking_response(
+        self, response: lib.Deserializable
+    ) -> typing.Tuple[typing.List[models.TrackingDetails], typing.List[models.Message]]:
+        return provider.parse_tracking_response(response, self.settings)

karrio/mappers/dhl_poland/proxy.py

@@ -0,0 +1,59 @@
+"""Karrio DHL Poland client proxy module."""
+import karrio.lib as lib
+import karrio.api.proxy as proxy
+import karrio.universal.mappers.rating_proxy as rating_proxy
+import karrio.mappers.dhl_poland.settings as provider_settings
+
+
+class Proxy(rating_proxy.RatingMixinProxy, proxy.Proxy):
+    settings: provider_settings.Settings
+
+    def _send_request(self, request: lib.Serializable, soapaction: str) -> str:
+        return lib.request(
+            url=f"{self.settings.server_url}",
+            data=request.serialize(),
+            trace=self.trace_as("xml"),
+            method="POST",
+            headers={
+                "Content-Type": "text/xml; charset=utf-8",
+                "soapaction": soapaction,
+            },
+        )
+
+    def get_rates(self, request: lib.Serializable) -> lib.Deserializable:
+        return super().get_rates(request)
+
+    def get_tracking(self, requests: lib.Serializable) -> lib.Deserializable:
+        responses = lib.run_asynchronously(
+            lambda request: dict(
+                number=request[0],
+                data=self._send_request(
+                    lib.Serializable(request[1]),
+                    soapaction=f"{self.settings.server_url}#getTrackAndTraceInfo",
+                ),
+            ),
+            requests.serialize().items(),
+        )
+
+        return lib.Deserializable(
+            responses,
+            lambda results: {
+                result["number"]: lib.to_element(result["data"]) for result in results
+            },
+        )
+
+    def create_shipment(self, request: lib.Serializable) -> lib.Deserializable:
+        response = self._send_request(
+            request,
+            soapaction=f"{self.settings.server_url}#createShipment",
+        )
+
+        return lib.Deserializable(response, lib.to_element)
+
+    def cancel_shipment(self, request: lib.Serializable) -> lib.Deserializable:
+        response = self._send_request(
+            request,
+            soapaction=f"{self.settings.server_url}#deleteShipment",
+        )
+
+        return lib.Deserializable(response, lib.to_element)

karrio/mappers/dhl_poland/settings.py

@@ -0,0 +1,34 @@
+"""Karrio DHL Parcel Poland client settings."""
+
+import attr
+import typing
+import jstruct
+import karrio.core.models as models
+import karrio.providers.dhl_poland.units as provider_units
+import karrio.providers.dhl_poland.utils as provider_utils
+from karrio.universal.mappers.rating_proxy import RatingMixinSettings
+
+
+@attr.s(auto_attribs=True)
+class Settings(provider_utils.Settings, RatingMixinSettings):
+    """DHL Parcel Poland connection settings."""
+
+    username: str  # type: ignore
+    password: str  # type: ignore
+    account_number: str = None
+
+    id: str = None
+    test_mode: bool = False
+    carrier_id: str = "dhl_poland"
+    account_country_code: str = "PL"
+    metadata: dict = {}
+    config: dict = {}
+
+    services: typing.List[models.ServiceLevel] = jstruct.JList[models.ServiceLevel, False, dict(default=provider_units.DEFAULT_SERVICES)]  # type: ignore
+
+    @property
+    def shipping_services(self) -> typing.List[models.ServiceLevel]:
+        if any(self.services or []):
+            return self.services
+
+        return provider_units.DEFAULT_SERVICES

karrio/plugins/dhl_poland/__init__.py

@@ -0,0 +1,23 @@
+import karrio.core.metadata as metadata
+import karrio.mappers.dhl_poland as mappers
+from karrio.providers.dhl_poland import units
+
+
+METADATA = metadata.PluginMetadata(
+    status="production-ready",
+    id="dhl_poland",
+    label="DHL Parcel Poland",
+    # Integrations
+    Mapper=mappers.Mapper,
+    Proxy=mappers.Proxy,
+    Settings=mappers.Settings,
+    # Data Units
+    services=units.Service,
+    options=units.ShippingOption,
+    packaging_types=units.PackagingType,
+    service_levels=units.DEFAULT_SERVICES,
+    # New fields
+    website="https://dhl24.com.pl/en",
+    documentation="https://dhl24.com.pl/en/webapi2/doc.html",
+    description="Global Logistics and International Shipping Poland.",
+)

karrio/providers/dhl_poland/__init__.py

@@ -0,0 +1,11 @@
+from karrio.providers.dhl_poland.utils import Settings
+from karrio.providers.dhl_poland.shipment import (
+    parse_shipment_cancel_response,
+    parse_shipment_response,
+    shipment_cancel_request,
+    shipment_request,
+)
+from karrio.providers.dhl_poland.tracking import (
+    parse_tracking_response,
+    tracking_request,
+)

karrio/providers/dhl_poland/error.py

@@ -0,0 +1,21 @@
+from typing import List
+from pysoap.envelope import Fault
+from karrio.core.models import Message
+from karrio.core.utils import Element, XP
+from karrio.providers.dhl_poland.utils import Settings
+
+
+def parse_error_response(
+    response: Element, settings: Settings, details: dict = None
+) -> List[Message]:
+    errors = XP.find("Fault", response, Fault)
+    return [
+        Message(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            message=error.faultstring,
+            code=error.faultcode,
+            details=details,
+        )
+        for error in errors
+    ]

karrio/providers/dhl_poland/shipment/__init__.py

@@ -0,0 +1,8 @@
+from karrio.providers.dhl_poland.shipment.create import (
+    parse_shipment_response,
+    shipment_request,
+)
+from karrio.providers.dhl_poland.shipment.cancel import (
+    parse_shipment_cancel_response,
+    shipment_cancel_request,
+)

karrio/providers/dhl_poland/shipment/cancel.py

@@ -0,0 +1,55 @@
+from typing import List, Tuple
+from karrio.schemas.dhl_poland.services import (
+    deleteShipment,
+    DeleteShipmentRequest,
+)
+from karrio.core.models import ShipmentCancelRequest, ConfirmationDetails, Message
+from karrio.core.utils import (
+    create_envelope,
+    Envelope,
+    Element,
+    Serializable,
+)
+from karrio.providers.dhl_poland.error import parse_error_response
+from karrio.providers.dhl_poland.utils import Settings
+import karrio.lib as lib
+
+
+def parse_shipment_cancel_response(
+    _response: lib.Deserializable[Element], settings: Settings
+) -> Tuple[ConfirmationDetails, List[Message]]:
+    response = _response.deserialize()
+    errors = parse_error_response(response, settings)
+    success = len(errors) == 0
+    confirmation: ConfirmationDetails = (
+        ConfirmationDetails(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            success=success,
+            operation="Cancel Shipment",
+        )
+        if success
+        else None
+    )
+
+    return confirmation, errors
+
+
+def shipment_cancel_request(
+    payload: ShipmentCancelRequest, settings: Settings
+) -> Serializable:
+    request = create_envelope(
+        body_content=deleteShipment(
+            authData=settings.auth_data,
+            shipment=DeleteShipmentRequest(
+                shipmentIdentificationNumber=payload.shipment_identifier
+            ),
+        )
+    )
+
+    return Serializable(
+        request,
+        lambda request: settings.serialize(
+            request, "deleteShipment", settings.server_url
+        ),
+    )

karrio/providers/dhl_poland/shipment/create.py

@@ -0,0 +1,307 @@
+import karrio.schemas.dhl_poland.services as dhl
+import time
+import typing
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+import karrio.providers.dhl_poland.error as provider_error
+import karrio.providers.dhl_poland.units as provider_units
+import karrio.providers.dhl_poland.utils as provider_utils
+
+
+def parse_shipment_response(
+    _response: lib.Deserializable[lib.Element], settings: provider_utils.Settings
+) -> typing.Tuple[models.ShipmentDetails, typing.List[models.Message]]:
+    response = _response.deserialize()
+    errors = provider_error.parse_error_response(response, settings)
+    shipment = (
+        _extract_details(response, settings)
+        if lib.find_element("createShipmentResult", response, first=True) is not None
+        else None
+    )
+
+    return shipment, errors
+
+
+def _extract_details(
+    response: lib.Element,
+    settings: provider_utils.Settings,
+) -> models.ShipmentDetails:
+    shipment: dhl.CreateShipmentResponse = lib.find_element(
+        "createShipmentResult", response, dhl.CreateShipmentResponse, first=True
+    )
+
+    return models.ShipmentDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        tracking_number=shipment.shipmentNotificationNumber,
+        shipment_identifier=shipment.shipmentTrackingNumber,
+        docs=models.Documents(
+            label=shipment.label.labelContent,
+            invoice=shipment.label.fvProformaContent,
+        ),
+        meta=dict(
+            carrier_tracking_link=settings.tracking_url.format(
+                shipment.shipmentNotificationNumber
+            ),
+        ),
+    )
+
+
+def shipment_request(
+    payload: models.ShipmentRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    packages = lib.to_packages(
+        payload.parcels,
+        required=["weight"],
+        package_option_type=provider_units.ShippingOption,
+    )
+    shipper = lib.to_address(payload.shipper)
+    recipient = lib.to_address(payload.recipient)
+    customs = lib.to_customs_info(payload.customs, weight_unit=packages.weight_unit)
+    options = lib.to_shipping_options(
+        payload.options,
+        package_options=packages.options,
+        initializer=provider_units.shipping_options_initializer,
+    )
+
+    is_international = shipper.country_code != recipient.country_code
+    service_type = provider_units.Service.map(payload.service).value_or_key or (
+        provider_units.Service.dhl_poland_polska.value
+        if is_international
+        else provider_units.Service.dhl_poland_09.value
+    )
+    label_type = provider_units.LabelType.map(payload.label_type or "PDF").value
+    payment = payload.payment or models.Payment()
+    quantity = len(customs.commodities or []) if customs.is_defined else 1
+
+    request = lib.create_envelope(
+        body_content=dhl.createShipment(
+            authData=settings.auth_data,
+            shipment=dhl.CreateShipmentRequest(
+                shipmentInfo=dhl.ShipmentInfo(
+                    wayBill=None,
+                    dropOffType="REGULAR_PICKUP",
+                    serviceType=service_type,
+                    billing=dhl.Billing(
+                        shippingPaymentType=provider_units.PaymentType[
+                            payment.paid_by
+                        ].value,
+                        billingAccountNumber=(
+                            payment.account_number or settings.account_number
+                        ),
+                        paymentType="BANK_TRANSFER",
+                        costsCenter=None,
+                    ),
+                    specialServices=(
+                        dhl.ArrayOfService(
+                            item=[
+                                dhl.Service(
+                                    serviceType=option.code,
+                                    serviceValue=lib.to_money(option.state),
+                                    textInstruction=None,
+                                    collectOnDeliveryForm=None,
+                                )
+                                for _, option in options.items()
+                            ]
+                        )
+                        if any(options.items())
+                        else None
+                    ),
+                    shipmentTime=(
+                        dhl.ShipmentTime(
+                            shipmentDate=(
+                                options.shipment_date.state or time.strftime("%Y-%m-%d")
+                            ),
+                            shipmentStartHour="10:00",
+                            shipmentEndHour="10:00",
+                        )
+                    ),
+                    labelType=label_type,
+                ),
+                content=payload.parcels[0].content or "N/A",
+                comment=None,
+                reference=payload.reference,
+                ship=dhl.Ship(
+                    shipper=dhl.Addressat(
+                        preaviso=(
+                            dhl.PreavisoContact(
+                                personName=shipper.person_name,
+                                phoneNumber=shipper.phone_number,
+                                emailAddress=shipper.email,
+                            )
+                            if any(
+                                [
+                                    shipper.person_name,
+                                    shipper.phone_number,
+                                    shipper.email,
+                                ]
+                            )
+                            else None
+                        ),
+                        contact=(
+                            dhl.PreavisoContact(
+                                personName=shipper.person_name,
+                                phoneNumber=shipper.phone_number,
+                                emailAddress=shipper.email,
+                            )
+                            if any(
+                                [
+                                    shipper.person_name,
+                                    shipper.phone_number,
+                                    shipper.email,
+                                ]
+                            )
+                            else None
+                        ),
+                        address=dhl.Address(
+                            name=(shipper.company_name or shipper.person_name),
+                            postalCode=(shipper.postal_code or "").replace("-", ""),
+                            city=shipper.city,
+                            street=shipper.address_line1,
+                            houseNumber=(shipper.street_number or "N/A"),
+                            apartmentNumber=shipper.address_line2,
+                        ),
+                    ),
+                    receiver=dhl.ReceiverAddressat(
+                        preaviso=(
+                            dhl.PreavisoContact(
+                                personName=recipient.person_name,
+                                phoneNumber=recipient.phone_number,
+                                emailAddress=recipient.email,
+                            )
+                            if any(
+                                [
+                                    recipient.person_name,
+                                    recipient.phone_number,
+                                    recipient.email,
+                                ]
+                            )
+                            else None
+                        ),
+                        contact=(
+                            dhl.PreavisoContact(
+                                personName=recipient.person_name,
+                                phoneNumber=recipient.phone_number,
+                                emailAddress=recipient.email,
+                            )
+                            if any(
+                                [
+                                    recipient.person_name,
+                                    recipient.phone_number,
+                                    recipient.email,
+                                ]
+                            )
+                            else None
+                        ),
+                        address=dhl.ReceiverAddress(
+                            country=recipient.country_code,
+                            isPackstation=None,
+                            isPostfiliale=None,
+                            postnummer=None,
+                            addressType=("C" if recipient.residential else "B"),
+                            name=(recipient.company_name or recipient.person_name),
+                            postalCode=(recipient.postal_code or "").replace("-", ""),
+                            city=recipient.city,
+                            street=recipient.address_line1,
+                            houseNumber=(shipper.street_number or "N/A"),
+                            apartmentNumber=recipient.address_line2,
+                        ),
+                    ),
+                    neighbour=None,
+                ),
+                pieceList=dhl.ArrayOfPackage(
+                    item=[
+                        dhl.Package(
+                            type_=provider_units.PackagingType[
+                                package.packaging_type or "your_packaging"
+                            ].value,
+                            euroReturn=None,
+                            weight=package.weight.KG,
+                            width=package.width.CM,
+                            height=package.height.CM,
+                            length=package.length.CM,
+                            quantity=quantity,
+                            nonStandard=None,
+                            blpPieceId=None,
+                        )
+                        for package in packages
+                    ]
+                ),
+                customs=(
+                    dhl.CustomsData(
+                        customsType="S",
+                        firstName=getattr(
+                            getattr(customs.duty, "bil_to", shipper.company_name),
+                            "company_name",
+                            "N/A",
+                        ),
+                        secondaryName=getattr(
+                            getattr(customs.duty, "bil_to", shipper.person_name),
+                            "person_name",
+                            "N/A",
+                        ),
+                        costsOfShipment=(
+                            getattr(customs.duty, "declared_value", None)
+                            or options.declard_value.state
+                        ),
+                        currency=(
+                            getattr(customs.duty, "currency", None)
+                            or options.currency.state
+                        ),
+                        nipNr=customs.options.nip_number.state,
+                        eoriNr=customs.options.eori_number.state,
+                        vatRegistrationNumber=customs.options.vat_registration_number.state,
+                        categoryOfItem=provider_units.CustomsContentType[
+                            customs.content_type or "other"
+                        ].value,
+                        invoiceNr=customs.invoice,
+                        invoice=None,
+                        invoiceDate=customs.invoice_date,
+                        countryOfOrigin=shipper.country_code,
+                        additionalInfo=None,
+                        grossWeight=packages.weight.KG,
+                        customsItem=(
+                            dhl.ArrayOfCustomsitemdata(
+                                item=[
+                                    dhl.CustomsItemData(
+                                        nameEn=lib.text(
+                                            item.title or item.description or "N/A",
+                                            max=35,
+                                        ),
+                                        namePl=lib.text(
+                                            item.title or item.description or "N/A",
+                                            max=35,
+                                        ),
+                                        quantity=item.quantity,
+                                        weight=units.Weight(
+                                            item.weight,
+                                            units.WeightUnit[item.weight_unit or "KG"],
+                                        ).KG,
+                                        value=item.value_amount,
+                                        tariffCode=item.hs_code or item.sku,
+                                    )
+                                    for item in customs.commodities
+                                ]
+                            )
+                            if any(customs.commodities)
+                            else None
+                        ),
+                        customAgreements=dhl.CustomsAgreementData(
+                            notExceedValue=True,
+                            notProhibitedGoods=True,
+                            notRestrictedGoods=True,
+                        ),
+                    )
+                    if customs.is_defined
+                    else None
+                ),
+            ),
+        )
+    )
+
+    return lib.Serializable(
+        request,
+        lambda req: settings.serialize(req, "createShipment", settings.server_url),
+    )

karrio/providers/dhl_poland/tracking.py

@@ -0,0 +1,91 @@
+import karrio.schemas.dhl_poland.services as dhl
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.dhl_poland.error as provider_error
+import karrio.providers.dhl_poland.utils as provider_utils
+
+
+def parse_tracking_response(
+    _response: lib.Deserializable[typing.Dict[str, lib.Element]],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.List[models.TrackingDetails], typing.List[models.Message]]:
+    response = _response.deserialize()
+    details = [
+        _extract_tracking_details(node, settings)
+        for node in response.values()
+        if lib.find_element("getTrackAndTraceInfoResult", node, first=True) is not None
+    ]
+    errors: typing.List[models.Message] = sum(
+        [
+            provider_error.parse_error_response(
+                node, settings, dict(tracking_number=number)
+            )
+            for number, node in response.items()
+            if lib.find_element("Fault", node, first=True) is not None
+        ],
+        [],
+    )
+
+    return details, errors
+
+
+def _extract_tracking_details(
+    node: lib.Element,
+    settings: provider_utils.Settings,
+) -> models.TrackingDetails:
+    track: dhl.TrackAndTraceResponse = lib.find_element(
+        "getTrackAndTraceInfoResult", node, dhl.TrackAndTraceResponse, first=True
+    )
+    events = [
+        lib.to_object(dhl.TrackAndTraceEvent, item)
+        for item in lib.find_element("item", node)
+    ]
+
+    return models.TrackingDetails(
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        tracking_number=track.shipmentId,
+        events=[
+            models.TrackingEvent(
+                date=lib.fdate(event.timestamp, "%Y-%m-%d %H:%M:%S"),
+                description=event.description,
+                location=event.terminal,
+                code=event.status,
+                time=lib.flocaltime(event.timestamp, "%Y-%m-%d %H:%M:%S"),
+            )
+            for event in events
+        ],
+        delivered=any(track.receivedBy or ""),
+        info=models.TrackingInfo(
+            carrier_tracking_link=settings.tracking_url.format(track.shipmentId),
+        ),
+    )
+
+
+def tracking_request(
+    payload: models.TrackingRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    requests = {
+        tracking_number: lib.create_envelope(
+            body_prefix="",
+            body_content=dhl.getTrackAndTraceInfo(
+                authData=settings.auth_data,
+                shipmentId=tracking_number,
+            ),
+        )
+        for tracking_number in payload.tracking_numbers
+    }
+
+    return lib.Serializable(
+        requests,
+        lambda requests: {
+            number: settings.serialize(
+                request,
+                "getTrackAndTraceInfo",
+                settings.server_url,
+            )
+            for number, request in requests.items()
+        },
+    )