SBT-API

 

版本编号

修订内容

修订日期

V 2.0

发布

2017/11/11

 

1      接入申请

1.1    测试环境

         申请接入社保通API测试环境的平台,提交如下信息api@shebaochina.com邮箱

一、    邮件标题:{公司}申请接入社保通API测试环境

二、    贵公司基本信息

  1. 公司名称(全称
  2. 企业法人
  3. 营业执照复印件
  4. 纳税人识别号(测试环境可不提供,接入生产环境必须提供
  5. 公司开户行和账号(测试环境可不提供,接入生产环境必须提供
  6. 联系人
  7. 联系方式
  8. 公司地址
  9. 联系邮箱如果API回写接口回写失败,发送邮件提醒

三、    贵公司接入社保通API的平台信息

  1. 贵司平台名称
  2. 贵司平台简介
  3. 贵司平台开发和测试环境IP地址,支持多个
  4. 贵司平台开发和测试环境接口回写地址(可开发过程中再提供

四、    贵公司接入社保通API的具体服务事项:(协议中需规定

  1. 贵司平台是否可通过社保通API创建企业会员账号

选项

  1. 贵司平台是否可通过社保通API创建个人会员账号

选项

  1. 贵司平台生成的社保订单付费方式

选项:

a)         会员付款

会员为订单付款。

b)         平台付款

平台为订单付款。贵平台需要预存费用在社保通账户中,生成并确认的订单将用贵平台在社保通的账户余额进行付款。当余额不足时,不会自动付款当再次充值后,按照订单提交先后顺序进行付款如果余额不足以支付订单,自动为下一个订单付款

  1. 贵司平台与社保通平台服务费结算方式

选项:

a)         会员自主

会员付社保通服务费。提交订单时,按照社保通默认的服务费规则(可查看服务费查询接口计算服务费各会员为订单付款时,同时已付服务费。

b)         平台结算

贵公司付社保通服务费。提交订单时,社保通API返回的订单中,将不返回订单服务费。社保通将每月定期生成与贵公司结算服务费的账单,账单生成后,贵公司按照服务费账单进行付款。

如果是平台结算,协议中需规定如下信息

1)         每月服务费账单生成日期

2)         正常汇缴每月次服务费单价(服务费为:单人单地区社保或公积金正常缴纳月数*单价

3)         补缴每月次服务费单价(服务费为:单人单地区社保或公积金补缴月数*单价

         我司审核通过后,如下信息发送给接入平台

一、    测试API平台的access_token

二、    测试ftp服务器地址、账号和密码

三、    测试API平台地址

1.2    生产环境

         申请接入社保通API生产环境的平台,提交如下信息到api@shebaochina.com邮箱:

一、    邮件标题:{贵公司}申请接入社保通API生产环境

二、    其它信息和申请接入测试环境一致

         我司审核通过后,会如下信息发送给接入平台

一、    生产环境API平台的access_token

二、    生产环境ftp服务器地址、账号和密码

三、    生产环境API平台地址

2      接口

 

         测试环境API_URLhttp://test.shebaotong.com/

         生产环境API_URLhttps://api.shebaotong.com/v4/

         所有接口必须提供accessToken参数合法的accessToken使用JSON数据提供参数时,accessToken必须在Query String Parameters例如http://test.shebaotong.com/base/cities?accessToken=9B85EB56F5245C62EF23CO1696F7D3CD

         所有的业务接口必须传递user_code(账号参数。

         接口为RESTful API如果直接用浏览器调用接口浏览器form表单只支持GETPOST请求,而httpdeleteputmethod并不支持,可提供参数:_method=DELETE表单的method必须POST

         如果是通过JSON提供参数,须设置header参数Content-Type=application/json

         如果调用接口提供的数据有误或接口出错,会返回包含errorcodejason错误信息,如:{errorcode:1001,msg:accessToken有误}errorcode为错误编码,msg为错误描述信息

         API中所有接口返回的数据格式为JSON

2.1    基础信息接口

2.1.1     获取可缴纳城市

         基本信息:

接口地址

base/cities

支持格式

JSON/Form Data/Query String Parameters

请求方式

http get

编码

UTF-8

是否需要授权

说明

获取社保通平台通过API接口可代缴社保公积金的地区信息

注意事项

有些信息每个缴费周期会发生变化,所以原则上需要接入平台,至少每天更新一次建议在凌晨4点后更新

         请求参数:

参数

类型

必填

说明

 

 

 

 

请求示例:

GET http(s)://API_URL/base/cities

         返回结果

返回JSON示例:

{

    "rows": [

        {

            "region": "华南",

            "pname": "广东",

            "prov": "guangdong",

            "city": "shenzhen",

            "areaNum": "440300",

            "name": "深圳",

            "closeDay": 15,

            "closeTime": 1492099199000,

            "rule": 1,

            "sbgjjRule": 1,

            "gjjBaseRule": 2,

            "gjjBaseRange": 1000,

            "timestamp": 1443159946000

        },

        {

            "region": "华东",

            "pname": "上海",

            "prov": "shanghaishi",

            "city": "shanghai",

            "areaNum": "310000",

            "name": "上海",

            "closeDay": 20,

            "closeTime": 1492703999000,

            "rule": 1,

            "sgRule": 1,

            "gjjBaseRule": 1,

            "gjjBaseRange": 0,

            "timestamp": 1443159946000

        }

    ]

}

参数说明:

返回数据格式

JSON

说明

rows为可缴交城市集合,按照最后修改时间倒序

参数

类型

必须

说明

region

String

城市所属区域。

取值范围华东、华南、华北、华中东北西南西北

pname

String

城市所属省中文名称

prov

String

城市所属省编码

city

String

城市编码

areaNum

String

城市行政区划代码

name

String

城市中文名称

closeDay

Number

该城市每月提交代缴订单并付款的截止日期。该值设定规则后一般不会变化,每月具体的订单截止日期可通过closeDate获取。

closeTime

Number

当前缴费周期最后提交订单时间精确到秒的时间戳截止时间每一缴费周期会发生变化根据closeDay自动计算,如遇节假日或其它情况会自动提前。

rule

Number

该城市报增报减的规则。

取值范围

0:为当月增减当月;

1:为当月增减次月;

2:为当月增减次月,且参保月加收当前月费用。

当值为2时,参保首月将收取当前月和次月两个月费用,之后每月将收取次月的费用

sbgjjAddRule

Number

该城市社保公积金申报规则

取值范围

1:社保公积金必须同时申报;

2:可单独申报社保不申报公积金。

gjjBaseRule

Number

该城市公积金基数规则

取值范围

0限制

1公积金基数必须和社保基数一致(但同时也必须满足政策的最低最高基数限制

2公积金基数必须小于等于社保基数(但同时也必须满足政策的最低基数限制

3公积金基数不得高于社保基数+{gjjBaseRange}

4公积金基数不得低于社保基数-{gjjBaseRange}

5公积金基数必须在社保基数±{gjjBaseRange}范围内

gjjBaseRange

Number

公积金基数差异范围保留两位有效数字gjjBaseRule345时有用。

timestamp

Number

该城市政策最后更新时间戳精确到

 

2.1.2     获取城市社保公积金政策

         基本信息:

接口地址

base/{area_num}/types

支持格式

JSON/Form Data/Query String Parameters

请求方式

http get

编码

UTF-8

是否需要授权

说明

根据城市编码获取该城市社保和公积金缴费规则

注意事项

政策可能不定期会发生变化,为了确保政策数据的一致性和准确性,建议每天凌晨4点后通过该接口更新本地政策数据

         请求参数:

参数

类型

必填

说明

area_num

String

url占位城市行政区划代码

请求示例:

GET http(s)://API_URL/base/310000/types

         返回结果:

返回JSON示例:

{

    "shebao": [

        {

            "type": "shanghaiwuxian",

            "name": "上海五险",

            "desc": "说明",

            "addMonth": "201705",

            "keepMonth": "201705",

            "obMonth": "201701",

            "oeMonth": "201704",

            "maxBase": 16353,

            "minBase": 3271,

            "efDate": 1436544000000,

            "itemList": [

                {

                    "code": "yanglao",

                    "name": "养老保险",

                    "payFreq": "month",

                    "maxBase": 16353,

                    "minBase": 3271,

                    "empProp": 8,

                    "orgProp": 21

                },

                {

                    "code": "yiliao",

                    "name": "医疗保险",

                    "payFreq": "month",

                    "maxBase": 16353,

                    "minBase": 3271,

                    "empProp": 8,

                    "orgProp": 21

                },

                {

                    "code": "canjijin",

                    "name": "残疾人保障金",

                    "payFreq": "year",

                    "empFee": 20,

                    "orgFee": 30

                }

            ],

            "files": [

                {

                    "code": "idcard_a",

                    "name": "身份证正面",

                    "original": true,

                    "suffix": "jpg,jpeg,png,bmp",

                    "status": "newaccount,renewal"

                },

                {

                    "code": "idcard_b",

                    "name": "身份证背面",

                    "original": true,

                    "suffix": "jpg,jpeg,png,bmp",

                    "status": "newaccount,renewal"

                },

                {

                    "code": "lizhizhengminBaseg",

                    "name": "离职证明",

                    "original": false,

                    "suffix": "doc,docx,pdf",

                    "status": "stop"

                }

            ]

        }

    ],

    "gongjj": [

        {

            "type": "shanghaigongjijin",

            "name": "上海公积金",

            "desc": "说明",

            "addMonth": "201705",

            "keepMonth": "201705",

            "obMonth": "201701",

            "oeMonth": "201704",

            "maxBase": 16353,

            "minBase": 3271,

            "efDate": 1436544000000,

            "itemList": [

                {

                    "code": "gongjinjin",

                    "name": "公积金",

                    "payFreq": "month",

                    "maxBase": 16357,

                    "minBase": 1820,

                    "empProp": 7,

                    "orgProp": 7

                }

            ],

            "files": [

                {

                    "code": "idcard_a",

                    "name": "身份证正面",

                    "original": true,

                    "suffix": "jpg,jpeg,png,bmp",

                    "status": "newaccount,renewal"

                },

                {

                    "code": "idcard_b",

                    "name": "身份证背面",

                    "original": true,

                    "suffix": "jpg,jpeg,png,bmp",

                    "status": "newaccount,renewal"

                }

            ]

        }

    ],

    "fields": [

        {

            "code": "education",

            "name": "学历",

            "type": "dd",

            "list": [

                {

                    "value": "01",

                    "text": "小学"

                },

                {

                    "value": "02",

                    "text": "初中"

                },

                {

                    "value": "03",

                    "text": "中专"

                },

                {

                    "value": "04",

                    "text": "高中"

                },

                {

                    "value": "05",

                    "text": "大专"

                },

                {

                    "value": "06",

                    "text": "本科"

                },

                {

                    "value": "07",

                    "text": "硕士"

                },

                {

                    "value": "08",

                    "text": "博士"

                }

            ],

            "status": "newaccount,renewal"

        },

        {

            "code": "residence_place",

            "name": "户籍地址",

            "type": "text",

            "length": 64,

            "status": "newaccount,renewal"

        },

        {

            "code": "grad_date",

            "name": "毕业日期",

            "type": "date",

            "status": "newaccount,renewal"

        },

        {

            "code": "begin_work",

            "name": "开始工作年月",

            "type": "yearMonth",

            "status": "newaccount,renewal"

        }

    ]

}

参数说明:

返回数据格式

JSON

说明

返回该城市社保公积金缴费规则、各项目规则,以及必须提交的扩展字段和材料信息

参数

类型

必须

说明

shebao

Array

该城市社保政策集合

gongjj

Array

该城市公积金政策集合

type

String

社保或公积金政策编码

name

String

社保或公积金政策名称

desc

String

政策描述说明

efDate

Number

政策生效日期时间戳

addMonth

String

该政策当前周期新报增的缴费月份,格式yyyyMM

keepMonth

String

该政策当前周期续缴的缴费月份,格式yyyyMM

obMonth

String

该政策当前周期允许补缴的起始月,包括该月格式yyyyMM。每个缴费周期该月份会发生变化,如果该政策不可补缴,为空

oeMonth

String

该政策当前周期允许补缴的结束月,包括该月格式yyyyMM。每个缴费周期该月份会发生变化,如果该政策不可补缴,为空

maxBase

Number

该政策允许最高基数,保留2位小数

minBase

Number

该政策允许最低基数,保留2位小数

itemList

Array

社保公积金政策中项目规则集合

code

String

项目编码

name

String

项目名称

payFreq

String

缴费频率:

month:月缴

year:年缴

once:一次性费用

maxBase

Number

该项目允许最高基数保留2位小数

minBase

Number

该项目允许最低基数保留2位小数

orgProp

Number

该项目企业缴费百分比保留4位小数

empProp

Number

该项目个人缴费百分比保留4位小数

orgFee

Number

该项目企业固定缴费金额保留2位小数果该参数有值,maxminorgpropempprop参数值为空

empFee

Number

该项目个人固定缴费金额保留2位小数果该参数有值,maxminorgpropempprop参数值为空

files

Array

该社保或公积金政策新参保、补缴、续保停缴时所需材料信息。

code

String

文件编码

name

String

文件名称

original

Boolean

是否需提供原件

true需提供(同时也需提供复印件

false:只需提供复印件

suffix

String

文件允许的后缀类型,多种类型用”,”分隔。”doc,png,jpg”

status

String

需提供该文件的状态,当多个状态都需要该文件时,用”,”分隔。

取值范围

newaccount新参保

overdue

renewal续保

stop停缴

fields

Array

该地区参保字段集合。人员新参保、补缴、续保停缴时,需要提交的字段信息。

code

String

该字段编码

name

String

该字段中文名称

type

String

该字段数据类型。

取值范围

text:文本类型;

dd:数据字典类型;

date:日期类型;

yearMonth:年月类型,格式为yyyyMM

list

Array

当数据类型为dd=数据字典时,提供该字典列表信息

value

String

数据字典的编码值

text

String

数据字典的文本值

length

Number

当数据类型为text=文本时,提供该字段允许的最大字符长度

status

String

需提供该字段的状态,当多个状态都需要该文件时,用”,”分隔。

取值范围

newaccount新参保

overdue

renewal续保

stop停缴

2.1.3     社保公积金计算器

         基本信息:

接口地址

base/calculate

支持格式

JSON/Form Data/Query String Parameters

请求方式

http get

编码

UTF-8

是否需要授权

说明

根据政策和基数计算出社保或公积金结果

注意事项

 

         请求参数:

参数

类型

必填

说明

type

String

需要计算的社保或公积金政策编码

base

Number

需要计算的社保或公积金基数保留2小数

请求示例:

GET http(s)://API_URL/base/calculate?type=shanghaishebao&base=5000

         返回结果:

返回JSON示例:

{

    "rows": [

        {

            "code": "yanglao",

            "name": "养老保险",

            "base": 5000,

            "org": 400,

            "emp": 1000,

            "orgprop": 20,

            "empprop": 8,

            "sum": 1400

        },

        {

            "code": "yiliao",

            "name": "医疗保险",

            "base": 5000,

            "org": 100,

            "emp": 500,

            "orgprop": 9,

            "empprop": 2,

            "sum": 600

        }

    ]

}

参数说明:

返回数据格式

JSON

说明

rows为计算结果集合

参数

类型

必须

说明

code

String

项目编码

name

String

项目名称

base

Number

基数,保留2位小数

org

Number

企业部分费用

emp

Number

个人部分费用

orgprop

Number

企业承担百分比

empprop

Number

个人承担百分比

sum

Number

费用总额

2.1.4     社保公积金补缴计算器

         基本信息:

接口地址

base/calcoverdue

支持格式

JSON/Form Data/Query String Parameters

请求方式

http get

编码

UTF-8

是否需要授权

说明

根据政策、基数和补缴月份计算出社保或公积金结果

注意事项

 

         请求参数:

参数

类型

必填

说明

type

String

需要计算的社保或公积金政策编码

base

Number

需要计算的社保或公积金基数。保留2位小数

month

String

补缴起始月份,月份格式为yyyyMM

请求示例:

GET http(s)://API_URL/base/calcoverdue?type=shanghaishebao&base=5000&month=201701

         返回结果:

返回JSON示例:

{

    "rows": [

        {

            "code": "yanglao",

            "name": "养老保险",

            "base": 5000,

            "org": 400,

            "emp": 1000,

            "orgprop": 20,

            "empprop": 8,

            "odf": 20,

            "sum": 1420

        },

        {

            "code": "yiliao",

            "name": "医疗保险",

            "base": 5000,

            "org": 100,

            "emp": 500,

            "orgprop": 9,

            "empprop": 2,

            "odf": 20,

            "sum": 620

        }

    ]

}

参数说明:

返回数据格式

JSON

说明

rows为计算结果集合

参数

类型

必须

说明

code

String

项目编码

name

String

项目名称

base

Number

基数

org

Number

企业部分费用

emp

Number

个人部分费用

orgprop

Number

企业承担百分比

empprop

Number

个人承担百分比

odf

Number

滞纳金

sum

Number

费用总额

2.2    账号接口

2.2.1     企业账号

         基本信息:

接口地址

创建账号accounts/company

修改账号accounts/company/{user_code}

支持格式

JSON/Form Data

请求方式

创建账号:http post

修改账号:http put

编码

UTF-8

是否需要授权

说明

创建社保通平台企业账号,如果创建成功,接口会返回会员账号所有业务操作的接口都需要提供该账号

注意事项

是否可创建企业账号,需在合作协议中进行约定

         请求参数:

参数

类型

必填

说明

user_code

String

url占位创建企业账号时接口返回的账号,修改账号时使用。只有账号未审核通过时才可修改。

data

JSON/Form Data

注册信息如果是修改需保证下列字段至少有一个不为空

name

String

企业公司名称,需真实且不能重名

phone

String

手机号码,需真实,不可重复

email

String

邮箱地址,需真实,不可重复

contact

String

联系人

bl

String

营业执照图片文件在ftp地址。文件格式可为:jpg,jpeg,bmp,png

请求示例:

创建 POST http(s)://API_URL/accounts/company

修改 PUT http(s)://API_URL/accounts/company/20170506396

RequestBodyJSON参数data格式

{

    "name": "社宝信息科技有限公司",

    "phone": "13888888888",

    "email": "test@shebaotong.com",

    "contact": "张三",

    "bl": "201704271822504442408.jpg"

}

 

         返回结果:

返回JSON示例:

{

    "userCode": "20170506396"

}

参数说明:

返回数据格式

JSON

说明

 

参数

类型

必须

说明

userCode

String

必须

会员账号

2.2.2     个人账号

         基本信息:

接口地址

创建账号:accounts/personal

修改账号:accounts/personal/{user_code}

支持格式

JSON/Form Data

请求方式

创建账号:http post

修改账号:http put

编码

UTF-8

是否需要授权

说明

创建社保通平台个人账号,如果创建成功,接口会返回会员账号所有业务操作的接口都需要提供该账号

注意事项

是否可创建个人账号,需在合作协议中进行约定

         请求参数:

参数

类型

必填

说明

user_code

String

url占位创建企业账号时接口返回的账号,修改账号时使用。只有账号未审核通过时才可修改。

data

JSON/Form Data

注册信息.如果是修改,需保证下列字段至少有一个不为空

name

String

注册个人会员的姓名

idNum

String

注册个人会员的身份证号不可重复

phone

String

注册个人会员的手机号码,需真实,不可重复

email

String

邮箱地址,需真实,不可重复

idcarda

String

身份证正面图片文件在ftp地址。文件格式可为:jpg,jpeg,bmp,png

idcardb

String

身份证背面图片文件在ftp地址。文件格式可为:jpg,jpeg,bmp,png

请求示例:

创建 POST http(s)://API_URL/accounts/personal

修改 PUT http(s)://API_URL/accounts/personal/20170506397

RequestBodyJSON参数data格式

{

"name": "李四",

"idNum": "410882198900000000",

    "phone": "13888888888",

"email": "zhangsan@shebaotong.com",

"idcarda": "201704271822504442408.jpg",

"idcardb": "201704271822504442409.jpg"

}

 

         返回结果:

返回JSON示例:

{

    "userCode": "20170506397"

}

参数说明:

返回数据格式

JSON

说明

 

参数

类型

必须

说明

userCode

String

会员账号

2.2.3     刷新TOKEN

         基本信息:

接口地址

accounts/token

支持格式

JSON/Form Data

请求方式

http put

编码

UTF-8

是否需要授权

说明

如果接入平台认为access_token已存在安全隐患,调用该接口获取最新tokentoken立即失效

注意事项

最大刷新频率为1分钟每次

         请求参数:

参数

类型

必填

说明

 

 

 

 

请求示例:

PUT http(s)://API_URL/accounts/token

         返回结果:

返回JSON示例:

{

    "accessToken": "1ACAECR7BB04E68BC39D9659C0516EC0"

}

参数说明:

返回数据格式

JSON

说明

 

参数

类型

必须

说明

accessToken

String

新的access_token

2.3    通用信息查询接口

2.3.1     账户余额查询

         基本信息:

接口地址

accounts/balance

支持格式

JSON/Form Data/Query String Parameters

请求方式

http get

编码

UTF-8

是否需要授权

说明

获取接入平台在社保通的账户余额

注意事项

只有在协议中规定【订单付费方式】为【平台付款的接入平台,才可调用该接口

         请求参数:

参数

类型

必填

说明

 

 

 

 

请求示例:

GET http(s)://API_URL/accounts/balance

         返回结果:

返回JSON示例:

{

    "result": 500000.65

}

参数说明:

返回数据格式

JSON

说明

 

参数

类型

必须

说明

result

Number

账户余额

2.3.2     服务费查询

         基本信息:

接口地址

{user_code}/service

支持格式

JSON/Form Data/Query String Parameters

请求方式

http get

编码

UTF-8

是否需要授权

说明

获取会员服务费信息

注意事项

  1. 创建会员账号后才可获取服务费。企业会员服务费按城市服务费乘以该城市服务次数收取服务费。个人会员按提交订单符合的服务费套餐乘以人数收取服务费
  2. 只有在协议中规定【订单付费方式】为【会员自主的接入平台,才可调用该接口

         请求参数:

参数

类型

必填

说明

user_code

String

url占位会员账号,创建账号后获得

请求示例:

GET http(s)://API_URL/20170506396/service

         返回结果:

返回JSON示例:

         企业会员

{

    "rows": [

        {

            "areaNum": "310000",

            "price": 30

        },

        {

            "areaNum": "540000",

            "price": 80

        }

    ]

}

         个人会员

{

    "rows": [

        {

            "months": 1,

            "price": 120

        },

        {

            "months": 3,

            "price": 300

        },

        {

            "months": 6,

            "price": 500

        },

        {

            "months": 12,

            "price": 1000

        }

    ]

}

参数说明:

返回数据格式

JSON

说明

rows为计算结果集合

参数

类型

必须

说明

如果是企业账号返回的参数:

areaNum

String

企业会员已报增社保公积金的城市行政区划代码计算服务费时,将按照服务费单价乘以服务次数进行计算。某一人缴纳某一月的社保或公积金将算作一次。

price

Number

城市服务费单价

如果是个人账号返回的参数:

months

Number

个人会员服务费套餐,一次订单缴纳的社保或公积金的月份。补缴社保公积金将按照单月服务费价格进行计算;正常汇缴将按照缴纳的月份对应的价格乘以人数计算服务费。

取值范围

1单月

3:季度。缴纳3个月

6半年缴纳6个月

12一年缴纳12个月

price

Number

服务费价格

2.4    人员接口

2.4.1     增员

         基本信息:

接口地址

{user_code}/employees/{area_num}

支持格式

JSON

请求方式

http post

编码

UTF-8

是否需要授权

说明

人员基本信息,社保公积金增员或修改

注意事项

  1. 需按照城市政策提供增员时人员的扩展字段和材料信息
  2. 批量增员时,每次提交的人数不可大于10
  3. 增员成功并不代表增员正式生效,必须提交订单并付款后才正式生效
  4. 如果再次提交已经提交过的【姓名+证件号码的人员数据,视为修改。
  5. 如果增员时根据参保起始月提交了社保或公积金补缴,在当前费用周期未提交订单,那么系统将自动清理其补缴数据;如果在后续的费用周期中,需要再次提交补缴,可通过接口再次提交该社保或公积金数据
  6. 人员材料审核通过后,才可生成订单所以最好在城市截止日前若干天进行增员,以免由于材料审核未通过导致订单无法及时提交

         请求参数:

参数

类型

必填

说明

user_code

String

url占位会员账号,创建账号后获得

area_num

String

url占位缴交城市行政区划代码

employees

Array

RequestBody JSON需要增员的人员列表

name

String

人员姓名

idNum

String

人员证件号码(如果包含有字母,则大写。同一个账号中人员的证件号码唯一

idType

String

人员证件类型。

取值范围

idcard身份证

passport护照

nationality

String

国家或地区。当证件类型为【passport=护照】时,必填提供,并不可为CHN(中国)中国大陆必须提供身份证号ISO 3166-1标准国家或地区代码使用3位字母代码

gender

String

性别。当证件类型为【passport=护照】时,必填提供

取值范围

male:男

female:女

birthday

String

出生日期。当证件类型为【passport=护照】时,必填提供。格式为yyyy-MM-dd

phone

String

手机号码

householdType

String

户籍性质。

取值范围相对于当前缴交的城市

1本地城镇

2本地农村

3外地城镇

4外地农村

shebao

Object

该人员社保申报信息

gongjj

Object

该人员公积金申报信息。如果缴纳的城市的【社保公积金申报规则】为【1=必须同时申报社保公积金】,必填提供公积金缴纳信息

status

String

该人员在该城市社保或公积金参保状态

取值范围

newaccount新参保。指在该城市从未缴纳过社保

renewal续保在该城市已缴纳过社保

type

String

在该城市中申报的社保或公积金政策编码

base

Number

该人员申报的社保或公积金基数,保留2位小数。必须在申报的政策的范围内,可等于最大或最小基数。

num

String

该人员社保或公积金编号。如果参保状态为【renewal=续保时,需提供该编号;否则不用提供。

beginMonth

String

 

该人员申报的社保或公积金的参保起始月份,格式yyyyMM如果为空,为汇缴当前可缴纳月,政策接口中返回的addMonth月份;不可比政策接口中返回的addMonth月份大;如果比政策接口中返回的addMonth月份小,视为需要补缴从obMonth月至addMonth的前一个月。

files

Array

根据该城市政策和人员社保或公积金参保情况需要提交的材料。如果已提交过,不用再提交。

1)         如果该人员缴纳的政策为【newaccount=新参保则必须提交政策接口中【新参保需要提交的材料;

2)         如果该人员缴纳的政策为renewal=续保则必须提交政策接口中【续保需要提交的材料;

3)         如果该人员缴纳的政策有【overdue=补缴则必须提交政策接口中【补缴需要提交的材料;

code

String

材料编码。政策接口中返回的材料编码

file

String

材料文件在ftp的地址。必须符合接口中规定的文件格式;文件必须小于1M

fields

Array

根据该城市政策和人员社保或公积金参保情况需要提交的其它字段。如果已提交过,不用再提交。

1)         如果该人员在该地区的社保为【newaccount=新参保则必须提交政策接口中【新参保需要提交的字段;

2)         如果该人员在该地区的社保为【renewal=续保则必须提交政策接口中【续保需要提交的字段;

3)         如果该人员在该地区的社保有【overdue=补缴则必须提交政策接口中【补缴需要提交的字段;

code

String

字段编码。政策接口中返回的字段编码

value

String

字段值。如果字段数据类型为【dd=数据字典】,需要返回数据字典的value其它字段,需要按照字段的定义的类型提供数据

如果人员数据中,已存在之前提交过的【姓名+【证件号码数据,视为修改。修改时各参数规则如下:

参数

类型

必填

说明

name

String

人员姓名

idNum

String

人员证件号码

idType

String

证件类型,一旦新增不可修改。

修改时,即使提供了该字段值,不会修改

phone

String

如果不为空修改

householdType

String

如果不为空修改

nationality

String

如果不为空且该人员证件类型为【passport=护照修改

gender

String

如果不为空且该人员证件类型为【passport=护照修改

birthday

String

如果不为空且该人员证件类型为【passport=护照修改

shebao

Object

如果不为空为修改社保缴纳。只有社保状态为【add=新增且未提交订单,才可修改。

gongjj

Object

如果不为空,且之前有提交公积金信息为修改公积金缴纳,否则为新缴纳公积金。只有公积金状态为【add=新增且未提交订单,才可修改。

beginMonth

String

如果社保、公积金已提交订单,再提交新的社保或公积金缴纳信息,不被允许的。除非该人员社保或公积金办理失败,通过提交beginMonth参数,修改参保起始月(默认情况下,如果不修改参保起始月,社保通将一直对办理失败的进行补缴修改参保起始月后,系统可将对办理失败月份的费用进行退款。

files

Array

材料数组中,如果已存在对应的材料,为覆盖之前提交的材料,只有材料状态为【0=审核失败或【-1=未审核的材料才可覆盖,如果已审核通过,系统不会覆盖,不会抛出错误;如果不存在,为新提交的材料。

fields

Array

字段数组中,如果已存在对应字段,为修改原字段值;否则则为新增加的字段。

请求示例:

POST http(s)://API_URL/20170506396/employees/310000

RequestBodyJSON参数data格式

{

    "employees": [

        {

            "name": "张三",

            "idNum": "410882198901010000",

            "idType": "idcard",

            "phone": "13588888888",

"householdType": "1",

            "shebao": {

                "status": "newaccount",

                "type": "shanghaishebao",

                "base": 5000.05,

                "beginMonth": "201701"

            },

            "gongjj": {

                "status": "newaccount",

                "type": "shanghaigongjijin",

                "base": 5000.05,

                "beginMonth": "201703"

            },

            "files": [

                {

                    "code": "idcard_a",

                    "file": "201704271822504442408.jpg"

                },

                {

                    "code": "idcard_b",

                    "file": "201704271822504442409.jpg"

                },

                {

                    "code": "laodonghetong",

                    "file": "201704271822504442410.docx"

                }

            ],

            "fields": [

                {

                    "code": "education",

                    "value": "01"

                },

                {

                    "code": "residence_place",

                    "value": "北京市朝阳区翠微路218"

                },

                {

                    "code": "grad_date",

                    "value": "2001-06-30"

                },

                {

                    "code": "begin_work",

                    "value": "200110"

                }

            ]

        },

        {

            "name": "Si Li",

            "idNum": "FE65982365",

            "idType": "passport",

            "nationality": "USA",

            "phone": "13588888889",

            "gender": "male",

            "birthday": "1986-10-01",

"householdType": "2",

            "shebao": {

                "status": "renewal",

                "type": "shanghaishebao2",

                "base": 7000,

                "num": "9878432231"

            },

            "gongjj": {

                "status": "renewal",

                "type": "shanghaigongjijin",

                "base": 7000,

                "num": "866723323123"

            },

            "files": [

                {

                    "code": "idcard_a",

                    "file": "201704271822504442407.jpg"

                },

                {

                    "code": "idcard_b",

                    "file": "201704271822504442406.jpg"

                }

            ],

            "fields": [ ]

        }

    ]

}

         返回结果:

返回JSON示例:

{

    "rows": [

        {

            "idNum": "410882198901010000",

            "result": true

        },

        {

            "idNum": "FE65982365",

            "result": false,

            "errcode": "3005",

            "errmsg": "手机号码有误"

        }

    ]

}

参数说明:

返回数据格式

JSON

说明

rows为增员结果数组,参数中的人员信息数组一一对应。如果批量增员,部分人员数据有误,那么这部分人员增员失败;其余数据无误的人员则增员成功

参数

类型

必须

说明

idNum

String

增员的人员证件号码

result

Boolean

如果数据无误,增员成功,返回该参数,true

errcode

String

如果数据有误,才返回该错误代码。错误详细代码参考错误代码表

errmsg

String

如果数据有误,才返回该错误信息。错误详细代码参考错误代码表

2.4.2     减员

         基本信息:

接口地址

{user_code}/employees/{area_num}

支持格式

JSON

请求方式

http delete

编码

UTF-8

是否需要授权

说明

社保公积金停缴减员

注意事项

  1. 需按照城市政策,提供停缴人员的扩展字段和材料信息
  2. 量减员时,每次提交的人数不可大于10
  3. 员成功并不代表减员正式生效,必须提交订单并确认后才正式生效

         请求参数:

参数

类型

必填

说明

user_code

String

url占位会员账号,创建账号后获得

area_num

String

url占位。缴交城市行政区划代码

employees

JSON Array

RequestBody JSON需要停缴的人员列表

idNum

String

停缴人员证件号码

shebStop

Boolean

是否停缴社保如果为空默认为是

如果该人员有申报公积金,必须被停缴。如果缴纳的城市的【社保公积金申报规则】为1=必须同时申报社保公积金】时,则必须同时停缴社保和公积金;否则可单独停缴公积金,停缴社保。

files

Array

根据该城市政策,社保或公积金状态为stop=停缴时需要提交的材料。如果已提交过,不用再提交

code

String

材料编码。政策接口中返回的材料编码

file

String

材料文件在ftp的地址。必须符合接口中规定的文件格式;文件必须小于1M

fields

Array

根据该城市政策,社保或公积金停缴时需要提交的字段。如果已提交过,不用再提交

code

String

字段编码。政策接口中返回的字段编码

value

String

字段值。如果字段为数据字典,需要返回数据字典的value其它字段,需要按照字段的定义的类型提供数据

请求示例:

DELETE http(s)://API_URL/20170506396/employees

RequestBodyJSON参数data格式

{

    "employees": [

        {

            "idNum": "410882198901010000",

            "shebStop": true,

            "files": [

                {

                    "code": "lizhizhengming",

                    "file": "201704271822504442897.jpg"

                }

            ],

            "fields": [

                {

                    "code": "lizhi_shijian",

                    "file": "2016-10-20"

                }

            ]

        },

        {

            "idNum": "FE65982365",

            "shebStop": false

        }

    ]

}

         返回结果:

返回JSON示例:

{

    "rows": [

        {

            "idNum": "410882198901010000",

            "result": true

        },

        {

            "idNum": "FE65982365",

            "result": false,

            "errcode": "3002",

            "errmsg": "缺少必填项"

        }

    ]

}

参数说明:

返回数据格式

JSON

说明

rows为减员结果数组,参数中的人员信息数组一一对应。如果批量减员,部分人员数据有误,那么这部分人员减员失败;其余数据无误的人员则减员成功

参数

类型

必须

说明

idNum

String

减员的人员证件号码

result

Boolean

如果数据无误,减员成功,返回该参数,true

errcode

String

如果数据有误,才返回该错误代码。错误详细代码参考错误代码表

errmsg

String

如果数据有误,才返回该错误信息。错误详细代码参考错误代码表

2.4.3     查询

2.4.3.1    查询人员信息

         基本信息:

接口地址

{user_code}/employees/{id_num}

支持格式

JSON/Form Data/Query String Parameters

请求方式

http get

编码

UTF-8

是否需要授权

说明

根据人员证件号码查询人员基本信息和当前社保公积金缴交信息

注意事项

每个人员的缴交信息,每天最多可查询3,所以人员的缴交信息最好在本地保存

         请求参数:

参数

类型

必填

说明

user_code

String

url占位会员账号,创建账号后获得

id_num

String

url占位人员证件号码

请求示例:

GET http(s)://API_URL/20170506396/employees/410882198901110000

         返回结果:

返回JSON示例:

{

    "name": "王五",

    "idNum": "410882198901110000",

    "idType": "idcard",

    "phone": "13588888888",

"nationality": "CHN",

    "nationalityText": "中国",

    "gender": "male",

    "birthday": "1989-01-11",

    "city": "zhengzhou",

    "areaNum": "410100",

"cityName": "郑州",

"householdType": "1",

    "shebao": {

        "type": "zhengzhoushebao",

        "base": 5000,

        "status": "add",

        "beginMonth": "201601",

        "num": "687399999",

        "orderList": [

            {

                "status": "add",

                "type": "zhengzhoushebao",

                "base": 5000,

                "month": "201705",

                "order": true,

                "itemList": [

                    {

                        "code": "yanglao",

                        "name": "养老保险",

                        "base": 5000,

                        "org": 1000,

                        "emp": 400

                    },

                    {

                        "code": "yiliao",

                        "name": "医疗保险",

                        "base": 5000,

                        "org": 475,

                        "emp": 100

                    },

                    {

                        "code": "gongshang",

                        "name": "工伤保险",

                        "base": 5000,

                        "org": 16,

                        "emp": 0

                    },

                    {

                        "code": "shengyu",

                        "name": "生育保险",

                        "base": 5000,

                        "org": 50,

                        "emp": 0

                    },

                    {

                        "code": "shiye",

                        "name": "失业保险",

                        "base": 5000,

                        "org": 25,

                        "emp": 25

                    }

                ]

            },

            {

                "status": "keep",

                "type": "zhengzhoushebao",

                "base": 5000,

                "month": "201706",

                "order": true,

                "itemList": [

                    {

                        "code": "yanglao",

                        "name": "养老保险",

                        "base": 5000,

                        "org": 1000,

                        "emp": 400

                    },

                    {

                        "code": "yiliao",

                        "name": "医疗保险",

                        "base": 5000,

                        "org": 475,

                        "emp": 100

                    },

                    {

                        "code": "gongshang",

                        "name": "工伤保险",

                        "base": 5000,

                        "org": 16,

                        "emp": 0

                    },

                    {

                        "code": "shengyu",

                        "name": "生育保险",

                        "base": 5000,

                        "org": 50,

                        "emp": 0

                    },

                    {

                        "code": "shiye",

                        "name": "失业保险",

                        "base": 5000,

                        "org": 25,

                        "emp": 25

                    }

                ]

            }

        ]

    },

    "gongjj": {

        "type": "zhengzhougongjj",

        "base": 5000,

        "status": "add",

        "beginMonth": "201601",

        "num": "52663555555",

        "orderList": [

            {

                "status": "add",

                "type": "zhengzhougongjj",

                "base": 5000,

                "month": "201705",

                "order": true,

                "itemList": [

                    {

                        "code": "gongjijin",

                        "name": "公积金",

                        "base": 5000,

                        "org": 500,

                        "emp": 500

                    }

                ]

            },

            {

                "status": "keep",

                "type": "zhengzhougongjj",

                "base": 5000,

                "month": "201706",

                "order": true,

                "itemList": [

                    {

                        "code": "gongjijin",

                        "name": "公积金",

                        "base": 5000,

                        "org": 500,

                        "emp": 500

                    }

                ]

            }

        ]

    },

    "fields": [

        {

            "code": "education",

            "name": "学历",

            "value": "01",

            "text": "小学"

        },

        {

            "code": "residence_place",

            "name": "户籍地址",

            "value": "北京市朝阳区翠微路218",

            "text": "北京市朝阳区翠微路218"

        }

    ]

}

参数说明:

返回数据格式

JSON

说明

返回指定证件号码人员基本信息和当前社保公积金缴交信息

参数

类型

必须

说明

name

String

人员姓名

idNum

String

人员证件号码

idType

String

人员证件类型。

取值范围

idcard身份证

passport护照

phone

String

手机号码

nationality

String

国籍编码

nationalityText

String

国籍中文名称

gender

String

性别

取值范围

male:男

female:女

birthday

String

出生日期。格式为yyyy-MM-dd

city

String

该人员当前缴交城市编码

areaNum

String

该人员当前缴交城市行政区划代码

cityName

String

该人员当前缴交城市中文名称

householdType

String

该人员户籍性质