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

karrio/server/proxy/views/rating.py

@@ -0,0 +1,57 @@
+import logging
+from django.urls import path
+from rest_framework import status
+from rest_framework.request import Request
+from rest_framework.response import Response
+
+from karrio.server.core.views.api import APIView
+from karrio.server.core.serializers import (
+    RateRequest,
+    RateResponse,
+    ErrorResponse,
+    ErrorMessages,
+)
+from karrio.server.core.gateway import Rates
+from karrio.server.proxy.router import router
+import karrio.server.openapi as openapi
+
+logger = logging.getLogger(__name__)
+ENDPOINT_ID = "@@"  # This endpoint id is used to make operation ids unique make sure not to duplicate
+
+DESCRIPTIONS = """
+The Shipping process begins by fetching rates for your shipment.
+Use this service to fetch a shipping rates available.
+"""
+
+
+class RateViewAPI(APIView):
+    throttle_scope = "carrier_request"
+
+    @openapi.extend_schema(
+        tags=["Proxy"],
+        operation_id=f"{ENDPOINT_ID}fetch_rates",
+        extensions={"x-operationId": "fetchRates"},
+        summary="Fetch shipment rates",
+        description=DESCRIPTIONS,
+        responses={
+            200: RateResponse(),
+            400: ErrorResponse(),
+            424: ErrorMessages(),
+            500: ErrorResponse(),
+        },
+        request=RateRequest(),
+    )
+    def post(self, request: Request):
+        payload = RateRequest.map(data=request.data).data
+
+        response = Rates.fetch(payload, context=request)
+        status_code = (
+            status.HTTP_207_MULTI_STATUS
+            if len(response.messages) > 0
+            else status.HTTP_200_OK
+        )
+
+        return Response(RateResponse(response).data, status=status_code)
+
+
+router.urls.append(path("proxy/rates", RateViewAPI.as_view(), name="shipment-rates"))

karrio/server/proxy/views/shipping.py

@@ -0,0 +1,139 @@
+import logging
+from django.urls import path
+from rest_framework import status
+from rest_framework.request import Request
+from rest_framework.reverse import reverse
+from rest_framework.response import Response
+
+import karrio.server.openapi as openapi
+import karrio.server.serializers as serializers
+import karrio.server.core.dataunits as dataunits
+import karrio.server.providers.models as providers
+from karrio.server.core.views.api import APIView
+from karrio.server.proxy.router import router
+from karrio.server.core.gateway import Shipments
+from karrio.server.core.serializers import (
+    COUNTRIES,
+    ShippingRequest,
+    ShipmentCancelRequest,
+    ShipmentContent,
+    ShipmentDetails,
+    OperationResponse,
+    Address as BaseAddress,
+    ErrorResponse,
+    ErrorMessages,
+)
+
+ENDPOINT_ID = "@@@"  # This endpoint id is used to make operation ids unique make sure not to duplicate
+logger = logging.getLogger(__name__)
+
+
+class Address(BaseAddress):
+    city = serializers.CharField(required=True, help_text="The address city")
+    person_name = serializers.CharField(required=True, help_text="attention to")
+    country_code = serializers.ChoiceField(
+        required=True, choices=COUNTRIES, help_text="The address country code"
+    )
+    address_line1 = serializers.CharField(
+        required=True, help_text="The address line with street number"
+    )
+
+
+class ShippingRequestValidation(ShippingRequest):
+    shipper = Address(
+        required=True, help_text="The origin address of the shipment (address from)"
+    )
+    recipient = Address(
+        required=True, help_text="The shipment destination address (address to)"
+    )
+
+
+class ShippingResponse(serializers.EntitySerializer, ShipmentContent, ShipmentDetails):
+    object_type = serializers.CharField(
+        default="shipment", help_text="Specifies the object type"
+    )
+
+
+class ShippingDetails(APIView):
+    throttle_scope = "carrier_request"
+
+    @openapi.extend_schema(
+        tags=["Proxy"],
+        operation_id=f"{ENDPOINT_ID}buy_label",
+        extensions={"x-operationId": "buyLabel"},
+        summary="Buy a shipment label",
+        request=ShippingRequest(),
+        responses={
+            200: ShippingResponse(),
+            400: ErrorResponse(),
+            424: ErrorMessages(),
+            500: ErrorResponse(),
+        },
+    )
+    def post(self, request: Request):
+        """
+        Once the shipping rates are retrieved, provide the required info to
+        submit the shipment by specifying your preferred rate.
+        """
+        payload = ShippingRequestValidation.map(data=request.data).data
+
+        response = Shipments.create(
+            payload,
+            resolve_tracking_url=(
+                lambda tracking_number, carrier_name: reverse(
+                    "karrio.server.proxy:shipment-tracking",
+                    kwargs=dict(
+                        tracking_number=tracking_number, carrier_name=carrier_name
+                    ),
+                )
+            ),
+        )
+
+        return Response(ShippingResponse(response).data, status=status.HTTP_200_OK)
+
+
+class ShippingCancel(APIView):
+    throttle_scope = "carrier_request"
+
+    @openapi.extend_schema(
+        tags=["Proxy"],
+        operation_id=f"{ENDPOINT_ID}void_label",
+        extensions={"x-operationId": "voidLabel"},
+        summary="Void a shipment label",
+        request=ShipmentCancelRequest(),
+        responses={
+            202: OperationResponse(),
+            400: ErrorResponse(),
+            424: ErrorMessages(),
+        },
+        parameters=[
+            openapi.OpenApiParameter(
+                "carrier_name",
+                location=openapi.OpenApiParameter.PATH,
+                type=openapi.OpenApiTypes.STR,
+                enum=dataunits.CARRIER_NAMES,
+            ),
+        ],
+    )
+    def post(self, request: Request, carrier_name: str):
+        """
+        Cancel a shipment and the label previously created
+        """
+        payload = ShipmentCancelRequest.map(data=request.data).data
+        response = Shipments.cancel(payload, context=request, carrier_name=carrier_name)
+
+        return Response(
+            OperationResponse(response).data, status=status.HTTP_202_ACCEPTED
+        )
+
+
+router.urls.append(
+    path("proxy/shipping", ShippingDetails.as_view(), name="shipping-request")
+)
+router.urls.append(
+    path(
+        "proxy/shipping/<carrier_name>/cancel",
+        ShippingCancel.as_view(),
+        name="shipping-cancel",
+    )
+)

karrio/server/proxy/views/tracking.py

@@ -0,0 +1,165 @@
+import logging
+from django.urls import path
+from rest_framework import status
+from rest_framework.response import Response
+from rest_framework.request import Request
+
+import karrio.server.openapi as openapi
+import karrio.server.core.dataunits as dataunits
+from karrio.server.core.views.api import APIView
+from karrio.server.core.serializers import (
+    TrackingData,
+    TrackingResponse,
+    ErrorResponse,
+    ErrorMessages,
+)
+from karrio.server.core.gateway import Shipments
+from karrio.server.proxy.router import router
+
+logger = logging.getLogger(__name__)
+ENDPOINT_ID = "@@@@"  # This endpoint id is used to make operation ids unique make sure not to duplicate
+
+
+class TrackingAPIView(APIView):
+    throttle_scope = "carrier_request"
+
+    @openapi.extend_schema(
+        tags=["Proxy"],
+        operation_id=f"{ENDPOINT_ID}get_tracking",
+        extensions={"x-operationId": "getTracking"},
+        summary="Get tracking details",
+        request=TrackingData(),
+        responses={
+            200: TrackingResponse(),
+            400: ErrorResponse(),
+            424: ErrorMessages(),
+            500: ErrorResponse(),
+        },
+        parameters=[
+            openapi.OpenApiParameter(
+                "hub",
+                location=openapi.OpenApiParameter.QUERY,
+                type=openapi.OpenApiTypes.STR,
+                required=False,
+            ),
+        ],
+    )
+    def post(self, request: Request):
+        """
+        You can track a shipment by specifying the carrier and the shipment tracking number.
+        """
+        query = request.query_params
+        serializer = TrackingData(data=request.data)
+        serializer.is_valid(raise_exception=True)
+        data = serializer.validated_data
+        carrier_filter = {
+            **{k: v for k, v in query.items() if k != "hub"},
+            # If a hub is specified, use the hub as carrier to track the package
+            "carrier_name": (
+                query.get("hub") if "hub" in query else data["carrier_name"]
+            ),
+        }
+        data = {
+            **data,
+            "tracking_numbers": [data["tracking_number"]],
+            "options": (
+                {data["tracking_number"]: {"carrier": data["carrier_name"]}}
+                if "hub" in query
+                else {}
+            ),
+        }
+
+        response = Shipments.track(data, context=request, **carrier_filter)
+
+        return Response(
+            TrackingResponse(response).data,
+            status=(
+                status.HTTP_200_OK
+                if response.tracking is not None
+                else status.HTTP_404_NOT_FOUND
+            ),
+        )
+
+
+class TrackingAPI(APIView):
+    throttle_scope = "carrier_request"
+    logging_methods = ["GET"]
+
+    @openapi.extend_schema(
+        tags=["Proxy"],
+        operation_id=f"{ENDPOINT_ID}track_shipment",
+        extensions={"x-operationId": "trackShipment"},
+        summary="Track a shipment",
+        deprecated=True,
+        responses={
+            200: TrackingResponse(),
+            400: ErrorResponse(),
+            424: ErrorMessages(),
+            500: ErrorResponse(),
+        },
+        parameters=[
+            openapi.OpenApiParameter(
+                "carrier_name",
+                location=openapi.OpenApiParameter.PATH,
+                type=openapi.OpenApiTypes.STR,
+                enum=dataunits.NON_HUBS_CARRIERS,
+                required=True,
+            ),
+            openapi.OpenApiParameter(
+                "tracking_number",
+                location=openapi.OpenApiParameter.PATH,
+                type=openapi.OpenApiTypes.STR,
+                required=True,
+            ),
+            openapi.OpenApiParameter(
+                "hub",
+                location=openapi.OpenApiParameter.QUERY,
+                type=openapi.OpenApiTypes.STR,
+                required=False,
+            ),
+        ],
+    )
+    def get(self, request: Request, carrier_name: str, tracking_number: str):
+        """
+        You can track a shipment by specifying the carrier and the shipment tracking number.
+        """
+        query = request.query_params
+        carrier_filter = {
+            **{k: v for k, v in query.items() if k != "hub"},
+            # If a hub is specified, use the hub as carrier to track the package
+            "carrier_name": (query.get("hub") if "hub" in query else carrier_name),
+        }
+        data = {
+            "tracking_numbers": [tracking_number],
+            "options": (
+                {tracking_number: {"carrier": carrier_name}} if "hub" in query else {}
+            ),
+        }
+
+        response = Shipments.track(data, context=request, **carrier_filter)
+
+        return Response(
+            TrackingResponse(response).data,
+            status=(
+                status.HTTP_200_OK
+                if response.tracking is not None
+                else status.HTTP_404_NOT_FOUND
+            ),
+        )
+
+
+router.urls.append(
+    path(
+        "proxy/tracking",
+        TrackingAPIView.as_view(),
+        name="get-tracking",
+    )
+)
+# Deprecated will be removed soon.
+router.urls.append(
+    path(
+        "proxy/tracking/<str:carrier_name>/<str:tracking_number>",
+        TrackingAPI.as_view(),
+        name="shipment-tracking",
+    )
+)

karrio_server_proxy-2025.5rc1.dist-info/METADATA

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: karrio_server_proxy
+Version: 2025.5rc1
+Summary: Multi-carrier shipping API Proxy module
+Author-email: karrio <hello@karrio.io>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/karrioapi/karrio
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: karrio_server_core
+
+# karrio.server.proxy
+
+This package is a module of the [karrio](https://pypi.org/project/karrio.server) universal shipping API.
+
+## Requirements
+
+`Python 3.11+`
+
+## Installation
+
+```bash
+pip install karrio.server.proxy
+```
+
+Check the [karrio docs](https://docs.karrio.io) to get started.

karrio_server_proxy-2025.5rc1.dist-info/RECORD

@@ -0,0 +1,22 @@
+karrio/server/proxy/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+karrio/server/proxy/admin.py,sha256=suMo4x8I3JBxAFBVIdE-5qnqZ6JAZV0FESABHOSc-vg,63
+karrio/server/proxy/apps.py,sha256=jSzNhgTmq6Z5mIo-pv5jeEx2PJMI31oUGfBBLEO3p-M,99
+karrio/server/proxy/models.py,sha256=Vjc0p2XbAPgE6HyTF6vll98A4eDhA5AvaQqsc4kQ9AQ,57
+karrio/server/proxy/router.py,sha256=IBUR7rfBkdEHQzWxYOPcVSM8NBp3fte9G6Q5BVTUNNw,95
+karrio/server/proxy/urls.py,sha256=DJFUFeaxOTyVNgu_A4opiX4-0gJlciRJNob-ScOkdV4,214
+karrio/server/proxy/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+karrio/server/proxy/tests/__init__.py,sha256=m6Nms0Mg2SsrhNtWGC9Pr67qxpWos3WHipHfQZ6Zslw,263
+karrio/server/proxy/tests/test_pickup.py,sha256=Z1P3a-ueLDkDPVnPEoPacHgtZXSgc6SCUYLpwv0DSzM,8817
+karrio/server/proxy/tests/test_rating.py,sha256=ACc-9DnlND1eEg2QN_roeIG6kOeKSrlQVEtXrubeKyA,3151
+karrio/server/proxy/tests/test_shipping.py,sha256=YG3uH5wL6bLEAO7iUQRsebKKuAFT23QegWRRyHgVOH0,10535
+karrio/server/proxy/tests/test_tracking.py,sha256=aO4y6MqgANCGA2QN3a79ZxyAGfXcEXlKV6ghogGbO-w,2965
+karrio/server/proxy/views/__init__.py,sha256=5W2I_z2WEgpnHzfrJWWMx0ptxGSGSHb3yO-ymYHggZQ,252
+karrio/server/proxy/views/manifest.py,sha256=8O9H8iUUTpL0wPge0_j7vmEYGcaksUk_5bxBp9FNgjE,1793
+karrio/server/proxy/views/pickup.py,sha256=GfmZBQMZSDDJKiHT-n3grIwgi02JMhnTQyaP7e4YcY8,4566
+karrio/server/proxy/views/rating.py,sha256=7S2N6szPSjQsShnCgzPL8iZpibpw8jbaWgSY9DWXYQI,1721
+karrio/server/proxy/views/shipping.py,sha256=gmO1OBVE8OgmyYIi_ksT_IARyqAeVKucUjMMiz_Vzyk,4459
+karrio/server/proxy/views/tracking.py,sha256=HwCMinmiLsLuYyQtQpdmorFQ0WoNQyQ3uJ12_l6IwpQ,5227
+karrio_server_proxy-2025.5rc1.dist-info/METADATA,sha256=D-e04IfxgPhkFTvaymOXcyaI73sLo1TXfoHvvvOivH8,680
+karrio_server_proxy-2025.5rc1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+karrio_server_proxy-2025.5rc1.dist-info/top_level.txt,sha256=D1D7x8R3cTfjF_15mfiO7wCQ5QMtuM4x8GaPr7z5i78,12
+karrio_server_proxy-2025.5rc1.dist-info/RECORD,,

karrio_server_proxy-2025.5rc1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

karrio_server_proxy-2025.5rc1.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+dist
+karrio