LINE Login 绑定客户

让你方的会员用自己的 LINE 账号完成绑定。你只需把会员 ID(customerExternalId)交给 LOMA,LOMA 返回一条一次性的 LINE 授权链接;会员在 LINE 授权后,LOMA 自动把该会员与其 LINE 账号绑定,并 302 回跳你指定的地址。

绑定成功后,你就能用发送消息向该会员推送通知 / OTP。

流程

1. 你方后端调 POST /api/v1/merchant/binding/line-login,带上会员 ID 和绑定完成后的回跳地址 returnUrl。
2. LOMA 返回 bindingUrl(有效期默认 10 分钟,一次性)。
3. 你把会员重定向 / 打开 bindingUrl。会员在 LINE 页面点“同意”。
4. LINE 回调 LOMA → LOMA 取到会员的 LINE userId、落绑定。
5. LOMA 把会员 302 回跳 到你的 returnUrl,并带上结果参数。

1. 创建绑定链接

POST /api/v1/merchant/binding/line-login

请求头

需带 X-Api-Key、X-Api-Secret(见认证)。

请求体

字段	类型	必填	说明
customerExternalId	string	✅	你方系统的会员 / 客户 ID
returnUrl	string	✅	绑定完成后 LOMA 回跳的地址

{
  "customerExternalId": "C10086",
  "returnUrl": "https://your-app.com/line/bound"
}

成功响应 200

{
  "code": "OK",
  "message": "Success",
  "requestId": "req_...",
  "data": {
    "bindingUrl": "https://access.line.me/oauth2/v2.1/authorize?response_type=code&client_id=...&state=...",
    "state": "9f2a...c1",
    "expiresAt": "2026-07-02T08:20:00Z"
  }
}

字段	说明
bindingUrl	一次性 LINE 授权链接,把会员重定向到这里
state	一次性令牌(LOMA 内部关联本次绑定,你无需处理)
expiresAt	链接过期时间(UTC),过期后需重新创建

主要错误

code	HTTP	说明
LOGIN_NOT_CONFIGURED	400	该商户尚未配置 LINE Login channel
VALIDATION_ERROR	400	customerExternalId 或 returnUrl 缺失

2. 回跳结果

会员完成(或取消)后,LOMA 会把浏览器 302 回跳到你的 returnUrl,并追加以下查询参数:

成功:

https://your-app.com/line/bound?binding=success&customerExternalId=C10086

失败 / 取消:

https://your-app.com/line/bound?binding=failed&customerExternalId=C10086&reason=cancelled

参数	说明
binding	success / failed
customerExternalId	本次绑定的会员 ID(原样回传)
reason	仅失败时出现:cancelled(用户取消)/ expired(链接过期)/ already_used(链接已用)/ ALREADY_BOUND(该会员已绑其它 LINE)/ LINE_ALREADY_BOUND(该 LINE 已被别的会员绑)/ exchange_failed(与 LINE 交互失败)

⚠️ 回跳参数仅用于前端提示。请以服务端为准:收到回跳后,用查询绑定状态二次确认再放行业务。

3. 解绑客户

解除某会员当前的 LINE 绑定。解绑后该会员即可重新走绑定流程(换绑另一个 LINE 账号也需先解绑)。

DELETE /api/v1/merchant/customer/{customerExternalId}/line-binding

请求头

需带 X-Api-Key、X-Api-Secret(见认证)。

路径参数

参数	说明
customerExternalId	你方系统的会员 / 客户 ID

成功响应 200

{
  "code": "OK",
  "message": "Success",
  "requestId": "req_...",
  "data": {
    "customerExternalId": "C10086",
    "unbound": true,
    "status": "UNBOUND"
  }
}

字段	说明
unbound	本次是否有有效绑定被解除。true=已解绑;false=该会员本就没有有效绑定(无需操作)
status	恒为 UNBOUND

幂等:对同一会员重复调用不会报错,已无绑定时返回 unbound=false。

示例

curl -X DELETE https://loma-dev.acorners.com/api/v1/merchant/customer/C10086/line-binding \
  -H "X-Api-Key: lk_xxxx" -H "X-Api-Secret: xxxx"

幂等与约束

• 一个会员同时只能绑定一个 LINE 账号,一个 LINE 账号也只能绑一个会员。
• 同一会员用同一 LINE 账号重复绑定 → 幂等,返回成功,不重复建记录。
• 会员想换绑,需先调解绑接口解除旧绑定,再走一次绑定流程。

示例

curl -X POST https://loma-dev.acorners.com/api/v1/merchant/binding/line-login \
  -H "X-Api-Key: lk_xxxx" -H "X-Api-Secret: xxxx" \
  -H "Content-Type: application/json" \
  -d '{"customerExternalId":"C10086","returnUrl":"https://your-app.com/line/bound"}'