karrio-server-manager 2025.5rc1__py3-none-any.whl

karrio/server/manager/router.py

@@ -0,0 +1,3 @@
+from rest_framework.routers import DefaultRouter
+
+router = DefaultRouter(trailing_slash=False)

karrio/server/manager/serializers/__init__.py

@@ -0,0 +1,50 @@
+from karrio.server.serializers import *
+from karrio.server.core.serializers import *
+from karrio.server.manager.serializers.address import (
+    AddressSerializer,
+    can_mutate_address,
+)
+from karrio.server.manager.serializers.parcel import (
+    ParcelSerializer,
+    can_mutate_parcel,
+)
+from karrio.server.manager.serializers.customs import (
+    CustomsSerializer,
+    can_mutate_customs,
+)
+from karrio.server.manager.serializers.commodity import (
+    CommoditySerializer,
+    can_mutate_commodity,
+)
+from karrio.server.manager.serializers.rate import RateSerializer
+from karrio.server.manager.serializers.tracking import (
+    TrackingSerializer,
+    TrackerUpdateData,
+    update_shipment_tracker,
+    can_mutate_tracker,
+)
+from karrio.server.manager.serializers.shipment import (
+    ShipmentRateData,
+    ShipmentSerializer,
+    ShipmentUpdateData,
+    ShipmentPurchaseData,
+    ShipmentPurchaseSerializer,
+    ShipmentCancelSerializer,
+    create_shipment_tracker,
+    reset_related_shipment_rates,
+    can_mutate_shipment,
+    buy_shipment_label,
+    fetch_shipment_rates,
+)
+from karrio.server.manager.serializers.pickup import (
+    PickupData,
+    PickupUpdateData,
+    PickupCancelData,
+)
+from karrio.server.manager.serializers.document import (
+    DocumentUploadSerializer,
+    can_upload_shipment_document,
+)
+from karrio.server.manager.serializers.manifest import (
+    ManifestSerializer,
+)

karrio/server/manager/serializers/address.py

@@ -0,0 +1,82 @@
+from rest_framework import status
+
+from karrio.server.core.exceptions import APIException
+from karrio.server.serializers import owned_model_serializer
+from karrio.core import utils
+from karrio.server.core import gateway
+from karrio.server.core.serializers import AddressData, ShipmentStatus
+from karrio.server.manager import models
+
+
+@owned_model_serializer
+class AddressSerializer(AddressData):
+    def validate(self, data):
+        validated_data = super().validate(data)
+        should_validate = validated_data.get("validate_location") is True or (
+            self.instance is not None and self.instance.validate_location
+        )
+
+        if should_validate:
+            address = {
+                **(
+                    AddressData(self.instance).data if self.instance is not None else {}
+                ),
+                **validated_data,
+            }
+            validation = gateway.Address.validate(address)
+            validated_data.update(dict(validation=utils.DP.to_dict(validation)))
+
+        return validated_data
+
+    def create(self, validated_data: dict, **kwargs) -> models.Address:
+        return models.Address.objects.create(**validated_data)
+
+    def update(
+        self, instance: models.Address, validated_data: dict, **kwargs
+    ) -> models.Address:
+        changes = []
+        for key, val in validated_data.items():
+            if getattr(instance, key) != val:
+                changes.append(key)
+                setattr(instance, key, val)
+
+        instance.save(update_fields=changes)
+        return instance
+
+
+def can_mutate_address(
+    address: models.Address, update: bool = False, delete: bool = False
+):
+    shipment = address.shipment
+    order = address.order
+
+    if shipment is None and order is None:
+        return
+
+    if update and shipment and shipment.status != ShipmentStatus.draft.value:
+        raise APIException(
+            f"Operation not permitted. The related shipment is '{shipment.status}'.",
+            status_code=status.HTTP_409_CONFLICT,
+            code="state_error",
+        )
+
+    if delete and shipment is not None:
+        raise APIException(
+            "This address is linked to a shipment and cannot be removed",
+            status_code=status.HTTP_409_CONFLICT,
+            code="state_error",
+        )
+
+    if update and order and order.status != "unfulfilled":
+        raise APIException(
+            f"Operation not permitted. The related order is '{order.status}'.",
+            status_code=status.HTTP_409_CONFLICT,
+            code="state_error",
+        )
+
+    if delete and order is not None:
+        raise APIException(
+            "This address is linked to an order and cannot be removed",
+            status_code=status.HTTP_409_CONFLICT,
+            code="state_error",
+        )

karrio/server/manager/serializers/commodity.py

@@ -0,0 +1,51 @@
+from rest_framework import status
+
+from karrio.server.core.exceptions import APIException
+from karrio.server.core.serializers import CommodityData, ShipmentStatus
+from karrio.server.serializers import owned_model_serializer
+import karrio.server.manager.models as models
+
+
+@owned_model_serializer
+class CommoditySerializer(CommodityData):
+    object_type = None
+
+    def create(self, validated_data: dict, **kwargs) -> models.Commodity:
+        return models.Commodity.objects.create(**validated_data)
+
+    def update(
+        self, instance: models.Commodity, validated_data: dict, **kwargs
+    ) -> models.Commodity:
+        changes = []
+
+        for key, val in validated_data.items():
+            if getattr(instance, key) != val:
+                changes.append(key)
+                setattr(instance, key, val)
+
+        instance.save()
+        return instance
+
+
+def can_mutate_commodity(
+    commodity: models.Commodity, update: bool = False, delete: bool = False, **kwargs
+):
+    shipment = commodity.shipment
+    order = commodity.order
+
+    if shipment is None and order is None:
+        return
+
+    if update and shipment and shipment.status != ShipmentStatus.draft.value:
+        raise APIException(
+            f"Operation not permitted. The related shipment is '{shipment.status}'.",
+            status_code=status.HTTP_409_CONFLICT,
+            code="state_error",
+        )
+
+    if delete and order and len(order.line_items.all()) == 1:
+        raise APIException(
+            f"Operation not permitted. The related order needs at least one line_item.",
+            status_code=status.HTTP_409_CONFLICT,
+            code="state_error",
+        )

karrio/server/manager/serializers/customs.py

@@ -0,0 +1,84 @@
+from django.db import transaction
+from rest_framework import status
+
+import karrio.server.manager.models as models
+import karrio.server.serializers as serializers
+import karrio.server.core.exceptions as exceptions
+from karrio.server.core.serializers import CustomsData, ShipmentStatus
+from karrio.server.manager.serializers.address import AddressSerializer
+from karrio.server.manager.serializers.commodity import CommoditySerializer
+
+
+@serializers.owned_model_serializer
+class CustomsSerializer(CustomsData):
+    def __init__(self, instance: models.Customs = None, **kwargs):
+        data = kwargs.get("data") or {}
+
+        if ("commodities" in data) and (instance is not None):
+            context = getattr(self, "__context", None) or kwargs.get("context")
+            serializers.save_many_to_many_data(
+                "commodities",
+                CommoditySerializer,
+                instance,
+                payload=data,
+                context=context,
+                partial=True,
+            )
+
+        super().__init__(instance, **kwargs)
+
+    @transaction.atomic
+    def create(self, validated_data: dict, context: dict, **kwargs) -> models.Customs:
+        instance = models.Customs.objects.create(
+            **{
+                **{
+                    key: value
+                    for key, value in validated_data.items()
+                    if key in models.Customs.DIRECT_PROPS
+                },
+                "duty_billing_address": serializers.save_one_to_one_data(
+                    "duty_billing_address",
+                    AddressSerializer,
+                    payload=validated_data,
+                    context=context,
+                ),
+            }
+        )
+
+        serializers.save_many_to_many_data(
+            "commodities",
+            CommoditySerializer,
+            instance,
+            payload=validated_data,
+            context=context,
+        )
+
+        return instance
+
+    @transaction.atomic
+    def update(
+        self, instance: models.Customs, validated_data: dict, **kwargs
+    ) -> models.Customs:
+        data = serializers.process_dictionaries_mutations(
+            ["options"], validated_data, instance
+        )
+        changes = []
+
+        for key, val in data.items():
+            if key in models.Customs.DIRECT_PROPS and getattr(instance, key) != val:
+                changes.append(key)
+                setattr(instance, key, val)
+
+        instance.save(update_fields=changes)
+        return instance
+
+
+def can_mutate_customs(customs: models.Customs, **kwargs):
+    shipment = customs.shipment
+
+    if shipment is not None and shipment.status != ShipmentStatus.create.value:
+        raise exceptions.APIException(
+            f"Operation not permitted. The related shipment is '{shipment.status}'.",
+            status_code=status.HTTP_409_CONFLICT,
+            code="state_error",
+        )

karrio/server/manager/serializers/document.py

@@ -0,0 +1,113 @@
+import rest_framework.status as status
+
+import karrio.lib as lib
+import karrio.server.serializers as serialiazers
+import karrio.server.core.exceptions as exceptions
+import karrio.server.core.serializers as core
+import karrio.server.core.gateway as gateway
+import karrio.server.manager.models as models
+
+
+@serialiazers.owned_model_serializer
+class DocumentUploadSerializer(core.DocumentUploadData):
+    def create(
+        self,
+        validated_data: dict,
+        context: serialiazers.Context,
+        **kwargs,
+    ) -> models.DocumentUploadRecord:
+        shipment = validated_data.get("shipment")
+        carrier = validated_data.get("carrier") or getattr(
+            shipment, "selected_rate_carrier", None
+        )
+        tracking_number = getattr(shipment, "tracking_number", None)
+        reference = validated_data.get("reference") or tracking_number
+
+        payload = core.DocumentUploadData(validated_data).data
+        options = ({
+            "origin_country_code": shipment.shipper.country_code,
+            "origin_postal_code": shipment.shipper.postal_code,
+            "destination_country_code": shipment.recipient.country_code,
+            "destination_postal_code": shipment.recipient.postal_code,
+            **(payload.get("options") or {})
+        } if shipment else payload.get("options"))
+
+        response = gateway.Documents.upload(
+            {
+                **payload,
+                "options": options,
+                "reference": reference,
+                "tracking_number": tracking_number,
+            },
+            carrier=carrier,
+            context=context,
+        )
+
+        upload_record = models.DocumentUploadRecord.objects.create(
+            documents=lib.to_dict(response.documents),
+            messages=lib.to_dict(response.messages),
+            options=response.options,
+            meta=response.meta,
+            shipment=shipment,
+            upload_carrier=carrier,
+            created_by=context.user,
+        )
+
+        return upload_record
+
+    def update(
+        self,
+        instance: models.DocumentUploadRecord,
+        validated_data: dict,
+        context: serialiazers.Context,
+        **kwargs,
+    ) -> models.DocumentUploadRecord:
+        changes = []
+
+        response = gateway.Documents.upload(
+            {
+                "reference": getattr(instance.shipment, "tracking_number", None),
+                **core.DocumentUploadData(validated_data).data,
+            },
+            carrier=instance.upload_carrier,
+            context=context,
+        )
+
+        if any(response.documents):
+            changes.append("documents")
+            instance.documents = [*instance.documents, *lib.to_dict(response.documents)]
+
+        if any(response.messages):
+            changes.append("messages")
+            instance.messages = lib.to_dict(response.messages)
+
+        instance.save(update_fields=changes)
+
+        return instance
+
+
+def can_upload_shipment_document(shipment: models.Shipment):
+    carrier = getattr(shipment, "selected_rate_carrier", None)
+    capabilities = getattr(carrier, "capabilities", [])
+
+    if shipment is None:
+        raise exceptions.APIException(
+            detail=f"No purchased shipment found for trade document upload.",
+            status_code=status.HTTP_400_BAD_REQUEST,
+        )
+
+    if shipment.status not in [
+        core.ShipmentStatus.shipped.value,
+        core.ShipmentStatus.purchased.value,
+        core.ShipmentStatus.in_transit.value,
+    ]:
+        raise exceptions.APIException(
+            detail=f"The trade document upload is not enabled for shipment status: '{shipment.status}'.",
+            status_code=status.HTTP_409_CONFLICT,
+        )
+
+    if "paperless" not in capabilities:
+        raise exceptions.APIException(
+            detail=f"trade document upload is not supported by carrier: '{carrier.carrier_id}'",
+            status_code=status.HTTP_406_NOT_ACCEPTABLE,
+        )

karrio/server/manager/serializers/manifest.py

@@ -0,0 +1,85 @@
+import typing
+
+import karrio.server.core.gateway as gateway
+import karrio.server.manager.models as models
+import karrio.server.core.serializers as core
+import karrio.server.serializers as serializers
+import karrio.server.manager.serializers as manager
+
+DEFAULT_CARRIER_FILTER: typing.Any = dict(active=True, capability="manifest")
+
+
+@serializers.owned_model_serializer
+class ManifestSerializer(core.ManifestData):
+    def create(
+        self, validated_data: dict, context: serializers.Context, **kwargs
+    ) -> models.Manifest:
+        data = validated_data.copy()
+        shipment_ids = list(set(data.pop("shipment_ids")))
+        carrier_name = data["carrier_name"]
+        carrier = gateway.Carriers.first(
+            context=context,
+            carrier_name=carrier_name,
+            **{"raise_not_found": True, **DEFAULT_CARRIER_FILTER},
+        )
+
+        shipments = models.Shipment.access_by(context).filter(
+            id__in=shipment_ids,
+            manifest__isnull=True,
+            selected_rate_carrier__carrier_code=carrier_name,
+        )
+        shipment_identifiers = [_.shipment_identifier for _ in shipments]
+
+        if (
+            len(shipment_identifiers) > len(shipment_ids)
+            or len(shipment_identifiers) == 0
+        ):
+            raise serializers.ValidationError(
+                {
+                    "shipment_ids": (
+                        "One or more shipment ids are invalid or not found. "
+                        "Please make sure that the shipments referenced exist and have been purchased with the same carrier."
+                    )
+                }
+            )
+
+        response = gateway.Manifests.create(
+            payload=core.ManifestRequest.map(
+                data={
+                    **data,
+                    "shipment_identifiers": shipment_identifiers,
+                    "options": {
+                        **data.get("options", {}),
+                        "shipments": core.Shipment(shipments, many=True).data,
+                    },
+                }
+            ).data,
+            carrier=carrier,
+        )
+
+        payload = {
+            key: value
+            for key, value in core.Manifest(response.manifest).data.items()
+            if key in models.Manifest.DIRECT_PROPS
+        }
+        address = serializers.save_one_to_one_data(
+            "address",
+            manager.AddressSerializer,
+            payload=validated_data,
+            context=context,
+        )
+
+        manifest = models.Manifest.objects.create(
+            **{
+                **payload,
+                "address": address,
+                "created_by": context.user,
+                "manifest_carrier": carrier,
+                "options": data.get("options", {}),
+                "test_mode": response.manifest.test_mode,
+                "manifest": response.manifest.doc.manifest,
+            }
+        )
+        manifest.shipments.set(shipments)
+
+        return manifest

karrio/server/manager/serializers/parcel.py

@@ -0,0 +1,84 @@
+from rest_framework import status
+
+from karrio.server.core.exceptions import APIException
+from karrio.server.core.serializers import ParcelData, ShipmentStatus
+from karrio.server.serializers import (
+    owned_model_serializer,
+    save_many_to_many_data,
+    process_dictionaries_mutations,
+)
+
+from karrio.server.manager.serializers.commodity import CommoditySerializer
+import karrio.server.manager.models as models
+
+
+@owned_model_serializer
+class ParcelSerializer(ParcelData):
+    object_type = None
+
+    def __init__(self, instance: models.Address = None, **kwargs):
+        data = kwargs.get("data") or {}
+
+        if ("items" in data) and (instance is not None):
+            context = getattr(self, "__context", None) or kwargs.get("context")
+            save_many_to_many_data(
+                "items",
+                CommoditySerializer,
+                instance,
+                payload=data,
+                context=context,
+            )
+
+        super().__init__(instance, **kwargs)
+
+    def create(self, validated_data: dict, context: dict, **kwargs) -> models.Parcel:
+        instance = models.Parcel.objects.create(
+            **{key: value for key, value in validated_data.items() if key != "items"}
+        )
+
+        save_many_to_many_data(
+            "items",
+            CommoditySerializer,
+            instance,
+            payload=validated_data,
+            context=context,
+        )
+
+        return instance
+
+    def update(
+        self, instance: models.Parcel, validated_data: dict, **kwargs
+    ) -> models.Parcel:
+        data = process_dictionaries_mutations(["options"], validated_data, instance)
+        changes = []
+
+        for key, val in data.items():
+            if getattr(instance, key) != val and key != "items":
+                changes.append(key)
+                setattr(instance, key, val)
+
+        instance.save(update_fields=changes)
+        return instance
+
+
+def can_mutate_parcel(
+    parcel: models.Parcel, update: bool = False, delete: bool = False, **kwargs
+):
+    shipment = parcel.shipment
+
+    if shipment is None:
+        return
+
+    if update and shipment.status != ShipmentStatus.draft.value:
+        raise APIException(
+            f"Operation not permitted. The related shipment is '{shipment.status}'.",
+            status_code=status.HTTP_409_CONFLICT,
+            code="state_error",
+        )
+
+    if delete and len(shipment.parcels.all()) == 1:
+        raise APIException(
+            f"Operation not permitted. The related shipment needs at least one parcel.",
+            status_code=status.HTTP_409_CONFLICT,
+            code="state_error",
+        )