登录&认证卡片集成
该文档面向 EasyAPI 数电发票（全电发票）客户，方便客户在自有系统中进行电子税务局登录&认证。
数电发票要求开票员定期在电子税务局登录并完成身份（扫脸）认证，认证时长间隔可在电子税务局设置。为了让客户系统的工作人员无需登录 EasyAPI 发票控制台，开发人员可以把「登录&认证卡片」集成在自有系统中：卡片实时显示开票员是否登录、是否认证，并提供登录、认证、刷新操作。在线演示见 接入演示 - 登录&认证。
名词解释
| 字段名 | 名称 | 解释 | 备注 |
|---|---|---|---|
| username | 用户标识 | 客户系统中的用户唯一编号 | 可以使用手机号，或者加密的字符串；用于本卡片时必须是开票员的电子税务局手机号 |
| accessToken | 访问令牌 | 通过 EasyAPI 获取的访问令牌 | 有效期 2 小时 |
1、调用「获取用户 accessToken」API 接口
接口文档：获取访问令牌
GET
https://fapiao-api.easyapi.com/access-token该接口需要客户后端系统调用封装，再给自己业务系统使用，不要把 appKey / appSecret 暴露在前端。
| 参数名称 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| appKey | string | 必填 | 发票服务 appKey |
| appSecret | string | 必填 | 发票服务 App 密钥 |
| username | string | 必填 | 用户标识（开票员手机号码）（必须是已在 EasyAPI 发票控制台配置员工，电子税务局存在的开票员） |
| taxNumber | string | 必填 | 企业纳税人识别号 |
curl "https://fapiao-api.easyapi.com/access-token?appKey=你的appKey&appSecret=你的appSecret&username=13600000000&taxNumber=91320211MA1WML8X6T"
{
"code": 1,
"message": "获取成功",
"content": {
"accessToken": "k3d8s9a1b2c3d4e5f6g7h8i9j0k1l2m3",
"username": "13600000000",
"taxNumber": "91320211MA1WML8X6T"
}
}
2、嵌入登录&认证卡片
卡片 URL 示例：
https://fapiao-robot-login.easyapi.com/access-token?taxNumber=税号&username=用户标识（开票员手机号码）&accessToken=步骤1获取的访问令牌
| 参数名称 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| accessToken | string | 必填 | 步骤 1 获取的访问令牌 |
| username | string | 必填 | 用户标识（开票员手机号码）（必须是已在 EasyAPI 发票控制台配置员工，电子税务局存在的开票员） |
| taxNumber | string | 必填 | 企业纳税人识别号 |
嵌入后效果（需自行增加激活按钮入口，点击按钮出现该卡片弹框）：
| 卡片内容 | 说明 |
|---|---|
| 标题「电子税务局登录&认证」 | 卡片右上角有关闭按钮 |
| 数电账号 | 开票员手机号（脱敏）与姓名 |
| 账号状态 | 已登录 / 未登录，已认证 / 未认证 |
| 登录时间 | 最近一次电子税务局登录成功时间 |
| 上次认证成功时间 | 最近一次身份认证成功时间 |
| 操作按钮 | 「登录」「认证」「刷新」，按当前状态显示 |
iframe 嵌入示例
<!-- 自有系统中的入口按钮 -->
<button id="loginAuthBtn">登录&认证</button>
<!-- 弹框中的卡片 -->
<div id="loginAuthDialog" style="display:none">
<iframe id="loginAuthFrame" frameborder="0" scrolling="no"></iframe>
</div>
<script>
const dialog = document.getElementById('loginAuthDialog')
const frame = document.getElementById('loginAuthFrame')
document.getElementById('loginAuthBtn').addEventListener('click', async () => {
// 1. 向自己的后端获取 accessToken（后端调用 GET /access-token）
const { accessToken, username, taxNumber } = await fetch('/api/fapiao/access-token').then(r => r.json())
// 2. 加载卡片
frame.src = `https://fapiao-robot-login.easyapi.com/access-token?taxNumber=${taxNumber}&username=${username}&accessToken=${accessToken}`
dialog.style.display = 'block'
})
// 3. 接收卡片通过 postMessage 发来的消息
window.addEventListener('message', (event) => {
if (!event.data)
return
if (event.data.type === 'setStyle') {
// 卡片告知自身尺寸，按此设置 iframe 大小
frame.width = event.data.width
frame.height = event.data.height
}
if (event.data.type === 'handleClose') {
// 用户点击了卡片右上角关闭
dialog.style.display = 'none'
}
})
</script>
卡片发出的 postMessage 消息
卡片页面会通过 window.parent.postMessage 向宿主页面发送消息，event.data 结构如下：
| type | 字段 | 说明 |
|---|---|---|
| setStyle | width、height | 卡片内容尺寸（像素），宿主页面应据此设置 iframe 的宽高，避免出现滚动条 |
| handleClose | - | 用户点击卡片关闭按钮，宿主页面应隐藏弹框 |
建议
- 卡片入口建议放在发票管理页面的显眼位置，并显示当前开票员的在线 / 认证状态，员工开票前先确认状态正常。
accessToken有效期 2 小时，每次打开卡片前重新向后端获取即可。- 一家企业有多个开票员时，
username传需要登录&认证的那位开票员的手机号。
3、在 EasyAPI 控制台内使用
已登录发票控制台的用户无需 accessToken，控制台右侧的「数电登录&认证」悬浮入口使用控制台登录令牌加载同一卡片：
https://fapiao-robot-login.easyapi.com/bearer-token?token=控制台登录Token&isClose=true&type=server
| 参数 | 说明 |
|---|---|
| token | 控制台登录后的 Bearer Token |
| isClose | true 时显示关闭按钮，并在关闭时发送 handleClose 消息 |
| type | server 托管版（服务器助手）；单机版助手传 single |
该方式仅供控制台内部使用，客户系统集成请使用步骤 1、2 的 accessToken 方式。