karrio-parcelone 2026.1__py3-none-any.whl

karrio/mappers/parcelone/__init__.py

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

karrio/mappers/parcelone/mapper.py

@@ -0,0 +1,50 @@
+"""Karrio ParcelOne client mapper."""
+
+import typing
+import karrio.lib as lib
+import karrio.api.mapper as mapper
+import karrio.core.models as models
+import karrio.providers.parcelone as provider
+import karrio.mappers.parcelone.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 create_cancel_shipment_request(
+        self, payload: models.ShipmentCancelRequest
+    ) -> lib.Serializable:
+        return provider.shipment_cancel_request(payload, self.settings)
+
+    def parse_rate_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[typing.List[models.RateDetails], typing.List[models.Message]]:
+        return provider.parse_rate_response(response, self.settings)
+
+    def parse_cancel_shipment_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.ConfirmationDetails, typing.List[models.Message]]:
+        return provider.parse_shipment_cancel_response(response, self.settings)
+
+    def parse_shipment_response(
+        self, response: lib.Deserializable[str]
+    ) -> typing.Tuple[models.ShipmentDetails, typing.List[models.Message]]:
+        return provider.parse_shipment_response(response, 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)

karrio/mappers/parcelone/proxy.py

@@ -0,0 +1,84 @@
+"""Karrio ParcelOne REST API client proxy."""
+
+import karrio.lib as lib
+import karrio.api.proxy as proxy
+import karrio.mappers.parcelone.settings as provider_settings
+
+
+class Proxy(proxy.Proxy):
+    settings: provider_settings.Settings
+
+    def get_rates(self, request: lib.Serializable) -> lib.Deserializable[dict]:
+        """Get shipping rates - not directly supported by ParcelOne API.
+
+        ParcelOne returns charges after shipment creation.
+        This method creates a shipment with ReturnCharges=1 to get rates.
+        """
+        response = lib.request(
+            url=f"{self.settings.server_url}/shipment",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": self.settings.authorization,
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict, request.ctx)
+
+    def create_shipment(self, request: lib.Serializable) -> lib.Deserializable[dict]:
+        """Create a shipment and get label."""
+        response = lib.request(
+            url=f"{self.settings.server_url}/shipment",
+            data=lib.to_json(request.serialize()),
+            trace=self.trace_as("json"),
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": self.settings.authorization,
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict, request.ctx)
+
+    def cancel_shipment(self, request: lib.Serializable) -> lib.Deserializable[dict]:
+        """Cancel a shipment."""
+        data = request.serialize()
+        ref_field = data.get("ref_field", "ShipmentID")
+        ref_value = data.get("ref_value")
+
+        response = lib.request(
+            url=f"{self.settings.server_url}/shipment/{ref_field}/{ref_value}",
+            trace=self.trace_as("json"),
+            method="DELETE",
+            headers={
+                "Authorization": self.settings.authorization,
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_dict)
+
+    def get_tracking(self, request: lib.Serializable) -> lib.Deserializable[list]:
+        """Get tracking information for multiple tracking numbers."""
+        tracking_requests = request.serialize()
+
+        # Make individual requests for each tracking number
+        responses = [
+            (
+                req["tracking_id"],
+                lib.to_dict(
+                    lib.request(
+                        url=f"{self.settings.tracking_url}/tracking/{req['carrier_id']}/{req['tracking_id']}",
+                        trace=self.trace_as("json"),
+                        method="GET",
+                        headers={
+                            "Authorization": self.settings.authorization,
+                        },
+                    )
+                ),
+            )
+            for req in tracking_requests
+        ]
+
+        return lib.Deserializable(responses, lambda x: x)

karrio/mappers/parcelone/settings.py

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

karrio/plugins/parcelone/__init__.py

@@ -0,0 +1,28 @@
+from karrio.core.metadata import PluginMetadata
+
+from karrio.mappers.parcelone.mapper import Mapper
+from karrio.mappers.parcelone.proxy import Proxy
+from karrio.mappers.parcelone.settings import Settings
+import karrio.providers.parcelone.units as units
+
+
+# This METADATA object is used by Karrio to discover and register this plugin
+# when loaded through Python entrypoints or local plugin directories.
+# The entrypoint is defined in pyproject.toml under [project.entry-points."karrio.plugins"]
+METADATA = PluginMetadata(
+    id="parcelone",
+    label="ParcelOne",
+    description="ParcelOne multi-carrier shipping integration for Karrio",
+    # Integrations
+    Mapper=Mapper,
+    Proxy=Proxy,
+    Settings=Settings,
+    # Data Units
+    is_hub=True,  # ParcelOne is a multi-carrier hub
+    options=units.ShippingOption,
+    services=units.ShippingService,
+    connection_configs=units.ConnectionConfig,
+    # Extra info
+    website="https://parcel.one",
+    documentation="https://parcel.one/api-documentation",
+)

karrio/providers/parcelone/__init__.py

@@ -0,0 +1,17 @@
+"""Karrio ParcelOne provider imports."""
+
+from karrio.providers.parcelone.utils import Settings
+from karrio.providers.parcelone.rate import (
+    parse_rate_response,
+    rate_request,
+)
+from karrio.providers.parcelone.tracking import (
+    parse_tracking_response,
+    tracking_request,
+)
+from karrio.providers.parcelone.shipment import (
+    parse_shipment_cancel_response,
+    parse_shipment_response,
+    shipment_cancel_request,
+    shipment_request,
+)

karrio/providers/parcelone/error.py

@@ -0,0 +1,76 @@
+"""Karrio ParcelOne error parser."""
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.parcelone.utils as provider_utils
+
+
+def parse_error_response(
+    response: dict,
+    settings: provider_utils.Settings,
+    **details,
+) -> typing.List[models.Message]:
+    """Parse error response from ParcelOne REST API."""
+    results = response.get("results") or {}
+    action_result = results.get("ActionResult") or results
+
+    # Collect all errors using list comprehensions
+    errors: typing.List[dict] = sum(
+        [
+            # Top-level API errors
+            [
+                *[
+                    {
+                        "code": e.get("ErrorNo") or e.get("StatusCode"),
+                        "message": e.get("Message"),
+                        "instance": response.get("instance"),
+                        "uniq_id": response.get("UniqId"),
+                    }
+                    for e in (response.get("errors") or [])
+                ],
+                # Top-level error message when no specific errors
+                *(
+                    [
+                        {
+                            "code": str(response.get("status", "")),
+                            "message": response.get("message"),
+                            "instance": response.get("instance"),
+                            "uniq_id": response.get("UniqId"),
+                        }
+                    ]
+                    if (
+                        response.get("success") == -1
+                        or response.get("type") == "error"
+                    )
+                    and not response.get("errors")
+                    and response.get("message")
+                    else []
+                ),
+            ],
+            # ActionResult errors
+            [
+                {
+                    "code": e.get("ErrorNo") or e.get("StatusCode"),
+                    "message": e.get("Message"),
+                    "shipment_id": action_result.get("ShipmentID"),
+                    "tracking_id": action_result.get("TrackingID"),
+                }
+                for e in (action_result.get("Errors") or [])
+                if isinstance(action_result, dict)
+            ],
+        ],
+        [],
+    )
+
+    return [
+        models.Message(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            code=error.get("code"),
+            message=error.get("message"),
+            details=lib.to_dict({**details, **{k: v for k, v in error.items() if k not in ("code", "message")}}),
+        )
+        for error in errors
+        if error.get("code") or error.get("message")
+    ]

karrio/providers/parcelone/rate.py

@@ -0,0 +1,162 @@
+"""Karrio ParcelOne rating implementation.
+
+Note: ParcelOne REST API returns charges as part of the shipment creation response.
+This implementation creates a rate request that can be used to get charges
+by setting ReturnCharges=1 on the shipment request.
+"""
+
+import typing
+import karrio.schemas.parcelone as parcelone
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.parcelone.error as error
+import karrio.providers.parcelone.utils as provider_utils
+import karrio.providers.parcelone.units as provider_units
+
+
+def parse_rate_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.List[models.RateDetails], typing.List[models.Message]]:
+    """Parse rate response from ParcelOne REST API."""
+    response = _response.deserialize()
+    messages = error.parse_error_response(response, settings)
+
+    rates = lib.identity(
+        [_extract_rate(response, settings, _response.ctx)]
+        if response.get("success") == 1 and response.get("results")
+        else []
+    )
+
+    return [rate for rate in rates if rate is not None], messages
+
+
+def _extract_rate(
+    data: dict,
+    settings: provider_utils.Settings,
+    ctx: typing.Dict[str, typing.Any] = None,
+) -> typing.Optional[models.RateDetails]:
+    """Extract rate details from API response."""
+    ctx = ctx or {}
+    result = lib.to_object(parcelone.ShipmentResultType, data.get("results") or {})
+
+    # Check if we have charges in the response
+    if result.TotalCharges is None and not result.Charges:
+        return None
+
+    service_code = ctx.get("service_code", "parcelone_pa1_eco")
+    service = provider_units.ShippingService.map(service_code)
+
+    total_charge = lib.failsafe(lambda: float(result.TotalCharges.Value)) if result.TotalCharges else 0.0
+    currency = lib.failsafe(lambda: result.TotalCharges.Currency) or "EUR"
+
+    extra_charges = [
+        models.ChargeDetails(
+            name=charge.Description or "Shipping Charge",
+            amount=lib.to_money(charge.Value),
+            currency=charge.Currency or currency,
+        )
+        for charge in (result.Charges or [])
+        if charge.Value
+    ]
+
+    return models.RateDetails(
+        carrier_name=settings.carrier_name,
+        carrier_id=settings.carrier_id,
+        service=service.name_or_key,
+        total_charge=lib.to_money(total_charge),
+        currency=currency,
+        extra_charges=extra_charges,
+        meta=dict(
+            service_name=service.name_or_key,
+        ),
+    )
+
+
+def rate_request(
+    payload: models.RateRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Create ParcelOne rate request.
+
+    Uses the shipment endpoint with ReturnCharges=1 to get rates.
+    """
+    shipper = lib.to_address(payload.shipper)
+    recipient = lib.to_address(payload.recipient)
+    packages = lib.to_packages(payload.parcels, required=["weight"])
+    services = lib.to_services(payload.services, service_type=provider_units.ShippingService)
+    options = lib.to_shipping_options(
+        payload.options,
+        package_options=packages.options,
+        initializer=provider_units.shipping_options_initializer,
+    )
+
+    # Get first service or use default
+    service = lib.identity(
+        next(iter(services), None)
+        or provider_units.ShippingService.parcelone_pa1_eco
+    )
+
+    # Parse service for CEP and product IDs
+    service_code = service.value if hasattr(service, 'value') else str(service)
+    cep_id, product_id = provider_units.parse_service_code(service_code)
+    cep_id = cep_id or settings.connection_config.cep_id.state
+    product_id = product_id or settings.connection_config.product_id.state
+
+    request = parcelone.ShippingDataRequestType(
+        ShippingData=parcelone.ShipmentType(
+            CEPID=cep_id,
+            ProductID=product_id,
+            MandatorID=settings.mandator_id,
+            ConsignerID=settings.consigner_id,
+            ShipToData=parcelone.ShipToType(
+                Name1=recipient.company_name or recipient.person_name,
+                ShipmentAddress=parcelone.AddressType(
+                    Street=recipient.street,
+                    PostalCode=recipient.postal_code,
+                    City=recipient.city,
+                    Country=recipient.country_code,
+                    State=recipient.state_code,
+                ),
+                PrivateAddressIndicator=1 if recipient.residential else 0,
+            ),
+            ShipFromData=parcelone.ShipFromType(
+                Name1=shipper.company_name or shipper.person_name,
+                ShipmentAddress=parcelone.AddressType(
+                    Street=shipper.street,
+                    PostalCode=shipper.postal_code,
+                    City=shipper.city,
+                    Country=shipper.country_code,
+                    State=shipper.state_code,
+                ),
+            ) if shipper else None,
+            ReturnCharges=1,  # Request charges only
+            PrintLabel=0,  # Don't generate label for rate request
+            Software="Karrio",
+            Packages=[
+                parcelone.ShipmentPackageType(
+                    PackageRef=str(index),
+                    PackageWeight=parcelone.MeasurementType(
+                        Value=str(pkg.weight.KG),
+                        Unit="kg",
+                    ),
+                    PackageDimensions=(
+                        parcelone.DimensionsType(
+                            Length=str(pkg.length.CM),
+                            Width=str(pkg.width.CM),
+                            Height=str(pkg.height.CM),
+                        )
+                        if pkg.length.CM and pkg.width.CM and pkg.height.CM
+                        else None
+                    ),
+                )
+                for index, pkg in enumerate(packages, 1)
+            ],
+        ),
+    )
+
+    return lib.Serializable(
+        request,
+        lib.to_dict,
+        dict(service_code=service.name if hasattr(service, 'name') else str(service)),
+    )

karrio/providers/parcelone/shipment/__init__.py

@@ -0,0 +1,17 @@
+"""ParcelOne shipment operations."""
+
+from karrio.providers.parcelone.shipment.create import (
+    parse_shipment_response,
+    shipment_request,
+)
+from karrio.providers.parcelone.shipment.cancel import (
+    parse_shipment_cancel_response,
+    shipment_cancel_request,
+)
+
+__all__ = [
+    "parse_shipment_response",
+    "shipment_request",
+    "parse_shipment_cancel_response",
+    "shipment_cancel_request",
+]

karrio/providers/parcelone/shipment/cancel.py

@@ -0,0 +1,60 @@
+"""Karrio ParcelOne shipment cancellation implementation."""
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.parcelone.error as error
+import karrio.providers.parcelone.utils as provider_utils
+
+
+def parse_shipment_cancel_response(
+    _response: lib.Deserializable[dict],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.Optional[models.ConfirmationDetails], typing.List[models.Message]]:
+    """Parse shipment cancellation response from ParcelOne REST API."""
+    response = _response.deserialize()
+    messages = error.parse_error_response(response, settings)
+    success = response.get("success") == 1
+
+    confirmation = lib.identity(
+        models.ConfirmationDetails(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            operation="Cancel Shipment",
+            success=success,
+        )
+        if success
+        else None
+    )
+
+    return confirmation, messages
+
+
+def shipment_cancel_request(
+    payload: models.ShipmentCancelRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Create ParcelOne shipment cancel request.
+
+    The API uses DELETE /shipment/{ShipmentRefField}/{ShipmentRefValue}
+    where ShipmentRefField can be: ShipmentID, ShipmentRef, or TrackingID
+    """
+    # Determine which reference field to use based on identifier format
+    identifier = payload.shipment_identifier
+
+    # If it's a numeric string, it's likely a ShipmentID
+    # If it starts with digits and has a specific length (13), it's likely a TrackingID
+    # Otherwise, treat it as a ShipmentRef
+    if identifier.isdigit() and len(identifier) < 10:
+        ref_field = "ShipmentID"
+    elif identifier.isdigit() and len(identifier) >= 10:
+        ref_field = "TrackingID"
+    else:
+        ref_field = "ShipmentRef"
+
+    request = dict(
+        ref_field=ref_field,
+        ref_value=identifier,
+    )
+
+    return lib.Serializable(request, lib.to_dict)