lingxingapi 1.1.4__py3-none-any.whl

lingxingapi/base/schema.py

@@ -0,0 +1,198 @@
+# -*- coding: utf-8 -*-
+import datetime
+from typing import Any, Optional
+from typing_extensions import Self
+from pydantic import BaseModel, Field, model_validator
+from lingxingapi import errors
+from lingxingapi.fields import StrOrNone2Blank
+
+
+# Token 令牌 --------------------------------------------------------------------------------------------------------------------
+class Token(BaseModel):
+    # 接口的访问令牌
+    access_token: str
+    # 用于续约 access_token 的更新令牌
+    refresh_token: str
+    # 访问令牌的有效时间 (单位: 秒)
+    expires_in: int
+
+
+# 公用 Schema -------------------------------------------------------------------------------------------------------------------
+class TagInfo(BaseModel):
+    """商品的标签信息."""
+
+    # 领星标签ID (GlobalTag.tag_id) [原字段 'global_tag_id']
+    tag_id: str = Field(validation_alias="global_tag_id")
+    # 领星标签名称 (GlobalTag.tag_name) [原字段 'tag_name']
+    tag_name: str = Field(validation_alias="tag_name")
+    # 领星标签颜色 (如: "#FF0000") [原字段 'color']
+    tag_color: str = Field(validation_alias="color")
+
+
+class AttachmentFile(BaseModel):
+    """附件信息"""
+
+    # 文件ID
+    file_id: int
+    # 文件名称
+    file_name: str
+    # 文件类型 (0: 未知, 1: 图片, 2: 压缩包)
+    file_type: int = 0
+    # 文件链接
+    file_url: str = ""
+
+
+class SpuProductAttribute(BaseModel):
+    """SPU 商品属性"""
+
+    # 属性ID
+    attr_id: int
+    # 属性名称
+    attr_name: str
+    # 属性值
+    attr_value: str
+
+
+class CustomField(BaseModel):
+    """自定义字段"""
+
+    # 自定义字段ID
+    field_id: int = Field(validation_alias="id")
+    # 自定义字段名称
+    field_name: str = Field(validation_alias="name")
+    # 自定义字段值
+    field_value: str = Field(validation_alias="val_text")
+
+
+class BaseResponse(BaseModel):
+    """基础响应数据"""
+
+    # 状态码
+    code: int = 0
+    # 提示信息
+    message: Optional[StrOrNone2Blank] = None
+    # 错误信息
+    errors: Optional[list] = Field(None, validation_alias="error_details")
+    # 请求链路id
+    request_id: Optional[str] = None
+    # 响应时间
+    response_time: Optional[str] = None
+
+    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+    @model_validator(mode="after")
+    def _adjustments(self) -> Self:
+        # 设置默认数值
+        if self.message is None:
+            self.message = "success"
+        if self.errors is None:
+            self.errors = []
+        if self.request_id is None:
+            self.request_id = ""
+        if self.response_time is None:
+            # fmt: off
+            dt = datetime.datetime.now()
+            self.response_time = "%04d-%02d-%02d %02d:%02d:%02d" % (
+                dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second
+            )
+            # fmt: on
+
+        # 返回
+        return self
+
+
+class ResponseV1(BaseResponse):
+    """响应数据 - 下划线命名"""
+
+    # 响应数据量
+    response_count: int = 0
+    # 总数据量
+    total_count: int = Field(0, validation_alias="total")
+    # 响应数据
+    data: Any = None
+
+    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+    @model_validator(mode="after")
+    def _set_count(self) -> Self:
+        # 计算响应数据量
+        if isinstance(self.data, list):
+            self.response_count = len(self.data)
+        elif isinstance(self.data, (dict, BaseModel)):
+            self.response_count = 1
+        else:
+            return self
+
+        # 调整总数据量
+        if self.response_count > 0:
+            self.total_count = max(self.total_count, self.response_count)
+        return self
+
+
+class ResponseV1Token(ResponseV1):
+    """响应数据 - 下划线命名 + 分页游标 (next_token)"""
+
+    # 分页游标
+    next_token: StrOrNone2Blank
+
+
+class ResponseV1TraceId(ResponseV1):
+    """响应数据 - request_id 替换为 traceId"""
+
+    # 请求链路id
+    request_id: Optional[str] = Field(None, validation_alias="traceId")
+
+
+class ResponseV2(ResponseV1):
+    """响应数据 - 驼峰命名"""
+
+    # 错误信息
+    errors: Optional[list] = Field(None, validation_alias="errorDetails")
+    # 请求链路id
+    request_id: Optional[str] = Field(None, validation_alias="requestId")
+    # 响应时间
+    response_time: Optional[str] = Field(None, validation_alias="responseTime")
+
+
+class ResponseResult(BaseResponse):
+    """响应结果"""
+
+    # 响应结果
+    data: Any = None
+
+
+# 特殊 Schema -------------------------------------------------------------------------------------------------------------------
+class FlattenDataRecords(BaseModel):
+    """从嵌套数据中提取列表数据 (records)
+
+    - 1. 从 data 字段中, 提取 total 并赋值至基础层
+    - 2. 从 data 字段中, 提取 records 并覆盖 data 字段
+    """
+
+    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+    @model_validator(mode="before")
+    def _flatten_data(cls, data: dict) -> dict:
+        try:
+            inner: dict = data.pop("data", {})
+            data["total"] = max(inner.get("total", 0), data.get("total", 0))
+            data["data"] = inner.get("records", [])
+        except Exception:
+            raise errors.ResponseDataError(cls.__name__, data=data)
+        return data
+
+
+class FlattenDataList(BaseModel):
+    """从嵌套数据中提取列表数据 (list)
+
+    - 1. 从 data 字段中, 提取 total 并赋值至基础层
+    - 2. 从 data 字段中, 提取 list 并覆盖 data 字段
+    """
+
+    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+    @model_validator(mode="before")
+    def _flatten_data(cls, data: dict) -> dict:
+        try:
+            inner: dict = data.pop("data", {})
+            data["total"] = max(inner.get("total", 0), data.get("total", 0))
+            data["data"] = inner.get("list", [])
+        except Exception:
+            raise errors.ResponseDataError(cls.__name__, data=data)
+        return data

lingxingapi/basic/api.py

@@ -0,0 +1,466 @@
+# -*- coding: utf-8 -*-c
+import datetime
+from decimal import Decimal
+from lingxingapi import errors
+from lingxingapi.base.api import BaseAPI
+from lingxingapi.base import schema as base_schema
+from lingxingapi.basic import param, route, schema
+
+
+# API ------------------------------------------------------------------------------------------------------------------
+class BasicAPI(BaseAPI):
+    """领星API `基础数据` 接口
+
+    ## Notice
+    请勿直接实例化此类
+    """
+
+    # 公共 API --------------------------------------------------------------------------------------
+    # . 基础数据
+    async def Marketplaces(self) -> schema.Marketplaces:
+        """查询所有的亚马逊站点信息
+
+        ## Docs
+        - 基础数据: [查询亚马逊市场列表](https://apidoc.lingxing.com/#/docs/BasicData/AllMarketplace)
+
+        :returns `<'Marketplaces'>`: 返回所有的亚马逊站点信息
+        ```python
+        {
+            # 状态码
+            "code": 0,
+            # 提示信息
+            "message": "success",
+            # 错误信息
+            "errors": [],
+            # 请求ID
+            "request_id": "44DAC5AE-7D76-9054-2431-0EF7E357CFE5",
+            # 响应时间
+            "response_time": "2025-08-13 19:23:04",
+            # 响应数据量
+            "response_count": 2,
+            # 总数据量
+            "total_count": 2,
+            # 响应数据
+            "data": [
+                {
+                    # 领星站点ID [唯一标识]
+                    "mid": 1,
+                    # 站点区域
+                    "region": "NA",
+                    # 站点亚马逊仓库所属区域 [原字段 'aws_region']
+                    "region_aws": "NA",
+                    # 站点国家 (中文)
+                    "country": "美国",
+                    # 站点国家代码 [原字段 'code']
+                    "country_code": "US",
+                    # 亚马逊市场ID
+                    "marketplace_id": "ATVPDKIKX0DER"
+                },
+                ...
+            ],
+        }
+        """
+        data = await self._request_with_sign("GET", route.MARKETPLACES)
+        return schema.Marketplaces.model_validate(data)
+
+    async def States(self, country_code: str) -> schema.States:
+        """查询亚马逊指定国家的周/省信息
+
+        ## Docs
+        - 基础数据: [查询亚马逊国家下地区列表](https://apidoc.lingxing.com/#/docs/BasicData/WorldStateLists)
+
+        :param country_code `<'str'>`: 国家代码, 如: `"US"`
+        :returns `<'States'>`: 返回指定国家的省/州信息
+        ```python
+        {
+            # 状态码
+            "code": 0,
+            # 提示信息
+            "message": "success",
+            # 错误信息
+            "errors": [],
+            # 请求ID
+            "request_id": "44DAC5AE-7D76-9054-2431-0EF7E357CFE5",
+            # 响应时间
+            "response_time": "2025-08-13 19:23:04",
+            # 响应数据量
+            "response_count": 2,
+            # 总数据量
+            "total_count": 2,
+            # 响应数据
+            "data": [
+                {
+                    # 国家代码
+                    "country_code": "US",
+                    # 省/州名称 [原字段 'state_or_province_name']
+                    "state": "California",
+                    # 省/州代码 # [原字段 'code']
+                    "state_code": "CA"
+                },
+                ...
+            ],
+        }
+        ```
+        """
+        url = route.STATES
+        # 解析并验证参数
+        args = {"country_code": country_code}
+        try:
+            p = param.CountryCode.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.States.model_validate(data)
+
+    async def Sellers(self) -> schema.Sellers:
+        """查询已授权到领星 ERP 全部的亚马逊店铺信息
+
+        ## Docs
+        - 基础数据: [查询亚马逊店铺列表](https://apidoc.lingxing.com/#/docs/BasicData/SellerLists)
+
+        :returns `<'Sellers'>`: 返回已授权到领星 ERP 全部的亚马逊店铺信息
+        ```python
+        {
+            # 状态码
+            "code": 0,
+            # 提示信息
+            "message": "success",
+            # 错误信息
+            "errors": [],
+            # 请求ID
+            "request_id": "44DAC5AE-7D76-9054-2431-0EF7E357CFE5",
+            # 响应时间
+            "response_time": "2025-08-13 19:23:04",
+            # 响应数据量
+            "response_count": 2,
+            # 总数据量
+            "total_count": 2,
+            # 响应数据
+            "data": [
+                {
+                    # 领星站点ID (Marketplace.mid)
+                    "mid": 1,
+                    # 领星店铺ID [唯一标识]
+                    "sid": 1,
+                    # 亚马逊卖家ID
+                    "seller_id": "AZTOL********",
+                    # 领星店铺名称 (含国家信息) [原字段 'name']
+                    "seller_name": "account**-ES",
+                    # 领星店铺帐号ID [原字段 'seller_account_id']
+                    "account_id": 1,
+                    # 领星店铺帐号名称
+                    "account_name": "account**",
+                    # 亚马逊市场ID (Marketplace.marketplace_id)
+                    "marketplace_id": "ATVPDKIKX0DER",
+                    # 店铺区域
+                    "region": "EU",
+                    # 店铺国家 (中文)
+                    "country": "西班牙",
+                    # 店铺状态 (0: 停止同步, 1: 正常, 2: 授权异常, 3: 欠费停服)
+                    "status": 1
+                    # 店铺是否授权广告 (0: 否, 1: 是) [原字段 'has_ads_setting']
+                    "ads_authorized": 0,
+                },
+                ...
+            ],
+        }
+        ```
+        """
+        data = await self._request_with_sign("GET", route.SELLERS)
+        return schema.Sellers.model_validate(data)
+
+    async def ConceptSellers(self) -> schema.ConceptSellers:
+        """查询全部的亚马逊概念店铺信息
+
+        ## Docs
+        - 基础数据: [查询亚马逊概念店铺列表](https://apidoc.lingxing.com/#/docs/BasicData/ConceptSellerLists)
+
+        :returns `<'ConceptSellers'>`: 返回全部的亚马逊概念店铺信息
+        ```python
+        {
+            # 状态码
+            "code": 0,
+            # 提示信息
+            "message": "success",
+            # 错误信息
+            "errors": [],
+            # 请求ID
+            "request_id": "44DAC5AE-7D76-9054-2431-0EF7E357CFE5",
+            # 响应时间
+            "response_time": "2025-08-13 19:23:04",
+            # 响应数据量
+            "response_count": 2,
+            # 总数据量
+            "total_count": 2,
+            # 响应数据
+            "data": [
+                {
+                    # 领星概念站点ID [原字段 'mid']
+                    "cmid": 10*****,
+                    # 领星概念店铺ID [唯一标识, 原字段 'id']
+                    "csid": 1222**************,
+                    # 亚马逊卖家ID
+                    "seller_id": "AZTOL********",
+                    # 领星概念店铺名称 (含区域信息)
+                    "seller_name": "account**-EU",
+                    # 领星概念店铺账号ID [原字段 'seller_account_id']
+                    "account_id": 1,
+                    # 领星概念店铺帐号名称 [原字段 'seller_account_name']
+                    "account_name": "account**",
+                    # 概念店铺区域
+                    "region": "EU",
+                    # 概念店铺国家, 如: "北美共享", "欧洲共享"
+                    "country": "欧洲共享",
+                    # 概念店铺状态 (1: 启用, 2: 停用)
+                    "status": 1
+                },
+                ...
+            ],
+        }
+        """
+        data = await self._request_with_sign("GET", route.CONCEPT_SELLERS)
+        return schema.ConceptSellers.model_validate(data)
+
+    async def RenameSellers(self, *rename: dict) -> schema.RenameSellersResult:
+        """批量修改领星店铺名称
+
+        ## Docs
+        - 基础数据: [批量修改店铺名称](https://apidoc.lingxing.com/#/docs/BasicData/SellerBatchRename)
+
+        :param *rename `<'dict'>`: 支持最多10个店铺名称的批量修改
+
+            - 每个字典必须包含 `sid` 和 `name` 字段, 如:
+              `{"sid": 1, "name": "account-ES"}`
+            - 必填字段 `sid` 领星店铺ID, 必须是 int 类型, 参数来源: `Seller.sid`
+            - 必填字段 `name` 新的店铺名称, 必须是 str 类型
+
+        :returns `<'RenameSellerResult'>`: 返回批量修改的结果
+        ```python
+        {
+            # 状态码
+            "code": 0,
+            # 提示信息
+            "message": "success",
+            # 错误信息
+            "errors": [],
+            # 请求ID
+            "request_id": "44DAC5AE-7D76-9054-2431-0EF7E357CFE5",
+            # 响应时间
+            "response_time": "2025-08-13 19:23:04",
+            # 响应结果
+            "data": {
+                # 修改成功数量 [原字段 'success_num']
+                "success": 1,
+                # 修改失败数量 [原字段 'failure_num']
+                "failure": 1,
+                # 修改失败详情
+                "failure_detail": [
+                    {
+                        # 领星店铺ID (Seller.sid)
+                        "sid": 1,
+                        # 新店铺名称
+                        "name": "account-ES",
+                        # 失败信息 [原字段 'error']
+                        "message": "新旧店铺名相同",
+                    },
+                    ...
+                ],
+            },
+        }
+        ```
+        """
+        url = route.RENAME_SELLERS
+        # 解析并验证参数
+        args = {"renames": rename}
+        try:
+            p = param.RenameSellers.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.RenameSellersResult.model_validate(data)
+
+    async def Accounts(self) -> schema.Accounts:
+        """查询所有领星的ERP账号信息
+
+        ## Docs
+        - 基础数据: [查询ERP用户信息列表](https://apidoc.lingxing.com/#/docs/BasicData/AccoutLists)
+
+        :returns `<'Accounts'>`: 返回所有领星的ERP账号信息
+        ```python
+        {
+            # 状态码
+            "code": 0,
+            # 提示信息
+            "message": "success",
+            # 错误信息
+            "errors": [],
+            # 请求ID
+            "request_id": "44DAC5AE-7D76-9054-2431-0EF7E357CFE5",
+            # 响应时间
+            "response_time": "2025-08-13 19:23:04",
+            # 响应数据量
+            "response_count": 2,
+            # 总数据量
+            "total_count": 2,
+            # 响应数据
+            "data": [
+                {
+                    # 领星账号所从属的ID (如主帐号ID) [原字段 'zid']
+                    "parent_id": 1,
+                    # 领星帐号ID [唯一标识] [原字段 'uid']
+                    "user_id": 1,
+                    # 是否为主账号 (0: 否, 1: 是)
+                    "is_master": 1
+                    # 帐号角色
+                    "role": "",
+                    # 领星帐号显示的姓名 [原字段 'realname']
+                    "display_name": "超级管理员",
+                    # 领星帐号登陆用户名
+                    "username": "user****",
+                    # 领星帐号电子邮箱
+                    "email": "15*******@qq.com",
+                    # 领星帐号电话号码 [原字段 'mobile']
+                    "phone": "15********",
+                    # 领星帐号创建时间 (北京时间)
+                    "create_time": "2024-07-12 19:07",
+                    # 领星帐号最后登录时间 (北京时间)
+                    "last_login_time": "2024-07-12 19:07",
+                    # 领星帐号最后登录IP
+                    "last_login_ip": "",
+                    # 领星帐号登录次数 [原字段 'login_num']
+                    "login_count": 1
+                    # 领星帐号状态 (0: 禁用, 1: 正常)
+                    "status": 1,
+                    # 关联的领星店铺名称, 逗号分隔 [原字段 'seller']
+                    "sellers": "acc**1,acc**2",
+                },
+                ...
+            ],
+        }
+        ```
+        """
+        data = await self._request_with_sign("GET", route.ACCOUNTS)
+        return schema.Accounts.model_validate(data)
+
+    async def ExchangeRates(
+        self,
+        date: str | datetime.date | datetime.datetime | None = None,
+    ) -> schema.ExchangeRates:
+        """查询指定月份的汇率信息
+
+        ## Docs
+        - 基础数据: [查询汇率](https://apidoc.lingxing.com/#/docs/BasicData/Currency)
+
+        :param date `<'str/date/datetime'>`: 指定查询的月份, 默认 `None` (当前月份)
+
+            - 如果是字符串, 必须是有效的日期字符串, 如: `"2025-07"`, `"2025-07-01"`
+            - 如果是 `date` 或 `datetime` 对象, 将自动转换为 `YYYY-MM` 格式
+            - 如果为 `None`, 则使用当前月份作为参数
+
+        :returns `<'ExchangeRates'>`: 返回指定月份的汇率信息
+        ```python
+        {
+            # 状态码
+            "code": 0,
+            # 提示信息
+            "message": "success",
+            # 错误信息
+            "errors": [],
+            # 请求ID
+            "request_id": "44DAC5AE-7D76-9054-2431-0EF7E357CFE5",
+            # 响应时间
+            "response_time": "2025-08-13 19:23:04",
+            # 响应数据量
+            "response_count": 2,
+            # 总数据量
+            "total_count": 2,
+            # 响应数据
+            "data": [
+                {
+                    # 汇率日期 (格式: YYYY-MM-DD)
+                    "date": "2025-01-01",
+                    # 货币名称 (中文) [原字段 'name']
+                    "currency": "美元",
+                    # 货币代码 [原字段 'code']
+                    "currency_code": "USD",
+                    # 货币符号 [原字段 'icon']
+                    "currency_icon": "$",
+                    # 中国银行官方汇率 (对比人民币) [原字段 'rate_org']
+                    "boc_rate": "7.1698",
+                    # 用户汇率 (对比人民币) [原字段 'my_rate']
+                    "user_rate": "7.1315",
+                    # 用户汇率修改时间 (北京时间)
+                    "update_time": "2025-03-10 17:14:10",
+                },
+                ...
+            ],
+        }
+        ```
+        """
+        url = route.EXCHANGE_RATES
+        # 解析并验证参数
+        args = {"date": date}
+        try:
+            p = param.ExchangeRateDate.model_validate(args)
+        except Exception as err:
+            raise errors.InvalidParametersError(err, url, args) from err
+
+        # 发送请求
+        data = await self._request_with_sign("POST", url, body={"date": p.date})
+        return schema.ExchangeRates.model_validate(data)
+
+    async def EditExchangeRate(
+        self,
+        date: str | datetime.date | datetime.datetime,
+        currency_code: str,
+        user_rate: str | float | Decimal,
+    ) -> base_schema.ResponseResult:
+        """修改指定月份的用户汇率
+
+        ## Docs
+        - 基础数据: [修改我的汇率](https://apidoc.lingxing.com/#/docs/BasicData/ExchangeRateUpdate)
+
+        :param date `<'str/date/datetime'>`: 指定要修改的汇率月份
+
+            - 如果是字符串, 必须是有效的日期字符串, 如: `"2025-07"`, `"2025-07-01"`
+            - 如果是 `date` 或 `datetime` 对象, 将自动转换为 `YYYY-MM` 格式
+
+        :param currency_code `<'str'>`: 指定的货币代码, 如: `"USD"`
+        :param user_rate `<'str/float/Decimal'>`: 用户自定义汇率, 对比人民币,
+            如: `"7.2008000000"`, 最多支持10位小数
+        :returns `<'ResponseResult'>`: 返回修改结果
+        ```python
+        {
+            # 状态码
+            "code": 0,
+            # 提示信息
+            "message": "success",
+            # 错误信息
+            "errors": [],
+            # 请求ID
+            "request_id": "44DAC5AE-7D76-9054-2431-0EF7E357CFE5",
+            # 响应时间
+            "response_time": "2025-08-13 19:23:04",
+            # 编辑结果
+            "data": None
+        }
+        ```
+        """
+        url = route.EDIT_EXCHANGE_RATE
+        # 解析并验证参数
+        args = {
+            "date": date,
+            "currency_code": currency_code,
+            "user_rate": user_rate,
+        }
+        try:
+            p = param.EditExchangeRate.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 base_schema.ResponseResult.model_validate(data)