SBT-API

版本编号 修订内容 修订日期
V 4.2 发布 2018/10/24

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创建企业会员账号?
    选项:是、否

  2. 贵司平台是否可通过社保通API创建个人会员账号?
    选项:是、否

  3. 贵司平台生成的社保【订单付费方式】
    选项:
      a) 会员付款
      会员为订单付款。
      b) 平台付款
      平台为订单付款。贵平台需要预存费用在社保通账户中,生成并确认的订单将用贵平台在社保通的账户余额进行付款。当余额不足时,不会自动付款;当再次充值后,将按照订单提交先后顺序进行付款,如果余额不足以支付订单,则自动为下一个订单付款。如果是平台支付,系统将自动创建一个企业账号,贵司不能再创建其他的企业/个人账号,所有的数据都归属于该账号。
      c) 贵司平台的开票信息
      如果贵司的结算方式为平台结算,则需要提供开票信息。  
      选项: 
         1) 增值税普通发票
         需要提供:发票抬头、纳税人识别号、公司电话等信息
         2) 增值税专用发票
         需要提供:发票抬头、纳税人识别号、公司地址、公司电话、开户行、银行账号等信息;另外还需要提供以下材料:一般纳税人资质认定表、发票信息。上述2个材料请和营业执照一样提供图片并以附件的形式放在邮件中。

  4. 贵司平台与社保通平台【服务费结算方式】。 
    选项:
      a) 会员自主
       会员付社保通服务费。提交订单时,按照社保通默认的服务费规则(可查看服务费查询接口)计算服务费。各会员为订单付款时,同时已付服务费。
      b) 平台结算
       如果是平台结算,在协议中需规定如下信息:
       1. 每月服务费账单生成日期
       2. 正常汇缴每月次服务费单价(服务费为:单人单地区社保或公积金正常缴纳月数*该单价)
       3. 补缴每月次服务费单价(服务费为:单人单地区社保或公积金补缴月数*该单价)
    我司审核通过后,会将如下信息发送给接入平台
    一. 测试API平台的access_token
    二. 测试ftp服务器地址、账号和密码
    三. 测试API平台地址
      

    1.2 生产环境

      申请接入社保通API生产环境的平台,需提交如下信息到api@shebaochina.com邮箱:
         一、 邮件标题:{贵公司}申请接入社保通API生产环境
         二、 其它信息和申请接入测试环境一致
     
      我司审核通过后,会将如下信息发送给接入平台
        一、 生产环境API平台的access_token
        二、 生产环境ftp服务器地址、账号和密码
        三、 生产环境API平台地址

    2. 接口

  5.  测试环境API_URL为http://test.shebaotong.com/

  6.  生产环境API_URL为https://api.shebaotong.com/v4/

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

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

  9.  本接口为RESTful API。如果直接用浏览器调用接口,浏览器form表单只支持GET与POST请求,而http的delete、put等method并不支持,可提供参数如:_method=DELETE,但表单的method必须为POST。

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

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

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

2.1 基础信息接口

2.1.1 获取可缴纳城市

基本信息

接口地址 base/cities
支持格式 JSON/Form Data/Query String Parameters
请求方式 http get
编码 UTF-8
是否需要授权
说明 获取社保通平台通过API接口可代缴社保公积金的地区信息。
注意事项 有些信息每个缴费周期会发生变化,所以原则上需要接入平台,至少每天更新一次,建议在凌晨4点后更新。

请求参数

参数 类型 必填 说明

请求示例:

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

返回结果
返回json示例

  1. {
  2. "rows": [
  3. {
  4. "region": "华南",
  5. "pname": "广东",
  6. "prov": "guangdong",
  7. "city": "shenzhen",
  8. "areaNum": "440300",
  9. "name": "深圳",
  10. "closeDay": 15,
  11. "closeTime": 1492099199000,
  12. "rule": 1,
  13. "sbgjjRule": 1,
  14. "gjjBaseRule": 2,
  15. "gjjBaseRange": 1000,
  16. "timestamp": 1443159946000
  17. },
  18. {
  19. "region": "华东",
  20. "pname": "上海",
  21. "prov": "shanghaishi",
  22. "city": "shanghai",
  23. "areaNum": "310000",
  24. "name": "上海",
  25. "closeDay": 20,
  26. "closeTime": 1492703999000,
  27. "rule": 1,
  28. "sgRule": 1,
  29. "gjjBaseRule": 1,
  30. "gjjBaseRange": 0,
  31. "timestamp": 1443159946000
  32. }
  33. ]
  34. }

参数说明:

返回数据格式 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 公积金基数差异范围,保留两位有效数字。当gjjBaseRule值为3、4、5时有用。
timestamp Number 该城市政策最后更新时间戳,精确到秒

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

基本信息:

接口地址 base/{area_num}/types
支持格式 JSON/Form Data/Query String Parameters
请求方式 http get
编码 UTF-8
是否需要授权
说明 根据城市编码获取该城市社保和公积金缴费规则。
注意事项 政策可能不定期会发生变化,为了确保政策数据的一致性和准确性,建议每天凌晨4点后通过该接口更新本地政策数据。

请求参数

参数 类型 必填 说明
area_numString url占位。城市行政区划代码

请求示例:

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

返回结果:

返回JSON示例:

  1. {
  2. "shebao": [
  3. {
  4. "type": "shanghaiwuxian",
  5. "name": "上海五险",
  6. "desc": "说明",
  7. "addMonth": "201705",
  8. "keepMonth": "201705",
  9. "obMonth": "201701",
  10. "oeMonth": "201704",
  11. "maxBase": 16353,
  12. "minBase": 3271,
  13. "efDate": 1436544000000,
  14. "itemList": [
  15. {
  16. "code": "yanglao",
  17. "name": "养老保险",
  18. "payFreq": "month",
  19. "maxBase": 16353,
  20. "minBase": 3271,
  21. "empProp": 8,
  22. "orgProp": 21
  23. },
  24. {
  25. "code": "yiliao",
  26. "name": "医疗保险",
  27. "payFreq": "month",
  28. "maxBase": 16353,
  29. "minBase": 3271,
  30. "empProp": 8,
  31. "orgProp": 21
  32. },
  33. {
  34. "code": "canjijin",
  35. "name": "残疾人保障金",
  36. "payFreq": "year",
  37. "empFee": 20,
  38. "orgFee": 30
  39. }
  40. ],
  41. "files": [
  42. {
  43. "code": "idcard_a",
  44. "name": "身份证正面",
  45. "original": true,
  46. "suffix": "jpg,jpeg,png,bmp",
  47. "status": "newaccount,renewal"
  48. },
  49. {
  50. "code": "idcard_b",
  51. "name": "身份证背面",
  52. "original": true,
  53. "suffix": "jpg,jpeg,png,bmp",
  54. "status": "newaccount,renewal"
  55. },
  56. {
  57. "code": "lizhizhengminBaseg",
  58. "name": "离职证明",
  59. "original": false,
  60. "suffix": "doc,docx,pdf",
  61. "status": "stop"
  62. }
  63. ]
  64. }
  65. ],
  66. "gongjj": [
  67. {
  68. "type": "shanghaigongjijin",
  69. "name": "上海公积金",
  70. "desc": "说明",
  71. "addMonth": "201705",
  72. "keepMonth": "201705",
  73. "obMonth": "201701",
  74. "oeMonth": "201704",
  75. "maxBase": 16353,
  76. "minBase": 3271,
  77. "efDate": 1436544000000,
  78. "itemList": [
  79. {
  80. "code": "gongjinjin",
  81. "name": "公积金",
  82. "payFreq": "month",
  83. "maxBase": 16357,
  84. "minBase": 1820,
  85. "empProp": 7,
  86. "orgProp": 7
  87. }
  88. ],
  89. "files": [
  90. {
  91. "code": "idcard_a",
  92. "name": "身份证正面",
  93. "original": true,
  94. "suffix": "jpg,jpeg,png,bmp",
  95. "status": "newaccount,renewal"
  96. },
  97. {
  98. "code": "idcard_b",
  99. "name": "身份证背面",
  100. "original": true,
  101. "suffix": "jpg,jpeg,png,bmp",
  102. "status": "newaccount,renewal"
  103. }
  104. ]
  105. }
  106. ],
  107. "fields": [
  108. {
  109. "code": "education",
  110. "name": "学历",
  111. "type": "dd",
  112. "list": [
  113. {
  114. "value": "01",
  115. "text": "小学"
  116. },
  117. {
  118. "value": "02",
  119. "text": "初中"
  120. },
  121. {
  122. "value": "03",
  123. "text": "中专"
  124. },
  125. {
  126. "value": "04",
  127. "text": "高中"
  128. },
  129. {
  130. "value": "05",
  131. "text": "大专"
  132. },
  133. {
  134. "value": "06",
  135. "text": "本科"
  136. },
  137. {
  138. "value": "07",
  139. "text": "硕士"
  140. },
  141. {
  142. "value": "08",
  143. "text": "博士"
  144. }
  145. ],
  146. "status": "newaccount,renewal"
  147. },
  148. {
  149. "code": "residence_place",
  150. "name": "户籍地址",
  151. "type": "text",
  152. "length": 64,
  153. "status": "newaccount,renewal"
  154. },
  155. {
  156. "code": "grad_date",
  157. "name": "毕业日期",
  158. "type": "date",
  159. "status": "newaccount,renewal"
  160. },
  161. {
  162. "code": "begin_work",
  163. "name": "开始工作年月",
  164. "type": "yearMonth",
  165. "status": "newaccount,renewal"
  166. }
  167. ]
  168. }

参数说明:

返回数据格式 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位小数。如果该参数有值,则max、min、orgprop、empprop参数值为空
>> empFee Number 该项目个人固定缴费金额,保留2位小数。如果该参数有值,则max、min、orgprop、empprop参数值为空
> 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示例:

  1. {
  2. "rows": [
  3. {
  4. "code": "yanglao",
  5. "name": "养老保险",
  6. "base": 5000,
  7. "org": 400,
  8. "emp": 1000,
  9. "orgprop": 20,
  10. "empprop": 8,
  11. "sum": 1400
  12. },
  13. {
  14. "code": "yiliao",
  15. "name": "医疗保险",
  16. "base": 5000,
  17. "org": 100,
  18. "emp": 500,
  19. "orgprop": 9,
  20. "empprop": 2,
  21. "sum": 600
  22. }
  23. ]
  24. }

参数说明:

返回数据格式 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示例:

  1. {
  2. "rows": [
  3. {
  4. "code": "yanglao",
  5. "name": "养老保险",
  6. "base": 5000,
  7. "org": 400,
  8. "emp": 1000,
  9. "orgprop": 20,
  10. "empprop": 8,
  11. "odf": 20,
  12. "sum": 1420
  13. },
  14. {
  15. "code": "yiliao",
  16. "name": "医疗保险",
  17. "base": 5000,
  18. "org": 100,
  19. "emp": 500,
  20. "orgprop": 9,
  21. "empprop": 2,
  22. "odf": 20,
  23. "sum": 620
  24. }
  25. ]
  26. }

参数说明:

返回数据格式 JSON 说明 rows为计算结果集合
参数 类型 必须 说明
cede String 项目编码
name String 项目名称
base Number 基数,保留2位小数
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_codeString url占位。创建企业账号时接口返回的账号,修改账号时使用。只有账号未审核通过时才可修改。
dataJSON/Form Data 注册信息。(如果是修改,则需保证下列字段至少有一个不为空)
> nameString 企业公司名称,需真实且不能重名
> phoneString 手机号码,需真实,不可重复
> emailString 邮箱地址,需真实,不可重复
> contactString 联系人
> blString 营业执照图片文件在ftp中地址。文件格式可为:jpg,jpeg,bmp,png
>payerNum String 纳税人识别号,格式为长度18位。
>address String 注册地址

请求示例:

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

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

RequestBody中JSON参数data格式:

  1. {
  2. "name": "社宝信息科技有限公司",
  3. "phone": "13888888888",
  4. "email": "test@shebaotong.com",
  5. "contact": "张三",
  6. "bl": "201704271822504442408.jpg"
  7. "payerNum":"212332145665477654",
  8. "address":"上海市静安区恒丰路436号"
  9. }

返回结果:
返回JSON示例:

  1. {
  2. "userCode": "20170506396"
  3. }

参数说明:

返回数据格式 JSON 说明
参数 类型 必须 说明
userCode String 必须 会员账号

2.2.2 个人账号

基本信息

接口地址 创建账号:accounts/personal 
修改账号:accounts/personal/{user_code}
支持格式 JSON/Form Data
请求方式 创建账号:http post 
修改账号:http put
编码 UTF-8
是否需要授权
说明 创建社保通平台个人账号,如果创建成功,接口会返回会员账号,所有业务操作的接口都需要提供该账号。
注意事项 是否可创建个人账号,需在合作协议中进行约定 
如果【订单付款方式】是【平台付款】则不可调用该接口。

请求参数

参数 类型 必填 说明
user_codeString url占位。创建企业账号时接口返回的账号,修改账号时使用。只有账号未审核通过时才可修改。
dataJSON/Form Data 注册信息。(如果是修改,则需保证下列字段至少有一个不为空)
> nameString 注册个人会员的姓名
> idNumString注册个人会员的身份证号,不可重复
> phoneString 注册个人会员的手机号码,需真实,不可重复
> emailString 邮箱地址,需真实,不可重复
> idcardaString 身份证正面图片文件在ftp中地址。文件格式可为:jpg,jpeg,bmp,png
> idcardbString 身份证背面图片文件在ftp中地址。文件格式可为:jpg,jpeg,bmp,png

请求示例:

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

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

RequestBody中JSON参数data格式:

  1. {
  2. "name": "李四",
  3. "idNum": "410882198900000000",
  4. "phone": "13888888888",
  5. "email": "zhangsan@shebaotong.com",
  6. "idcarda": "201704271822504442408.jpg",
  7. "idcardb": "201704271822504442409.jpg"
  8. }

返回结果:
返回JSON示例:

  1. {
  2. "userCode": "20170506397"
  3. }

参数说明:

返回数据格式 JSON 说明  
参数 类型 必须 说明
userCode String 会员账号

2.2.3 刷新TOKEN

基本信息

接口地址 accounts/token
支持格式 JSON/Form Data
请求方式 http put
编码 UTF-8
是否需要授权
说明 如果接入平台认为access_token已存在安全隐患,可调用该接口获取最新token,原token立即失效
注意事项 最大刷新频率为1分钟每次

请求参数

参数 类型 必填 说明
 

请求示例:

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

返回结果:

返回JSON示例:

  1. {
  2. "accessToken": "1ACAECR7BB04E68BC39D9659C0516EC0"
  3. }

参数说明:

返回数据格式 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示例:

  1. {
  2. "result": 500000.65
  3. }

参数说明:

返回数据格式 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示例:

企业会员

  1. {
  2. "rows": [
  3. {
  4. "areaNum": "310000",
  5. "price": 30
  6. },
  7. {
  8. "areaNum": "540000",
  9. "price": 80
  10. }
  11. ]
  12. }

个人会员

  1. {
  2. "rows": [
  3. {
  4. "months": 1,
  5. "price": 120
  6. },
  7. {
  8. "months": 3,
  9. "price": 300
  10. },
  11. {
  12. "months": 6,
  13. "price": 500
  14. },
  15. {
  16. "months": 12,
  17. "price": 1000
  18. }
  19. ]
  20. }

参数说明:

返回数据格式 JSON 说明 rows为计算结果集合
参数 类型 必须 说明
如果是企业账号返回的参数:
areaNum String 企业会员已报增社保公积金的城市行政区划代码。计算服务费时,将按照服务费单价乘以服务次数进行计算。某一人缴纳某一月的社保或公积金将算作一次。
price Number 城市服务费单价
如果是个人账号返回的参数:
months Number 个人会员服务费套餐,一次订单缴纳的社保或公积金的月份。补缴社保公积金将按照单月服务费价格进行计算;正常汇缴将按照缴纳的月份对应的价格乘以人数计算服务费。 
取值范围 
1:单月 
3:季度。缴纳3个月 
6:半年。缴纳6个月 
12:一年。缴纳12个月
price 服务费价格

2.3.3 服务费账单查询

基本信息

接口地址 accounts/bill/{month}
支持格式 JSON/Form Data/Query String Parameters
请求方式 http get
编码 UTF-8
是否需要授权
说明 获取服务费账单
注意事项 1. 只有在协议中规定【订单付费方式】为【平台付款】的接入平台,才可调用该接口  
2. 服务费账单每月出具一次,按照协议中规定的【服务费账单结算日】进行出具 
3、服务费账单中将结转补收补退的费用,,订单中将不再有补收补退费用

请求参数

参数 类型 必填 说明
month String url占位。服务费账单月份,该参数不填则默认查询当月服务费账单

请求示例:

GET http(s)://API_URL/accounts/bill/201810

返回结果:

返回JSON示例:

  1. {
  2. "orderNum": "408517020210561",
  3. "orderAmount": 3006,
  4. "orderFee": 2761,
  5. "serviceFee": 30,
  6. "refundFee": 10,
  7. "paymentFee": 200,
  8. "addFee": 5,
  9. "handlingFee": 0,
  10. "peopleTotal": 1,
  11. "serviceCount": 1,
  12. "createTime": 1493135999000,
  13. "lastPayTime": 1493481599000,
  14. "orderStatus": 3,
  15. "paidTime": 1493266831000,
  16. "paymentList": [
  17. {
  18. "idNum": "410882198901010000",
  19. "item": "gongjijin",
  20. "type": "shanghaigongjijin",
  21. "month": "201701",
  22. "emp": 100,
  23. "org": 100,
  24. "serviceFee": 0,
  25. "desc": "差异补收",
  26. "itemList": [
  27. {
  28. "code": "gongjijin",
  29. "orgDiff": 100,
  30. "empDiff": 100
  31. }
  32. ]
  33. }
  34. ],
  35. "refundList": [
  36. {
  37. "idNum": "410882198901010000",
  38. "item": "shebao",
  39. "type": "shanghaishebao",
  40. "month": "201701",
  41. "emp": 5,
  42. "org": 5,
  43. "serviceFee": 0,
  44. "desc": "差异补退",
  45. "itemList": [
  46. {
  47. "code": "yiliao",
  48. "orgDiff": 5,
  49. "empDiff": 5
  50. }
  51. ]
  52. }
  53. ]
  54. }

参数说明:

返回数据格式 JSON 说明 rows为计算结果集合
参数 类型 必须 说明`
orderNum String 账单编号
orderAmount Number 账单总额。账单订单服务费+正常账单费用-结转补退费用+结转补收费用+手续费
serviceFee 账单服务费。账单服务费计算规则,参考服务费查询接口
orderFee 正常费用合计
refundFee
paymentFee 结转补收费用合计
addFee 补充费用合计
handlingFee支付手续费
peopleTotal 账单人数
serviceCount 服务次数
createTime 账单创建时间
lastPayTime 账单最后付款时间。如果账单已付款或取消了最后付款期限,则为空
orderStatus String 账单状态。
取值范围
1:未确认
2:已确认。
3:已付款。
0:已关闭。
paidTimeNumber 账单支付时间。当账单未支付时为空
paymentList Array 账单结转的补收明细
refundList 账单结转的补退明细
>iidNum String 结转补收或补退人员证件号码
>iitem 结转补收或补退类型。
取值范围
shebao:社保
gongjijin:公积金
once:一次性费用
>itype 结转补收或补退人员缴纳政策编码
>imonth 导致出现补收补退差异的费用月份
>iemp Number 企业部分补收或补退总额
>iorg 个人部分补收或补退总额
>iserviceFee 补收或补退服务费
>desc String 补收或补退原因说明
>itemList Array 补收或补退项目明细
>> code String 补收或补退项目明细编码
>> orgDiffNumber 补收或补退项目企业部分费用差异
>> empDiff 补收或补退项目企业个人费用差异

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 如果不为空则修改。只有公积金|公积金状态为且仅为【add=新增】且未提交订单,才可修改。
nationality String 如果不为空且该人员证件类型为【passport=护照】,则修改
gender String 如果不为空且该人员证件类型为【passport=护照】,则修改
birthday String 如果不为空且该人员证件类型为【passport=护照】,则修改
shebao Object 如果不为空,则为修改社保缴纳。只有社保状态为【add=新增】且未提交订单,才可修改。
gongjj Object 如果不为空,且之前有提交公积金信息则为修改公积金缴纳,否则为新缴纳公积金。只有公积金状态为【add=新增】且未提交订单,才可修改。
> beginMonth String 如果社保、公积金已提交订单,再提交新的社保或公积金缴纳信息,是不被允许的。除非该人员社保或公积金办理失败,可通过提交beginMonth参数,来修改参保起始月(默认情况下,如果不修改参保起始月,社保通将一直对办理失败的进行补缴),修改参保起始月后,系统可将对办理失败月份的费用进行退款。
files Array 材料数组中,如果已存在对应的材料,则为覆盖之前提交的材料,只有材料状态为【0=审核失败】或【-1=未审核】的材料才可覆盖,如果已审核通过,则系统不会覆盖,也不会抛出错误;如果不存在,则为新提交的材料。
fields Array 字段数组中,如果已存在对应字段,则为修改原字段值;否则则为新增加的字段。只有公积金|公积金状态为且仅为【add=新增】且未提交订单,才可修改。

请求示例:

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

RequestBody中JSON参数data格式:

  1. {
  2. "employees": [
  3. {
  4. "name": "张三",
  5. "idNum": "410882198901010000",
  6. "idType": "idcard",
  7. "phone": "13588888888",
  8. "householdType": "1",
  9. "shebao": {
  10. "status": "newaccount",
  11. "type": "shanghaishebao",
  12. "base": 5000.05,
  13. "beginMonth": "201701"
  14. },
  15. "gongjj": {
  16. "status": "newaccount",
  17. "type": "shanghaigongjijin",
  18. "base": 5000.05,
  19. "beginMonth": "201703"
  20. },
  21. "files": [
  22. {
  23. "code": "idcard_a",
  24. "file": "201704271822504442408.jpg"
  25. },
  26. {
  27. "code": "idcard_b",
  28. "file": "201704271822504442409.jpg"
  29. },
  30. {
  31. "code": "laodonghetong",
  32. "file": "201704271822504442410.docx"
  33. }
  34. ],
  35. "fields": [
  36. {
  37. "code": "education",
  38. "value": "01"
  39. },
  40. {
  41. "code": "residence_place",
  42. "value": "北京市朝阳区翠微路218号"
  43. },
  44. {
  45. "code": "grad_date",
  46. "value": "2001-06-30"
  47. },
  48. {
  49. "code": "begin_work",
  50. "value": "200110"
  51. }
  52. ]
  53. },
  54. {
  55. "name": "Si Li",
  56. "idNum": "FE65982365",
  57. "idType": "passport",
  58. "nationality": "USA",
  59. "phone": "13588888889",
  60. "gender": "male",
  61. "birthday": "1986-10-01",
  62. "householdType": "2",
  63. "shebao": {
  64. "status": "renewal",
  65. "type": "shanghaishebao2",
  66. "base": 7000,
  67. "num": "9878432231"
  68. },
  69. "gongjj": {
  70. "status": "renewal",
  71. "type": "shanghaigongjijin",
  72. "base": 7000,
  73. "num": "866723323123"
  74. },
  75. "files": [
  76. {
  77. "code": "idcard_a",
  78. "file": "201704271822504442407.jpg"
  79. },
  80. {
  81. "code": "idcard_b",
  82. "file": "201704271822504442406.jpg"
  83. }
  84. ],
  85. "fields": [ ]
  86. }
  87. ]
  88. }

返回结果:
返回JSON示例:

  1. {
  2. "rows": [
  3. {
  4. "idNum": "410882198901010000",
  5. "result": true
  6. },
  7. {
  8. "idNum": "FE65982365",
  9. "result": false,
  10. "errcode": "3005",
  11. "errmsg": "手机号码有误"
  12. }
  13. ]
  14. }

参数说明:

返回数据格式 JSON 说明 rows为增员结果数组,和参数中的人员信息数组一一对应。如果批量增员,有部分人员数据有误,那么这部分人员增员失败;其余数据无误的人员则增员成功
参数 类型 必须 说明
idNum String 增员的人员证件号码
result String 如果数据无误,增员成功,才返回该参数,值为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
RequestBody中JSON参数data格式:

  1. {
  2. "employees": [
  3. {
  4. "idNum": "410882198901010000",
  5. "shebStop": true,
  6. "files": [
  7. {
  8. "code": "lizhizhengming",
  9. "file": "201704271822504442897.jpg"
  10. }
  11. ],
  12. "fields": [
  13. {
  14. "code": "lizhi_shijian",
  15. "file": "2016-10-20"
  16. }
  17. ]
  18. },
  19. {
  20. "idNum": "FE65982365",
  21. "shebStop": false
  22. }
  23. ]
  24. }

返回结果:
返回JSON示例:

  1. {
  2. "rows": [
  3. {
  4. "idNum": "410882198901010000",
  5. "result": true
  6. },
  7. {
  8. "idNum": "FE65982365",
  9. "result": false,
  10. "errcode": "3002",
  11. "errmsg": "缺少必填项"
  12. }
  13. ]
  14. }

参数说明:

返回数据格式 JSON 说明 rows为减员结果数组,和参数中的人员信息数组一一对应。如果批量减员,有部分人员数据有误,那么这部分人员减员失败;其余数据无误的人员则减员成功
参数 类型 必须 说明
idNum String 减员的人员证件号码
result Boolean 如果数据无误,减员成功,才返回该参数,值为true
errcode String 如果数据有误,才返回该错误代码。错误详细代码参考错误代码表
errmsg String 如果数据有误,才返回该错误信息。错误详细代码参考错误代码表

2.4.3 取消减员

基本信息:

接口地址 {user_code}/employees/undo
支持格式 JSON
请求方式 http put
编码 UTF-8
是否需要授权
说明 取消社保公积金停缴减员
注意事项 1. 已经在缴的人员调用停缴接口后,且还未提交订单时,可调用该接口取消停缴(新增的人员,可重新报增,无需调用该接口)。

请求参数:

参数 类型 必填 说明
user_code String url占位。会员账号,创建账号后获得
idNum String 取消停缴的人员证件号码

请求示例:
PUT http(s)://API_URL/20170506396/employees/undo?idNum=410882198901010000
返回结果:
返回JSON示例:

  1. {
  2. "result": true
  3. }

参数说明:

返回数据格式 JSON 说明
参数 类型 必须 说明
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示例:

  1. {
  2. "name": "王五",
  3. "idNum": "410882198901110000",
  4. "idType": "idcard",
  5. "phone": "13588888888",
  6. "nationality": "CHN",
  7. "nationalityText": "中国",
  8. "gender": "male",
  9. "birthday": "1989-01-11",
  10. "city": "zhengzhou",
  11. "areaNum": "410100",
  12. "cityName": "郑州",
  13. "householdType": "1",
  14. "shebao": {
  15. "type": "zhengzhoushebao",
  16. "base": 5000,
  17. "status": "add",
  18. "beginMonth": "201601",
  19. "num": "687399999",
  20. "orderList": [
  21. {
  22. "status": "add",
  23. "type": "zhengzhoushebao",
  24. "base": 5000,
  25. "month": "201705",
  26. "order": true,
  27. "itemList": [
  28. {
  29. "code": "yanglao",
  30. "name": "养老保险",
  31. "base": 5000,
  32. "org": 1000,
  33. "emp": 400
  34. },
  35. {
  36. "code": "yiliao",
  37. "name": "医疗保险",
  38. "base": 5000,
  39. "org": 475,
  40. "emp": 100
  41. },
  42. {
  43. "code": "gongshang",
  44. "name": "工伤保险",
  45. "base": 5000,
  46. "org": 16,
  47. "emp": 0
  48. },
  49. {
  50. "code": "shengyu",
  51. "name": "生育保险",
  52. "base": 5000,
  53. "org": 50,
  54. "emp": 0
  55. },
  56. {
  57. "code": "shiye",
  58. "name": "失业保险",
  59. "base": 5000,
  60. "org": 25,
  61. "emp": 25
  62. }
  63. ]
  64. },
  65. {
  66. "status": "keep",
  67. "type": "zhengzhoushebao",
  68. "base": 5000,
  69. "month": "201706",
  70. "order": true,
  71. "itemList": [
  72. {
  73. "code": "yanglao",
  74. "name": "养老保险",
  75. "base": 5000,
  76. "org": 1000,
  77. "emp": 400
  78. },
  79. {
  80. "code": "yiliao",
  81. "name": "医疗保险",
  82. "base": 5000,
  83. "org": 475,
  84. "emp": 100
  85. },
  86. {
  87. "code": "gongshang",
  88. "name": "工伤保险",
  89. "base": 5000,
  90. "org": 16,
  91. "emp": 0
  92. },
  93. {
  94. "code": "shengyu",
  95. "name": "生育保险",
  96. "base": 5000,
  97. "org": 50,
  98. "emp": 0
  99. },
  100. {
  101. "code": "shiye",
  102. "name": "失业保险",
  103. "base": 5000,
  104. "org": 25,
  105. "emp": 25
  106. }
  107. ]
  108. }
  109. ]
  110. },
  111. "gongjj": {
  112. "type": "zhengzhougongjj",
  113. "base": 5000,
  114. "status": "add",
  115. "beginMonth": "201601",
  116. "num": "52663555555",
  117. "orderList": [
  118. {
  119. "status": "add",
  120. "type": "zhengzhougongjj",
  121. "base": 5000,
  122. "month": "201705",
  123. "order": true,
  124. "itemList": [
  125. {
  126. "code": "gongjijin",
  127. "name": "公积金",
  128. "base": 5000,
  129. "org": 500,
  130. "emp": 500
  131. }
  132. ]
  133. },
  134. {
  135. "status": "keep",
  136. "type": "zhengzhougongjj",
  137. "base": 5000,
  138. "month": "201706",
  139. "order": true,
  140. "itemList": [
  141. {
  142. "code": "gongjijin",
  143. "name": "公积金",
  144. "base": 5000,
  145. "org": 500,
  146. "emp": 500
  147. }
  148. ]
  149. }
  150. ]
  151. },
  152. "fields": [
  153. {
  154. "code": "education",
  155. "name": "学历",
  156. "value": "01",
  157. "text": "小学"
  158. },
  159. {
  160. "code": "residence_place",
  161. "name": "户籍地址",
  162. "value": "北京市朝阳区翠微路218号",
  163. "text": "北京市朝阳区翠微路218号"
  164. }
  165. ]
  166. }

参数说明:

返回数据格式 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 该人员户籍性质
shebao Object 该人员社保缴交情况
gongjj Object 该人员公积金缴交情况。如果未申报公积金,则为空
> type String 当前缴交的社保或公积金政策
> base Number 当前缴交的社保或公积金基数
> num Number 当前缴交的社保或公积金编号。如果申报时是【renewal=续保】,则通过增员接口提供该数据;否则办理成功后由社保通回填。
> status String 社保或公积金当前缴纳状态。
取值范围
add:新增
keep:在缴
stop:停缴
> beginMonth String 社保或公积金开始缴费月份
> orderList Array 社保或公积金当前周期月订单。如果已停缴成功,则为空
>> status String 社保或公积金订单缴纳状态。
取值范围
add:新增
overdue:补缴
keep:在缴
stop:停缴
>> type String 社保或公积金订单缴纳政策
>> base Number 社保或公积金订单缴纳基数
>> month String 社保或公积金订单缴费月份
>> order Boolean 是否已生成订单
>>itemList Array 社保或公积金缴纳项目明细。如果当前status为stop,则无该项信息
>>> code String 社保或公积金项目明细编码
>>> name String 社保或公积金项目明细名称
>>> base Number 社保或公积金项目基数
>>> org Number 社保或公积金项目企业部分费用
>>> emp Number 社保或公积金项目个人部分费用
>>> odf Number 滞纳金。如果是补缴,则可能产生滞纳金
fields Array 该人员的扩展字段信息
> code String 扩展字段编码
> name String 扩展字段中文名称
> value String 扩展字段值
> text String 扩展字段内容。如果是非数据字典字段,则该值和value一致

2.4.3.2 查询材料信息

基本信息:

接口地址 {user_code}/employees/{id_num}/files
支持格式 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/files

返回结果:

返回JSON示例:

  1. {
  2. "rows": [
  3. {
  4. "code": "idcard_a",
  5. "name": "身份证正面",
  6. "status": 0,
  7. "comment": "不清晰"
  8. },
  9. {
  10. "code": "idcard_b",
  11. "name": "身份证背面",
  12. "status": 0,
  13. "comment": "不清晰"
  14. },
  15. {
  16. "code": "laodonghetong",
  17. "name": "劳动合同",
  18. "status": 1
  19. }
  20. ]
  21. }

参数说明:

返回数据格式 JSON 说明 rows为返回指定证件号人员的材料信息数组。如果无材料,则长度为0
参数 类型 必须 说明
code String 文件编码
name String 是 |文件名称
status Number 文件当前状态。
取值范围
1:审核通过
0:审核未通过
-1:待审核
comment String 文件审核说明信息

2.5 订单接口

2.5.1 订单提交

基本信息:

接口地址 {user_code}/orders/{area_num}
支持格式 JSON
请求方式 http post
编码 UTF-8
是否需要授权
说明 根据城市提交订单
注意事项 1. 当指定某些人员生成订单时,可提供这些人员的证件号码列表,如果不提供或为空,则为生成该城市所有人员订单。
2. 如果过了城市截止日,之前续缴的人员未提交任何订单,则社保通平台会将其自动停缴。
3. 订单必须在最后付款时间前付款,否则订单将会被关闭
4. 如果【订单付款方式】是【平台付款】,则订单不自动结转补收补退,补收补退将在服务费账单中进行结转(依然可以通过“查询订单补收/补退记录”接口进行查询相应的记录),各接入平台可以自行按照补收/补退接口查询到的记录进行处理。

请求参数:

参数 类型 必填 说明
user_code String url占位。会员账号,创建账号后获得
area_num String url占位。城市行政区划代码
data JSON Object 当指定某些人员生成订单时,可提供这些人员的证件号码列表,如果不提供或为空,则为生成该城市所有人员订单
> idNum Array 提交订单的人员证件号码数组
> months Number 提交订单月数。只有个人会员提交订单时,才可提供该参数,和个人会员服务费对应。
取值范围
1:提交一个月订单。如果是一月可不用传递该参数。
3:提交3个月订单,即按季度。
6:提交6个月订单,即按半年。
12:提交12个月订单,即按年。

请求示例:

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

RequestBody中JSON参数data格式:

  1. {
  2. "idNum": [
  3. "410882198901010000",
  4. "FE65982365"
  5. ],
  6. "months": 3
  7. }

返回结果:
返回JSON示例:

  1. {
  2. "orderNum": "408517020210561",
  3. "orderAmount": 8798,
  4. "orderFee": 8283,
  5. "serviceFee": 300,
  6. "refundFee": 10,
  7. "paymentFee": 200,
  8. "addFee": 5,
  9. "handlingFee": 0,
  10. "peopleTotal": 1,
  11. "serviceCount": 3,
  12. "createTime": 1493135999000,
  13. "lastPayTime": 1493481599000,
  14. "orderStatus": 1
  15. }

参数说明:

返回数据格式 JSON Object 说明 返回订单基本信息
参数 类型 必须 说明
orderNum String 订单编号
orderAmount String 订单总额。等于订单服务费+正常订单费用-结转补退费用+结转补收费用+补充费用+手续费
serviceFee Number 订单服务费。订单服务费计算规则,参考服务费查询接口。如果【服务费结算方式】为【平台结算】,则为0。
orderFee Number 政策订单费用合计
refundFee Number 结转补退费用合计
paymentFee Number 结转补收费用合计
addFee Number 补充费用合计
handlingFee Number 支付手续费
peopleTotal Number 订单人数(只包括正常订单人数)
serviceCount Number 服务次数(只包括正常订单次数)
createTime Number 订单创建时间
lastPayTime Number 订单最后付款时间。如果订单已付款或取消了最后付款期限,则为空
orderStatus String 订单状态。
取值范围
1:未确认。只提交了订单,但未调用确认接口进行确认
2:已确认。调用了确认订单接口,进行确认,确认后不可再取消
3:已付款。社保通已收到该订单款项,订单已付款
0:已关闭。如果订单过期未付款,则订单将被关闭,已关闭的订单是无效订单,社保通不会进行相关业务办理,且不可查看具体订单明细

2.5.2 订单确认

基本信息:

接口地址 {user_code}/orders/{order_num}
支持格式 SON/Form Data
请求方式 http put
编码 UTF-8
是否需要授权
说明 确认订单
注意事项 1. 只有订单状态为【1=未确认】的订单可确认;
2. 订单确认后,订单状态变为【2=已确认】,不可再取消;
3. 如果与贵司的协议中约定【订单付费方式】为【平台付款】,则系统将尝试用贵司在社保通的账户余额为订单付款。

请求参数:

参数 类型 必填 说明
user_code String url占位。会员账号,创建账号后获得
order_num String url占位。订单编号

请求示例:
PUT http(s)://API_URL/20170506396/orders/408517020210561
返回结果:
返回JSON示例:
【订单付费方式】为【平台付款】:

  1. {
  2. "balance": 1000,
  3. "paid": true
  4. }

【订单付费方式】为【会员自主】:

  1. {
  2. "bankName": "招商银行",
  3. "openingBank": "招商银行上海张杨路支行",
  4. "accountName": "社宝信息科技(上海)有限公司",
  5. "accountNumber": "5128888888888888",
  6. "paymentComent": "请将订单号408517020210561填写在付款说明中"
  7. }

参数说明:

返回数据格式 JSON Object 说明  
参数 类型 必须 说明
如果【订单付费方式】为【平台付款】,系统自动用贵司账户余额付款时,返回参数
balance Number 当前账户余额
paid Boolean 是否已支付。
ture:已支付;
false:未支付
如果【订单付费方式】为【会员自主】,返回付款账户信息
bankName String 账户银行
openingBank 开户支行
accountName 户名
accountNumber 账号
paymentComent 线下付款注意事项,需要显示给用户

2.5.3 订单取消

基本信息:

接口地址 {user_code}/orders/{order_num}
支持格式 JSON/Form Data
请求方式 http delete
编码 UTF-8
是否需要授权
说明 取消订单
注意事项 只有订单状态为【1=未确认】的订单才可取消,取消后的订单不可再查询到

请求参数:

参数 类型 必填 说明
user_code String url占位。会员账号,创建账号后获得
order_num String url占位。订单编号

请求示例:
DELETE http(s)://API_URL/20170506396/orders/408517020210561
返回结果:
返回JSON示例:

  1. {
  2. "result": true
  3. }

参数说明:

返回数据格式 JSON Object 说明  
参数 类型 必须 说明
result Boolean 如果取消成功,返回true

2.5.4 提交付款凭证

基本信息:

接口地址 {user_code}/orders/{order_num}/pro
支持格式 JSON/Form Data
请求方式 http post
编码 UTF-8
是否需要授权
说明 当订单线下转账付款道指定账户后,可上传相关付款凭证,方便进行核销
注意事项 只有订单状态为【2=已确认】的订单才可提交付款凭证

请求参数:

参数 类型 必填 说明
user_code String url占位。会员账号,创建账号后获得
order_num String url占位。订单编号
data JSON Object  
> file String 付款凭证图片文件在ftp中的地址。文件格式为:jpg,jpeg,bmp,png。文件必须小于1M

请求示例:
POST http(s)://API_URL/20170506396/orders/408517020210561/pro
RequestBody中JSON参数data格式:

  1. {
  2. "file": "201704271822504042111.jpg"
  3. }

返回结果:
返回JSON示例:

  1. {
  2. "result": true
  3. }

参数说明:

返回数据格式 JSON Object 说明  
参数 类型 必须 说明
result Boolean 提交成功

2.5.5 订单查询

2.5.5.1 查询订单记录

基本信息:

接口地址 {user_code}/orders
支持格式 JSON/Form Data/Query String Parameters
请求方式 http get
编码 UTF-8
是否需要授权
说明 查询订单记录
注意事项 只可查询距离订单创建时间31天(包括)内的订单。每个账号每天最多可查询3次。

请求参数:

参数 类型 必填 说明
user_code String url占位。会员账号,创建账号后获得
date String “yyyy-MM-dd”格式的订单创建日期,查询当天提交的订单(如果为空,默认为当天)。日期必须小于等于系统当前日期,大于等于系统当前日期-31天。
status Number 订单状态。(如果为空,默认查询【未确认】的订单)
1:未确认
2:已确认
3:已付款
0:已关闭

请求示例:
GET http(s)://API_URL/USER_CODE/orders?date=2017-05-06&status=3

返回结果:
返回JSON示例:

  1. {
  2. "rows": [
  3. {
  4. "orderNum": "408517020210561",
  5. "orderAmount": 3006,
  6. "orderFee": 2761,
  7. "serviceFee": 30,
  8. "refundFee": 10,
  9. "paymentFee": 200,
  10. "addFee": 5,
  11. "handlingFee": 0,
  12. "peopleTotal": 1,
  13. "serviceCount": 1,
  14. "createTime": 1493135999000,
  15. "lastPayTime": 1493481599000,
  16. "orderStatus": 3,
  17. "paidTime": 1493266831000
  18. },
  19. {
  20. "orderNum": "349612021210551",
  21. "orderAmount": 80230,
  22. "orderFee": 81000,
  23. "serviceFee": 30,
  24. "refundFee": 1000,
  25. "paymentFee": 200,
  26. "addFee": 0,
  27. "handlingFee": 0,
  28. "peopleTotal": 10,
  29. "serviceCount": 14,
  30. "createTime": 1493135999000,
  31. "lastPayTime": 1493481599000,
  32. "orderStatus": 3,
  33. "paidTime": 1493266831000
  34. }
  35. ]
  36. }

参数说明:

返回数据格式 JSON 说明 rows为返回订单基本信息数组,按照创建时间倒序。如果为空,数组长度为0。
参数 类型 必须 说明
orderNum String 订单编号
orderAmount Number 订单总额。等于订单服务费+正常订单费用-结转补退费用+结转补收费用+补充费用+手续费
serviceFee Number 订单服务费。订单服务费计算规则,参考服务费查询接口
orderFee Number 政策订单费用合计
refundFee Number 结转补退费用合计
paymentFee Number 结转补收费用合计
addFee Number 补充费用合计
handlingFee Number 支付手续费
peopleTotal Number 订单人数(只包括正常订单)
serviceCount Number 服务次数(只包括正常订单)
createTime Number 订单创建时间
lastPayTime Number 订单最后付款时间。如果订单已付款或取消了最后付款期限,则为空
orderStatus String 订单状态。
取值范围
1:未确认。只提交了订单,但未调用确认接口进行确认
2:已确认。调用了确认订单接口,进行确认,确认后不可再取消
3:已付款。社保通已收到该订单款项,订单已付款
0:已关闭。如果订单过期未付款,则订单将被关闭,已关闭的订单是无效订单,社保通不会进行相关业务办理,且不可查看具体订单明细
paidTime Number 订单支付时间。当订单未支付时为空

2.5.5.2 查询单个订单详情

基本信息:

接口地址 {user_code}/orders/{order_num}
支持格式 JSON/Form Data/Query String Parameters
请求方式 http get
编码 UTF-8
是否需要授权
说明 根据订单编号查询订单详情
注意事项 只可查询距离订单创建时间31天(包括)内的订单,订单状态为【0=已关闭】的订单只有订单基本信息。同一个订单每天最多可查询3次

请求参数:

参数 类型 必填 说明
user_code String url占位。会员账号,创建账号后获得
order_num String url占位。订单编号

请求示例:
GET http(s)://API_URL/20170506396/orders/408517020210561

返回结果:
返回JSON示例:

  1. {
  2. "orderNum": "408517020210561",
  3. "orderAmount": 3006,
  4. "orderFee": 2761,
  5. "serviceFee": 30,
  6. "refundFee": 10,
  7. "paymentFee": 200,
  8. "addFee": 5,
  9. "handlingFee": 0,
  10. "peopleTotal": 1,
  11. "serviceCount": 1,
  12. "createTime": 1493135999000,
  13. "lastPayTime": 1493481599000,
  14. "orderStatus": 3,
  15. "paidTime": 1493266831000,
  16. "orderList": [
  17. {
  18. "idNum": "410882198901010000",
  19. "item": "shebao",
  20. "type": "shanghaishebao",
  21. "base": 5000,
  22. "month": "201701",
  23. "status": "add",
  24. "itemList": [
  25. {
  26. "code": "yanglao",
  27. "base": 5000,
  28. "org": 1000,
  29. "emp": 400
  30. },
  31. {
  32. "code": "yiliao",
  33. "base": 5000,
  34. "org": 475,
  35. "emp": 100
  36. },
  37. {
  38. "code": "gongshang",
  39. "base": 5000,
  40. "org": 16,
  41. "emp": 0
  42. },
  43. {
  44. "code": "shengyu",
  45. "base": 5000,
  46. "org": 50,
  47. "emp": 0
  48. },
  49. {
  50. "code": "shiye",
  51. "base": 5000,
  52. "org": 25,
  53. "emp": 25
  54. }
  55. ]
  56. },
  57. {
  58. "idNum": "410882198901010000",
  59. "item": "gongjijin",
  60. "type": "shanghaigongjijin",
  61. "base": 5000,
  62. "month": "201701",
  63. "status": "overdue",
  64. "itemList": [
  65. {
  66. "code": "gongjijin",
  67. "base": 5000,
  68. "org": 350,
  69. "emp": 350,
  70. "odf": 10
  71. }
  72. ]
  73. }
  74. ],
  75. "paymentList": [
  76. {
  77. "idNum": "410882198901010000",
  78. "item": "gongjijin",
  79. "type": "shanghaigongjijin",
  80. "month": "201701",
  81. "emp": 100,
  82. "org": 100,
  83. "serviceFee": 0,
  84. "desc": "差异补收",
  85. "itemList": [
  86. {
  87. "code": "gongjijin",
  88. "orgDiff": 100,
  89. "empDiff": 100
  90. }
  91. ]
  92. }
  93. ],
  94. "refundList": [
  95. {
  96. "idNum": "410882198901010000",
  97. "item": "shebao",
  98. "type": "shanghaishebao",
  99. "month": "201701",
  100. "emp": 5,
  101. "org": 5,
  102. "serviceFee": 0,
  103. "desc": "差异补退",
  104. "itemList": [
  105. {
  106. "code": "yiliao",
  107. "orgDiff": 5,
  108. "empDiff": 5
  109. }
  110. ]
  111. }
  112. ],
  113. "addFeeList": [
  114. {
  115. "fee": 5,
  116. "desc": "快递费"
  117. }
  118. ]
  119. }

参数说明:

返回数据格式 JSON Object 说明 返回订单全部信息
参数 类型 必须 说明
orderNum String 订单编号
orderAmount Number 订单总额。等于订单服务费+正常订单费用-结转补退费用+结转补收费用+补充费用+手续费
serviceFee Number 订单服务费。订单服务费计算规则,参考服务费查询接口
orderFee Number 政策订单费用合计
refundFee Number 结转补退费用合计
paymentFee Number 结转补收费用合计
addFee Number 补充费用合计
handlingFee Number 支付手续费
peopleTotal Number 订单人数(只包括正常订单)
serviceCount Number 服务次数(只包括正常订单)
createTime Number 订单创建时间
lastPayTime Number 订单最后付款时间。如果订单已付款或取消了最后付款期限,则为空
orderStatus String 订单状态。
取值范围
1:未确认。只提交了订单,但未调用确认接口进行确认
2:已确认。调用了确认订单接口,进行确认,确认后不可再取消
3:已付款。社保通已收到该订单款项,订单已付款
0:已关闭。如果订单过期未付款,则订单将被关闭,已关闭的订单是无效订单,社保通不会进行相关业务办理,且不可查看具体订单明细
paidTime Number 订单支付时间。当订单未支付时为空
orderList Array 正常订单明细。如果订单已关闭或无正常订单信息,则为空
> idNum String 人员证件号码
> item String 缴纳的项目。
取值范围
shebao:社保;
gongjijin:公积金
> type String 社保或公积金缴纳的政策编码
> base Number 社保或公积金缴纳的基数
> month String 社保或公积金缴纳的费用月份
> status String 社保或公积金状态。
取值范围
add:新增
overdue:补缴
keep:在缴
stop:停缴
> itemList Array 社保或公积金项目明细。如果状态为停缴,则该明细为空
>> code String 社保或公积金项目明细编码
>> base Number 社保或公积金项目基数
>> org Number 社保或公积金项目企业部分费用
>> emp Number 社保或公积金项目个人部分费用
>> odf Number 社保或公积金项目补缴产生的滞纳金
paymentList Array 订单结转的补收明细
refundList Array 订单结转的补退明细
> idNum String 结转补收或补退人员证件号码
> item String 结转补收或补退类型。
取值范围
shebao:社保
gongjijin:公积金
once:一次性费用
> type String 结转补收或补退人员缴纳政策编码
> month String 导致出现补收补退差异的费用月份
> emp Number 企业部分补收或补退总额
> org Number 个人部分补收或补退总额
> serviceFee Number 补收或补退服务费
> desc String 补收或补退原因说明
> itemList Array 补收或补退项目明细
>> code String 补收或补退项目明细编码
>> orgDiff Number 补收或补退项目企业部分费用差异
>> empDiff Number 补收或补退项目企业个人费用差异
addFeeList Array 订单补充费用明细
> fee Number 补充费用
> desc String 补充费用说明

2.5.5.3 查询订单补收\补退记录

基本信息:

接口地址 获取待补收记录:{user_code}/orders/differences/less
获取待补退记录:{user_code}/orders/differences/more
支持格式 JSON/Form Data/Query String Parameters
请求方式 http get
编码 UTF-8
是否需要授权
说明 查询会员未处理的订单补收和补退
注意事项 生成订单时,系统将自动结转补收和补退数据。每个账号每天最多可查询3次

请求参数:

参数 类型 必填 说明
user_code String url占位。会员账号,创建账号后获得

请求示例:
GET http(s)://API_URL/20170506396/orders/differences/less

返回结果:
返回JSON示例:

  1. {
  2. "rows": [
  3. {
  4. "idNum": "410882198901010000",
  5. "item": "gongjijin",
  6. "type": "shanghaigongjijin",
  7. "month": "201701",
  8. "emp": 100,
  9. "org": 100,
  10. "serviceFee": 0,
  11. "desc": "差异补收",
  12. "itemList": [
  13. {
  14. "code": "gongjijin",
  15. "orgDiff": 100,
  16. "empDiff": 100
  17. }
  18. ]
  19. },
  20. {
  21. "idNum": "410882198901010000",
  22. "item": "shebao",
  23. "type": "shanghaishebao",
  24. "month": "201701",
  25. "emp": 5,
  26. "org": 5,
  27. "serviceFee": 0,
  28. "desc": "差异补退",
  29. "itemList": [
  30. {
  31. "code": "yiliao",
  32. "orgDiff": 5,
  33. "empDiff": 5
  34. }
  35. ]
  36. }
  37. ]
  38. }

参数说明:

返回数据格式 JSON 说明 rows为待补收或补退记录数组。如果无数据,数组长度为0
参数 类型 必须 说明
idNum String 补收或补退人员证件号码
item String 补收或补退类型。
取值范围
shebao:社保
gongjijin:公积金
once:一次性费用
type String 补收或补退人员缴纳政策编码
month String 导致出现补收补退差异的费用月份
emp Number 企业部分补收或补退总额
org Number 个人部分补收或补退总额
serviceFee Number 补收或补退服务费
desc String 补收或补退原因说明
itemList Array 补收或补退项目明细
> code String 补收或补退项目明细编码
> orgDiff Number 补收或补退项目企业部分费用差异
> empDiff Number 补收或补退项目企业个人费用差异

2.6 发票信息接口

2.6.1 设置专票信息

基本信息:

接口地址 新增:{user_code}/taxpayers
支持格式 JSON/Form Data
请求方式 http put
编码 UTF-8
是否需要授权
说明 如果需要开增值税专用发票,需要通过该接口提供一般纳税人资质、开票信息等相关材料;
注意事项 1. 企业账号才可调用该接口。
2. 【订单付费方式】为【会员付款】的才可调用该接口。
3. 发票信息必须审核通过后,才可使用。
4. 每个账户只会有一条开票信息,开票时将使用会员的开票信息进行开票。
5. 如果开票信息中修改了【公司名称】,我司审核通过后,将同步修改其会员名称
6. 如果需开增值税专用发票,可通过该接口设置相关信息

请求参数:

参数 类型 必填 说明
user_code String url占位。会员账号,创建账号后获得
data JSON Object 专票相关信息。(如果是修改,则需保证下列字段至少有一个不为空)
> address String 公司地址
> phone String 公司电话
> bank String 开户行
> bankNum String 开户行账号
> pro String 一般纳税人证明材料图片文件ftp地址。文件格式可为:jpg,jpeg,bmp,png
> doc String 开票信息材料图片文件ftp地址。文件格式可为:jpg,jpeg,bmp,png

请求示例:
PUT http(s)://API_URL/20170506396/taxpayer
RequestBody中JSON参数data格式:

  1. {
  2. "address": "上海市浦东新区芳华路18号",
  3. "phone": "021-456235",
  4. "bank": "中国建设银行上海龙漕路支行",
  5. "bankNum": "6258888888888888",
  6. "pro": "201704271922504442408.jpg",
  7. "doc": "201704271922504442409.jpg"
  8. }

返回结果:
返回JSON示例:

  1. {
  2. "result": true
  3. }

参数说明:

返回数据格式 JSON Object 说明
参数 类型 必须 说明
result Boolean已设置,信息审核中

2.6.2 发票信息查询

基本信息:

接口地址 {user_code}/taxpayer
支持格式 JSON/Form Data/Query String Parameters
请求方式 http get
编码 UTF-8
是否需要授权
说明 根据专票信息id查询专票信息,可以查询到审核状态
注意事项 1. 只有协议中规定【订单付费方式】为【会员付款】的平台,才可调用该接口。

请求参数:

参数 类型 必填 说明
user_code String url占位。会员账号,创建账号后获得

请求示例:
GET http(s)://API_URL/20170506396/taxpayer

返回结果:
返回JSON示例:

  1. {
  2. "title": "上海某某公司",
  3. "payerNum": "20160387240981",
  4. "address": "上海市浦东新区芳华路18号",
  5. "phone": "021-456235",
  6. "bank": "中国建设银行上海龙漕路支行",
  7. "bankNum": "6258888888888888",
  8. "status": "0",
  9. "comment": "不清晰"
  10. }

参数说明:

返回数据格式 JSON Object 说明 返回专票信息id。申请用该专票信息开票时,需提供该id。
参数 类型 必须 说明
title String 发票抬头
payerNum String 纳税人识别号
address String 公司地址(专票才有该信息)
phone String 公司电话(专票才有该信息)
bank String 开户行(专票才有该信息)
bankNum String 开户行账号(专票才有该信息)
status Number 状态。
取值范围
0:审核未通过
1:审核通过
-1:待审核
comment String 审核说明

2.7 订单开票接口

2.7.1 开票申请

基本信息:

接口地址 {user_code}/invoices
支持格式 JSON/Form Data
请求方式 http post
编码 UTF-8
是否需要授权
说明 订单开票,按照已经设置的开票信息进行开票。
注意事项 1. 只有订单状态为【3=已付款】,订单总额大于0且【未申请开票】的订单才可申请开票,可为多个订单合并开票。
2. 只有协议中规定【订单付费方式】为【会员付款】的接入平台,才可调用该接口。
3. 个人用户只可开个人发票。

请求参数:

参数 类型 必填 说明
user_code String url占位。会员账号,创建账号后获得
data JSON Object 申请开票信息
> orderList Array 需要开票的订单编号数组
>> orderNum String 订单编号
> express Object 收件信息
>> receiver String 收件人
>> phone String 收件人手机号码
>> address String 收件地址

请求示例:
POST http(s)://API_URL/20170506396/invoices
RequestBody中JSON参数data格式:

  1. {
  2. "orderList": [
  3. {
  4. "orderNum": "408517020210561"
  5. },
  6. {
  7. "orderNum": "349612021210551"
  8. }
  9. ],
  10. "express": {
  11. "receiver": "张三",
  12. "phone": "13888888888",
  13. "address": "上海市淮海路110号"
  14. }
  15. }

返回结果:
返回JSON示例:

  1. {
  2. "num": "20170512213223238"
  3. }

参数说明:

返回数据格式 JSON Object 说明  
参数 类型 必须 说明
num String 开票申请编号。可根据该编号查询开票进度

2.7.2 开票查询

基本信息:

接口地址 {user_code}/invoices/{apply_num}
支持格式 JSON/Form Data/Query String Parameters
请求方式 http get
编码 UTF-8
是否需要授权
说明 根据开票申请单号查询发票及快递信息
注意事项 1. 只有协议中规定【订单付费方式】为【会员付款】的接入平台,才可调用该接口。
2. 只可查询距离申请时间31天(包括)内的开票信息。同一个开票信息每天最多可查询3次。

请求参数:

参数 类型 必填 说明
user_code String url占位。会员账号,创建账号后获得
apply_num String url占位。开票申请编号

请求示例:
GET http(s)://API_URL/20170506396/invoices/20170512213223238

返回结果:
返回JSON示例:

  1. {
  2. "invoice": [
  3. {
  4. "num": "6954555532633",
  5. "date": "2017-04-21",
  6. "amount": 2000
  7. }
  8. ],
  9. "express": [
  10. {
  11. "company": "顺丰速递",
  12. "num": "8526636666366"
  13. }
  14. ]
  15. }

参数说明:

返回数据格式 JSON Object 说明  
参数 类型 必须 说明
invoice Array 发票集合。如果还未开票,则为空
> num String 发票号
> date 开票日期
> amount Number 发票金额
express Array 发票快递信息。如果未快递,则为空;如果发票有多张,可能有多条快递信息
> company String 快递公司
> num 快递单号

2.8 回写接口

  一、 回写接口需要接入的平台提供对应的接口,供社保通API在需要回写数据时调用。如果回写失败,将最多回写3次,就不会在自动回写。


  二、 可根据各接入平台要求,在调用回写接口时,设置Header请求头参数,或其它Form Data/JSON参数,但不可和已有的业务参数相同。

2.8.1 新创建账号审核状态回写

基本信息:

支持格式 JSON/Form Data
请求方式 http post
编码 UTF-8
是否需要授权
说明 通过创建账号接口创建的账号如果社保通已审核,则会通过该接口回写审核结果。
注意事项 审核通过的账号才可调用业务接口

传递的业务参数:

参数 类型 必填 说明
userCode String 会员账号
status Number 审核状态。
取值范围
1:审核通过
0:审核失败
comment String 审核说明

回写请求示例:
RequestBody中JSON参数data格式

  1. {
  2. "usercode": "20170501234",
  3. "status": 1,
  4. "comment": "不清晰"
  5. }

需返回的JSON结果:
返回JSON示例:

  1. {
  2. "result": 1
  3. }

参数说明:

参数 类型 必须 说明
result Number 如果为1,则更新成功,否则为回写失败。如果失败,社保通API会最多尝试3次回写

2.8.2 人员材料审核状态回写

基本信息:

支持格式 JSON/Form Data
请求方式 http post
编码 UTF-8
说明 人员提交的材料信息,社保通如何已审核,则通过该接口回写审核结果
注意事项 只有材料审核通过的人员才可提交订单

传递的业务参数:

参数 类型 必填 说明
userCode String 用户账号
idNum String 人员证件号码
code String 材料编码
status Number 审核状态。
取值范围
1:审核通过
0:审核失败
comment String 审核说明

回写请求示例:
RequestBody中JSON参数data格式

  1. {
  2. "userCode": "20170501234",
  3. "idNum": "410882198901010000",
  4. "code": "idcard_a",
  5. "status": "0",
  6. "comment": "不清晰"
  7. }

需返回的JSON结果:
返回JSON示例:

  1. {
  2. "result": 1
  3. }

参数说明:

参数 类型 必须 说明
result Number 如果为1,则更新成功,否则为回写失败。如果失败,社保通API会最多尝试3次回写

2.8.3 订单发生变更回写

基本信息:

支持格式 JSON/Form Data
请求方式 http post
编码 UTF-8
说明 如果状态或其它信息发生变更,则通过该接口回写
注意事项  

传递的业务参数:

参数 类型 必填 说明
userCode String 用户账号
orderNum String 订单编号
status Number 变更内容
选项:
1:已付款
2:已关闭
3:订单发生变更
4:新产生的订单

回写请求示例:
RequestBody中JSON参数data格式

  1. {
  2. "userCode": "20170501234",
  3. "orderNum": "408517020210561",
  4. "status": 1
  5. }

需返回的JSON结果:
返回JSON示例:

  1. {
  2. "result": 1
  3. }

参数说明:

参数 类型 必须 说明
result Number 如果为1,则更新成功,否则为回写失败。如果失败,社保通API会最多尝试3次回写

2.8.4 办理结果回写

基本信息:

支持格式 JSON/Form Data
请求方式 http post
编码 UTF-8
说明 人员社保公积金补缴、新增和停缴的办理结果会通过该接口回写
注意事项 已经增员成功的社保公积金续缴时,不会回写

传递的业务参数:

参数 类型 必填 说明
userCode String 用户账号
idNum String 人员证件号码
item String 取值范围
shebao:社保
gongjijin:公积金
month String 社保或公积金月份
status String 社保或公积金状态。
取值范围
overdue:补缴
add:新增
stop:停缴
result String 社保或公积金办理结果。
取值范围
1:办理成功
0:办理失败
2:部分成功
comment String 办理说明

回写请求示例:

RequestBody中JSON参数data格式

  1. {
  2. "userCode": "20170501234",
  3. "idNum": "410882198901010000",
  4. "item": "shebao",
  5. "month": "201701",
  6. "status": "overdue",
  7. "result": "1"
  8. }

需返回的JSON结果:
返回JSON示例:

  1. {
  2. "result": 1
  3. }

参数说明:

参数 类型 必须 说明
result Number 如果为1,则更新成功,否则为回写失败。如果失败,社保通API会最多尝试3次回写

3 错误代码表

系统级错误代码

 

1) 服务器错误

错误代码  
(errorcode)
错误信息 
(msg)
可能出现该错误的接口
-1 服务器错误 全局
0 服务器忙 全局

 

2) 授权或账号错误

错误代码 
(errorcode)
错误信息  
(msg)
可能出现该错误的接口
1001 access_token有误 全局 
accessToken有误或未能匹配绑定ip
1002 无该接口权限 所有接口
1003 已超过最高{n}次的请求限制 有请求次数限制的接口
1004 账号有误 所有业务操作接口
1005 账号未审核通过 所有业务操作接口
1006 账号已失效 所有业务操作接口
1007 该帐号正在执行该操作,不可重复提交 1. 人员数据操作接口 
2. 订单数据操作接口

 

3) 通用错误

错误代码  
(errorcode)
错误信息 
(msg)
可能出现该错误的接口
2001 参数有误 全局
2002 缺少必须参数 全局
2003 数据格式有误 全局
2004 字符长度不符合规范 1. 增员接口; 
2. 专票信息新增接口; 
3. 申请开票接口
2005 {材料名称}格式有误,允许的格式为{文件后缀} 所有可提交材料的接口
2006 文件超过1M限制 所有可提交材料的接口
2007 手机号码有误 1. 创建账号接口 
2. 增员接口
2008 邮箱格式有误 创建账号接口
2009 年月格式有误,正确格式为yyyyMM 1. 计算器接口 
2. 补缴计算器接口 
3. 增员接口
2010 身份证格式错误 1. 增员接口
2011 会员已经审核通过,不能编辑 1. 修改企业账号
2012 身份证已经审核通过,不能编辑 1. 修改个人账号

业务级错误代码

错误代码  
(errorcode)
错误信息 
(msg)
可能出现该错误的接口
5001 城市代码有误 1. 获取城市社保公积金政策接口 
2. 增员接口 
3. 订单提交接口
5002 政策编码有误 1. 计算器接口 
2. 补缴计算器接口 
3. 增员接口
5003 公司名称已被注册 1. 创建企业账号接口
5004 身份证号已被注册 1. 创建个人账号接口
5005 邮箱已被注册 1. 创建企业账号接口 
2. 创建个人账号接口
5006 手机号已被注册 1. 创建企业账号接口 
2. 创建个人账号接口
5007 提交的人数超过最大{n}次的限制 1. 增员接口 
2. 减员接口
5008 证件类型错误 1. 增员接口
5009 证件号码已存在 1. 增员接口
5010 性别类型错误 1. 增员接口
5011 人员的年龄不在可缴交范围内,{男|女}性缴交的年龄范围为{0}岁-{1}岁 1. 增员接口
5012 该城市必须同时缴纳社保和公积金 1. 增员接口
5013 {社保|公积金}基数不在政策规定范围内 1. 增员接口
5014 {社保|公积金}参保起始月不在政策规定范围内 1. 增员接口
5015 {社保|公积金}参保起始月当月办理结果必须为失败才可修改 1. 增员接口
5016 {社保|公积金}参保状态错误 1. 增员接口
5017 需提供{社保|公积金}编号 1. 增员接口
5018 缺少所需材料 1. 增员接口
5019 缺少所需字段 1. 增员接口 
2. 减员接口
5020 材料编码错误 1. 增员接口 
2. 减员接口
5021 字段编码错误 1. 增员接口 
2. 减员接口
5022 {字段名称}数据错误 1. 增员接口 
2. 减员接口
5023 社保公积金必须同时停缴 1. 减员接口
5024 证件号码{证件号码}不存在 1. 减员接口 
2. 查询人员信息接口 
3. 查询材料信息接口 
4. 订单提交接口
5025 无可提交订单数据 1. 订单提交接口
5026 城市订单最后提交时间已截止 1. 订单提交接口
5027 提交订单月数错误 1. 订单提交接口
5028 订单不存在 1. 订单确认接口 
2. 订单取消接口 
3. 提交订单付款凭证接口 
4. 查询单个订单详情接口 
5. 开票申请接口
5029 订单已关闭 1. 订单确认接口 
2. 订单取消接口 
3. 提交订单付款凭证接口
5030 订单已确认 1. 订单确认接口 
2. 订单取消接口
5032 开票申请编号错误 1. 开票查询接口
5033 专票已审核,不可修改 1. 专票修改接口
5034 专票不可用 1. 开票申请接口
5035 订单不可开票 1. 开票申请接口
5036 人员停缴已提交订单,不可取消 1. 取消减员接口
5037 人员当前不为停缴状态 1. 取消减员接口