Linksfield Developer
OverviewCube APIs旧版本API
OverviewCube APIs旧版本API
  1. Notification
  • CSSS APIs
    • 全局说明/Overview
    • 国际化/ Internationalization
    • 状态码/Status code
    • 签名代码示例 / Sign code Example
    • SIM
      • 批量获取拥有的设备信息/Get all SIM cards info
      • 查询单一设备实时信息/Get real-time info about one SIM card
      • 同步使用中SIM卡信息/Get the SIM Cards in use
    • Usage
      • 查询单张SIM卡流量使用情况/ Example Query the traffic usage of a single SIM card
      • 批量查询SIM卡流量接口 /Batch querying SIM card usage
      • 查询单日流量使用情况 / Example Query the daily usage
      • 批量查询指定月份的流量使用情况/ Batch querying the usage in a specified month
    • Plan
      • 同步资费套餐 / Get data plan
      • 订购流量套餐/ Order data plan
      • 批量订购套餐/ Bulk order package
      • 续订流量套餐/ Renew your data plan
      • 查询套餐订单信息 / Query the package order information
      • 开通/启用流量套餐订单 / To enable the order
      • 取消流量套餐订单/ Cancel an unenabled package order
      • 提前结束设备套餐订单/ End package orders early
      • [不推荐]停机/暂停流量套餐订单
      • [不推荐]复机/重新启动流量套餐订单
      • 【不推荐】分页批量(查询)同步设备可订购套餐
    • SMS
      • 发送短信/ send SMS
    • Customized
      • OTA日套餐下单/Order OTA Plan
      • 运营商侧剩余流量查询/Query the remaing data by MNO side
  • Notification
    • Notification全局说明
    • Notification状态码
    • 流量使用量API预警
      POST
    • 短信下行回调
      POST
    • 短信上行回调
      POST
    • 短信上行回调(区分文本二进制)
      POST
    • 订单状态变更回调(IMSI)
      POST
  • Mall APIs
    • Mall全局说明
    • Mall业务流程
    • Mall签名代码示例
    • APP调用Stripe的SDK示例说明
    • Vshop
      • 卡片登录验证
      • 获取可购套餐商品列表
      • 创建用户订单
      • 查询正在使用、未启用订单
      • 获取生效中的自动续费
      • 关闭自动续费
      • 用户下单(第三方支付)
    • Payment
      • 获取stripe单次支付权限
      • 获取Stripe订阅支付权限
      • 创建Stripe订阅/自动续费
      • 支付结果查询
    • Notification
      • 充值成功消息推送
        POST
    • Bundle-groups
      • 添加SIM卡至指定分组
      • 从指定分组删除SIM卡
      • 查询所有分组及套餐基本信息
      • 查询指定分组的 SIM 卡号
      • 异步结果获取
    • Order
      • 订单详情查询
  • eSIM QR Mall APIs
    • Introduction
    • Pre - order
    • webhook
    • 用户登录
    • My eSIM Detail
OverviewCube APIs旧版本API
OverviewCube APIs旧版本API
  1. Notification

充值成功消息推送

Cube UAT
https://api-uat.io.linksfield.net/cube/v4
Cube UAT
https://api-uat.io.linksfield.net/cube/v4
POST
客户自定义的URL

概述#

领科Cube API 出口(Webhook)系统采取RESTful API发送Notification API。
通知的内容为领科系统的events。
客户通过以下方式可以收到event通知
1.
经过客户的授权,FAE在BBC为客户代为配置某些系统事件的notification API

Header结构#

参数必须类型示例值说明是否加入签名计算
x-lf-notification-version必须String1.0Notification api的版本标识是
x-lf-algo必须StringHMAC-SHA1算法标识,目前支持HMAC-SHA1。以后可以扩展, md5, sha256,等,默认为hmac-sha1是
x-lf-signature必须String{keyId}/{signature}签名。有可能存在多对业务密钥。需要传keyid是
x-lf-timestamp必须String1683524066000发送的时间戳,毫秒是

算法#

API出口携带领科定义的算法标识,其目的是加强通信双方的安全,防止报文篡改或非法发送。
接收Notification需要独立的Key。

HMAC-SHA1#

计算signature步骤#

1.
Load notification key ( in raw hex)
2.
组织报文:
2.1 POST 的body做JSON String encode, top-level key按字典排序(即数组不排序)=> sorted_message
2.2 加上头信息 {x-lf-notification-version}:{x-lf-algo}:{x-lf-timestamp}
例:
3.
算法HMAC-SHA1(key=key_hex, data =message)
4.
摘要做base64转换
5.
x-lf-signature = {keyId}/{digest}
例:

验证signature步骤#

1.
根据x-lf-signature中的{keyId}, Load notification key
2.
组织报文
2.1 POST 的body做JSON String encode, top-level key按字典排序(即数组不排序)=> sorted_message
2.2 加上头信息 {x-lf-notification-version}:{x-lf-algo}:{x-lf-timestamp}
例:
3.
做HAMC-SHA1(key=key_hex, data =message)
注:key_hex指Cube页面中开发者模块的notification key value位置如下图所示
image.png
4.
base64转换摘要
5.
计算的摘要和接收到的x-lf-signature中的digest比较
推荐客户端应用在接收到校验失败的报文时,进行抛弃。

签名代码示例#

Notification签名代码示例
如何获取Notification Key

重发机制#

遇到下列情况,启动自动重发。自动重发3次(共4次),阶梯间隔:1,5, 10 (分钟)
1.
领科内部超时(wait timeout, 等)或发送服务异常时
2.
外部响应超时(read timeout, connection timeout等)
3.
Status code >=500 时(2xx,3xx,4xx不需要重发)

请求参数

Header 参数

Body 参数application/json

示例
{
    "notification_id": "NT-09887665434565",
    "org_id": "P001234",
    "event_type": "payment",
    "event_subtype": "payment_succeeded",
    "level": "normal",
    "trigger_mode": 0,
    "source": {
        "type": "bbc-event",
        "reference_id": "bbc001",
        "reference_name": "payment_succeeded"
    },
    "event": {
        "occurred_at": 1683178613876,
        "sim_id": "89852123456789012345",
        "id": "EV-9988776666666",
        "detail": {
            "order_id": "CU-7ZOIHX0RB16U20250828111429591",
            "purchase_order_id": "4567",
            "bundle_name": "CLJF_ZRR_20250317_001",
            "cycles": "1",
            "total_amount": 1000,
            "payment_method": "stripe",
            "payee": "linksfield",
            "currency": "USD",
            "partner_name": "Excepteur deserunt eu labore",
            "paid_at": 1683178613876,
            "order_status": "active",
            "payment_status": "paid",
            "dispute_status": "none",
            "risk_status": "normal",
            "transaction_type": "one-time"
        }
    }
}

请求示例代码

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
请求示例请求示例
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://api-uat.io.linksfield.net/cube/v4客户自定义的URL' \
--header 'x-lf-notification-version;' \
--header 'x-lf-algo: HMAC-SHA1' \
--header 'x-lf-signature;' \
--header 'x-lf-timestamp;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "notification_id": "NT-09887665434565",
    "org_id": "P001234",
    "event_type": "payment",
    "event_subtype": "payment_succeeded",
    "level": "normal",
    "trigger_mode": 0,
    "source": {
        "type": "bbc-event",
        "reference_id": "bbc001",
        "reference_name": "payment_succeeded"
    },
    "event": {
        "occurred_at": 1683178613876,
        "sim_id": "89852123456789012345",
        "id": "EV-9988776666666",
        "detail": {
            "order_id": "CU-7ZOIHX0RB16U20250828111429591",
            "purchase_order_id": "4567",
            "bundle_name": "CLJF_ZRR_20250317_001",
            "cycles": "1",
            "total_amount": 1000,
            "payment_method": "stripe",
            "payee": "linksfield",
            "currency": "USD",
            "partner_name": "Excepteur deserunt eu labore",
            "paid_at": 1683178613876,
            "order_status": "active",
            "payment_status": "paid",
            "dispute_status": "none",
            "risk_status": "normal",
            "transaction_type": "one-time"
        }
    }
}'

返回响应

🟢200成功
application/json
Body

示例
{}
修改于 2026-01-08 01:50:30
上一页
支付结果查询
下一页
添加SIM卡至指定分组
Built with