karrio-postat 2026.1__py3-none-any.whl

karrio/mappers/postat/__init__.py

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

karrio/mappers/postat/mapper.py

@@ -0,0 +1,41 @@
+"""Karrio PostAT client mapper."""
+
+import typing
+import karrio.lib as lib
+import karrio.api.mapper as mapper
+import karrio.core.models as models
+import karrio.providers.postat as provider
+import karrio.mappers.postat.settings as provider_settings
+import karrio.universal.providers.rating as universal_provider
+
+
+class Mapper(mapper.Mapper):
+    settings: provider_settings.Settings
+
+    def create_rate_request(self, payload: models.RateRequest) -> lib.Serializable:
+        return universal_provider.rate_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[str]:
+        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 universal_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)

karrio/mappers/postat/proxy.py

@@ -0,0 +1,43 @@
+"""Karrio PostAT client proxy."""
+
+import karrio.lib as lib
+import karrio.api.proxy as proxy
+import karrio.mappers.postat.settings as provider_settings
+import karrio.universal.mappers.rating_proxy as rating_proxy
+
+
+class Proxy(rating_proxy.RatingMixinProxy, proxy.Proxy):
+    settings: provider_settings.Settings
+
+    def get_rates(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        return super().get_rates(request)
+
+    def create_shipment(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        """Create a shipment using ImportShipment SOAP operation."""
+        response = lib.request(
+            url=self.settings.server_url,
+            data=request.serialize(),
+            trace=self.trace_as("xml"),
+            method="POST",
+            headers={
+                "Content-Type": "text/xml; charset=utf-8",
+                "SOAPAction": "http://post.ondot.at/IShippingService/ImportShipment",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_element)
+
+    def cancel_shipment(self, request: lib.Serializable) -> lib.Deserializable[str]:
+        """Cancel a shipment using CancelShipments SOAP operation."""
+        response = lib.request(
+            url=self.settings.server_url,
+            data=request.serialize(),
+            trace=self.trace_as("xml"),
+            method="POST",
+            headers={
+                "Content-Type": "text/xml; charset=utf-8",
+                "SOAPAction": "http://post.ondot.at/IShippingService/CancelShipments",
+            },
+        )
+
+        return lib.Deserializable(response, lib.to_element)

karrio/mappers/postat/settings.py

@@ -0,0 +1,35 @@
+"""Karrio PostAT client settings."""
+
+import attr
+import typing
+import jstruct
+import karrio.core.models as models
+import karrio.providers.postat.units as provider_units
+import karrio.providers.postat.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):
+    """PostAT connection settings."""
+
+    # Required credentials (from Austrian Post onboarding)
+    client_id: str
+    org_unit_id: str
+    org_unit_guid: str
+
+    # generic properties
+    id: str = None
+    test_mode: bool = False
+    carrier_id: str = "postat"
+    services: typing.List[models.ServiceLevel] = jstruct.JList[models.ServiceLevel, False, dict(default=provider_units.DEFAULT_SERVICES)]  # type: ignore
+    account_country_code: str = "AT"
+    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/postat/__init__.py

@@ -0,0 +1,28 @@
+from karrio.core.metadata import PluginMetadata
+
+from karrio.mappers.postat.mapper import Mapper
+from karrio.mappers.postat.proxy import Proxy
+from karrio.mappers.postat.settings import Settings
+import karrio.providers.postat.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="postat",
+    label="PostAT",
+    description="Austrian Post (Österreichische Post) shipping integration via Post-Labelcenter API",
+    # Integrations
+    Mapper=Mapper,
+    Proxy=Proxy,
+    Settings=Settings,
+    # Data Units
+    is_hub=False,
+    options=units.ShippingOption,
+    services=units.ShippingService,
+    connection_configs=units.ConnectionConfig,
+    # Extra info
+    website="https://www.post.at",
+    documentation="https://www.post.at/en/business-post-labelcenter",
+)

karrio/providers/postat/__init__.py

@@ -0,0 +1,8 @@
+"""Karrio PostAT provider imports."""
+from karrio.providers.postat.utils import Settings
+from karrio.providers.postat.shipment import (
+    parse_shipment_cancel_response,
+    parse_shipment_response,
+    shipment_cancel_request,
+    shipment_request,
+)

karrio/providers/postat/error.py

@@ -0,0 +1,30 @@
+"""Karrio PostAT error parser."""
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+from karrio.core.utils.soap import extract_fault
+import karrio.providers.postat.utils as provider_utils
+
+
+def parse_error_response(
+    response: lib.Element,
+    settings: provider_utils.Settings,
+    **kwargs,
+) -> typing.List[models.Message]:
+    """Parse error response from PostAT SOAP API."""
+    errors = lib.find_element("Error", response) or []
+
+    return [
+        models.Message(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            code=error.findtext("Code") or "ERROR",
+            message=error.findtext("Message") or "",
+            details={
+                **({"description": error.findtext("Description")} if error.findtext("Description") else {}),
+                **kwargs,
+            },
+        )
+        for error in errors
+    ] + extract_fault(response, settings)

karrio/providers/postat/shipment/__init__.py

@@ -0,0 +1,9 @@
+
+from karrio.providers.postat.shipment.create import (
+    parse_shipment_response,
+    shipment_request,
+)
+from karrio.providers.postat.shipment.cancel import (
+    parse_shipment_cancel_response,
+    shipment_cancel_request,
+)

karrio/providers/postat/shipment/cancel.py

@@ -0,0 +1,65 @@
+"""Karrio PostAT shipment cancellation API implementation."""
+
+import karrio.schemas.postat.void_types as postat_void
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.postat.error as error
+import karrio.providers.postat.utils as provider_utils
+
+
+def parse_shipment_cancel_response(
+    _response: lib.Deserializable[lib.Element],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.Optional[models.ConfirmationDetails], typing.List[models.Message]]:
+    """Parse shipment cancellation response from PostAT SOAP API."""
+    response = _response.deserialize()
+    messages = error.parse_error_response(response, settings)
+
+    # Check for VoidShipmentResult
+    result = lib.find_element("VoidShipmentResult", response, first=True)
+    success_elem = lib.find_element("Success", result, first=True)
+    success = (
+        success_elem is not None
+        and success_elem.text
+        and success_elem.text.lower() == "true"
+        and not any(messages)
+    )
+
+    confirmation = (
+        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 a shipment cancellation request for the PostAT SOAP API."""
+    # Build request using generated schema types
+    request = lib.Envelope(
+        Body=lib.Body(
+            postat_void.VoidShipmentType(
+                row=[
+                    postat_void.VoidShipmentRowType(
+                        TrackingNumber=payload.shipment_identifier,
+                        OrgUnitID=settings.org_unit_id,
+                        OrgUnitGuid=settings.org_unit_guid,
+                    )
+                ]
+            )
+        )
+    )
+
+    return lib.Serializable(request, lib.envelope_serializer)
+    

karrio/providers/postat/shipment/create.py

@@ -0,0 +1,147 @@
+"""Karrio PostAT shipment API implementation."""
+
+import karrio.schemas.postat.plc_types as postat
+
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.postat.error as error
+import karrio.providers.postat.utils as provider_utils
+import karrio.providers.postat.units as provider_units
+
+
+def parse_shipment_response(
+    _response: lib.Deserializable[lib.Element],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.Optional[models.ShipmentDetails], typing.List[models.Message]]:
+    response = _response.deserialize()
+    messages = error.parse_error_response(response, settings)
+    result = lib.find_element("ImportShipmentResult", response, first=True)
+    shipment = (
+        _extract_details(response, settings)
+        if result is not None and not any(messages)
+        else None
+    )
+
+    return shipment, messages
+
+
+def _extract_details(
+    response: lib.Element,
+    settings: provider_utils.Settings,
+) -> models.ShipmentDetails:
+    """Extract shipment details from ImportShipmentResponse."""
+    result = lib.find_element("ImportShipmentResult", response, first=True)
+    pdf_data = lib.find_element("pdfData", response, first=True)
+    zpl_data = lib.find_element("zplLabelData", response, first=True)
+
+    code_elements = lib.find_element("Code", result) or []
+    tracking_numbers = [code.text for code in code_elements if code.text]
+    tracking_number = tracking_numbers[0]
+
+    label = lib.failsafe(lambda: zpl_data.text) or lib.failsafe(lambda: pdf_data.text)
+    label_type = "ZPL" if zpl_data is not None and zpl_data.text else "PDF"
+
+    return models.ShipmentDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        tracking_number=tracking_number,
+        shipment_identifier=tracking_number,
+        label_type=label_type,
+        docs=models.Documents(label=label),
+        meta=dict(
+            tracking_numbers=tracking_numbers,
+        ),
+    )
+
+
+def shipment_request(
+    payload: models.ShipmentRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    """Create a shipment request for the PostAT SOAP API."""
+    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
+    options = lib.to_shipping_options(
+        payload.options,
+        package_options=packages.options,
+        initializer=provider_units.shipping_options_initializer,
+    )
+
+    # Label configuration with fallbacks
+    label_format = lib.identity(
+        settings.connection_config.label_format.state or payload.label_type
+    )
+    label_size = lib.identity(
+        settings.connection_config.label_size.state
+        or options.postat_label_size.state
+        or "SIZE_100x150"
+    )
+    paper_layout = lib.identity(
+        settings.connection_config.paper_layout.state
+        or options.postat_paper_layout.state
+        or "LAYOUT_2xA5inA4"
+    )
+
+    # Build request using generated schema types
+    request = lib.Envelope(
+        Body=lib.Body(
+            postat.ImportShipmentType(
+                row=[
+                    postat.ImportShipmentRowType(
+                        ClientID=settings.client_id,
+                        OrgUnitID=settings.org_unit_id,
+                        OrgUnitGuid=settings.org_unit_guid,
+                        DeliveryServiceThirdPartyID=service,
+                        CustomDataBit1=False,
+                        OUShipperReference1=payload.reference,
+                        ColloList=postat.ColloListType(
+                            ColloRow=[
+                                postat.ColloRowType(
+                                    Weight=package.weight.KG,
+                                    Length=package.length.CM,
+                                    Width=package.width.CM,
+                                    Height=package.height.CM,
+                                )
+                                for package in packages
+                            ]
+                        ),
+                        OURecipientAddress=postat.AddressType(
+                            Name1=recipient.company_name or recipient.person_name,
+                            Name2=(
+                                recipient.person_name
+                                if recipient.company_name
+                                else None
+                            ),
+                            AddressLine1=recipient.street,
+                            AddressLine2=recipient.address_line2,
+                            HouseNumber=recipient.street_number,
+                            PostalCode=recipient.postal_code,
+                            City=recipient.city,
+                            CountryID=recipient.country_code,
+                            Email=recipient.email,
+                            Tel1=recipient.phone_number,
+                        ),
+                        OUShipperAddress=postat.AddressType(
+                            Name1=shipper.company_name or shipper.person_name,
+                            Name2=shipper.person_name if shipper.company_name else None,
+                            AddressLine1=shipper.street,
+                            AddressLine2=shipper.address_line2,
+                            PostalCode=shipper.postal_code,
+                            City=shipper.city,
+                            CountryID=shipper.country_code,
+                        ),
+                        PrinterObject=postat.PrinterObjectType(
+                            LabelFormatID=label_size,
+                            LanguageID=label_format,
+                            PaperLayoutID=paper_layout,
+                        ),
+                    )
+                ]
+            )
+        )
+    )
+
+    return lib.Serializable(request, lib.envelope_serializer)

karrio/providers/postat/units.py

@@ -0,0 +1,241 @@
+"""PostAT units and enums."""
+
+import csv
+import pathlib
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+
+
+class LabelFormat(lib.StrEnum):
+    """Supported label formats."""
+
+    PDF = "pdf"
+    ZPL2 = "zpl2"
+
+
+class LabelSize(lib.StrEnum):
+    """Supported label sizes."""
+
+    SIZE_100x150 = "100x150"
+    SIZE_100x200 = "100x200"
+
+
+class PaperLayout(lib.StrEnum):
+    """Supported paper layouts for PDF output."""
+
+    LAYOUT_2xA5inA4 = "2xA5inA4"
+    LAYOUT_4xA6inA4 = "4xA6inA4"
+    LAYOUT_A4 = "A4"
+
+
+class ConnectionConfig(lib.Enum):
+    """PostAT connection configuration options."""
+
+    server_url = lib.OptionEnum("server_url", str)
+    label_format = lib.OptionEnum(
+        "label_format",
+        lib.units.create_enum("LabelFormat", [_.name for _ in LabelFormat]),
+    )
+    label_size = lib.OptionEnum(
+        "label_size",
+        lib.units.create_enum("LabelSize", [_.name for _ in LabelSize]),
+    )
+    paper_layout = lib.OptionEnum(
+        "paper_layout",
+        lib.units.create_enum("PaperLayout", [_.name for _ in PaperLayout]),
+    )
+    shipping_services = lib.OptionEnum("shipping_services", list)
+    shipping_options = lib.OptionEnum("shipping_options", list)
+
+
+class ShippingService(lib.StrEnum):
+    """PostAT shipping services.
+
+    Note: Service codes (DeliveryServiceThirdPartyID) are configured per account
+    by Austrian Post. These are common examples.
+    """
+
+    postat_standard_domestic = "10"
+    postat_express_domestic = "20"
+    postat_international_standard = "30"
+    postat_international_express = "40"
+
+
+class ShippingOption(lib.Enum):
+    """PostAT shipping options (Features)."""
+
+    # Label configuration (can be set per-shipment)
+    postat_label_size = lib.OptionEnum("label_size", str)
+    postat_paper_layout = lib.OptionEnum("paper_layout", str)
+
+    # Cash on Delivery
+    postat_cod = lib.OptionEnum("COD", float)
+    postat_cod_currency = lib.OptionEnum("COD_CURRENCY", str)
+
+    # Insurance
+    postat_insurance = lib.OptionEnum("INS", float)
+    postat_insurance_currency = lib.OptionEnum("INS_CURRENCY", str)
+
+    # Signature required
+    postat_signature = lib.OptionEnum("SIG", bool)
+
+    # Saturday delivery
+    postat_saturday_delivery = lib.OptionEnum("SAT", bool)
+
+    # Email notification
+    postat_email_notification = lib.OptionEnum("MAIL", str)
+
+    # SMS notification
+    postat_sms_notification = lib.OptionEnum("SMS", str)
+
+    # Age verification (16 or 18)
+    postat_age_verification = lib.OptionEnum("AGE", int)
+
+    # Unified option mappings
+    cash_on_delivery = postat_cod
+    insurance = postat_insurance
+    signature_required = postat_signature
+    saturday_delivery = postat_saturday_delivery
+    email_notification = postat_email_notification
+
+
+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):
+    """PostAT tracking status mapping."""
+
+    pending = [
+        "REGISTERED",
+        "CREATED",
+        "DATA_RECEIVED",
+        "LABEL_PRINTED",
+    ]
+    delivered = [
+        "DELIVERED",
+        "ZUGESTELLT",
+        "POD",
+    ]
+    in_transit = [
+        "IN_TRANSIT",
+        "UNTERWEGS",
+        "DEPARTED",
+        "ARRIVED",
+    ]
+    out_for_delivery = [
+        "OUT_FOR_DELIVERY",
+        "IN_ZUSTELLUNG",
+    ]
+    on_hold = [
+        "HELD",
+        "CUSTOMS",
+    ]
+    delivery_failed = [
+        "FAILED",
+        "NOT_DELIVERED",
+        "REFUSED",
+    ]
+
+
+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="PostAT Standard Domestic",
+                service_code="postat_standard_domestic",
+                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()
+            ]
+
+            # Parse transit days (handle "1-3" format)
+            transit_days = None
+            if row.get("transit_days"):
+                transit_str = row["transit_days"].split("-")[0]
+                if transit_str.isdigit():
+                    transit_days = int(transit_str)
+
+            # Create zone
+            zone = models.ServiceZone(
+                label=row.get("zone_label", "Default Zone"),
+                rate=float(row.get("rate", 0.0)),
+                transit_days=transit_days,
+                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()