lingxingapi 1.1.4__py3-none-any.whl

lingxingapi/basic/param.py

@@ -0,0 +1,72 @@
+# -*- coding: utf-8 -*-
+from pydantic import Field, field_validator
+from lingxingapi import utils
+from lingxingapi.base.param import Parameter
+from lingxingapi.fields import NonEmptyStr, CountryCode, CurrencyCode, NonNegativeInt
+
+
+# 基础数据 -----------------------------------------------------------------------------------------------------------------------
+# . Country Code
+class CountryCode(Parameter):
+    # 国家代码, 如: "US", "CA"
+    country_code: CountryCode
+
+
+# . Rename Sellers
+class RenameSeller(Parameter):
+    # 领星店铺ID (Seller.sid)
+    sid: NonNegativeInt
+    # 新的店铺名称
+    name: NonEmptyStr
+
+
+class RenameSellers(Parameter):
+    # 修改店铺名称参数列表
+    renames: list = Field(alias="sid_name_list")
+
+    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+    @field_validator("renames", mode="before")
+    @classmethod
+    def _validate_renames(cls, v) -> list[dict]:
+        if not isinstance(v, (list, tuple)):
+            res = [RenameSeller.model_validate_params(v)]
+        else:
+            res = [RenameSeller.model_validate_params(i) for i in v]
+            if len(res) == 0:
+                raise ValueError("必须提供至少一个 rename 来修改店铺名称")
+        return res
+
+
+# . Excahnge Rate Date
+class ExchangeRateDate(Parameter):
+    # 日期, 格式为 "YYYY-MM"
+    date: str
+
+    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+    @field_validator("date", mode="before")
+    @classmethod
+    def _validate_date(cls, v) -> str:
+        dt = utils.validate_datetime(v, True, "汇率日期 date")
+        return "%04d-%02d" % (dt.year, dt.month)
+
+
+# . Edit Exchange Rate
+class EditExchangeRate(Parameter):
+    # 汇率日期, 格式为 "YYYY-MM"
+    date: str
+    # 货币代码, 如 "CNY", "USD", "EUR"
+    currency_code: CurrencyCode = Field(alias="code")
+    # 用户自定义汇率 (对比人民币, 如: 7.2008000000), 最多支持10位小数
+    user_rate: str = Field(alias="my_rate")
+
+    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+    @field_validator("date", mode="before")
+    @classmethod
+    def _validate_date(cls, v) -> str:
+        dt = utils.validate_datetime(v, False, "汇率日期 date")
+        return "%04d-%02d" % (dt.year, dt.month)
+
+    @field_validator("user_rate", mode="before")
+    @classmethod
+    def _validate_user_rate(cls, v) -> str:
+        return str(utils.validate_exchange_rate(v, "用户自定义汇率 user_rate"))

lingxingapi/basic/route.py

@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+
+# fmt: off
+# 基础数据 -----------------------------------------------------------------------------------------------------------------------
+# https://apidoc.lingxing.com/#/docs/BasicData/AllMarketplace
+MARKETPLACES: str = "/erp/sc/data/seller/allMarketplace"
+# https://apidoc.lingxing.com/#/docs/BasicData/WorldStateLists
+STATES: str = "/erp/sc/data/worldState/lists"
+# https://apidoc.lingxing.com/#/docs/BasicData/SellerLists
+SELLERS: str = "/erp/sc/data/seller/lists"
+# https://apidoc.lingxing.com/#/docs/BasicData/ConceptSellerLists
+CONCEPT_SELLERS: str = "/erp/sc/data/seller/conceptLists"
+# https://apidoc.lingxing.com/#/docs/BasicData/SellerBatchRename
+RENAME_SELLERS: str = "/erp/sc/data/seller/batchEditSellerName"
+# https://apidoc.lingxing.com/#/docs/BasicData/AccoutLists
+ACCOUNTS: str = "/erp/sc/data/account/lists"
+# https://apidoc.lingxing.com/#/docs/BasicData/Currency
+EXCHANGE_RATES: str = "/erp/sc/routing/finance/currency/currencyMonth"
+# https://apidoc.lingxing.com/#/docs/BasicData/ExchangeRateUpdate
+EDIT_EXCHANGE_RATE: str = "/basicOpen/settings/exchangeRate/update"

lingxingapi/basic/schema.py

@@ -0,0 +1,218 @@
+# -*- coding: utf-8 -*-
+from pydantic import BaseModel, Field, field_validator
+from lingxingapi.fields import IntOrNone2Zero
+from lingxingapi.base.schema import ResponseV1, ResponseResult
+
+
+# 基础数据 -----------------------------------------------------------------------------------------------------------------------
+# . Marketplaces
+class Marketplace(BaseModel):
+    """亚马逊站点."""
+
+    # 领星站点ID [唯一标识]
+    mid: int
+    # 站点区域
+    region: str
+    # 站点亚马逊仓库所属区域 [原字段 'aws_region']
+    region_aws: str = Field(validation_alias="aws_region")
+    # 站点国家 (中文)
+    country: str
+    # 站点国家代码 [原字段 'code']
+    country_code: str = Field(validation_alias="code")
+    # 亚马逊市场ID
+    marketplace_id: str
+
+
+class Marketplaces(ResponseV1):
+    """亚马逊站点查询结果."""
+
+    data: list[Marketplace]
+
+
+# . States
+class State(BaseModel):
+    """国家的省/州."""
+
+    # 国家代码
+    country_code: str
+    # 省/州名称 [原字段 'state_or_province_name']
+    state: str = Field(validation_alias="state_or_province_name")
+    # 省/州代码 [原字段 'code']
+    state_code: str = Field(validation_alias="code")
+
+
+class States(ResponseV1):
+    """国家的省/州查询结果."""
+
+    data: list[State]
+
+
+# . Sellers
+class Seller(BaseModel):
+    """领星店铺."""
+
+    # 领星站点ID (Marketplace.mid)
+    mid: int
+    # 领星店铺ID [唯一标识]
+    sid: int
+    # 亚马逊卖家ID
+    seller_id: str
+    # 领星店铺名称 (含国家信息) [原字段 'name']
+    seller_name: str = Field(validation_alias="name")
+    # 领星店铺帐号ID [原字段 'seller_account_id']
+    account_id: int = Field(validation_alias="seller_account_id")
+    # 领星店铺帐号名称
+    account_name: str
+    # 亚马逊市场ID (Marketplace.marketplace_id)
+    marketplace_id: str
+    # 店铺区域
+    region: str
+    # 店铺国家 (中文)
+    country: str
+    # 店铺状态 (0: 停止同步, 1: 正常, 2: 授权异常, 3: 欠费停服)
+    status: int
+    # 店铺是否授权广告 (0: 否, 1: 是) [原字段 'has_ads_setting']
+    ads_authorized: int = Field(validation_alias="has_ads_setting")
+
+
+class Sellers(ResponseV1):
+    """领星店铺查询结果."""
+
+    data: list[Seller]
+
+
+# . Concept Sellers
+class ConceptSeller(BaseModel):
+    """领星概念店铺."""
+
+    # 领星概念站点ID [原字段 'mid']
+    cmid: int = Field(validation_alias="mid")
+    # 领星概念店铺ID [唯一标识, 原字段 'id']
+    csid: int = Field(validation_alias="id")
+    # 亚马逊卖家ID
+    seller_id: str
+    # 领星概念店铺名称 (含区域信息) [原字段 'name']
+    seller_name: str = Field(validation_alias="name")
+    # 领星概念店铺账号ID [原字段 'seller_account_id']
+    account_id: int = Field(validation_alias="seller_account_id")
+    # 领星概念店铺帐号名称 [原字段 'seller_account_name']
+    account_name: str = Field(validation_alias="seller_account_name")
+    # 概念店铺区域
+    region: str
+    # 概念店铺国家, 如: "北美共享", "欧洲共享"
+    country: str
+    # 概念店铺状态 (1: 启用, 2: 停用)
+    status: int
+
+
+class ConceptSellers(ResponseV1):
+    """领星概念店铺查询结果."""
+
+    data: list[ConceptSeller]
+
+
+# . Rename Sellers
+class RenameSellersFailureDetail(BaseModel):
+    """批量修改店铺名称失败的详情."""
+
+    # 领星店铺ID (Seller.sid)
+    sid: int
+    # 新店铺名称
+    name: str
+    # 失败信息 [原字段 'error']
+    message: str = Field(validation_alias="error")
+
+
+class RenameSellers(BaseModel):
+    """批量修改店铺名称的结果."""
+
+    success: IntOrNone2Zero = Field(validation_alias="success_num")
+    # 修改失败数量 [原字段 'failure_num']
+    failure: IntOrNone2Zero = Field(validation_alias="failure_num")
+    # 修改失败详情
+    failure_detail: list[RenameSellersFailureDetail]
+
+    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+    @field_validator("failure_detail", mode="before")
+    def _validate_failure_detail(cls, v):
+        if v is None:
+            return []
+        return [RenameSellersFailureDetail.model_validate(i) for i in v]
+
+
+class RenameSellersResult(ResponseResult):
+    """批量修改店铺名称的响应结果."""
+
+    data: RenameSellers
+
+
+# . Accounts
+class Account(BaseModel):
+    """领星账号."""
+
+    # 领星账号所从属的ID (如主帐号ID) [原字段 'zid']
+    parent_id: int = Field(validation_alias="zid")
+    # 领星帐号ID [唯一标识] [原字段 'uid']
+    user_id: int = Field(validation_alias="uid")
+    # 是否为主账号 (0: 否, 1: 是)
+    is_master: int
+    # 帐号角色
+    role: str
+    # 领星帐号显示的姓名 [原字段 'realname']
+    display_name: str = Field(validation_alias="realname")
+    # 领星帐号登陆用户名
+    username: str
+    # 领星帐号电子邮箱
+    email: str
+    # 领星帐号电话号码 [原字段 'mobile']
+    phone: str = Field(validation_alias="mobile")
+    # 领星帐号创建时间 (北京时间)
+    create_time: str
+    # 领星帐号最后登录时间 (北京时间)
+    last_login_time: str
+    # 领星帐号最后登录IP
+    last_login_ip: str
+    # 领星帐号登录次数 [原字段 'login_num']
+    login_count: int = Field(validation_alias="login_num")
+    # 领星帐号状态 (0: 禁用, 1: 正常)
+    status: int
+    # 关联的领星店铺名称, 逗号分隔 [原字段 'seller']
+    sellers: str = Field(validation_alias="seller")
+
+
+class Accounts(ResponseV1):
+    """领星账号查询结果."""
+
+    data: list[Account]
+
+
+# . Exchange Rates
+class ExchangeRate(BaseModel):
+    """货币汇率."""
+
+    # 汇率日期 (格式: YYYY-MM-DD)
+    date: str
+    # 货币名称 (中文) [原字段 'name']
+    currency: str = Field(validation_alias="name")
+    # 货币代码 [原字段 'code']
+    currency_code: str = Field(validation_alias="code")
+    # 货币符号 [原字段 'icon']
+    currency_icon: str = Field(validation_alias="icon")
+    # 中国银行官方汇率 (对比人民币, 如: 7.1541) [原字段 'rate_org']
+    boc_rate: float = Field(validation_alias="rate_org")
+    # 用户汇率 (对比人民币, 如: 7.2008000000) [原字段 'my_rate']
+    user_rate: float = Field(validation_alias="my_rate")
+    # 用户汇率修改时间 (北京时间)
+    update_time: str
+
+    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+    @field_validator("date", mode="after")
+    @classmethod
+    def _validate_date(cls, v: str) -> str:
+        return v + "-01"
+
+
+class ExchangeRates(ResponseV1):
+    """货币汇率查询结果."""
+
+    data: list[ExchangeRate]

lingxingapi/errors.py

@@ -0,0 +1,152 @@
+# -*- coding: utf-8 -*-
+from typing import Any
+
+
+# Base errors -----------------------------------------------------------------------------------------------------------
+class BaseApiError(Exception):
+    """The base class for all API errors."""
+
+    def __init__(
+        self,
+        msg: object,
+        url: str | None = None,
+        data: Any | None = None,
+        err_code: int | None = None,
+    ):
+        if not isinstance(msg, str):
+            msg = str(msg)
+        if url is not None:
+            msg += "\n请求路径: %s" % url
+        if data is not None:
+            if isinstance(data, dict):
+                data = {k: v for k, v in data.items() if v is not None}
+            msg += "\n数据信息: %r" % data
+        if err_code is not None:
+            msg += "\n错误代码: %r" % err_code
+        super().__init__(msg)
+
+
+# API Settings errors ---------------------------------------------------------------------------------------------------
+class ApiSettingsError(BaseApiError):
+    """Raised when there is an error with the API settings."""
+
+
+# Request errors --------------------------------------------------------------------------------------------------------
+class RequestError(BaseApiError):
+    """Raised when a request to the API fails."""
+
+
+# Internet Error
+class InternetConnectionError(RequestError):
+    """Raised when there is an internet connectivity issue."""
+
+
+# Timeout
+class ApiTimeoutError(RequestError, TimeoutError):
+    """Raise when the API request times out."""
+
+
+# Server
+class ServerError(RequestError):
+    """Raised when the API server deos not return proper response."""
+
+
+class InternalServerError(ServerError):
+    """Raised when the API server returns a 500 error."""
+
+
+# Authrization
+class AuthorizationError(RequestError):
+    """Raised when the API server returns a 4xx error related to authorization."""
+
+
+class UnauthorizedApiError(AuthorizationError):
+    """Raised when the API is not authorized for the app ID or secret."""
+
+
+class UnauthorizedRequestIpError(AuthorizationError):
+    """Raised when the IP address is not whitelisted for API access."""
+
+
+# Token
+class TokenError(RequestError):
+    """Raised when the access token has expired."""
+
+
+class TokenExpiredError(TokenError):
+    """Raised when the access token has expired."""
+
+
+class AccessTokenExpiredError(TokenExpiredError):
+    """Raised when the access token has expired."""
+
+
+class RefreshTokenExpiredError(TokenExpiredError):
+    """Raised when the refresh token has expired."""
+
+
+class InvalidTokenError(TokenError):
+    """Raised when the token is invalid or malformed."""
+
+
+class InvalidAccessTokenError(InvalidTokenError):
+    """Raised when the access token is invalid."""
+
+
+class InvalidRefreshTokenError(InvalidTokenError):
+    """Raised when the refresh token is invalid."""
+
+
+# App ID or Secret
+class AppIdOrSecretError(RequestError):
+    """Raised when the app ID or secret is invalid or missing."""
+
+
+# Signature errors
+class SignatureError(RequestError):
+    """Raised when the signature is invalid or missing."""
+
+
+class SignatureExpiredError(SignatureError):
+    """Raised when the signature has expired."""
+
+
+class InvalidSignatureError(SignatureError):
+    """Raised when the signature is invalid."""
+
+
+# Parameter
+class ParametersError(RequestError):
+    """Raised when the request parameters are invalid or missing."""
+
+
+class InvalidApiUrlError(ParametersError):
+    """Raised when the API server returns an error response."""
+
+
+class InvalidParametersError(ParametersError):
+    """Raised when a required parameter is missing."""
+
+
+# API Limit
+class ApiLimitError(RequestError):
+    """Raised when the API limit has been reached."""
+
+
+class TooManyRequestsError(ApiLimitError):
+    """Raised when too many requests have been made to the API."""
+
+
+# Unknown
+class UnknownRequestError(RequestError):
+    """Raised when an unknown error occurs during the request."""
+
+
+# Response errors -------------------------------------------------------------------------------------------------------
+class ReponseError(BaseApiError):
+    """Raised when the data returned by the API is invalid or malformed."""
+
+
+# Response data
+class ResponseDataError(ReponseError):
+    """Raised when the response data is not in the expected format."""