shopline-sdk-python 0.1.0__py3-none-any.whl

shopline_sdk/apis/orders/search_orders.py

@@ -0,0 +1,339 @@
+from typing import Any, Dict, List, Optional, Union
+import aiohttp
+from pydantic import BaseModel, ValidationError, Field
+from typing_extensions import Literal
+
+# 导入异常类
+from ...exceptions import ShoplineAPIError
+
+# 导入需要的模型
+from ...models.order import Order
+from ...models.paginatable import Paginatable
+from ...models.server_error import ServerError
+from ...models.unprocessable_entity_error import UnprocessableEntityError
+
+class Request(BaseModel):
+    """查询参数模型"""
+    page: Optional[int] = None
+    """Page
+      頁數（第n頁）
+      (Default: 1)"""
+    per_page: Optional[int] = None
+    """Numbers of Orders per page
+      每頁顯示 n 筆資料
+       (Default: 24, Max: 999)
+      -
+       *If there're many orders, it's suggested to set per_page number to 50
+       如果訂單眾多，建議per_page至多設定50"""
+    order_number: Optional[str] = None
+    """訂單號碼 (order_number, merchant_order_number)"""
+    customer_id: Optional[str] = None
+    """顧客 ID"""
+    customer_email: Optional[str] = None
+    """顧客電郵"""
+    name: Optional[str] = None
+    """顧客、收件人名稱 (customer_name, delivery_address.recipient_name, delivery_data.recipient_name)"""
+    phone_number: Optional[str] = None
+    """電話號碼 (customer_phone, delivery_data.recipient_phone)"""
+    delivery_data_tracking_number: Optional[str] = None
+    """配送資料追蹤編號"""
+    promotion_id: Optional[str] = None
+    """促銷活動 ID"""
+    item_id: Optional[str] = None
+    """訂單項目 ID"""
+    previous_id: Optional[str] = None
+    """To fetch data for the next page, include the ID of the last order from the previous page. 
+       用於拿取下一分頁資料，請帶入前一分頁的最後一筆訂單 ID 
+      
+       When fetching orders for the first page, this parameter is not required. 
+       拿取第一頁訂單時，可以不用帶此參數"""
+    query: Optional[str] = None
+    """Support query order fields
+      支援搜尋以下欄位
+       product_name
+       order_number
+       customer_id
+       customer_name
+       customer_phone
+       customer_email
+       delivery_address.recipient_name
+       delivery_data.recipient_name
+       delivery_data.recipient_phone
+       delivery_data.tracking_number
+       promotion_id
+       item_id*"""
+    search_fields: Optional[str] = None
+    """Targeted search fields
+      搜尋欄位
+       Default to 'default'
+       Values allow
+      
+      
+      <b>default</b>
+       Support query order fields
+      支援搜尋以下欄位
+       product_name
+       order_number
+       customer_id
+       customer_name
+       customer_phone
+       customer_email
+       delivery_address.recipient_name
+       delivery_data.recipient_name
+       delivery_data.recipient_phone
+       delivery_data.tracking_number
+       promotion_id
+       item_id*
+      
+      
+      <b>phone_number</b>
+       Support query order fields
+      支援搜尋以下欄位
+       customer_phone
+       delivery_data.recipient_phone
+      
+      
+      <b>order_number</b>
+       Support query order fields
+      支援搜尋以下欄位
+       order_number
+       merchant_order_number
+      
+      
+      <b>customize_customer_info</b>
+       Support query order fields
+      支援搜尋以下欄位
+       customer_info.value
+      
+      
+      <b>social_user_name</b>
+       Support query order fields
+      支援搜尋以下欄位
+       social_user_name"""
+    shipped_before: Optional[str] = None
+    """Filter orders by those shipped before specific time.
+       取得 shipped_at 小於指定時間的訂單(包含指定時間)
+      -
+       *should use UTC time"""
+    shipped_after: Optional[str] = None
+    """Filter orders by those shipped after specific time.
+       取得 shipped_at 大於指定時間的訂單(包含指定時間)
+      -
+       *should use UTC time"""
+    arrived_before: Optional[str] = None
+    """Filter orders by those arrived before specific time.
+       取得 arrived_at 小於指定時間的訂單(包含指定時間)
+      -
+       *should use UTC time"""
+    arrived_after: Optional[str] = None
+    """Filter orders by those arrived after specific time.
+       取得 arrived_at 大於指定時間的訂單(包含指定時間)
+      -
+       *should use UTC time"""
+    collected_before: Optional[str] = None
+    """Filter orders by those collected before specific time.
+       取得 collected_at 小於指定時間的訂單(包含指定時間)
+      -
+       *should use UTC time"""
+    collected_after: Optional[str] = None
+    """Filter orders by those collected after specific time.
+       取得 collected_at 大於指定時間的訂單(包含指定時間)
+      -
+       *should use UTC time"""
+    returned_before: Optional[str] = None
+    """Filter orders by those returned before specific time.
+       取得 returned_at 小於指定時間的訂單(包含指定時間)
+      -
+      should use UTC time
+      
+       Note: Will only show returned status updated after 2019-06-01
+       在2019/06/01之後產生的退貨狀態才能被搜尋出來"""
+    returned_after: Optional[str] = None
+    """Filter orders by those returned after specific time.
+       取得 returned_at 大於指定時間的訂單(包含指定時間)
+      -
+      should use UTC time
+      
+       Note: Will only show returned status updated after 2019-06-01
+      在2019/06/01之後產生的退貨狀態才能被搜尋出來"""
+    cancelled_before: Optional[str] = None
+    """Filter orders by those cancelled before specific time.
+       取得 cancelled_at 小於指定時間的訂單(包含指定時間)
+      -
+       *should use UTC time"""
+    cancelled_after: Optional[str] = None
+    """Filter orders by those cancelled after specific time.
+       取得 cancelled_at 大於指定時間的訂單(包含指定時間)
+      -
+       *should use UTC time"""
+    paid_before: Optional[str] = None
+    """Filter orders by those paid before specific time.
+       取得 paid_at 小於指定時間的訂單(包含指定時間)
+      -
+       *should use UTC time"""
+    paid_after: Optional[str] = None
+    """Filter orders by those paid after specific time.
+       取得 paid_at 大於指定時間的訂單(包含指定時間)
+      -
+       *should use UTC time"""
+    updated_before: Optional[str] = None
+    """Filter orders by those updated before specific time.
+       取得 updated_at 小於指定時間的訂單(包含指定時間)
+      -
+       *should use UTC time"""
+    updated_after: Optional[str] = None
+    """Filter orders by those updated after specific time.
+       取得 updated_at 大於指定時間的訂單(包含指定時間)
+      -
+       *should use UTC time"""
+    status: Optional[Literal['pending', 'removed', 'confirmed', 'completed', 'cancelled']] = None
+    """Status
+      訂單狀態
+      -
+      Status allow
+       pending 處理中
+      removed 已刪除
+       confirmed 已確認
+      completed 已完成
+       cancelled 已取消"""
+    statuses: Optional[List[Literal['pending', 'removed', 'confirmed', 'completed', 'cancelled']]] = None
+    """Statuses
+      多個訂單狀態
+      -
+      Status allow
+       pending 處理中
+      removed 已刪除
+       confirmed 已確認
+      completed 已完成
+       cancelled 已取消"""
+    payment_id: Optional[str] = None
+    """Payment Method ID
+      付款方式ID"""
+    payment_status: Optional[Literal['pending', 'failed', 'expired', 'completed', 'refunding', 'refunded', 'partially_refunded']] = None
+    """Payment Status
+      付款狀態
+      -
+      Payment status allows
+      pending 未付款(包含 temp 暫存狀態)
+       failed 付款失敗
+      expired 超過付款時間
+       completed 已付款
+      refunding 退款中
+       refunded 已退款
+      partially refunded 已部分退款"""
+    delivery_option_id: Optional[str] = None
+    """Delivery Option ID
+      物流方式ID"""
+    delivery_status: Optional[Literal['pending', 'shipping', 'shipped', 'arrived', 'collected', 'returned', 'returning']] = None
+    """Delivery Status
+      物流狀態 
+      -
+       Delivery status allows
+       pending 備貨中
+       shipping 發貨中
+       shipped 已發貨
+       arrived 已到達
+       collected 已取貨
+       returned 已退貨
+       * returning 退貨中"""
+    delivery_statuses: Optional[List[Literal['pending', 'shipping', 'shipped', 'arrived', 'collected', 'returned', 'returning']]] = None
+    """Delivery Statuses
+      多個物流狀態 
+      -
+       Delivery status allows
+       pending 備貨中
+       shipping 發貨中
+       shipped 已發貨
+       arrived 已到達
+       collected 已取貨
+       returned 已退貨
+       returning 退貨中"""
+    affiliate_data_affiliate_source: Optional[str] = None
+    """Keys allow to search:
+      * affiliate_source(String)訂單來源
+      (第三方夥伴適用)"""
+    created_before: Optional[str] = None
+    """Filter orders by those updated before specific time.
+       取得 created_at 小於指定時間的訂單(包含指定時間)
+      -
+       *should use UTC time"""
+    created_after: Optional[str] = None
+    """Filter orders by those created after specific time.
+       取得 created_at 大於指定時間的訂單(包含指定時間)
+      -
+      *should use UTC time"""
+    created_by: Optional[str] = None
+    """Filter orders by those created by specific channel.
+       取得特定由渠道建立的訂單"""
+    order_by: Optional[Literal['asc', 'desc']] = None
+    """Order responses items by created time in ascending/descending order.
+       訂單按訂單創造日期順序或倒序排序。
+       If sort_by is passed, Order the record by the sort_by value in asc/desc order.
+       如果傳入sort_by，則按照sort_by的參數順序或倒序排序。"""
+    sort_by: Optional[Literal['created_at', 'total']] = None
+    """Sort responses items by created_at or total.
+       訂單按訂單創造日期或商品總價排序。 If order_by is not passed, by default showing records in descending order.
+       如果沒有傳入order_by, 則按倒序排序。"""
+    include_fields: Optional[List[Literal['affiliate_campaign']]] = None
+    """Provide additional attributes in the response
+      結果添加哪些參數"""
+
+class Response(BaseModel):
+    """响应体模型"""
+    items: Optional[List[Order]] = None
+    pagination: Optional[Paginatable] = None
+
+async def call(
+    session: aiohttp.ClientSession, request: Optional[Request] = None
+) -> Response:
+    """
+    Search Orders
+    
+    To search orders with specific conditions.
+    利用特殊條件搜尋訂單列表。
+    
+    Path: GET /orders/search
+    """
+    # 构建请求 URL
+    url = "orders/search"
+
+    # 构建查询参数
+    params = {}
+    if request:
+        request_dict = request.model_dump(exclude_none=True)
+        for key, value in request_dict.items():
+            if value is not None:
+                params[key] = value
+
+    # 构建请求头
+    headers = {"Content-Type": "application/json"}
+
+    # 发起 HTTP 请求
+    async with session.get(
+        url, params=params, headers=headers
+    ) as response:
+        if response.status >= 400:
+            error_data = await response.json()
+            if response.status == 422:
+                error_model = UnprocessableEntityError(**error_data)
+                raise ShoplineAPIError(
+                    status_code=422,
+                    error=error_model,
+                    **error_data
+                )
+            if response.status == 500:
+                error_model = ServerError(**error_data)
+                raise ShoplineAPIError(
+                    status_code=500,
+                    error=error_model,
+                    **error_data
+                )
+            # 默认错误处理
+            raise ShoplineAPIError(
+                status_code=response.status,
+                **error_data
+            )
+        response_data = await response.json()
+
+        # 验证并返回响应数据
+        return Response(**response_data)

shopline_sdk/apis/orders/split_order.py

@@ -0,0 +1,84 @@
+from typing import Any, Dict, List, Optional, Union
+import aiohttp
+from pydantic import BaseModel, ValidationError, Field
+from typing_extensions import Literal
+
+# 导入异常类
+from ...exceptions import ShoplineAPIError
+
+# 导入需要的模型
+from ...models.order import Order
+from ...models.server_error import ServerError
+from ...models.unprocessable_entity_error import UnprocessableEntityError
+
+
+class OrderItemsItem(BaseModel):
+    """Item model for order_items"""
+    id: str
+    quantity: float
+
+class Request(BaseModel):
+    """请求体模型"""
+    order_items: List[OrderItemsItem]
+    """The order_items of the order would like to be split to a new order.
+       想要拆單的訂單項目"""
+    updated_at: str
+    """The updated_at of the order would like to be split.
+       欲被拆單的訂單更新時間
+       * Should use UTC time"""
+    send_child_email: Optional[bool] = None
+    """Do you want to notify the customer that the child order already created by email?
+       是否發送拆單成立通知（新訂單）給顧客"""
+    send_parent_email: Optional[bool] = None
+    """Do you want to notify the customer that the parent order already split by email?
+       是否發送拆單成立通知（原訂單）給顧客"""
+
+async def call(
+    session: aiohttp.ClientSession, id: str, request: Optional[Request] = None
+) -> Order:
+    """
+    Split Order
+    
+    To split an order with open API
+    透過 open API 進行拆單
+    
+    Path: POST /orders/{id}/split
+    """
+    # 构建请求 URL
+    url = f"orders/{id}/split"
+
+    # 构建请求头
+    headers = {"Content-Type": "application/json"}
+
+    # 构建请求体
+    json_data = request.model_dump(exclude_none=True) if request else None
+
+    # 发起 HTTP 请求
+    async with session.post(
+        url, json=json_data, headers=headers
+    ) as response:
+        if response.status >= 400:
+            error_data = await response.json()
+            if response.status == 422:
+                error_model = UnprocessableEntityError(**error_data)
+                raise ShoplineAPIError(
+                    status_code=422,
+                    error=error_model,
+                    **error_data
+                )
+            if response.status == 500:
+                error_model = ServerError(**error_data)
+                raise ShoplineAPIError(
+                    status_code=500,
+                    error=error_model,
+                    **error_data
+                )
+            # 默认错误处理
+            raise ShoplineAPIError(
+                status_code=response.status,
+                **error_data
+            )
+        response_data = await response.json()
+
+        # 验证并返回响应数据
+        return Order(**response_data)

shopline_sdk/apis/orders/update_order.py

@@ -0,0 +1,123 @@
+from typing import Any, Dict, List, Optional, Union
+import aiohttp
+from pydantic import BaseModel, ValidationError, Field
+from typing_extensions import Literal
+
+# 导入异常类
+from ...exceptions import ShoplineAPIError
+
+# 导入需要的模型
+from ...models.not_found_error import NotFoundError
+from ...models.order import Order
+from ...models.server_error import ServerError
+from ...models.translatable import Translatable
+
+
+class CustomDataItem(BaseModel):
+    """Item model for custom_data"""
+    value: Optional[str] = None
+    field_id: Optional[str] = None
+
+class Request(BaseModel):
+    """请求体模型"""
+    tracking_number: Optional[str] = None
+    """Delivery Tracking Number
+      物流追蹤號碼"""
+    tracking_url: Optional[str] = None
+    """Delivery Tracking url
+      物流追蹤url"""
+    delivery_provider_name: Optional[Translatable] = None
+    ref_order_id: Optional[str] = None
+    """For third party custom order id
+      可供儲存第三方訂單ID"""
+    custom_data: Optional[List[CustomDataItem]] = None
+    """Custom data
+      自定義資料"""
+    delivery_data: Optional[Dict[str, Any]] = None
+    """Delivery Data
+      運送資訊
+      
+      Able to update the fields below
+      可修改以下欄位
+      - location_code
+      - location_name
+      - store_address
+      - recipient_name
+      - recipient_phone"""
+    delivery_address: Optional[Dict[str, Any]] = None
+    """Delivery Address Information
+      運送地址資訊
+      
+      Able to update the fields below
+      可修改以下欄位
+      - country
+      - country_code
+      - address_1
+      - address_2
+      - city
+      - state
+      - postcode"""
+    force_update: Optional[Literal['delivery_data']] = None
+    """To skip filtering delivery_data fields if force_update = ['delivery_data'] is passed
+       略過delivery_data的篩選。"""
+    has_notes: Optional[bool] = None
+    """Order has notes or not
+       訂單是否有備註"""
+
+async def call(
+    session: aiohttp.ClientSession, id: str, request: Optional[Request] = None
+) -> Order:
+    """
+    Update Order
+    
+    To update an order with open API
+    透過open API更新一筆訂單
+    
+    Path: PATCH /orders/{id}
+    """
+    # 构建请求 URL
+    url = f"orders/{id}"
+
+    # 构建查询参数
+    params = {}
+    if request:
+        request_dict = request.model_dump(exclude_none=True)
+        for key, value in request_dict.items():
+            if value is not None:
+                params[key] = value
+
+    # 构建请求头
+    headers = {"Content-Type": "application/json"}
+
+    # 构建请求体
+    json_data = request.model_dump(exclude_none=True) if request else None
+
+    # 发起 HTTP 请求
+    async with session.patch(
+        url, params=params, json=json_data, headers=headers
+    ) as response:
+        if response.status >= 400:
+            error_data = await response.json()
+            if response.status == 404:
+                error_model = NotFoundError(**error_data)
+                raise ShoplineAPIError(
+                    status_code=404,
+                    error=error_model,
+                    **error_data
+                )
+            if response.status == 500:
+                error_model = ServerError(**error_data)
+                raise ShoplineAPIError(
+                    status_code=500,
+                    error=error_model,
+                    **error_data
+                )
+            # 默认错误处理
+            raise ShoplineAPIError(
+                status_code=response.status,
+                **error_data
+            )
+        response_data = await response.json()
+
+        # 验证并返回响应数据
+        return Order(**response_data)

shopline_sdk/apis/orders/update_order_delivery_status.py

@@ -0,0 +1,88 @@
+from typing import Any, Dict, List, Optional, Union
+import aiohttp
+from pydantic import BaseModel, ValidationError, Field
+from typing_extensions import Literal
+
+# 导入异常类
+from ...exceptions import ShoplineAPIError
+
+# 导入需要的模型
+from ...models.not_found_error import NotFoundError
+from ...models.order_delivery import OrderDelivery
+from ...models.server_error import ServerError
+from ...models.unprocessable_entity_error import UnprocessableEntityError
+
+class Request(BaseModel):
+    """请求体模型"""
+    status: Optional[Literal['pending', 'shipping', 'shipped', 'arrived', 'collected', 'returned', 'returning']] = None
+    mail_notify: Optional[bool] = None
+    """Do you want to notify the customer via email with the change?
+      此更新是否要以email通知顧客？
+      (Default: false)"""
+    force_update: Optional[Literal['status']] = None
+    """To force update delivery status for third party delivery providers
+       強制更新第三方物流服務供應商訂單運送狀態"""
+
+class Response(BaseModel):
+    """响应体模型"""
+    order_id: Optional[str] = None
+    status: Optional[Literal['pending', 'shipping', 'shipped', 'arrived', 'collected', 'returned', 'returning']] = None
+    updated_at: Optional[str] = None
+
+async def call(
+    session: aiohttp.ClientSession, id: str, request: Optional[Request] = None
+) -> Response:
+    """
+    Update Order Delivery Status
+    
+    To update order's delivery status
+    更新訂單運送狀態
+    
+    Path: PATCH /orders/{id}/order_delivery_status
+    """
+    # 构建请求 URL
+    url = f"orders/{id}/order_delivery_status"
+
+    # 构建查询参数
+    params = {}
+    if request:
+        request_dict = request.model_dump(exclude_none=True)
+        for key, value in request_dict.items():
+            if value is not None:
+                params[key] = value
+
+    # 构建请求头
+    headers = {"Content-Type": "application/json"}
+
+    # 构建请求体
+    json_data = request.model_dump(exclude_none=True) if request else None
+
+    # 发起 HTTP 请求
+    async with session.patch(
+        url, params=params, json=json_data, headers=headers
+    ) as response:
+        if response.status >= 400:
+            error_data = await response.json()
+            if response.status == 404:
+                error_model = NotFoundError(**error_data)
+                raise ShoplineAPIError(
+                    status_code=404,
+                    error=error_model,
+                    **error_data
+                )
+            if response.status == 500:
+                error_model = ServerError(**error_data)
+                raise ShoplineAPIError(
+                    status_code=500,
+                    error=error_model,
+                    **error_data
+                )
+            # 默认错误处理
+            raise ShoplineAPIError(
+                status_code=response.status,
+                **error_data
+            )
+        response_data = await response.json()
+
+        # 验证并返回响应数据
+        return Response(**response_data)