Metadata-Version: 2.1
Name: sf-sdk
Version: 2.1.0.0
Summary: Shunfeng Express Python SDK
Home-page: https://github.com/block-cat/sf-sdk
Author: blackcat
Author-email: kfx2007@163.com
License: GNU
Description: [![Build Status](https://travis-ci.org/block-cat/sf-sdk.svg?branch=master)](https://travis-ci.org/block-cat/sf-sdk)
        [![Coverage Status](https://coveralls.io/repos/github/block-cat/sf-sdk/badge.svg?branch=master)](https://coveralls.io/github/block-cat/sf-sdk?branch=master)
        [![PYPI](https://img.shields.io/pypi/v/sf-sdk)](https://pypi.org/project/sf-sdk/)
        
        # 顺丰 Python SDK
        
        基于顺丰官网开放平台2.0 API开发的Python SDK
        
        版本：2.1.0.0
        
        ## 功能概述
        
        目前已经开发完成的接口列表:
        
        * 下订单接口
        * 订单确认/取消接口-速运类API
        * 订单结果查询接口
        * 路由查询接口接口-速运类API
        * 订单筛选接口-速运类API
        * 时效标准及价格查询接口-速运类API
        * 产品推荐接口-速运类API
        * 预估总费用接口-国际件API
        * 清单运费查询接口-速运类API
        
        其他接口正在陆续对接中...
        
        ## 安装
        
        ```python
        pip install sf-sdk
        ```
        
        ## 使用示例
        
        clientcode和checkword是在顺丰官网注册后得到的用户编码和校验码
        
        ```python
        from sf.api import SF
        
        sf = SF("clientcode","checkword")
        sf.order.create_order(clientid,..)
        ```
        
        ### 下单
        
        ```python
        contacts = []
        sender = ContactInfo("北京市昌平区回龙观天慧园",company="测试公司",mobile="18512345678",contactType=1)
        receiver = ContactInfo("北京市海淀区新中关大厦A座",company="新东方",mobile="18511223344",contactType=2)
        contacts.append(sender)
        contacts.append(receiver)
        cargo_detail = CargoDetail("测试货物")
        res = self.sf.order.create_order(self.order_no, contacts,[cargo_detail])
        ```
        
        ### 订单查询
        
        ```python
        res = self.sf.order.get_order(self.order_no)
        ```
        
        ### 确认/取消订单
        
        ```python
        res = self.sf.order.confirm_order(self.order_no, dealType=2)
        ```
        
        ### 路由信息
        
        ```python
        res = self.sf.order.get_route_info(self.order_no)
        ```
        
        ### 判断是否可以派单
        
        ```python
        res = self.sf.order.can_delivery(self.order_no)
        ```
        
        ### 打印电子面单
        
        ```python
        res = self.sf.order.get_order(self.order_no)
        documents = [
            {
                "masterWaybillNo": res['msgData']['waybillNoInfoList'][0]['waybillNo'],
            }
        ]
        res = self.sf.sheet.sync_print(f"fm_150_standard_QXH",documents)
        ```
        
        ### 产品推荐与预估费用
        
        产品推荐接口需要先开通 `EXP_RECE_PSDS_PRODUCT_RECOMMEND` 权限。返回值中的
        `msgData.productList` 会包含 `totalFee`、`currency` 和 `serviceFeeList`；其中
        燃油附加费的服务代码为 `IN15`。
        
        ```python
        res = sf.order.recommend_products(
            srcProvince="香港",
            srcCity="香港",
            destProvince="澳门",
            destCity="澳门",
            sendTime="2026-09-04 12:00:00",
            weight=1,
            paymentTerms="1",
            srcAddress="香港葵涌永建路",
            destAddress="澳门半岛南湾大马路",
            monthlyCard="your-monthly-card",
            commodityNameList=["文件"],
        )
        ```
        
        国际件预估总费用接口会返回 `currency`、`totalFee` 和 `feeInfoList`，需要单独
        申请对应的国际接口权限。
        
        ```python
        res = sf.order.estimate_total_fee(
            customerCode="your-international-customer-code",
            interProductCode="INT0001",
            senderInfo={"country": "HK", "postCode": "999077", "address": "Kwai Chung"},
            receiverInfo={"country": "MO", "postCode": "999078", "address": "Macau"},
            parcelQuantity=1,
            parcelTotalWeight=1,
        )
        ```
        
        ### 清单运费查询
        
        `trackingType` 为 `1` 时按客户订单号查询，为 `2` 时按顺丰运单号查询。
        返回值中的 `msgData.waybillFeeList` 是实际费用明细，燃油附加费的费用类型为
        `14`。
        
        ```python
        res = sf.order.query_waybill_fee(
            trackingType=2,
            trackingNum="SF1234567890",
        )
        ```
        
        ### 沙箱联调
        
        实时沙箱测试默认跳过。需要运行时通过环境变量提供凭据，凭据不会写入代码：
        
        ```bash
        export SF_SANDBOX_CLIENT_CODE="your-client-code"
        export SF_SANDBOX_CHECKWORD="your-checkword"
        pytest
        ```
        
Keywords: sf sdk
Platform: UNKNOWN
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Description-Content-Type: text/markdown
