karrio-hermes 2026.1__py3-none-any.whl

karrio/providers/hermes/shipment/create.py

@@ -0,0 +1,336 @@
+"""Karrio Hermes shipment API implementation."""
+
+import typing
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+import karrio.providers.hermes.error as error
+import karrio.providers.hermes.utils as provider_utils
+import karrio.providers.hermes.units as provider_units
+import karrio.schemas.hermes.shipment_request as hermes_req
+import karrio.schemas.hermes.shipment_response as hermes_res
+
+
+def _split_name(name: typing.Optional[str]) -> typing.Tuple[str, str]:
+    """Split full name into firstname and lastname for Hermes API."""
+    if not name:
+        return (None, None)
+    parts = name.split()
+    firstname = parts[0] if parts else None
+    lastname = " ".join(parts[1:]) if len(parts) > 1 else firstname
+    return (firstname, lastname)
+
+
+def parse_shipment_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.Optional[models.ShipmentDetails], typing.List[models.Message]]:
+    """Parse Hermes shipment response."""
+    response = _response.deserialize()
+    messages = error.parse_error_response(response, settings)
+
+    # Check if we have valid shipment data (shipmentID indicates success)
+    # Only proceed if response is a dict
+    shipment = None
+    if isinstance(response, dict) and (response.get("shipmentID") or response.get("shipmentOrderID")):
+        shipment = _extract_details(response, settings)
+
+    return shipment, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+) -> models.ShipmentDetails:
+    """Extract shipment details from Hermes response."""
+    response = lib.to_object(hermes_res.ShipmentResponseType, data)
+
+    # Hermes uses shipmentID as tracking number (14 or 20 characters)
+    tracking_number = response.shipmentID or ""
+    shipment_order_id = response.shipmentOrderID or ""
+
+    # Label is returned as base64 encoded image
+    label_image = response.labelImage or ""
+
+    # Commercial invoice for international shipments
+    invoice_image = response.commInvoiceImage or ""
+
+    # Label media type
+    label_type = response.labelMediatype or "PDF"
+
+    documents = models.Documents(label=label_image)
+    if invoice_image:
+        documents.invoice = invoice_image
+
+    return models.ShipmentDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        tracking_number=tracking_number,
+        shipment_identifier=shipment_order_id,
+        label_type=label_type,
+        docs=documents,
+        meta=dict(
+            shipment_id=tracking_number,
+            shipment_order_id=shipment_order_id,
+        ),
+    )
+
+
+def shipment_request(
+    payload: models.ShipmentRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Create a Hermes shipment request."""
+    shipper = lib.to_address(payload.shipper)
+    recipient = lib.to_address(payload.recipient)
+    packages = lib.to_packages(payload.parcels)
+    package = packages.single  # Hermes handles one parcel per request
+    options = lib.to_shipping_options(
+        payload.options,
+        package_options=packages.options,
+        initializer=provider_units.shipping_options_initializer,
+    )
+
+    # Determine product type
+    product_type = provider_units.PackagingType.map(
+        package.packaging_type or "your_packaging"
+    ).value
+
+    # Build services object based on options
+    service = _build_service(options)
+
+    # Build customs for international shipments
+    customs = None
+    if payload.customs:
+        customs = _build_customs(payload.customs, shipper)
+
+    # Split names for Hermes API
+    recipient_firstname, recipient_lastname = _split_name(recipient.person_name)
+    shipper_firstname, shipper_lastname = _split_name(shipper.person_name)
+
+    # Create the request using generated schema types
+    # Field length limits per OpenAPI spec:
+    # - street: 50, houseNumber: 5, town: 30
+    # - addressAddition: 50, addressAddition2: 20, addressAddition3: 20
+    # - clientReference: 20, clientReference2: 20, phone: 20
+    request = hermes_req.ShipmentRequestType(
+        clientReference=lib.text(payload.reference, max=20) or "",
+        clientReference2=lib.text((payload.options or {}).get("clientReference2"), max=20),
+        # Receiver name
+        receiverName=hermes_req.ErNameType(
+            title=None,
+            gender=None,
+            firstname=recipient_firstname,
+            middlename=None,
+            lastname=recipient_lastname,
+        ),
+        # Receiver address
+        receiverAddress=hermes_req.ErAddressType(
+            street=lib.text(recipient.street_name, max=50),
+            houseNumber=lib.text(recipient.street_number, max=5) or "",
+            zipCode=recipient.postal_code,
+            town=lib.text(recipient.city, max=30),
+            countryCode=recipient.country_code,
+            addressAddition=lib.text(recipient.address_line2, max=50),
+            addressAddition2=None,
+            addressAddition3=lib.text(recipient.company_name, max=20),
+        ),
+        # Receiver contact
+        receiverContact=lib.identity(
+            hermes_req.ReceiverContactType(
+                phone=lib.text(recipient.phone_number, max=20),
+                mobile=None,
+                mail=recipient.email,
+            )
+            if recipient.phone_number or recipient.email
+            else None
+        ),
+        # Sender (divergent sender if different from account default)
+        senderName=lib.identity(
+            hermes_req.ErNameType(
+                title=None,
+                gender=None,
+                firstname=shipper_firstname,
+                middlename=None,
+                lastname=shipper_lastname,
+            )
+            if shipper.person_name
+            else None
+        ),
+        senderAddress=lib.identity(
+            hermes_req.ErAddressType(
+                street=lib.text(shipper.street_name, max=50),
+                houseNumber=lib.text(shipper.street_number, max=5) or "",
+                zipCode=shipper.postal_code,
+                town=lib.text(shipper.city, max=30),
+                countryCode=shipper.country_code,
+                addressAddition=lib.text(shipper.address_line2, max=50),
+                addressAddition2=None,
+                addressAddition3=lib.text(shipper.company_name, max=20),
+            )
+            if shipper.street
+            else None
+        ),
+        # Parcel details (weight in grams)
+        parcel=hermes_req.ParcelType(
+            parcelClass=None,  # Optional, calculated from dimensions
+            parcelHeight=lib.to_int(package.height.MM) if package.height else None,
+            parcelWidth=lib.to_int(package.width.MM) if package.width else None,
+            parcelDepth=lib.to_int(package.length.MM) if package.length else None,
+            parcelWeight=lib.to_int(package.weight.G),  # Weight in grams
+            parcelVolume=None,  # Optional
+            productType=product_type,
+        ),
+        # Services
+        service=service if any([
+            getattr(service, attr) for attr in dir(service)
+            if not attr.startswith('_') and getattr(service, attr) is not None
+        ]) else None,
+        # Customs for international
+        customsAndTaxes=customs,
+    )
+
+    return lib.Serializable(request, lib.to_dict)
+
+
+def _build_service(options: units.ShippingOptions) -> hermes_req.ServiceType:
+    """Build Hermes service object from shipping options."""
+    # Cash on delivery
+    cod_service = None
+    if options.hermes_cod_amount.state:
+        cod_service = hermes_req.CashOnDeliveryServiceType(
+            amount=options.hermes_cod_amount.state,
+            currency=options.hermes_cod_currency.state or "EUR",
+            bankTransferAmount=options.hermes_cod_amount.state,
+            bankTransferCurrency=options.hermes_cod_currency.state or "EUR",
+        )
+
+    # Customer alert service
+    alert_service = None
+    if options.hermes_notification_email.state:
+        alert_service = hermes_req.CustomerAlertServiceType(
+            notificationType=options.hermes_notification_type.state or "EMAIL",
+            notificationEmail=options.hermes_notification_email.state,
+            notificationNumber=None,
+        )
+
+    # Ident service
+    ident_service = None
+    if options.hermes_ident_fsk.state or options.hermes_ident_id.state:
+        ident_service = hermes_req.IdentServiceType(
+            identID=options.hermes_ident_id.state,
+            identType=options.hermes_ident_type.state,
+            identVerifyFsk=options.hermes_ident_fsk.state,
+            identVerifyBirthday=options.hermes_ident_birthday.state,
+        )
+
+    # Parcel shop delivery
+    parcel_shop_service = None
+    if options.hermes_parcel_shop_id.state:
+        parcel_shop_service = hermes_req.ParcelShopDeliveryServiceType(
+            psCustomerFirstName=options.hermes_parcel_shop_customer_firstname.state,
+            psCustomerLastName=options.hermes_parcel_shop_customer_lastname.state,
+            psID=options.hermes_parcel_shop_id.state,
+            psSelectionRule=options.hermes_parcel_shop_selection_rule.state or "SELECT_BY_ID",
+        )
+
+    # Stated day service
+    stated_day_service = None
+    if options.hermes_stated_day.state:
+        stated_day_service = hermes_req.StatedDayServiceType(
+            statedDay=options.hermes_stated_day.state,
+        )
+
+    # Stated time service
+    stated_time_service = None
+    if options.hermes_time_slot.state:
+        stated_time_service = hermes_req.StatedTimeServiceType(
+            timeSlot=options.hermes_time_slot.state,
+        )
+
+    # Multipart service
+    multipart_service = None
+    if options.hermes_number_of_parts.state:
+        multipart_service = hermes_req.MultipartServiceType(
+            partNumber=options.hermes_part_number.state or 1,
+            numberOfParts=options.hermes_number_of_parts.state,
+            parentShipmentOrderID=options.hermes_parent_shipment_order_id.state,
+        )
+
+    return hermes_req.ServiceType(
+        tanService=options.hermes_tan_service.state,
+        multipartService=multipart_service,
+        limitedQuantitiesService=options.hermes_limited_quantities.state,
+        cashOnDeliveryService=cod_service,
+        bulkGoodService=options.hermes_bulk_goods.state,
+        statedTimeService=stated_time_service,
+        householdSignatureService=options.hermes_household_signature.state,
+        customerAlertService=alert_service,
+        parcelShopDeliveryService=parcel_shop_service,
+        compactParcelService=options.hermes_compact_parcel.state,
+        identService=ident_service,
+        statedDayService=stated_day_service,
+        nextDayService=options.hermes_next_day.state,
+        signatureService=options.hermes_signature.state,
+        redirectionProhibitedService=options.hermes_redirection_prohibited.state,
+        excludeParcelShopAuthorization=options.hermes_exclude_parcel_shop_auth.state,
+        lateInjectionService=options.hermes_late_injection.state,
+    )
+
+
+def _build_customs(
+    customs: models.Customs,
+    shipper,
+) -> hermes_req.CustomsAndTaxesType:
+    """Build customs and taxes for international shipments."""
+    items = [
+        hermes_req.ItemType(
+            sku=item.sku,
+            category=None,
+            countryCodeOfManufacture=item.origin_country,
+            value=lib.to_int(item.value_amount * 100) if item.value_amount else None,  # In cents
+            weight=lib.to_int(item.weight * 1000) if item.weight else None,  # In grams
+            quantity=item.quantity or 1,
+            description=item.description or item.title,
+            exportDescription=None,
+            exportHsCode=None,
+            hsCode=item.hs_code,
+            url=None,
+        )
+        for item in customs.commodities or []
+    ]
+
+    shipper_firstname, shipper_lastname = _split_name(shipper.person_name) if shipper else (None, None)
+
+    return hermes_req.CustomsAndTaxesType(
+        currency=lib.identity(customs.duty.currency if customs.duty else "EUR"),
+        shipmentCost=None,
+        items=items or None,
+        invoiceReferences=None,
+        value=None,
+        exportCustomsClearance=None,
+        client=None,
+        shipmentOriginAddress=lib.identity(
+            hermes_req.ShipmentOriginAddressType(
+                title=None,
+                firstname=shipper_firstname,
+                lastname=shipper_lastname,
+                company=shipper.company_name,
+                street=shipper.street_name,
+                houseNumber=shipper.street_number or "",
+                zipCode=shipper.postal_code,
+                town=shipper.city,
+                state=shipper.state_code,
+                countryCode=shipper.country_code,
+                addressAddition=shipper.address_line2,
+                addressAddition2=None,
+                addressAddition3=None,
+                phone=shipper.phone_number,
+                fax=None,
+                mobile=None,
+                mail=shipper.email,
+            )
+            if shipper
+            else None
+        ),
+    )

karrio/providers/hermes/units.py

@@ -0,0 +1,242 @@
+import csv
+import pathlib
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+
+
+class ConnectionConfig(lib.Enum):
+    """Carrier connection configuration options."""
+
+    shipping_options = lib.OptionEnum("shipping_options", list)
+    shipping_services = lib.OptionEnum("shipping_services", list)
+    label_type = lib.OptionEnum("label_type", str, "PDF")
+    language = lib.OptionEnum("language", str, "DE")  # DE or EN
+
+
+class ParcelClass(lib.StrEnum):
+    """Hermes parcel size classes."""
+
+    XS = "XS"
+    S = "S"
+    M = "M"
+    L = "L"
+    XL = "XL"
+
+
+class ProductType(lib.StrEnum):
+    """Hermes product types."""
+
+    BAG = "BAG"
+    BIKE = "BIKE"
+    LARGE_ITEM = "LARGE_ITEM"
+    PARCEL = "PARCEL"
+
+
+class PackagingType(lib.StrEnum):
+    """Carrier specific packaging type."""
+
+    hermes_parcel = "PARCEL"
+    hermes_bag = "BAG"
+    hermes_bike = "BIKE"
+    hermes_large_item = "LARGE_ITEM"
+
+    """Unified Packaging type mapping."""
+    envelope = hermes_parcel
+    pak = hermes_parcel
+    tube = hermes_parcel
+    pallet = hermes_large_item
+    small_box = hermes_parcel
+    medium_box = hermes_parcel
+    your_packaging = hermes_parcel
+
+
+class ShippingService(lib.StrEnum):
+    """Carrier specific services."""
+
+    hermes_standard = "hermes_standard"
+    hermes_next_day = "hermes_next_day"
+    hermes_stated_day = "hermes_stated_day"
+    hermes_parcel_shop = "hermes_parcel_shop"
+    hermes_international = "hermes_international"
+
+
+class ShippingOption(lib.Enum):
+    """Carrier specific options."""
+
+    # Hermes services as options
+    hermes_tan_service = lib.OptionEnum("tanService", bool)
+    hermes_limited_quantities = lib.OptionEnum("limitedQuantitiesService", bool)
+    hermes_bulk_goods = lib.OptionEnum("bulkGoodService", bool)
+    hermes_household_signature = lib.OptionEnum("householdSignatureService", bool)
+    hermes_compact_parcel = lib.OptionEnum("compactParcelService", bool)
+    hermes_next_day = lib.OptionEnum("nextDayService", bool)
+    hermes_signature = lib.OptionEnum("signatureService", bool)
+    hermes_redirection_prohibited = lib.OptionEnum("redirectionProhibitedService", bool)
+    hermes_exclude_parcel_shop_auth = lib.OptionEnum("excludeParcelShopAuthorization", bool)
+    hermes_late_injection = lib.OptionEnum("lateInjectionService", bool)
+
+    # Cash on delivery
+    hermes_cod_amount = lib.OptionEnum("codAmount", float)
+    hermes_cod_currency = lib.OptionEnum("codCurrency", str)
+
+    # Customer alert service
+    hermes_notification_email = lib.OptionEnum("notificationEmail", str)
+    hermes_notification_type = lib.OptionEnum("notificationType", str)  # EMAIL, SMS, EMAIL_SMS
+
+    # Stated day service
+    hermes_stated_day = lib.OptionEnum("statedDay", str)  # YYYY-MM-DD format
+
+    # Stated time service
+    hermes_time_slot = lib.OptionEnum("timeSlot", str)  # FORENOON, NOON, AFTERNOON, EVENING
+
+    # Ident service
+    hermes_ident_id = lib.OptionEnum("identID", str)
+    hermes_ident_type = lib.OptionEnum("identType", str)  # GERMAN_IDENTITY_CARD, etc.
+    hermes_ident_fsk = lib.OptionEnum("identVerifyFsk", str)  # 18
+    hermes_ident_birthday = lib.OptionEnum("identVerifyBirthday", str)  # YYYY-MM-DD
+
+    # Parcel shop delivery
+    hermes_parcel_shop_id = lib.OptionEnum("psID", str)
+    hermes_parcel_shop_selection_rule = lib.OptionEnum("psSelectionRule", str)  # SELECT_BY_ID, SELECT_BY_RECEIVER_ADDRESS
+    hermes_parcel_shop_customer_firstname = lib.OptionEnum("psCustomerFirstName", str)
+    hermes_parcel_shop_customer_lastname = lib.OptionEnum("psCustomerLastName", str)
+
+    # Multipart service
+    hermes_part_number = lib.OptionEnum("partNumber", int)
+    hermes_number_of_parts = lib.OptionEnum("numberOfParts", int)
+    hermes_parent_shipment_order_id = lib.OptionEnum("parentShipmentOrderID", str)
+
+    """Unified Option type mapping."""
+    signature_required = hermes_signature
+    cash_on_delivery = hermes_cod_amount
+
+
+def shipping_options_initializer(
+    options: dict,
+    package_options: units.ShippingOptions = None,
+) -> units.ShippingOptions:
+    """Apply default values to the given options."""
+
+    if package_options is not None:
+        options.update(package_options.content)
+
+    def items_filter(key: str) -> bool:
+        return key in ShippingOption  # type: ignore
+
+    return units.ShippingOptions(options, ShippingOption, items_filter=items_filter)
+
+
+class TrackingStatus(lib.Enum):
+    """Hermes tracking status mapping."""
+
+    on_hold = ["on_hold"]
+    delivered = ["delivered"]
+    in_transit = ["in_transit"]
+    delivery_failed = ["delivery_failed"]
+    delivery_delayed = ["delivery_delayed"]
+    out_for_delivery = ["out_for_delivery"]
+    ready_for_pickup = ["ready_for_pickup"]
+
+
+class LabelType(lib.StrEnum):
+    """Hermes label formats - use +json variants for JSON response with base64 label."""
+
+    PDF = "application/shippinglabel-pdf+json"
+    ZPL = "application/shippinglabel-zpl+json;dpi=300"
+    PNG = "application/shippinglabel-data+json"
+
+
+class PickupTimeSlot(lib.StrEnum):
+    """Hermes pickup time slots per OpenAPI spec."""
+
+    BETWEEN_10_AND_13 = "BETWEEN_10_AND_13"
+    BETWEEN_12_AND_15 = "BETWEEN_12_AND_15"
+    BETWEEN_14_AND_17 = "BETWEEN_14_AND_17"
+
+
+def load_services_from_csv() -> list:
+    """
+    Load service definitions from CSV file.
+    CSV format: service_code,service_name,zone_label,country_codes,min_weight,max_weight,max_length,max_width,max_height,rate,currency,transit_days,domicile,international
+    """
+    csv_path = pathlib.Path(__file__).resolve().parent / "services.csv"
+
+    if not csv_path.exists():
+        # Fallback to simple default if CSV doesn't exist
+        return [
+            models.ServiceLevel(
+                service_name="Hermes Standard",
+                service_code="hermes_standard",
+                currency="EUR",
+                domicile=True,
+                zones=[models.ServiceZone(rate=0.0)],
+            )
+        ]
+
+    # Group zones by service
+    services_dict: dict[str, dict] = {}
+
+    with open(csv_path, "r", encoding="utf-8") as f:
+        reader = csv.DictReader(f)
+        for row in reader:
+            service_code = row["service_code"]
+            service_name = row["service_name"]
+
+            # Map carrier service code to karrio service code
+            karrio_service_code = ShippingService.map(service_code).name_or_key
+
+            # Initialize service if not exists
+            if karrio_service_code not in services_dict:
+                services_dict[karrio_service_code] = {
+                    "service_name": service_name,
+                    "service_code": karrio_service_code,
+                    "currency": row.get("currency", "EUR"),
+                    "min_weight": (
+                        float(row["min_weight"]) if row.get("min_weight") else None
+                    ),
+                    "max_weight": (
+                        float(row["max_weight"]) if row.get("max_weight") else None
+                    ),
+                    "max_length": (
+                        float(row["max_length"]) if row.get("max_length") else None
+                    ),
+                    "max_width": (
+                        float(row["max_width"]) if row.get("max_width") else None
+                    ),
+                    "max_height": (
+                        float(row["max_height"]) if row.get("max_height") else None
+                    ),
+                    "weight_unit": "KG",
+                    "dimension_unit": "CM",
+                    "domicile": row.get("domicile", "").lower() == "true",
+                    "international": (
+                        True if row.get("international", "").lower() == "true" else None
+                    ),
+                    "zones": [],
+                }
+
+            # Parse country codes
+            country_codes = [
+                c.strip() for c in row.get("country_codes", "").split(",") if c.strip()
+            ]
+
+            # Create zone
+            zone = models.ServiceZone(
+                label=row.get("zone_label", "Default Zone"),
+                rate=float(row.get("rate", 0.0)),
+                transit_days=(
+                    int(row["transit_days"].split("-")[0]) if row.get("transit_days") and row["transit_days"].split("-")[0].isdigit() else None
+                ),
+                country_codes=country_codes if country_codes else None,
+            )
+
+            services_dict[karrio_service_code]["zones"].append(zone)
+
+    # Convert to ServiceLevel objects
+    return [
+        models.ServiceLevel(**service_data) for service_data in services_dict.values()
+    ]
+
+
+DEFAULT_SERVICES = load_services_from_csv()

karrio/providers/hermes/utils.py

@@ -0,0 +1,102 @@
+import datetime
+import karrio.lib as lib
+import karrio.core as core
+import karrio.core.errors as errors
+
+
+class Settings(core.Settings):
+    """Hermes connection settings."""
+
+    # OAuth2 credentials (password flow)
+    username: str
+    password: str
+    client_id: str
+    client_secret: str
+
+    @property
+    def carrier_name(self):
+        return "hermes"
+
+    @property
+    def server_url(self):
+        return (
+            "https://de-api-int.hermesworld.com/services/hsi"
+            if self.test_mode
+            else "https://de-api.hermesworld.com/services/hsi"
+        )
+
+    @property
+    def token_url(self):
+        return (
+            "https://authme-int.myhermes.de/authorization-facade/oauth2/access_token"
+            if self.test_mode
+            else "https://authme.myhermes.de/authorization-facade/oauth2/access_token"
+        )
+
+    @property
+    def connection_config(self) -> lib.units.Options:
+        from karrio.providers.hermes.units import ConnectionConfig
+
+        return lib.to_connection_config(
+            self.config or {},
+            option_type=ConnectionConfig,
+        )
+
+    @property
+    def access_token(self):
+        """Retrieve the access_token using the username|password pair
+        or collect it from the cache if an unexpired access_token exists.
+        """
+        cache_key = f"{self.carrier_name}|{self.username}|{self.client_id}"
+
+        return self.connection_cache.thread_safe(
+            refresh_func=lambda: login(self),
+            cache_key=cache_key,
+            buffer_minutes=5,
+        ).get_state()
+
+
+def login(settings: Settings):
+    """Authenticate with Hermes OAuth2 password flow."""
+    import karrio.providers.hermes.error as error
+    import karrio.core.models as models
+
+    result = lib.request(
+        url=settings.token_url,
+        trace=settings.trace_as("json"),
+        method="POST",
+        headers={
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        data=lib.to_query_string({
+            "grant_type": "password",
+            "username": settings.username,
+            "password": settings.password,
+            "client_id": settings.client_id,
+            "client_secret": settings.client_secret,
+        }),
+    )
+    response = lib.to_dict(result)
+
+    # Handle case where response is not a dict
+    if not isinstance(response, dict):
+        raise errors.ParsedMessagesError(
+            messages=[
+                models.Message(
+                    carrier_id=settings.carrier_id,
+                    carrier_name=settings.carrier_name,
+                    code="AUTH_ERROR",
+                    message=f"Authentication failed - unexpected response: {str(response)[:200]}",
+                )
+            ]
+        )
+
+    messages = error.parse_error_response(response, settings)
+
+    if any(messages):
+        raise errors.ParsedMessagesError(messages=messages)
+
+    expiry = datetime.datetime.now() + datetime.timedelta(
+        seconds=float(response.get("expires_in", 3600))
+    )
+    return {**response, "expiry": lib.fdatetime(expiry)}