karrio-tnt 2025.5rc1__py3-none-any.whl

karrio/providers/tnt/shipment/create.py

@@ -0,0 +1,226 @@
+import karrio.schemas.tnt.shipping_request as tnt
+import karrio.schemas.tnt.shipping_response as shipping
+import uuid
+import typing
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+import karrio.providers.tnt.error as provider_error
+import karrio.providers.tnt.utils as provider_utils
+import karrio.providers.tnt.units as provider_units
+
+
+def parse_shipment_response(
+    _response: lib.Deserializable[lib.Element],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[models.ShipmentDetails, typing.List[models.Message]]:
+    response = _response.deserialize()
+
+    messages = provider_error.parse_error_response(response, settings)
+    create: shipping.CREATE = lib.find_element(
+        "CREATE", response, element_type=shipping.CREATE, first=True
+    )
+    shipment = (
+        _extract_detail(create, settings, ctx=_response.ctx)
+        if getattr(create, "SUCCESS", None) == "Y"
+        else None
+    )
+
+    return shipment, messages
+
+
+def _extract_detail(
+    detail: shipping.CREATE,
+    settings: provider_utils.Settings,
+    ctx: dict,
+) -> typing.Optional[models.ShipmentDetails]:
+    label = ctx.get("label")
+
+    return models.ShipmentDetails(
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        tracking_number=detail.CONNUMBER,
+        shipment_identifier=detail.CONREF,
+        docs=models.Documents(label=label),
+    )
+
+
+def shipment_request(
+    payload: models.ShipmentRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    shipper = lib.to_address(payload.shipper)
+    recipient = lib.to_address(payload.recipient)
+    packages = lib.to_packages(payload.parcels)
+    service = provider_units.ShippingService.map(payload.service).value_or_key
+    payment = payload.payment or models.Payment(paid_by="sender")
+    is_document = all([parcel.is_document for parcel in payload.parcels])
+    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,
+    )
+    ref = payload.parcels[0].reference_number or f"ref_{uuid.uuid4()}"
+    insurance = options.tnt_insurance.state
+
+    request = tnt.ESHIPPER(
+        LOGIN=tnt.LOGIN(
+            COMPANY=settings.username,
+            PASSWORD=settings.password,
+            APPID=settings.connection_config.app_id.state or "EC",
+            APPVERSION="3.1",
+        ),
+        CONSIGNMENTBATCH=tnt.CONSIGNMENTBATCH(
+            GROUPCODE=None,
+            SENDER=tnt.SENDER(
+                COMPANYNAME=shipper.company_name,
+                STREETADDRESS1=shipper.address_line1,
+                STREETADDRESS2=shipper.address_line2,
+                STREETADDRESS3=None,
+                CITY=shipper.city,
+                PROVINCE=shipper.state_code,
+                POSTCODE=shipper.postal_code,
+                COUNTRY=shipper.country_code,
+                ACCOUNT=settings.account_number,
+                VAT=shipper.tax_id,
+                CONTACTNAME=shipper.person_name,
+                CONTACTDIALCODE=None,
+                CONTACTTELEPHONE=shipper.phone_number,
+                CONTACTEMAIL=shipper.email,
+                COLLECTION=tnt.COLLECTION(
+                    COLLECTIONADDRESS=None,
+                    SHIPDATE=lib.fdatetime(
+                        options.shipment_date.state,
+                        current_format="%Y-%m-%d",
+                        output_format="%d/%m/%Y",
+                    ),
+                    PREFCOLLECTTIME=None,
+                    ALTCOLLECTTIME=None,
+                    COLLINSTRUCTIONS=None,
+                    CONFIRMATIONEMAILADDRESS=None,
+                ),
+            ),
+            CONSIGNMENT=[
+                tnt.CONSIGNMENT(
+                    CONREF=ref,
+                    DETAILS=tnt.DETAILS(
+                        RECEIVER=tnt.RECEIVER(
+                            COMPANYNAME=recipient.company_name,
+                            STREETADDRESS1=recipient.address_line1,
+                            STREETADDRESS2=recipient.address_line2,
+                            STREETADDRESS3=None,
+                            CITY=recipient.city,
+                            PROVINCE=recipient.state_code,
+                            POSTCODE=recipient.postal_code,
+                            COUNTRY=recipient.country_code,
+                            VAT=recipient.tax_id,
+                            CONTACTNAME=recipient.person_name,
+                            CONTACTDIALCODE=None,
+                            CONTACTTELEPHONE=recipient.phone_number,
+                            CONTACTEMAIL=recipient.email,
+                            ACCOUNT=None,
+                            ACCOUNTCOUNTRY=None,
+                        ),
+                        DELIVERY=None,
+                        CONNUMBER=None,
+                        CUSTOMERREF=payload.reference,
+                        CONTYPE=("D" if is_document else "N"),
+                        PAYMENTIND=provider_units.PaymentType.map(
+                            payment.paid_by
+                        ).value,
+                        ITEMS=len(packages),
+                        TOTALWEIGHT=packages.weight.KG,
+                        TOTALVOLUME=packages.volume.m3,
+                        CURRENCY=options.currency.state,
+                        GOODSVALUE=options.declared_value.state,
+                        INSURANCEVALUE=insurance,
+                        INSURANCECURRENCY=options.currency.state,
+                        DIVISION=None,
+                        SERVICE=service,
+                        OPTION=[
+                            option.code
+                            for _, option in options.items()
+                            if "division" not in _
+                        ],
+                        DESCRIPTION=None,
+                        DELIVERYINST=None,
+                        CUSTOMCONTROLIN=None,
+                        HAZARDOUS=None,
+                        UNNUMBER=None,
+                        PACKINGGROUP=None,
+                        PACKAGE=[
+                            tnt.PACKAGE(
+                                ITEMS=package.items.quantity,
+                                DESCRIPTION=package.parcel.description,
+                                LENGTH=package.length.M,
+                                HEIGHT=package.height.M,
+                                WIDTH=package.width.M,
+                                WEIGHT=package.weight.KG,
+                                ARTICLE=(
+                                    [
+                                        tnt.ARTICLE(
+                                            ITEMS=item.quantity,
+                                            DESCRIPTION=lib.text(
+                                                item.title or item.description or "N/A",
+                                                max=35,
+                                            ),
+                                            WEIGHT=units.Weight(
+                                                item.weight,
+                                                units.WeightUnit[item.weight_unit],
+                                            ).KG,
+                                            INVOICEVALUE=item.value_amount,
+                                            INVOICEDESC=lib.text(
+                                                item.description or item.title,
+                                                max=35,
+                                            ),
+                                            HTS=item.hs_code or item.sku,
+                                            COUNTRY=item.origin_country,
+                                        )
+                                        for item in package.items
+                                    ]
+                                    if len(package.items) > 0
+                                    else None
+                                ),
+                            )
+                            for package in packages
+                        ],
+                    ),
+                )
+            ],
+        ),
+        ACTIVITY=tnt.ACTIVITY(
+            CREATE=tnt.CREATE(CONREF=[ref]),
+            RATE=tnt.RATE(CONREF=[ref]),
+            BOOK=tnt.BOOK(CONREF=[ref]),
+            SHIP=tnt.SHIP(CONREF=[ref]),
+            PRINT=tnt.PRINT(
+                REQUIRED=tnt.REQUIRED(CONREF=[ref]),
+                CONNOTE=tnt.CONNOTE(CONREF=[ref]),
+                LABEL=tnt.LABEL(CONREF=[ref]),
+                MANIFEST=tnt.MANIFEST(CONREF=[ref]),
+                INVOICE=tnt.INVOICE(CONREF=[ref]),
+                EMAILTO=(
+                    tnt.EMAILTO(
+                        type_=None,
+                        valueOf_=(
+                            options.email_notification_to.state or recipient.email
+                        ),
+                    )
+                    if (
+                        options.email_notification.state
+                        and any([options.email_notification_to.state, recipient.email])
+                    )
+                    else None
+                ),
+                EMAILFROM=settings.connection_config.email_from.state,
+            ),
+            SHOW_GROUPCODE=tnt.SHOW_GROUPCODE(),
+        ),
+    )
+
+    return lib.Serializable(request, lib.to_xml, dict(payload=payload))

karrio/providers/tnt/tracking.py

@@ -0,0 +1,71 @@
+import karrio.schemas.tnt.tracking_request as tnt
+import karrio.schemas.tnt.tracking_response as tracking
+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.utils as provider_utils
+import karrio.providers.tnt.units as provider_units
+
+
+def parse_tracking_response(
+    _response: lib.Deserializable[lib.Element],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.List[models.TrackingDetails], typing.List[models.Message]]:
+    response = _response.deserialize()
+    messages = provider_error.parse_error_response(response, settings)
+    tracking_details = [
+        _extract_detail(node, settings)
+        for node in lib.find_element("Consignment", response)
+    ]
+
+    return tracking_details, messages
+
+
+def _extract_detail(
+    node: dict, settings: provider_utils.Settings
+) -> models.TrackingDetails:
+    detail = lib.to_object(tracking.ConsignmentType, node)
+    events: typing.List[tracking.StatusStructure] = detail.StatusData
+
+    return models.TrackingDetails(
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        tracking_number=detail.ConsignmentNumber,
+        events=[
+            models.TrackingEvent(
+                date=lib.fdate(status.LocalEventDate.valueOf_, "%Y%m%d"),
+                description=status.StatusDescription,
+                location=lib.join(
+                    status.Depot, status.DepotName, join=True, separator="-"
+                ),
+                code=status.StatusCode,
+                time=lib.flocaltime(status.LocalEventTime.valueOf_, "%H%M"),
+            )
+            for status in events
+        ],
+        delivered=(detail.SummaryCode == "DEL"),
+    )
+
+
+def tracking_request(
+    payload: models.TrackingRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    request = tnt.TrackRequest(
+        locale=settings.connection_config.locale.state or "en_US",
+        version="3.1",
+        SearchCriteria=tnt.SearchCriteriaType(
+            marketType="INTERNATIONAL",
+            originCountry=(settings.account_country_code or "US"),
+            ConsignmentNumber=payload.tracking_numbers,
+        ),
+        LevelOfDetail=tnt.LevelOfDetailType(
+            Complete=tnt.CompleteType(
+                originAddress=True,
+                destinationAddress=True,
+            )
+        ),
+    )
+
+    return lib.Serializable(request, lib.to_xml)

karrio/providers/tnt/units.py

@@ -0,0 +1,166 @@
+""" TNT Native Types """
+
+import karrio.lib as lib
+
+PRESET_DEFAULTS = dict(dimension_unit="CM", weight_unit="KG")
+
+
+class PackagePresets(lib.Enum):
+    tnt_envelope_doc = lib.units.PackagePreset(
+        **dict(width=35.0, height=1.0, length=27.5, packaging_type="envelope"),
+        **PRESET_DEFAULTS
+    )
+    tnt_satchel_bag1 = lib.units.PackagePreset(
+        **dict(weight=2.0, width=40.0, height=1.0, length=30.0, packaging_type="pak"),
+        **PRESET_DEFAULTS
+    )
+    tnt_satchel_bag2 = lib.units.PackagePreset(
+        **dict(weight=4.0, width=47.5, height=1.0, length=38.0, packaging_type="pak"),
+        **PRESET_DEFAULTS
+    )
+    tnt_box_B = lib.units.PackagePreset(
+        **dict(
+            weight=4.0,
+            width=29.5,
+            height=19.0,
+            length=40.0,
+            packaging_type="medium_box",
+        ),
+        **PRESET_DEFAULTS
+    )
+    tnt_box_C = lib.units.PackagePreset(
+        **dict(
+            weight=6.0,
+            width=29.5,
+            height=29.0,
+            length=40.0,
+            packaging_type="medium_box",
+        ),
+        **PRESET_DEFAULTS
+    )
+    tnt_box_D = lib.units.PackagePreset(
+        **dict(
+            weight=10.0,
+            width=39.5,
+            height=29.0,
+            length=50.0,
+            packaging_type="medium_box",
+        ),
+        **PRESET_DEFAULTS
+    )
+    tnt_box_E = lib.units.PackagePreset(
+        **dict(
+            weight=15.0,
+            width=39.5,
+            height=49.5,
+            length=44.0,
+            packaging_type="medium_box",
+        ),
+        **PRESET_DEFAULTS
+    )
+    tnt_medpack_ambient = lib.units.PackagePreset(
+        **dict(width=18.0, height=12.0, length=23.0, packaging_type="medium_box"),
+        **PRESET_DEFAULTS
+    )
+    tnt_medpack_fronzen_10 = lib.units.PackagePreset(
+        **dict(width=37.0, height=35.5, length=40.0, packaging_type="large_box"),
+        **PRESET_DEFAULTS
+    )
+
+
+class PackageType(lib.StrEnum):
+    tnt_envelope = "envelope"
+    tnt_satchel = "satchel"
+    tnt_box = "box"
+    tnt_cylinder = "cylinder"
+    tnt_pallet = "pallet"
+
+    """ Unified Packaging type mapping """
+    envelope = tnt_envelope
+    pak = tnt_satchel
+    tube = tnt_cylinder
+    pallet = tnt_pallet
+    small_box = tnt_box
+    medium_box = tnt_box
+    large_box = tnt_box
+    your_packaging = "your_packaging"
+
+
+class PaymentType(lib.StrEnum):
+    sender = "S"
+    recipient = "R"
+    third_party = recipient
+
+
+class ConnectionConfig(lib.Enum):
+    app_id = lib.OptionEnum("app_id")
+    email_from = lib.OptionEnum("email_from")
+
+
+class ShippingService(lib.StrEnum):
+    tnt_special_express = "1N"
+    tnt_9_00_express = "09N"
+    tnt_10_00_express = "10N"
+    tnt_12_00_express = "12N"
+    tnt_express = "EX"
+    tnt_economy_express = "48N"
+    tnt_global_express = "15N"
+
+
+class ShippingOption(lib.Enum):
+    tnt_priority = lib.OptionEnum("PR")
+    tnt_insurance = lib.OptionEnum("IN", lib.to_money)
+    tnt_enhanced_liability = lib.OptionEnum("EL")
+    tnt_dangerous_goods_fully_regulated = lib.OptionEnum("HZ")
+    tnt_dangerous_goods_in_limited_quantities = lib.OptionEnum("LQ")
+    tnt_dry_ice_shipments = lib.OptionEnum("DI")
+    tnt_biological_substances = lib.OptionEnum("BB")
+    tnt_lithium_batteries = lib.OptionEnum("LB")
+    tnt_dangerous_goods_in_excepted_quantities = lib.OptionEnum("EQ")
+    tnt_radioactive_materials_in_excepted_packages = lib.OptionEnum("XP")
+    tnt_pre_delivery_notification = lib.OptionEnum("SMS")
+
+    tnt_division_international_shipments = lib.OptionEnum("G", bool)
+    tnt_division_global_link_domestic = lib.OptionEnum("D", bool)
+    tnt_division_german_domestic = lib.OptionEnum("H", bool)
+    tnt_division_uk_domestic = lib.OptionEnum("010", bool)
+
+    insurance = tnt_insurance
+
+
+def shipping_options_initializer(
+    options: dict,
+    package_options: lib.units.Options = None,
+    is_international: bool = None,
+    shipper_country_code: str = None,
+    recipient_country_code: str = None,
+) -> lib.units.Options:
+    """
+    Apply default values to the given options.
+    """
+    _options = options.copy()
+
+    if package_options is not None:
+        _options.update(package_options.content)
+
+    if is_international:
+        _options.update(tnt_division_international_shipments=True)
+
+    if shipper_country_code == "DE" and recipient_country_code == "DE":
+        _options.update(tnt_division_german_domestic=True)
+
+    if shipper_country_code == "GB" and recipient_country_code == "GB":
+        _options.update(tnt_division_uk_domestic=True)
+
+    if shipper_country_code == recipient_country_code and shipper_country_code not in [
+        "DE",
+        "GB",
+    ]:
+        _options.update(tnt_division_global_link_domestic=True)
+
+    def items_filter(key: str) -> bool:
+        return key in ShippingOption  # type: ignore
+
+    return lib.units.ShippingOptions(
+        _options, ShippingOption, items_filter=items_filter
+    )

karrio/providers/tnt/utils.py

@@ -0,0 +1,162 @@
+import karrio.schemas.tnt.label_request as tnt
+import karrio.schemas.tnt.shipping_response as shipping
+import typing
+import base64
+import karrio.lib as lib
+import karrio.core as core
+import karrio.core.models as models
+
+
+class Settings(core.Settings):
+    """TNT connection settings."""
+
+    username: str
+    password: str
+
+    account_number: str = None
+    account_country_code: str = None
+    metadata: dict = {}
+    config: dict = {}
+
+    @property
+    def carrier_name(self):
+        return "tnt"
+
+    @property
+    def server_url(self):
+        return "https://express.tnt.com"
+
+    @property
+    def authorization(self):
+        pair = "%s:%s" % (self.username, self.password)
+        return base64.b64encode(pair.encode("utf-8")).decode("ascii")
+
+    @property
+    def connection_config(self) -> lib.units.Options:
+        from karrio.providers.tnt.units import ConnectionConfig
+
+        return lib.to_connection_config(
+            self.config or {},
+            option_type=ConnectionConfig,
+        )
+
+
+def create_label_request(
+    shipment_response: str,
+    settings: Settings,
+    ctx: dict,
+) -> typing.Optional[lib.Serializable]:
+    import karrio.providers.tnt.units as provider_units
+
+    payload: models.ShipmentRequest = ctx.get("payload")
+    response = lib.to_element(shipment_response)
+    consignment = lib.find_element("CONNUMBER", response, first=True)
+    groupcode = lib.find_element("GROUPCODE", response, first=True)
+    price: shipping.document = lib.find_element(
+        "PRICE", response, shipping.PRICE, first=True
+    )
+
+    if consignment is None or groupcode is None or price is None:
+        return None
+
+    shipper = lib.to_address(payload.shipper)
+    recipient = lib.to_address(payload.recipient)
+    packages = lib.to_packages(payload.parcels)
+    customs = lib.to_customs_info(payload.customs)
+
+    request = tnt.labelRequest(
+        consignment=[
+            tnt.labelConsignmentsType(
+                key="1",
+                consignmentIdentity=tnt.consignmentIdentityType(
+                    consignmentNumber=getattr(consignment, "text", None),
+                    customerReference=payload.reference,
+                ),
+                collectionDateTime=None,
+                sender=tnt.nameAndAddressRequestType(
+                    name=recipient.contact,
+                    addressLine1=shipper.street,
+                    addressLine2=shipper.address_line2,
+                    addressLine3=None,
+                    town=shipper.city,
+                    exactMatch=None,
+                    province=shipper.state_code,
+                    postcode=shipper.postal_code,
+                    country=shipper.country_code,
+                ),
+                delivery=tnt.nameAndAddressRequestType(
+                    name=recipient.contact,
+                    addressLine1=recipient.street,
+                    addressLine2=recipient.address_line2,
+                    addressLine3=None,
+                    town=recipient.city,
+                    exactMatch=None,
+                    province=recipient.state_code,
+                    postcode=recipient.postal_code,
+                    country=recipient.country_code,
+                ),
+                contact=tnt.contactType(
+                    name=shipper.person_name,
+                    telephoneNumber=shipper.phone_number,
+                    emailAddress=shipper.email,
+                ),
+                product=tnt.productType(
+                    lineOfBusiness=None,
+                    groupId=getattr(groupcode, "text", None),
+                    subGroupId=None,
+                    id=price.SERVICE,
+                    type_=price.SERVICEDESC,
+                    option=price.OPTION,
+                ),
+                account=tnt.accountType(
+                    accountNumber=settings.account_number,
+                    accountCountry=settings.account_country_code,
+                ),
+                cashAmount=price.RATE,
+                cashCurrency=price.CURRENCY,
+                cashType=None,
+                ncolNumber=None,
+                specialInstructions=None,
+                bulkShipment="N",
+                customControlled=("N" if payload.customs is None else "Y"),
+                termsOfPayment=provider_units.PaymentType.map(
+                    getattr(payload.payment, "paidby", "sender")
+                ).value,
+                totalNumberOfPieces=len(packages),
+                pieceLine=[
+                    tnt.pieceLineType(
+                        identifier=1,
+                        goodsDescription=package.parcel.description,
+                        barcodeForCustomer="Y",
+                        pieceMeasurements=tnt.measurementsType(
+                            length=package.length.M,
+                            width=package.width.M,
+                            height=package.height.M,
+                            weight=package.weight.KG,
+                        ),
+                        pieces=(
+                            [
+                                tnt.pieceType(
+                                    sequenceNumbers=(index + 1),
+                                    pieceReference=piece.sku or piece.hs_code,
+                                )
+                                for index, piece in enumerate(
+                                    (
+                                        package.items
+                                        if len(package.items) > 0
+                                        else customs.commodities
+                                    ),
+                                    start=1,
+                                )
+                            ]
+                            if len(package.items) > 0 or len(customs.commodities) > 0
+                            else None
+                        ),
+                    )
+                    for package in packages
+                ],
+            )
+        ]
+    )
+
+    return lib.Serializable(request, lib.to_xml)