karrio-tnt 2025.5rc1__py3-none-any.whl

karrio/mappers/tnt/__init__.py

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

karrio/mappers/tnt/mapper.py

@@ -0,0 +1,40 @@
+"""Karrio TNT client mapper."""
+
+import typing
+import karrio.lib as lib
+import karrio.api.mapper as mapper
+import karrio.core.models as models
+import karrio.providers.tnt as provider
+import karrio.mappers.tnt.settings as provider_settings
+
+
+class Mapper(mapper.Mapper):
+    settings: provider_settings.Settings
+
+    def create_rate_request(self, payload: models.RateRequest) -> lib.Serializable:
+        return 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 parse_rate_response(
+        self, response: lib.Deserializable
+    ) -> typing.Tuple[typing.List[models.RateDetails], typing.List[models.Message]]:
+        return 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/tnt/proxy.py

@@ -0,0 +1,97 @@
+import urllib.parse
+import karrio.lib as lib
+import karrio.api.proxy as proxy
+import karrio.providers.tnt.error as provider_error
+import karrio.providers.tnt.utils as provider_utils
+import karrio.mappers.tnt.settings as provider_settings
+
+
+class Proxy(proxy.Proxy):
+    settings: provider_settings.Settings
+
+    """ Proxy Methods """
+
+    def get_rates(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = lib.request(
+            url=f"{self.settings.server_url}/expressconnect/pricing/getprice",
+            data=urllib.parse.urlencode(dict(xml_in=request.serialize())),
+            trace=self.trace_as("xml"),
+            method="POST",
+            headers={
+                "Content-Type": "application/x-www-form-urlencoded",
+                "Authorization": f"Basic {self.settings.authorization}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_element)
+
+    def create_shipment(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        ctx: dict = {}
+        shipment_response = lib.request(
+            url=f"{self.settings.server_url}/expressconnect/shipping/ship",
+            data=urllib.parse.urlencode(dict(xml_in=request.serialize())),
+            trace=self.trace_as("xml"),
+            method="POST",
+            headers={
+                "Content-Type": "application/x-www-form-urlencoded",
+                "Authorization": f"Basic {self.settings.authorization}",
+            },
+        )
+
+        label_request = provider_utils.create_label_request(
+            shipment_response, self.settings, request.ctx
+        )
+
+        if label_request is not None:
+            label_response = lib.request(
+                url=f"{self.settings.server_url}/expresslabel/documentation/getlabel",
+                trace=self.trace_as("xml"),
+                method="POST",
+                headers={
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    "Authorization": f"Basic {self.settings.authorization}",
+                },
+                data=urllib.parse.urlencode(dict(xml_in=label_request.serialize())),
+            )
+
+            label_errors = provider_error.parse_error_response(
+                lib.to_element(label_response), self.settings
+            )
+
+            if not any(label_errors):
+                label = lib.request(
+                    url=f"{self.settings.server_url}/expresswebservices-website/app/render.html",
+                    trace=self.trace_as("xml"),
+                    method="POST",
+                    headers={
+                        "Content-Type": "application/x-www-form-urlencoded",
+                        "Authorization": f"Basic {self.settings.authorization}",
+                    },
+                    data=urllib.parse.urlencode(
+                        dict(
+                            responseXml=label_response,
+                            documentType="routingLabel",
+                            contentType="pdf",
+                        ),
+                    ),
+                    decoder=lib.encode_base64,
+                )
+
+                ctx.update(label=label)
+
+        return lib.Deserializable(shipment_response, lib.to_element, ctx=ctx)
+
+    def get_tracking(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        response = lib.request(
+            url="https://necta.az.fxei.fedex.com/ectrack/track",
+            data=urllib.parse.urlencode(dict(xml_in=request.serialize())),
+            trace=self.trace_as("xml"),
+            method="POST",
+            headers={
+                "accept": "text/xml; charset=UTF-8",
+                "Content-Type": "application/x-www-form-urlencoded",
+                "Authorization": f"Basic {self.settings.authorization}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_element)

karrio/mappers/tnt/settings.py

@@ -0,0 +1,22 @@
+"""Karrio TNT settings."""
+
+import attr
+import karrio.providers.tnt.utils as provider_utils
+
+
+@attr.s(auto_attribs=True)
+class Settings(provider_utils.Settings):
+    """TNT connection settings."""
+
+    # Carrier specific properties
+    username: str
+    password: str
+    account_number: str = None
+    account_country_code: str = None
+    metadata: dict = {}
+    config: dict = {}
+
+    # Base properties
+    id: str = None
+    test_mode: bool = False
+    carrier_id: str = "tnt"

karrio/plugins/tnt/__init__.py

@@ -0,0 +1,24 @@
+import karrio.core.metadata as metadata
+import karrio.mappers.tnt as mappers
+import karrio.providers.tnt.units as units
+
+
+METADATA = metadata.PluginMetadata(
+    status="beta",
+    id="tnt",
+    label="TNT",
+    # Integrations
+    Mapper=mappers.Mapper,
+    Proxy=mappers.Proxy,
+    Settings=mappers.Settings,
+    # Data Units
+    options=units.ShippingOption,
+    services=units.ShippingService,
+    packaging_types=units.PackageType,
+    package_presets=units.PackagePresets,
+    connection_configs=units.ConnectionConfig,
+    has_intl_accounts=True,
+    # New fields
+    website="https://www.tnt.com",
+    description="TNT is an international courier delivery services company with headquarters in the Netherlands.",
+)

karrio/providers/tnt/__init__.py

@@ -0,0 +1,10 @@
+from karrio.providers.tnt.utils import Settings
+from karrio.providers.tnt.rate import parse_rate_response, rate_request
+from karrio.providers.tnt.shipment import (
+    parse_shipment_response,
+    shipment_request,
+)
+from karrio.providers.tnt.tracking import (
+    parse_tracking_response,
+    tracking_request,
+)

karrio/providers/tnt/error.py

@@ -0,0 +1,129 @@
+import karrio.schemas.tnt.rating_response as tnt
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.tnt.utils as provider_utils
+
+
+def parse_error_response(
+    response,
+    settings: provider_utils.Settings,
+) -> typing.List[models.Message]:
+    structure_errors = lib.find_element("ErrorStructure", response)
+    broken_rules_nodes = lib.find_element("brokenRules", response)
+    broken_rule_nodes = lib.find_element("brokenRule", response)
+    runtime_errors = lib.find_element("runtime_error", response)
+    parse_errors = lib.find_element("parse_error", response)
+    ERRORS = lib.find_element("ERROR", response)
+    errors = lib.find_element("Error", response)
+    faults = lib.find_element("fault", response)
+
+    return [
+        *[_extract_structure_error(node, settings) for node in structure_errors],
+        *[_extract_broken_rules(node, settings) for node in broken_rules_nodes],
+        *[_extract_broken_rule(node, settings) for node in broken_rule_nodes],
+        *[_extract_runtime_error(node, settings) for node in runtime_errors],
+        *[_extract_parse_error(node, settings) for node in parse_errors],
+        *[_extract_structure_error(node, settings) for node in errors],
+        *[_extract_error(node, settings) for node in ERRORS],
+        *[_extract_faut(node, settings) for node in faults],
+    ]
+
+
+def _extract_structure_error(
+    node: lib.Element, settings: provider_utils.Settings
+) -> models.Message:
+    return models.Message(
+        # context info
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        # carrier error info
+        code=lib.find_element("Code", node, first=True).text,
+        message=lib.find_element("Message", node, first=True).text,
+    )
+
+
+def _extract_broken_rules(
+    node: lib.Element, settings: provider_utils.Settings
+) -> models.Message:
+    return models.Message(
+        # context info
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        # carrier error info
+        code=lib.find_element("errorCode", node, first=True).text,
+        message=lib.find_element("errorMessage", node, first=True).text,
+    )
+
+
+def _extract_broken_rule(
+    node: lib.Element, settings: provider_utils.Settings
+) -> models.Message:
+    error = lib.to_object(tnt.brokenRule, node)
+
+    return models.Message(
+        # context info
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        # carrier error info
+        code=getattr(error, "code", None),
+        message=getattr(error, "description", None),
+        details=dict(messageType=getattr(error, "messageType", None)),
+    )
+
+
+def _extract_runtime_error(
+    node: lib.Element, settings: provider_utils.Settings
+) -> models.Message:
+    error = lib.to_object(tnt.runtimeError, node)
+
+    return models.Message(
+        # context info
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        # carrier error info
+        code="runtime",
+        message=getattr(error, "errorReason", None),
+        details=dict(srcTxt=getattr(error, "errorSrcText", None)),
+    )
+
+
+def _extract_parse_error(
+    node: lib.Element, settings: provider_utils.Settings
+) -> models.Message:
+    error = lib.to_object(tnt.parseError, node)
+
+    return models.Message(
+        # context info
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        # carrier error info
+        code="parsing",
+        message=getattr(error, "errorReason", None),
+        details=dict(srcText=getattr(error, "errorSrcText", None)),
+    )
+
+
+def _extract_error(
+    node: lib.Element, settings: provider_utils.Settings
+) -> models.Message:
+    return models.Message(
+        # context info
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        # carrier error info
+        code=lib.find_element("CODE", node, first=True).text,
+        message=lib.find_element("DESCRIPTION", node, first=True).text,
+    )
+
+
+def _extract_faut(
+    node: lib.Element, settings: provider_utils.Settings
+) -> models.Message:
+    return models.Message(
+        # context info
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        # carrier error info
+        code=lib.find_element("key", node, first=True).text,
+    )

karrio/providers/tnt/rate.py

@@ -0,0 +1,184 @@
+import functools
+import karrio.schemas.tnt.rating_request as tnt
+import karrio.schemas.tnt.rating_response as rating
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.tnt.error as provider_error
+import karrio.providers.tnt.units as provider_units
+import karrio.providers.tnt.utils as provider_utils
+
+
+def parse_rate_response(
+    _response: lib.Deserializable[lib.Element],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.List[models.RateDetails], typing.List[models.Message]]:
+    response = _response.deserialize()
+
+    messages = provider_error.parse_error_response(response, settings)
+    services: typing.List[rating.ratedServices] = lib.find_element(
+        "ratedServices", response, rating.ratedServices
+    )
+    rates: typing.List[models.RateDetails] = sum(
+        [
+            [
+                _extract_details((rate, svc.currency), settings)
+                for rate in svc.ratedService
+            ]
+            for svc in services
+        ],
+        start=[],
+    )
+
+    return rates, messages
+
+
+def _extract_details(
+    details: typing.Tuple[rating.ratedService, str],
+    settings: provider_utils.Settings,
+) -> models.RateDetails:
+    rate, currency = details
+    service = provider_units.ShippingService.map(rate.product.id)
+    charges = [
+        ("Base charge", rate.totalPriceExclVat),
+        ("VAT", rate.vatAmount),
+        *(
+            (charge.description, charge.chargeValue)
+            for charge in rate.chargeElements.chargeElement
+        ),
+    ]
+
+    return models.RateDetails(
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        currency=currency,
+        service=service.name_or_key,
+        total_charge=lib.to_decimal(rate.totalPrice),
+        extra_charges=[
+            models.ChargeDetails(
+                name=name,
+                amount=lib.to_decimal(amount),
+                currency=currency,
+            )
+            for name, amount in charges
+            if amount is not None
+        ],
+        meta=dict(service_name=rate.product.productDesc),
+    )
+
+
+def rate_request(
+    payload: models.RateRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    service = lib.to_services(payload.services, provider_units.ShippingService).first
+    packages = lib.to_packages(
+        payload.parcels,
+        presets=provider_units.PackagePresets,
+        package_option_type=provider_units.PackageType,
+    )
+    options = lib.to_shipping_options(
+        payload.options,
+        package_options=packages.options,
+        shipper_country_code=payload.shipper.country_code,
+        recipient_country_code=payload.recipient.country_code,
+        is_international=(
+            payload.shipper.country_code != payload.recipient.country_code
+        ),
+        initializer=provider_units.shipping_options_initializer,
+    )
+    is_document = all([parcel.is_document for parcel in payload.parcels])
+
+    request = tnt.priceRequest(
+        appId=settings.connection_config.app_id.state or "PC",
+        appVersion="3.2",
+        priceCheck=[
+            tnt.priceCheck(
+                rateId=None,
+                sender=tnt.address(
+                    country=payload.shipper.country_code,
+                    town=payload.shipper.city,
+                    postcode=payload.shipper.postal_code,
+                ),
+                delivery=tnt.address(
+                    country=payload.recipient.country_code,
+                    town=payload.recipient.city,
+                    postcode=payload.recipient.postal_code,
+                ),
+                collectionDateTime=lib.fdatetime(
+                    options.shipment_date.state,
+                    current_format="%Y-%m-%d",
+                    output_format="%Y-%m-%dT%H:%M:%S",
+                ),
+                product=tnt.product(
+                    id=getattr(service, "value", None),
+                    division=next(
+                        (
+                            option.code
+                            for key, option in options.items()
+                            if "division" in key and option.state is True
+                        ),
+                        None,
+                    ),
+                    productDesc=None,
+                    type_=("D" if is_document else "N"),
+                    options=(
+                        tnt.options(
+                            option=[
+                                tnt.option(optionCode=option.code)
+                                for key, option in options.items()
+                                if "division" not in key
+                            ]
+                        )
+                        if any(options.items())
+                        else None
+                    ),
+                ),
+                account=(
+                    tnt.account(
+                        accountNumber=settings.account_number,
+                        accountCountry=settings.account_country_code,
+                    )
+                    if any([settings.account_number, settings.account_country_code])
+                    else None
+                ),
+                insurance=(
+                    tnt.insurance(
+                        insuranceValue=options.insurance.state,
+                        goodsValue=options.declared_value.state,
+                    )
+                    if options.insurance.state is not None
+                    else None
+                ),
+                termsOfPayment=provider_units.PaymentType.sender.value,
+                currency=options.currency.state,
+                priceBreakDown=True,
+                consignmentDetails=tnt.consignmentDetails(
+                    totalWeight=packages.weight.KG,
+                    totalVolume=packages.volume.m3,
+                    totalNumberOfPieces=len(packages),
+                ),
+                pieceLine=[
+                    tnt.pieceLine(
+                        numberOfPieces=1,
+                        pieceMeasurements=tnt.pieceMeasurements(
+                            length=package.length.M,
+                            width=package.width.M,
+                            height=package.height.M,
+                            weight=package.weight.KG,
+                        ),
+                        pallet=(package.packaging_type == "pallet"),
+                    )
+                    for package in packages
+                ],
+            )
+        ],
+    )
+
+    return lib.Serializable(
+        request,
+        functools.partial(
+            lib.to_xml,
+            namespacedef_='xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"',
+        ),
+    )

karrio/providers/tnt/shipment/__init__.py

@@ -0,0 +1,4 @@
+from karrio.providers.tnt.shipment.create import (
+    parse_shipment_response,
+    shipment_request,
+)