lingxingapi 1.0.0__py3-none-any.whl

lingxingapi/tools/api.py

@@ -0,0 +1,291 @@
+# -*- coding: utf-8 -*-c
+import datetime
+from typing import Literal
+from lingxingapi import errors
+from lingxingapi.base.api import BaseAPI
+from lingxingapi.tools import param, route, schema
+
+# Type Aliases ---------------------------------------------------------------------------------------------------------
+ALERT_SEARCH_FIELD = Literal["rule_name", "asin", "msku"]
+
+
+# API ------------------------------------------------------------------------------------------------------------------
+class ToolsAPI(BaseAPI):
+    """领星API `工具数据` 接口
+
+    ## Notice
+    请勿直接实例化此类
+    """
+
+    # 公共 API --------------------------------------------------------------------------------------
+    async def MonitorKeywords(
+        self,
+        *,
+        mid: int | None = None,
+        start_date: str | datetime.date | datetime.datetime | None = None,
+        end_date: str | datetime.date | datetime.datetime | None = None,
+        offset: int | None = None,
+        length: int | None = None,
+    ) -> schema.MoniterKeywords:
+        """查询关键词监控
+
+        ## Docs
+        - 工具: [关键词列表](https://apidoc.lingxing.com/#/docs/Tools/GetKeywordList)
+
+        :param mid `<'str/None'>`: 领星站点ID列表 (Seller.mid), 默认 `None` (不筛选)
+        :param start_date `<'str/date/datetime/None'>`: 关键词监控创建开始日期,
+            参数来源 `MonitorKeyword.monitor_keyword_create_time`, 默认 `None` (不筛选)
+        :param end_date `<'str/date/datetime/None'>`: 关键词监控创建结束日期,
+            参数来源 `MonitorKeyword.monitor_keyword_create_time`
+        :param offset `<'int/None'>`: 分页偏移量, 默认 `None` (使用: 0)
+        :param length `<'int/None'>`: 分页长度, 最大值 2000, 默认 `None` (使用: 20)
+        :return `<'MoniterKeywords'>`: 查询到的关键词监控结果
+        ```python
+        {
+            # 状态码
+            "code": 0,
+            # 提示信息
+            "message": "success",
+            # 错误信息
+            "errors": [],
+            # 请求ID
+            "request_id": "",
+            # 响应时间
+            "response_time": "2025-08-13 19:23:04",
+            # 响应数据量
+            "response_count": 2,
+            # 总数据量
+            "total_count": 2,
+            # 响应数据
+            "data": [
+                {
+                    # 关键词监控ID [原字段 'id']
+                    "moniter_id": 44118,
+                    # 关键词 [原字段 'key_word']
+                    "keyword": "65 ink cartridge for hp printers",
+                    # 关键词数量 [原字段 'keyword_num']
+                    "keyword_count": 70,
+                    # 关键词备注 [原字段 'keyword_remark']
+                    "keyword_note": "",
+                    # 监控终端 (1: PC端, 2: 移动端) [原字段 'type']
+                    "moniter_type": 1,
+                    # 监控国家 [原字段 'country']
+                    "monitor_country": "美国",
+                    # 监控邮编城市 [原字段 'postcode_name']
+                    "monitor_city": "New york",
+                    # 监控邮编 [原字段 'postcode']
+                    "monitor_postcode": "10008",
+                    # 监控排名类型 (0: 自然排名, 1: 广告排名) [原字段 'is_sponsored']
+                    "rank_type": 0,
+                    # 关键词排名
+                    "rank": 75,
+                    # 关键词排名页面 [原字段 'page']
+                    "page": 5,
+                    # 关键词页面排名 [原字段 'current_page_rank']
+                    "page_rank": 11,
+                    # 关键词排名描述 [原字段 'rank_text']
+                    "rank_desc": "75(第5页第11名)",
+                    # SBV广告排名页面 [原字段 'sbv_page']
+                    "sbv_page": -1,
+                    # SBV广告排名描述 [原字段 'sbv_text']
+                    "sbv_desc": "",
+                    # 关键词ASIN
+                    "asin": "B0DP8QGQN7",
+                    # 关键词父ASIN
+                    "parent_asin": "",
+                    # ASIN标题
+                    "title": "",
+                    # ASIN备注 [原字段 'asin_remark']
+                    "asin_note": "",
+                    # 监控创建人
+                    "monitor_creator_name": "周思琪",
+                    # 监控人列表
+                    "monitor_user_names": ["周思琪"],
+                    # ASIN监控创建时间 [原字段 'asin_create_time']
+                    "monitor_asin_create_time": "2025-09-10 15:22",
+                    # 关键词监控创建时间 [原字段 'create_time']
+                    "monitor_keyword_create_time": "2025-09-10 15:23",
+                    # 监控更新时间 [原字段 'monitor_time']
+                    "update_time": "2025-09-17 02:00",
+                },
+                ...
+            ]
+        }
+        ```
+        """
+        url = route.MONITOR_KEYWORDS
+        # 构建参数
+        args = {
+            "mid": mid,
+            "start_date": start_date,
+            "end_date": end_date,
+            "offset": offset,
+            "length": length,
+        }
+        try:
+            p = param.MonitorKeywords.model_validate(args)
+        except Exception as err:
+            raise errors.InvalidParametersError(err, url, args) from err
+
+        # 发送请求
+        data = await self._request_with_sign("POST", url, body=p.model_dump_params())
+        return schema.MoniterKeywords.model_validate(data)
+
+    async def MonitorAsins(
+        self,
+        *,
+        start_time: str | datetime.date | datetime.datetime | None = None,
+        end_time: str | datetime.date | datetime.datetime | None = None,
+        monitor_levels: int | list[int] | None = None,
+        search_value: str | list[str] | None = None,
+        offset: int | None = None,
+        length: int | None = None,
+    ) -> schema.MoniterAsins:
+        """查询ASIN监控
+
+        ## Docs
+        - 工具: [查询竞品监控列表](https://apidoc.lingxing.com/#/docs/Tools/CompetitiveMonitorList)
+
+        :param start_time `<'str/date/datetime/None'>`: 更新开始时间, 默认 `None` (不筛选)
+        :param end_time `<'str/date/datetime/None'>`: 更新结束时间, 默认 `None` (不筛选)
+        :param monitor_levels `<'int/list[int]/None'>`: 监控等级编码或编码列表 (1: A, 2: B, 3: C, 4: D), 默认 `None` (不筛选)
+        :param search_value `<'str/list[str]/None'>`: 搜索值, ASIN或ASIN列表, 默认 `None` (不筛选)
+        :param offset `<'int/None'>`: 分页偏移量, 默认 `None` (使用: 0)
+        :param length `<'int/None'>`: 分页长度, 最大值 200, 默认 `None` (使用: 20)
+        :return `<'MoniterAsins'>`: 查询到的ASIN监控结果
+        ```python
+        {
+            # 状态码
+            "code": 0,
+            # 提示信息
+            "message": "success",
+            # 错误信息
+            "errors": [],
+            # 请求ID
+            "request_id": "",
+            # 响应时间
+            "response_time": "2025-08-13 19:23:04",
+            # 响应数据量
+            "response_count": 2,
+            # 总数据量
+            "total_count": 2,
+            # 响应数据
+            "data": [
+                {
+                    # 监控状态 (0: 关闭, 1: 开启)
+                    "monitor_status": 1,
+                    # 监控等级 (1: A, 2: B, 3: C, 4: D) [原字段 'level_name']
+                    "monitor_level": "A",
+                    # 领星站点ID
+                    "mid": 5,
+                    # 监控ASIN
+                    "asin": "B0B*******",
+                    # 父ASIN [原字段 'parent']
+                    "parent_asin": "",
+                    # 关联的子ASIN列表 [原字段 'children']
+                    "child_asins": [],
+                    # ASIN链接
+                    "asin_url": "https://www.amazon.de/dp/B0B*******",
+                    # 商品主图 [原字段 'main_image']
+                    "image_url": "https://m.media-amazon.com/images/I/****.jpg",
+                    # ASIN所属类目列表 [原字段 'category_list']
+                    "asin_categories": [],
+                    # 商品价格
+                    "price": 32.98,
+                    # 商品价格货币符号 [原字段 'currency']
+                    "price_currency_icon": "€",
+                    # BuyBox当前价格
+                    "buybox_price": 32.98,
+                    # BuyBox初始价格 [原字段 'init_buybox_price']
+                    "buybox_init_price": 32.99,
+                    # BuyBox价格货币符号 [原字段 'buybox_currency']
+                    "buybox_currency_icon": "€",
+                    # BuyBox美元价格
+                    "buybox_usd_price": 35.6,
+                    # 30天平均价格 [原字段 'avg_price']
+                    "price_avg_30d": 0.0,
+                    # 30天平均价格货币符号 [原字段 'avg_currency']
+                    "price_avg_currency_icon": "$",
+                    # 30天预估销量 [原字段 'bought_num']
+                    "sales_qty_30d": 2000,
+                    # 评论分 [原字段 'star']
+                    "review_score": "4.2",
+                    # 评论数 [原字段 'review_num']
+                    "review_count": "16",
+                    # 大类目名称 [原字段 'big_category']
+                    "category": "Computer & Zubehör",
+                    # 大类目排名 [原字段 'big_category_rank']
+                    "category_rank": "670",
+                    # 大类目初始排名 [原字段 'init_big_category_rank']
+                    "category_init_rank": 355,
+                    # 小类目排名 [原字段 'small_ranks']
+                    "subcategories": [
+                        {
+                            # 小类目名称 [原字段 'small_category_text']
+                            "subcategory": "Tintenpatronen für Tintenstrahldrucker",
+                            # 小类目排名 [原字段 'small_rank']
+                            "subcategory_rank": 73,
+                            # 小类目初始排名 [原字段 'init_small_rank']
+                            "subcategory_init_rank": 44,
+                        },
+                        ...
+                    ],
+                    # FBA卖家数量 [原字段 'fba_seller_num']
+                    "fba_seller_count": 1,
+                    # 初始FBA卖家数量 [原字段 'init_fba_seller_num']
+                    "fba_seller_init_count": 0,
+                    # FBM卖家数量 [原字段 'fbm_seller_num']
+                    "fbm_seller_count": 0,
+                    # 初始FBM卖家数量 [原字段 'init_fbm_seller_num']
+                    "fbm_seller_init_count": 0,
+                    # 商品重量
+                    "item_weight": " 130 Gramm",
+                    # 商品尺寸
+                    "product_dimensions": "4,2 x 14,7 x 7,4 cm",
+                    # 搜索词
+                    "search_term": "",
+                    # 最新更新事件列表 [原字段 'last_update_event']
+                    "latest_update_events": ["优惠券价格"],
+                    # 商品图片列表 [原字段 'thumbnail']
+                    "images": [
+                        "https://m.media-amazon.com/images/I/****.jpg",
+                        ...
+                    ],
+                    # 商品标题
+                    "title": "Product Title",
+                    # 商品卖点 [原字段 'featurebullets']
+                    "bullet_points": [
+                        "bullet point 1",
+                        ...
+                    ],
+                    # 监控创建人ID [原字段 'creator_uid']
+                    "creator_id": "106*****",
+                    # 监控创建人名称 [原字段 'creator']
+                    "creator_name": "白小白",
+                    # 监控人ID列表 [原字段 'monitor_uids']
+                    "monitor_user_ids": ["106*****"],
+                }
+                ...
+            ]
+        }
+        ```
+        """
+        url = route.MONITOR_ASINS
+        # 构建参数
+        args = {
+            "start_time": start_time,
+            "end_time": end_time,
+            "monitor_levels": monitor_levels,
+            "search_field": "asin",
+            "search_value": search_value,
+            "offset": offset,
+            "length": length,
+        }
+        try:
+            p = param.MonitorAsins.model_validate(args)
+        except Exception as err:
+            raise errors.InvalidParametersError(err, url, args) from err
+
+        # 发送请求
+        data = await self._request_with_sign("POST", url, body=p.model_dump_params())
+        return schema.MoniterAsins.model_validate(data)

lingxingapi/tools/param.py

@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+from typing import Any, Optional
+from typing_extensions import Self
+from pydantic import ValidationInfo, Field, field_validator, model_validator
+from lingxingapi import utils
+from lingxingapi.base.param import Parameter, PageOffestAndLength
+from lingxingapi.fields import NonEmptyStr, NonNegativeInt, CurrencyCode
+
+
+# 工具数据 ----------------------------------------------------------------------------------------------------------------------
+# . Monitor Keywords
+class MonitorKeywords(PageOffestAndLength):
+    """查询关键词参数"""
+
+    # 领星站点ID列表 (Seller.mid)
+    mid: Optional[NonNegativeInt] = None
+    # 关键词监控创建开始日期
+    start_date: Optional[str] = None
+    # 关键词监控创建结束日期
+    end_date: Optional[str] = None
+
+    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+    @field_validator("start_date", "end_date", mode="before")
+    @classmethod
+    def _validate_date(cls, v: Any, info: ValidationInfo) -> Optional[str]:
+        if v is None:
+            return v
+        dt = utils.validate_datetime(v, False, "关键词创建日期 %s" % info.field_name)
+        return "%4d-%02d-%02d" % (dt.year, dt.month, dt.day)
+
+
+# . Monitor Asins
+class MonitorAsins(PageOffestAndLength):
+    """查询ASIN监控参数"""
+
+    # 更新开始时间
+    start_time: Optional[str] = None
+    # 更新结束时间
+    end_time: Optional[str] = None
+    # 监控等级 (1: A, 2: B, 3: C, 4: D)
+    monitor_levels: Optional[list] = Field(None, alias="levels")
+    # 搜索字段
+    search_field: Optional[NonEmptyStr] = None
+    # 搜索值
+    search_value: Optional[NonEmptyStr] = None
+
+    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+    @field_validator("start_time", "end_time", mode="before")
+    @classmethod
+    def _validate_datetime(cls, v: Any, info: ValidationInfo) -> Optional[str]:
+        if v is None:
+            return v
+        dt = utils.validate_datetime(v, True, "更新时间 %s" % info.field_name)
+        # fmt: off
+        return "%4d-%02d-%02d %02d:%02d:%02d" % (
+            dt.year, dt.month, dt.day, 
+            dt.hour, dt.minute, dt.second
+        )
+        # fmt: on
+
+    @field_validator("monitor_levels", mode="before")
+    @classmethod
+    def _validate_levels(cls, v) -> list[int] | None:
+        if v is None:
+            return None
+        return utils.validate_array_of_unsigned_int(v, "监控等级 monitor_levels")
+
+    @field_validator("search_value", mode="before")
+    @classmethod
+    def _validate_search_value(cls, v) -> str | None:
+        if v is None:
+            return None
+        return ",".join(utils.validate_array_of_non_empty_str(v, "搜索值 search_value"))

lingxingapi/tools/route.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+
+# fmt: off
+# 工具数据 ----------------------------------------------------------------------------------------------------------------------
+# https://apidoc.lingxing.com/#/docs/Tools/GetKeywordList
+MONITOR_KEYWORDS: str = "/erp/sc/routing/tool/toolKeywordRank/getKeywordList"
+# https://apidoc.lingxing.com/#/docs/Tools/CompetitiveMonitorList
+MONITOR_ASINS: str = "/basicOpen/tool/competitiveMonitor/list"

lingxingapi/tools/schema.py

@@ -0,0 +1,169 @@
+# -*- coding: utf-8 -*-
+from typing import Any
+from pydantic import BaseModel, Field, field_validator
+from lingxingapi.base.schema import ResponseV1, ResponseV1TraceId, FlattenDataRecords
+from lingxingapi.fields import IntOrNone2Zero, FloatOrNone2Zero, StrOrNone2Blank
+
+
+# 工具数据 ----------------------------------------------------------------------------------------------------------------------
+# . Minitor Keywords
+class MoniterKeyword(BaseModel):
+    """关键词监控"""
+
+    # 关键词监控ID [原字段 'id']
+    moniter_id: int = Field(validation_alias="id")
+    # 关键词 [原字段 'key_word']
+    keyword: str = Field(validation_alias="key_word")
+    # 关键词数量 [原字段 'keyword_num']
+    keyword_count: int = Field(validation_alias="keyword_num")
+    # 关键词备注 [原字段 'keyword_remark']
+    keyword_note: str = Field(validation_alias="keyword_remark")
+    # 监控终端 [原字段 'type']
+    # (1: PC端, 2: 移动端)
+    moniter_type: int = Field(validation_alias="type")
+    # 监控国家 [原字段 'country']
+    monitor_country: str = Field(validation_alias="country")
+    # 监控邮编城市 [原字段 'postcode_name']
+    monitor_city: str = Field(validation_alias="postcode_name")
+    # 监控邮编 [原字段 'postcode']
+    monitor_postcode: str = Field(validation_alias="postcode")
+    # 监控排名类型 [原字段 'is_sponsored']
+    # (0: 自然排名, 1: 广告排名)
+    rank_type: int = Field(validation_alias="is_sponsored")
+    # 关键词排名
+    rank: int
+    # 关键词排名页面 [原字段 'page']
+    page: int = Field(validation_alias="page")
+    # 关键词页面排名 [原字段 'current_page_rank']
+    page_rank: int = Field(validation_alias="current_page_rank")
+    # 关键词排名描述 [原字段 'rank_text']
+    rank_desc: str = Field(validation_alias="rank_text")
+    # SBV广告排名页面 [原字段 'sbv_page']
+    sbv_page: int = Field(validation_alias="sbv_page")
+    # SBV广告排名描述 [原字段 'sbv_text']
+    sbv_desc: str = Field(validation_alias="sbv_text")
+    # 关键词ASIN
+    asin: str
+    # 关键词父ASIN
+    parent_asin: str
+    # ASIN标题
+    title: str
+    # ASIN备注 [原字段 'asin_remark']
+    asin_note: str = Field(validation_alias="asin_remark")
+    # 监控创建人
+    monitor_creator_name: str = Field(validation_alias="creator")
+    # 监控人列表
+    monitor_user_names: list[str] = Field(validation_alias="monitors")
+    # ASIN监控创建时间 [原字段 'asin_create_time']
+    monitor_asin_create_time: str = Field(validation_alias="asin_create_time")
+    # 关键词监控创建时间 [原字段 'create_time']
+    monitor_keyword_create_time: str = Field(validation_alias="create_time")
+    # 监控更新时间 [原字段 'monitor_time']
+    update_time: str = Field(validation_alias="monitor_time")
+
+
+class MoniterKeywords(ResponseV1):
+    """关键词监控列表"""
+
+    data: list[MoniterKeyword]
+
+
+# . Product Asins
+class SubcategoryRank(BaseModel):
+    """小类目排名"""
+
+    # 小类目名称 [原字段 'small_category_text']
+    subcategory: str = Field(validation_alias="small_category_text")
+    # 小类目排名 [原字段 'small_rank']
+    subcategory_rank: int = Field(validation_alias="small_rank")
+    # 小类目初始排名 [原字段 'init_small_rank']
+    subcategory_init_rank: int = Field(validation_alias="init_small_rank")
+
+
+class MinitorAsin(BaseModel):
+    """ASIN监控"""
+
+    # fmt: off
+    # 监控状态 (0: 关闭, 1: 开启)
+    monitor_status: int
+    # 监控等级 (1: A, 2: B, 3: C, 4: D) [原字段 'level_name']
+    monitor_level: str = Field(validation_alias="level_name")
+    # 领星站点ID
+    mid: int
+    # 监控ASIN
+    asin: str
+    # 父ASIN [原字段 'parent']
+    parent_asin: StrOrNone2Blank = Field(validation_alias="parent")
+    # 关联的子ASIN列表 [原字段 'children']
+    child_asins: list[str] = Field(validation_alias="children")
+    # ASIN链接
+    asin_url: StrOrNone2Blank 
+    # 商品主图 [原字段 'main_image']
+    image_url: StrOrNone2Blank = Field(validation_alias="main_image")
+    # ASIN所属类目列表 [原字段 'category_list']
+    asin_categories: list[str] = Field(validation_alias="category_list")
+    # 商品价格
+    price: FloatOrNone2Zero
+    # 商品价格货币符号 [原字段 'currency']
+    price_currency_icon: StrOrNone2Blank = Field(validation_alias="currency")
+    # BuyBox当前价格
+    buybox_price: FloatOrNone2Zero
+    # BuyBox初始价格 [原字段 'init_buybox_price']
+    buybox_init_price: FloatOrNone2Zero = Field(validation_alias="init_buybox_price")
+    # BuyBox价格货币符号 [原字段 'buybox_currency']
+    buybox_currency_icon: StrOrNone2Blank = Field(validation_alias="buybox_currency")
+    # BuyBox美元价格
+    buybox_usd_price: FloatOrNone2Zero
+    # 30天平均价格 [原字段 'avg_price']
+    price_avg_30d: FloatOrNone2Zero = Field(validation_alias="avg_price")
+    # 30天平均价格货币符号 [原字段 'avg_currency']
+    price_avg_currency_icon: StrOrNone2Blank = Field(validation_alias="avg_currency")
+    # 30天预估销量 [原字段 'bought_num']
+    sales_qty_30d: IntOrNone2Zero = Field(validation_alias="bought_num")
+    # 评论分 [原字段 'star']
+    review_score: StrOrNone2Blank = Field(validation_alias="star")
+    # 评论数 [原字段 'review_num']
+    review_count: StrOrNone2Blank = Field(validation_alias="review_num")
+    # 大类目名称 [原字段 'big_category']
+    category: StrOrNone2Blank = Field(validation_alias="big_category")
+    # 大类目排名 [原字段 'big_category_rank']
+    category_rank: StrOrNone2Blank = Field(validation_alias="big_category_rank")
+    # 大类目初始排名 [原字段 'init_big_category_rank']
+    category_init_rank: IntOrNone2Zero = Field(validation_alias="init_big_category_rank")
+    # 小类目排名 [原字段 'small_ranks']
+    subcategories: list[SubcategoryRank] = Field(validation_alias="small_ranks")
+    # FBA卖家数量 [原字段 'fba_seller_num']
+    fba_seller_count: IntOrNone2Zero = Field(validation_alias="fba_seller_num")
+    # 初始FBA卖家数量 [原字段 'init_fba_seller_num']
+    fba_seller_init_count: IntOrNone2Zero = Field(validation_alias="init_fba_seller_num")
+    # FBM卖家数量 [原字段 'fbm_seller_num']
+    fbm_seller_count: IntOrNone2Zero = Field(validation_alias="fbm_seller_num")
+    # 初始FBM卖家数量 [原字段 'init_fbm_seller_num']
+    fbm_seller_init_count: IntOrNone2Zero = Field(validation_alias="init_fbm_seller_num")
+    # 商品重量
+    item_weight: StrOrNone2Blank
+    # 商品尺寸
+    product_dimensions: str
+    # 搜索词
+    search_term: str
+    # 最新更新事件列表 [原字段 'last_update_event']
+    latest_update_events: list[str] = Field(validation_alias="last_update_event")
+    # 商品图片列表 [原字段 'thumbnail']
+    images: list[str] = Field(validation_alias="thumbnail")
+    # 商品标题
+    title: str
+    # 商品卖点 [原字段 'featurebullets']
+    bullet_points: list[str] = Field(validation_alias="featurebullets")
+    # 监控创建人ID [原字段 'creator_uid']
+    creator_id: str = Field(validation_alias="creator_uid")
+    # 监控创建人名称 [原字段 'creator']
+    creator_name: str = Field(validation_alias="creator")
+    # 监控人ID列表 [原字段 'monitor_uids']
+    monitor_user_ids: list[str] = Field(validation_alias="monitor_uids")
+    # fmt: on
+
+
+class MoniterAsins(ResponseV1):
+    """ASIN监控列表"""
+
+    data: list[MinitorAsin]