API认证指南 - 开放平台

认证方式

我们的API使用API密钥进行身份认证。API密钥是一种简单而有效的身份验证方式，适用于服务器间通信。

🔑 API密钥认证

API密钥是一串唯一的字符串，用于识别API请求的发起者。每个用户可以生成自己的API密钥，并在API请求中通过api_key参数进行传递。

API密钥认证的优点：

实现简单，易于集成
适合服务器端应用程序
便于追踪和管理API使用情况

获取API密钥

要获取API密钥，请按照以下步骤操作：

1

登录到用户后台

首先，您需要登录到您的用户后台。如果还没有账号，请先注册一个新账号。

2

进入个人资料页面

登录成功后，点击左侧菜单栏中的「个人信息」，进入个人资料页面。

3

生成API密钥

在个人资料页面底部，您会找到API密钥管理区域。点击「生成API密钥」按钮，系统将为您生成一个新的API密钥。

4

复制并保存API密钥

生成成功后，系统会显示完整的API密钥。请立即复制并安全保存，因为离开该页面后将无法再次查看完整密钥。

⚠️ 安全提示

API密钥等同于您的账号密码，请妥善保管，不要与他人分享
如果怀疑API密钥泄露，请立即在个人资料页面重置密钥
建议定期更换API密钥以提高安全性
不要在客户端代码中直接嵌入API密钥，以防止泄露

使用API密钥

获取API密钥后，您可以在API请求中包含api_key参数进行身份认证。以下是不同请求方式中包含API密钥的示例：

GET请求

https://example.com/api/shortlink_api.php?action=get&short_code=abc123&api_key=YOUR_API_KEY_HERE

POST请求 (表单数据)

POST /api/shortlink_api.php HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

action=generate&target_url=https://www.example.com&title=示例链接&api_key=YOUR_API_KEY_HERE
                

POST请求 (JSON)

POST /api/shortlink_api.php HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "action": "generate",
    "target_url": "https://www.example.com",
    "title": "示例链接",
    "api_key": "YOUR_API_KEY_HERE"
}
                

cURL请求

curl -X POST 'https://example.com/api/shortlink_api.php' \
  -d 'action=generate' \
  -d 'target_url=https://www.example.com' \
  -d 'title=示例链接' \
  -d 'api_key=YOUR_API_KEY_HERE'
                

代码示例

以下是使用不同编程语言集成API密钥认证的示例代码：

PHP示例

请求失败：未知错误                

Python示例

import requests

# 设置API密钥和目标URL
api_key = 'YOUR_API_KEY_HERE'
api_url = 'https://example.com/api/shortlink_api.php'

# 准备请求参数
data = {
    'action': 'generate',
    'target_url': 'https://www.example.com',
    'title': '示例链接',
    'api_key': api_key
}

# 发送POST请求
response = requests.post(api_url, data=data)

# 解析响应
result = response.json()

if result.get('status') == 'success':
    print(f"短链接创建成功：{result['data']['a_url']}")
else:
    print(f"请求失败：{result.get('message', '未知错误')}")
                

JavaScript示例 (Node.js)

const axios = require('axios');

// 设置API密钥和目标URL
const apiKey = 'YOUR_API_KEY_HERE';
const apiUrl = 'https://example.com/api/shortlink_api.php';

// 准备请求参数
const data = {
    action: 'generate',
    target_url: 'https://www.example.com',
    title: '示例链接',
    api_key: apiKey
};

// 发送POST请求
axios.post(apiUrl, new URLSearchParams(data))
    .then(response => {
        const result = response.data;
        if (result.status === 'success') {
            console.log(`短链接创建成功：${result.data.a_url}`);
        } else {
            console.error(`请求失败：${result.message || '未知错误'}`);
        }
    })
    .catch(error => {
        console.error('请求出错：', error.message);
    });
                

认证错误处理

在使用API密钥进行认证时，可能会遇到以下常见错误。请参考下表了解错误原因和解决方法：

错误代码	错误消息	可能原因	解决方法
401	API密钥无效或已过期	API密钥不存在或已被撤销	检查API密钥是否正确，或在个人资料页面重新生成密钥
401	缺少API密钥	请求中未包含api_key参数	确保在每个需要认证的请求中都包含有效的api_key参数
403	无权限执行此操作	API密钥没有足够的权限执行请求的操作	确认您的账号是否有权限执行该操作，如有疑问请联系客服
429	请求过于频繁	超出了API调用频率限制	减少请求频率，或联系客服申请提高限制

如果您遇到了表中未列出的认证错误，请查看API返回的详细错误信息，或联系我们获取帮助。

API密钥管理

在个人资料页面，您可以对API密钥进行以下管理操作：

1

查看API密钥

在个人资料页面，您可以查看已生成的API密钥的部分内容（中间部分会被隐藏）。

2

复制API密钥

点击「复制」按钮，可以将API密钥复制到剪贴板，方便在其他应用中使用。

3

重置API密钥

点击「重置API密钥」按钮，可以生成一个新的API密钥。请注意，重置后旧密钥将立即失效。

4

清除API密钥

点击「清除API密钥」按钮，可以删除当前的API密钥。清除后，您将无法通过API访问您的账号，直到生成新的密钥。

⚠️ 重要提醒

重置或清除API密钥会影响所有使用该密钥的应用程序
建议在更新密钥后及时更新所有集成的应用程序
如果您需要在多个应用中使用API，建议为每个应用使用不同的API密钥（目前系统暂不支持，后续将优化）