API 概览

AttriKit API 接口文档总览

API 基础信息

Base URL

https://api.attrikit.com/v1

认证方式

所有 API 请求需要在 Header 中携带 API Key：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

请求限流

计划请求限制
免费版1,000 次/天
专业版100,000 次/天
企业版无限制

API 端点列表

事件上报

端点方法说明
/events/trackPOST上报单个事件
/events/batchPOST批量上报事件
/events/validatePOST验证事件数据格式

数据查询

端点方法说明
/eventsGET查询事件列表
/events/:idGET获取事件详情
/conversionsGET查询转化数据
/attributionGET查询归因结果

用户管理

端点方法说明
/usersGET获取用户列表
/users/:idGET获取用户详情
/users/:id/eventsGET获取用户事件

报表导出

端点方法说明
/reports/performanceGET效果报表
/reports/conversionGET转化报表
/reports/exportPOST导出报表

通用响应格式

成功响应

{
  "success": true,
  "data": {
    // 返回数据
  }
}

错误响应

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "错误描述",
    "details": {}
  }
}

HTTP 状态码

状态码说明
200请求成功
201创建成功
400请求参数错误
401未授权
403禁止访问
404资源不存在
429请求过于频繁
500服务器错误

错误码参考

错误码说明解决方案
INVALID_API_KEYAPI Key 无效检查 API Key 是否正确
MISSING_REQUIRED_FIELD缺少必填字段补充必填参数
INVALID_EVENT_NAME事件名称无效使用合法的事件名称
RATE_LIMIT_EXCEEDED超出限流减少请求频率或升级套餐
SERVER_ERROR服务器错误稍后重试或联系技术支持

快速开始

1. 获取 API Key

登录控制台，进入「设置 > API 管理」创建 API Key。

2. 发起第一个请求

curl -X POST https://api.attrikit.com/v1/events/track \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "page_view",
    "properties": {
      "page_title": "首页",
      "page_url": "https://example.com"
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }'

3. 验证响应

{
  "success": true,
  "data": {
    "event_id": "evt_1234567890",
    "received_at": "2024-01-15T10:30:01Z"
  }
}

SDK vs API

特性SDKAPI
易用性高，开箱即用中，需要自行实现
自动重试支持需要自行实现
离线缓存支持需要自行实现
灵活性中高
适用场景前端数据采集后端数据同步

Webhook

AttriKit 支持 Webhook 回调，当关键事件发生时会主动推送通知。

配置 Webhook

在控制台设置 Webhook URL：

https://your-domain.com/webhooks/attrikit

Webhook 事件

事件触发时机
conversion.created新增转化
attribution.completed归因完成
threshold.alert阈值告警

Webhook 签名验证

为确保请求来自 AttriKit，需要验证签名：

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

相关文档