click_and_drop_api 3.0.2__tar.gz → 3.0.4__tar.gz

{click_and_drop_api-3.0.2/click_and_drop_api.egg-info → click_and_drop_api-3.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: click_and_drop_api
-Version: 3.0.2
+Version: 3.0.4
 Summary: ChannelShipper & Royal Mail Public API
 Home-page: 
 Author: OpenAPI Generator community

click_and_drop_api-3.0.4/click_and_drop_api/examples/oba_full_workflow.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python
+"""Full OBA workflow: create a cheap domestic order, generate a label,
+apply postage via manifest, and mark the order as despatched.
+
+Steps performed:
+  1. Verify the account is OBA (required for label generation and OBA services)
+  2. Pick the cheapest domestic OBA service
+  3. Create the order (with label generation requested at creation time)
+  4. Save the label PDF to disk
+  5. Manifest eligible orders (applies postage)
+  6. Set the order status to "despatched"
+
+Note: Label generation is only available for OBA customers.
+"""
+
+import os
+import sys
+from datetime import datetime, UTC
+from pathlib import Path
+
+from click_and_drop_api.simple import (
+    ClickAndDrop,
+    CreateOrder,
+    LabelGeneration,
+    RecipientDetails,
+    Address,
+    db,
+)
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+API_KEY = os.environ["API_KEY"]
+REFERENCE = "oba-workflow-{now}".format(now=datetime.now(UTC).strftime("%Y%m%d%H%M%S"))
+WEIGHT_GRAMS = 100
+
+api = ClickAndDrop(API_KEY)
+
+# ---------------------------------------------------------------------------
+# Step 1: verify OBA
+# ---------------------------------------------------------------------------
+
+print("Checking account type…")
+if not api.is_oba():
+    print("ERROR: This account is not OBA. Label generation requires an OBA account.")
+    sys.exit(1)
+print("Account is OBA.")
+
+# ---------------------------------------------------------------------------
+# Step 2: pick cheapest domestic OBA service
+# ---------------------------------------------------------------------------
+
+cheapest = db.filter(is_oba=True, international=False).any_or_none
+if cheapest is None:
+    print("ERROR: No domestic OBA service found in the shipping database.")
+    sys.exit(1)
+
+print(
+    f"Using service: {cheapest.brand} {cheapest.service_code}"
+    f" ({cheapest.delivery_speed}) — £{cheapest.gross}"
+)
+
+# ---------------------------------------------------------------------------
+# Step 3: create the order, requesting a label in the response
+# ---------------------------------------------------------------------------
+
+order = CreateOrder(
+    order_reference=REFERENCE,
+    recipient=RecipientDetails(
+        address=Address(
+            full_name="Nicco Kunzmann",
+            address_line1="1 Test Street",
+            city="London",
+            postcode="SW1A 1AA",
+            country_code="GB",
+        )
+    ),
+    order_date=datetime.now(UTC),
+    subtotal=1.00,
+    shipping_cost_charged=float(cheapest.gross),
+    total=1.00 + float(cheapest.gross),
+    currency_code="GBP",
+    postage_details=cheapest.as_postage_details(),
+    packages=[cheapest.as_package_request(weight_in_grams=WEIGHT_GRAMS)],
+    label=LabelGeneration(
+        include_label_in_response=True,
+        include_cn=False,
+        include_returns_label=False,
+    ),
+)
+
+print(f"Creating order {REFERENCE!r}…")
+response = api.create_order(order)
+
+if response.errors_count or not response.created_orders:
+    print(f"ERROR: Order creation failed: {response.failed_orders}")
+    sys.exit(1)
+
+created = response.created_orders[0]
+order_id = created.order_identifier
+print(f"Order created: id={order_id}, reference={created.order_reference}")
+
+# ---------------------------------------------------------------------------
+# Step 4: save label PDF
+# ---------------------------------------------------------------------------
+
+print("Fetching label…")
+label_pdf = api.get_label(order_id, "postageLabel", include_returns_label=False)
+label_path = Path(__file__).parent / "label.pdf"
+label_path.write_bytes(label_pdf)
+print(f"Label saved to {label_path}")
+
+# ---------------------------------------------------------------------------
+# Step 5: manifest (applies postage)
+# ---------------------------------------------------------------------------
+
+print("Manifesting eligible orders…")
+manifest = api.manifest_orders()
+print(f"Manifest number: {manifest.manifest_number}")
+if manifest.pdf is not None:
+    manifest_path = Path(__file__).parent / "manifest.pdf"
+    manifest_path.write_bytes(manifest.pdf)
+    print(f"Manifest PDF saved to {manifest_path}")
+
+# ---------------------------------------------------------------------------
+# Step 6: mark as despatched
+# ---------------------------------------------------------------------------
+
+print(f"Setting order {order_id} to 'despatched'…")
+update = api.update_orders([order_id], status="despatched")
+
+if update.errors:
+    print(f"WARNING: status update errors: {update.errors}")
+else:
+    print("Order marked as despatched.")
+
+print("Done.")

{click_and_drop_api-3.0.2 → click_and_drop_api-3.0.4}/click_and_drop_api/examples/shipping_countries.py

@@ -3,9 +3,14 @@
 
 Uses test_shipping internally: a test order is created and immediately deleted
 for each country, so no real shipments are made.
+
+Arguments:
+
+- service code (optional, defaults to OLP1)
 """
 
 import os
+import sys
 
 from click_and_drop_api.simple import ClickAndDrop
 
@@ -14,7 +19,7 @@ API_KEY = os.environ["API_KEY"]
 api = ClickAndDrop(API_KEY)
 
 PACKAGE_SIZE = "letter"
-SERVICE_CODE = "OLP1"
+SERVICE_CODE = "OLP1" if len(sys.argv) == 1 else sys.argv[1]
 
 countries = api.get_countries_for_shipping(
     package_size=PACKAGE_SIZE,

{click_and_drop_api-3.0.2 → click_and_drop_api-3.0.4}/click_and_drop_api/simple/api.py

@@ -101,60 +101,23 @@ class ClickAndDrop(AbstractClickAndDrop):
         """The API key in use."""
         return self._key
 
-    def get_orders(
-        self, order_identifiers: Union[list[Union[str, int]], str, int]
+    def _get_orders(
+        self, order_identifiers: Union[list[Union[str, int]]]
     ) -> list[click_and_drop_api.GetOrderInfoResource]:
-        """Get specific orders.
-
-        Parameters:
-            order_identifiers:
-                One or several Order Identifiers or Order References.
-                Order Identifiers are integer numbers.
-                Order References are strings.
-                The maximum number of identifiers is 100.
-
-        Returns:
-            A list of orders
-
-        Raises:
-            click_and_drop_api.exceptions.BadRequestException if an order with the same reference already exists
-
-        https://api.parcel.royalmail.com/#tag/Orders/operation/GetSpecificOrdersAsync
-        """
         return self._orders_api.get_specific_orders_async(
             order_identifiers=order_identifiers_to_string(order_identifiers)
         )
 
-    def delete_orders(
-        self, order_identifiers: Union[list[Union[str, int]], str, int]
+    def _delete_orders(
+        self, order_identifiers: list[Union[str, int]]
     ) -> click_and_drop_api.DeleteOrdersResource:
-        """Delete specific orders.
-
-        Please be aware labels generated on orders which are deleted are no longer valid and must be destroyed.
-        Cancelled label information is automatically shared with Royal Mail Revenue Protection,
-        and should a cancelled label be identified on an item in the Royal Mail Network,
-        you will be charged on your account and an additional handling fee applied.
-
-        Parameters:
-            order_identifiers:
-                One or several Order Identifiers or Order References.
-                Order Identifiers are integer numbers.
-                Order References are strings.
-                The maximum number of identifiers is 100.
-
-        https://api.parcel.royalmail.com/#tag/Orders/operation/DeleteOrdersAsync
-        """
         return self._orders_api.delete_orders_async(
             order_identifiers=order_identifiers_to_string(order_identifiers)
         )
 
-    def create_orders(
+    def _create_orders(
         self, orders: Union[list[CreateOrder], CreateOrder]
     ) -> click_and_drop_api.CreateOrdersResponse:
-        """Create a new order.
-
-        https://api.parcel.royalmail.com/#tag/Orders/operation/CreateOrdersAsync
-        """
         if not isinstance(orders, list):
             orders = [orders]
         request = click_and_drop_api.CreateOrdersRequest(items=orders)
@@ -207,5 +170,15 @@ class ClickAndDrop(AbstractClickAndDrop):
             include_cn=include_cn,
         )
 
+    def _set_order_status(
+        self, request: click_and_drop_api.UpdateOrdersStatusRequest
+    ) -> click_and_drop_api.UpdateOrderStatusResponse:
+        return self._orders_api.update_orders_status_async(request)
+
+    def _manifest_orders(
+        self, request: click_and_drop_api.ManifestEligibleOrdersRequest
+    ) -> click_and_drop_api.ManifestOrdersResponse:
+        return self._manifests_api.manifest_eligible_async(request)
+
 
 __all__ = ["ClickAndDrop"]