使用Syncari SDK创建eBay连接器调用GetOrders获取订单数据

第一步：调整synapse_info()基础配置 #

原有配置缺少eBay API的固定参数预设，补充后可以减少用户重复配置成本，将固定值设为默认项即可：

def synapse_info(self):
    return SynapseInfo(
        name='ebayOrderSynapse', 
        category='ecommerce',
        metadata=UIMetadata(displayName='eBay 订单拉取连接器'),
        supportedAuthTypes=[
            AuthMetadata(
                authType=AuthType.BASIC_TOKEN, 
                label='eBay Auth\'n\'Auth 令牌', 
                fields=[AuthField(name='token', label='eBay认证令牌', dataType=DataType.PASSWORD)]
            )
        ],
        configuredFields=[
            AuthField(name='endpoint', label='API端点', dataType=DataType.STRING, defaultValue="https://api.ebay.com/ws/api.dll"),
            AuthField(name='siteId', label='站点ID', dataType=DataType.NUMBER, defaultValue=0),
            AuthField(name='apiVersion', label='API兼容版本', dataType=DataType.STRING, defaultValue="967")
        ]
    )

第二步：封装eBay专属请求头生成方法 #

单独抽离私有方法生成接口要求的固定请求头，统一维护避免重复硬编码，注意必须指定XML格式的Content-Type，否则eBay服务端无法识别请求：

def __build_ebay_headers(self, connection: Connection):
    site_id = connection.configuredFields.get("siteId", 0)
    api_version = connection.configuredFields.get("apiVersion", "967")
    return {
        "X-EBAY-API-SITEID": str(site_id),
        "X-EBAY-API-COMPATIBILITY-LEVEL": str(api_version),
        "X-EBAY-API-CALL-NAME": "GetOrders",
        "Content-Type": "text/xml;charset=utf-8"
    }

第三步：封装XML请求体生成方法 #

使用标准XML库生成请求体，不要手动拼接字符串，避免特殊字符转义导致格式错误，将认证令牌、订单ID列表作为动态参数传入：

import xml.etree.ElementTree as ET

def __build_get_orders_body(self, auth_token: str, order_ids: list[str]):
    ns = "urn:ebay:apis:eBLBaseComponents"
    ET.register_namespace("", ns)
    root = ET.Element(f"{{{ns}}}GetOrdersRequest")
    
    # 填充认证节点
    requester_cred = ET.SubElement(root, f"{{{ns}}}RequesterCredentials")
    auth_token_node = ET.SubElement(requester_cred, f"{{{ns}}}eBayAuthToken")
    auth_token_node.text = auth_token

    # 填充基础配置节点
    error_lang = ET.SubElement(root, f"{{{ns}}}ErrorLanguage")
    error_lang.text = "en_US"
    warning_level = ET.SubElement(root, f"{{{ns}}}WarningLevel")
    warning_level.text = "High"
    order_role = ET.SubElement(root, f"{{{ns}}}OrderRole")
    order_role.text = "Seller"

    # 填充待查询订单ID节点
    order_id_array = ET.SubElement(root, f"{{{ns}}}OrderIDArray")
    for oid in order_ids:
        oid_node = ET.SubElement(order_id_array, f"{{{ns}}}OrderID")
        oid_node.text = oid.strip()

    # 拼接XML声明头，返回符合接口要求的请求体
    return b'<?xml version="1.0" encoding="utf-8"?>' + ET.tostring(root, encoding="utf-8")

第四步：改造test()连接验证逻辑 #

原有test方法调用的GET /users接口不符合eBay Trading API的调用规则，eBay所有Trading接口均为POST请求，test方法只需验证鉴权有效性即可：

def test(self, connection: Connection):
    auth_token = connection.auth.get("token")
    endpoint = connection.configuredFields.get("endpoint")
    headers = self.__build_ebay_headers(connection)
    
    # 传空订单ID数组做验证，鉴权失败会直接返回401/403，无需依赖具体订单数据
    test_body = self.__build_get_orders_body(auth_token, order_ids=[])
    resp = self.client.post(endpoint, headers=headers, data=test_body)
    
    if resp.status_code in [401, 403]:
        raise Exception("eBay认证令牌无效，请检查配置")
    resp.raise_for_status()

    if not connection.metaConfig:
        connection.metaConfig = {}
    return connection

第五步：实现正式订单拉取方法 #

完成基础封装后，编写业务方法接收订单ID参数，调用接口后解析返回的XML结构化数据即可：

def fetch_orders(self, connection: Connection, order_ids: list[str]):
    auth_token = connection.auth.get("token")
    endpoint = connection.configuredFields.get("endpoint")
    headers = self.__build_ebay_headers(connection)
    req_body = self.__build_get_orders_body(auth_token, order_ids)

    resp = self.client.post(endpoint, headers=headers, data=req_body)
    resp.raise_for_status()
    # 自行实现XML转Syncari实体格式的解析逻辑即可
    return self.__parse_ebay_order_response(resp.content)

注意事项 #

• 传入GetOrders的订单ID必须为legacy格式：即商品ID（ItemID）和交易ID（TransactionID）用横杠拼接，拍卖类订单的交易ID固定为0，不能传Fulfillment等REST API使用的ExtendedOrderID，否则接口会返回参数错误
• 若需要按时间范围批量拉取订单，无需传入OrderIDArray节点，新增CreateTimeFrom、CreateTimeTo时间节点传入UTC格式时间范围即可，节点拼接逻辑和上述代码一致
• 不同eBay站点对应不同siteId值，默认0对应美国站点，其他站点可根据实际业务调整配置项默认值
• 解析接口返回的XML时必须带上urn:ebay:apis:eBLBaseComponents命名空间匹配节点，否则会出现找不到节点的问题

内容的提问来源于stack exchange，提问作者Idriss