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

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

Python 3.10+，使用标准库发送 HTTP 请求。从仓库根目录执行：

```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.1.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)
client = GuangdongSocialSecurityClient(session, transport=transport)

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

已有 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)。

增员提交接收调用方已确认的全部原始待提交行，名单跨页时逐页读取和确认。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)。
