Metadata-Version: 2.4
Name: guangdong-social-security
Version: 0.3.0
Summary: Python SDK for Guangdong employer social security enrollment, removal and wage adjustment
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 广东社保单位增减员 Python SDK

Python 3.10+，使用标准库发送 HTTP 请求。在线安装：

```sh
python -m pip install --index-url https://pypi.org/simple guangdong-social-security==0.2.0
```

从仓库根目录安装本地源码：

```sh
python -m pip install ./sdk/guangdong-social-security
```

给其他项目分发时，可以先构建 wheel，再在目标项目安装。

```sh
python -m pip wheel ./sdk/guangdong-social-security --wheel-dir dist
python -m pip install dist/guangdong_social_security-0.2.0-py3-none-any.whl
```

## 接入单位会话

调用方登录广东社保网报并选定办理单位，再传入该会话的 `dwsbh`、`token`，以及会话所需的 Cookie 和其他请求头。单位或令牌变化时重新创建客户端。

```python
import os

from guangdong_social_security import (
    EmployerSession,
    GuangdongSocialSecurityClient,
    HttpTransport,
)

session = EmployerSession(
    dwsbh=os.environ["GD_SOCIAL_EMPLOYER_NUMBER"],
    token=os.environ["GD_SOCIAL_TOKEN"],
    # 查询历史时另外提供 djxh 和 swgljg_dm。
)
transport = HttpTransport(
    headers={"Cookie": os.environ["GD_SOCIAL_COOKIE"]},
    timeout=30,
    proxies={
        "http": "http://代理IP:端口",
        "https": "http://代理IP:端口",
    },
)
client = GuangdongSocialSecurityClient(session, transport=transport)

add_options = client.get_add_options()
remove_options = client.get_remove_options()
```

`proxies` 自 0.2.0 起支持，填入登录时使用的代理地址。字典键是目标请求的协议，值是代理 URL，包含协议、IP 和端口，例如 `http://127.0.0.1:8080`。省略或传 `None` 时沿用系统、环境代理配置，传 `{}` 时使用直连。HTTP 代理可同时处理 HTTP 请求和 HTTPS CONNECT 隧道。

已有 HTTP 客户端时，可以提供自己的 `transport(request)`，返回 `TransportResponse(status, data)`。请求对象包含 `method`、`url`、`query`、可选的 `json` 和 `file`。上传时 `file` 是 `(filename, bytes)`，表单字段为 `file`。传输层需要返回解析后的 `head/body` 对象，并禁用写请求的自动重试和重定向。

## 增减员调用

| 办理阶段 | 增员 | 减员 |
| --- | --- | --- |
| 查询配置 | `get_add_options(scope=None)` | `get_remove_options()` |
| 查询人员 | `list_add_drafts(page_index=1, page_size=10)` | `list_registered_employees(social_numbers=[...])`，也可按姓名或证件号码筛选 |
| 手工录入或选人 | `save_add_draft(person)` | `create_remove_row(employee, reason, month=None)` |
| Excel 导入 | `import_add_drafts(path)` 返回 `drid` | `import_remove_candidates(path)` 返回名单，或返回导入键供 `get_remove_import_candidates(key)` 补查 |
| 确认后正式提交 | `submit_add(reviewed_drafts, drid=None)` | `submit_remove(rows)` |
| 查询结果 | `get_add_result(business_numbers)`、`list_add_history()` | `get_last_remove_result(expected_tran_seq=...)`、`list_remove_history()` |

手工增员的 `person` 使用税局表单的字段名，`xz` 为险种代码列表。编辑暂存时同时传入原行的 `id` 和 `sbzydjId`。字段及枚举见 [增减员参数与枚举](增减员参数与枚举.md)。

缴费工资调整提供 `get_wage_adjustment_options()`、`create_wage_adjustment_row()`、`submit_wage_adjustment()`、Excel 导入及历史查询。例如：

```python
from guangdong_social_security import create_wage_adjustment_row

options = client.get_wage_adjustment_options()
employees = client.list_registered_employees(social_numbers=["个人社保号"])["rows"]
if len(employees) != 1:
    raise ValueError("在册人员未唯一匹配")
row = create_wage_adjustment_row(
    employees[0], new_wage="8000", start_month="2026-11", end_month="长期"
)
result = client.submit_wage_adjustment([row])
if result["status"] == "processing":
    drid = result["drid"]
    history = client.list_wage_adjustment_history(page_index=1, page_size=20)
    matched = next((item for item in history["rows"] if item.get("drid") == drid), None)
    print(matched)  # 处理中时稍后再查；按 drid 核对本次调整
```

结束年月“长期”会按页面协议转换为 `2099-12`。正式提交返回 `unknown` 时先查历史，避免重复提交。Excel 路径使用 `import_wage_adjustments(path)`、`list_wage_import_rows(drid)` 和 `submit_wage_import(drid)`。完整说明见仓库中的 [缴费工资调整 Python 流程](缴费工资调整-Python流程.md)。

增员提交接收调用方已确认的全部原始待提交行，名单跨页时逐页读取和确认。Excel 增员另传本次的 `drid`。若返回 `reason="warning"`，确认提示后可带原文 `acknowledged_warning` 再进入提交前检查。双重用人单位正式提交会返回 `dual_scope_unverified`。

手工减员从在册查询中选定原始人员行，并从 `get_remove_options()["reasons"]` 选定原因。

```python
from guangdong_social_security import create_remove_row

def submit_confirmed_removal(client, confirmed_employee, confirmed_reason):
    row = create_remove_row(confirmed_employee, confirmed_reason)
    return client.submit_remove([row])
```

Excel 减员导入的原始名单行经逐人确认和补齐原因后，直接传给 `submit_remove`。人员字段保留税局原名和原值，SDK 封装的结果字段使用 Python 命名，例如 `business_numbers` 和 `tran_seq`。

正式提交返回 `processing` 时，增员用返回的 `business_numbers` 查询，减员用返回的 `tran_seq` 核对上次结果。收到 `unknown` 时先查询结果或历史对账。查询或提交前检查出错会抛出 `SocialSecurityError`，可读取 `kind`、`step` 和 `details`。

Python 版通过模拟传输和本地 HTTP 测试验证。真实会话只读证据和正式提交的样本覆盖范围见 [原 SDK 说明](README.md)。
