karrio-hermes 2026.1__py3-none-any.whl → 2026.1.3__py3-none-any.whl

karrio/mappers/hermes/mapper.py

@@ -53,6 +53,17 @@ class Mapper(mapper.Mapper):
     ) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
         return provider.parse_pickup_cancel_response(response, self.settings)
 
+    # Tracking operations
+    def create_tracking_request(
+        self, payload: models.TrackingRequest
+    ) -> lib.Serializable:
+        return provider.tracking_request(payload, self.settings)
+
+    def parse_tracking_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[typing.List[models.TrackingDetails], typing.List[models.Message]]:
+        return provider.parse_tracking_response(response, self.settings)
+
     # Note: Hermes API does not support:
     # - cancel_shipment (no DELETE endpoint for shipments)
     # - pickup_update (no PUT endpoint for pickups)

karrio/mappers/hermes/proxy.py

@@ -4,6 +4,7 @@ import karrio.lib as lib
 import karrio.api.proxy as proxy
 import karrio.mappers.hermes.settings as provider_settings
 import karrio.universal.mappers.rating_proxy as rating_proxy
+import karrio.providers.hermes.utils as provider_utils
 from karrio.providers.hermes.units import LabelType
 
 
@@ -13,58 +14,56 @@ class Proxy(rating_proxy.RatingMixinProxy, proxy.Proxy):
     def get_rates(self, request: lib.Serializable) -> lib.Deserializable[str]:
         return super().get_rates(request)
 
-    def _get_headers(self, accept: str = "application/json") -> dict:
-        """Get common headers for Hermes API requests."""
-        token_data = self.settings.access_token
-        # Handle case where token_data might not be a dict
-        access_token = token_data.get("access_token") if isinstance(token_data, dict) else token_data
-        language = self.settings.connection_config.language.state or "DE"
-
-        return {
-            "Content-Type": "application/json",
-            "Accept": accept,
-            "Accept-Language": language,
-            "Authorization": f"Bearer {access_token}",
-        }
-
     def create_shipment(self, request: lib.Serializable) -> lib.Deserializable[str]:
-        """Create a shipment order with label.
-
-        Endpoint: POST /shipmentorders/labels
-        """
+        """Create shipment order(s) with label(s). Sequential for multi-piece linking."""
+        requests_data, is_multi_piece = provider_utils.prepare_shipment_data(request)
         label_type = self.settings.connection_config.label_type.state or "PDF"
         accept_header = LabelType.map(label_type).value or "application/pdf"
 
-        response = lib.request(
-            url=f"{self.settings.server_url}/shipmentorders/labels",
-            data=lib.to_json(request.serialize()),
-            trace=self.trace_as("json"),
-            method="POST",
-            headers=self._get_headers(accept=accept_header),
-        )
-
-        return lib.Deserializable(response, lib.to_dict)
+        responses, parent_id = [], None
+        for idx, req_data in enumerate(requests_data):
+            if is_multi_piece and idx > 0 and parent_id:
+                req_data = provider_utils.inject_parent_shipment_id(req_data, parent_id)
+
+            response = lib.request(
+                url=f"{self.settings.server_url}/shipmentorders/labels",
+                data=lib.to_json(req_data),
+                trace=self.trace_as("json"),
+                method="POST",
+                headers={
+                    "Content-Type": "application/json",
+                    "Accept": accept_header,
+                    "Accept-Language": self.settings.connection_config.language.state or "DE",
+                    "Authorization": f"Bearer {provider_utils.get_access_token(self.settings)}",
+                },
+            )
+
+            response_dict = lib.to_dict(response)
+            responses.append(response_dict)
+            if idx == 0 and is_multi_piece:
+                parent_id = provider_utils.extract_shipment_order_id(response_dict)
+
+        return lib.Deserializable(responses, lambda res: res)
 
     def schedule_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
-        """Create a pickup order.
-
-        Endpoint: POST /pickuporders
-        """
+        """Create a pickup order. Endpoint: POST /pickuporders"""
         response = lib.request(
             url=f"{self.settings.server_url}/pickuporders",
             data=lib.to_json(request.serialize()),
             trace=self.trace_as("json"),
             method="POST",
-            headers=self._get_headers(),
+            headers={
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "Accept-Language": self.settings.connection_config.language.state or "DE",
+                "Authorization": f"Bearer {provider_utils.get_access_token(self.settings)}",
+            },
         )
 
         return lib.Deserializable(response, lib.to_dict)
 
     def cancel_pickup(self, request: lib.Serializable) -> lib.Deserializable[str]:
-        """Cancel a pickup order.
-
-        Endpoint: DELETE /pickuporders/{pickupOrderID}
-        """
+        """Cancel a pickup order. Endpoint: DELETE /pickuporders/{pickupOrderID}"""
         payload = request.serialize()
         pickup_order_id = payload.get("pickupOrderID")
 
@@ -72,7 +71,31 @@ class Proxy(rating_proxy.RatingMixinProxy, proxy.Proxy):
             url=f"{self.settings.server_url}/pickuporders/{pickup_order_id}",
             trace=self.trace_as("json"),
             method="DELETE",
-            headers=self._get_headers(),
+            headers={
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "Accept-Language": self.settings.connection_config.language.state or "DE",
+                "Authorization": f"Bearer {provider_utils.get_access_token(self.settings)}",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def get_tracking(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        """Get tracking information. Endpoint: GET /shipmentinfo"""
+        tracking_numbers = request.serialize()
+        query_params = "&".join([f"shipmentID={num}" for num in tracking_numbers])
+
+        response = lib.request(
+            url=f"{self.settings.server_url}/shipmentinfo?{query_params}",
+            trace=self.trace_as("json"),
+            method="GET",
+            headers={
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "Accept-Language": self.settings.connection_config.language.state or "DE",
+                "Authorization": f"Bearer {provider_utils.get_access_token(self.settings)}",
+            },
         )
 
         return lib.Deserializable(response, lib.to_dict)

karrio/providers/hermes/__init__.py

@@ -10,6 +10,10 @@ from karrio.providers.hermes.pickup import (
     pickup_cancel_request,
     pickup_request,
 )
+from karrio.providers.hermes.tracking import (
+    parse_tracking_response,
+    tracking_request,
+)
 
 # Note: Hermes API does not support:
 # - shipment cancellation (no DELETE endpoint for shipments)

karrio/providers/hermes/pickup/create.py

@@ -48,6 +48,14 @@ def pickup_request(
     settings: provider_utils.Settings,
 ) -> lib.Serializable:
     """Create a Hermes pickup request."""
+    # Hermes only supports one-time pickups via API
+    pickup_type = getattr(payload, "pickup_type", "one_time") or "one_time"
+    if pickup_type not in ("one_time", None):
+        raise lib.exceptions.FieldError({
+            "pickup_type": f"Hermes only supports 'one_time' pickups via API. Received: '{pickup_type}'. "
+            "For daily/recurring pickups, please contact Hermes to set up a regular pickup schedule."
+        })
+
     address = lib.to_address(payload.address)
 
     # Parse parcel counts by size (XS, S, M, L, XL)