概览
使用 URLZ API 构建短链接、文件上传、访问统计和付费访问流程。本参考将服务器 API 密钥集成与已登录账户会话分开说明。
服务器到服务器
在后端、自动化或内部工具中使用有效 API 密钥。
apikey=YOUR_API_KEY账户会话
使用 Bearer 会话管理账户链接、上传、统计和变现。
Authorization: Bearer …快速开始
三步创建第一个短链接,然后查阅完整生产参考。
- 1创建账户
打开控制面板并启用 API 套餐。
- 2复制 API 密钥
仅保存在服务器上,切勿写入公开代码。
- 3发送请求
发送目标地址,并从 JSON 响应读取 result.short_url。
curl -X POST "https://api.urlz.li/url/create" \
--data-urlencode "apikey=YOUR_API_KEY" \
--data-urlencode "fullUrl=https://example.com/private-report"
// Server-side JavaScript (Node.js)
const body = new URLSearchParams({
apikey: 'YOUR_API_KEY',
fullUrl: 'https://example.com/private-report'
});
const response = await fetch('https://api.urlz.li/url/create', {
method: 'POST',
body
});
const data = await response.json();
console.log(data.result.short_url);
$request = curl_init('https://api.urlz.li/url/create');
curl_setopt_array($request, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query([
'apikey' => 'YOUR_API_KEY',
'fullUrl' => 'https://example.com/private-report',
]),
CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($request), true, 512, JSON_THROW_ON_ERROR);
echo $data['result']['short_url'];
import requests
response = requests.post(
"https://api.urlz.li/url/create",
data={
"apikey": "YOUR_API_KEY",
"fullUrl": "https://example.com/private-report",
},
timeout=15,
)
response.raise_for_status()
print(response.json()["result"]["short_url"])
身份验证
URLZ 支持两种身份验证方式,请选择适合的方式。
API 密钥
用于后端集成。在 URL 或表单中发送 apikey,密钥和订阅必须有效。
apikey=YOUR_API_KEYBearer 会话
用于账户功能。从登录接口获取令牌,并在 Authorization 请求头中发送。
Authorization: Bearer SESSION_TOKEN切勿在浏览器 JavaScript、移动日志、版本控制或公开仓库中发布密钥、密码或令牌。
接口索引
选择接口查看参数和请求、响应示例。
/url/create创建短链接
GET/url/list列出并筛选链接
POST/mobile/v1/auth/login.php打开账户会话
POST/mobile/v1/shorten.php创建账户链接
POST/mobile/v1/upload.php上传文件或照片
GET/mobile/v1/links.php列出账户链接
GET/mobile/v1/clicks.php查看点击统计
DELETE/mobile/v1/delete-link.php删除链接
POST/mobile/v1/collaboration/configure.phpEnable URLZ Chat or URLZ Request
GET/mobile/v1/collaboration/chats.phpList link conversations
GET/mobile/v1/collaboration/requests.phpTrack document requests
POST/mobile/v1/monetization/links.php创建或转换付费链接
POST/mobile/v1/monetization/upload.php创建付费文件或照片
GET/mobile/v1/monetization/links.php列出付费链接
GET/mobile/v1/monetization/transactions.php列出付费销售
API 密钥接口
用于创建和搜索短链接的稳定服务器接口。
/url/create创建短链接
使用有效 API 密钥创建短网址。
apikey参数
| 参数 | 类型 | 必填 | 默认值 |
|---|---|---|---|
apikey | string | 是 | — |
fullUrl | URL | 是 | — |
encrypt | string | 否 | "" |
password | string | 否 | "" |
curl -X POST "https://api.urlz.li/url/create" \
--data-urlencode "apikey=YOUR_API_KEY" \
--data-urlencode "fullUrl=https://example.com/report.pdf"
{
"result": {
"short_url": "https://urlz.li/7b3c2e5a",
"hash": "7b3c2e5a",
"date": "2026-11-02",
"time": "14:32:10"
}
}
/url/list列出并筛选链接
返回带筛选和分页的链接。
apikey参数
| 参数 | 类型 | 必填 | 默认值 |
|---|---|---|---|
apikey | string | 是 | — |
limit | integer (1–1000) | 否 | 100 |
offset | integer | 否 | 0 |
order | asc | desc | 否 | desc |
date | YYYY-MM-DD | 否 | — |
from_date | YYYY-MM-DD | 否 | — |
to_date | YYYY-MM-DD | 否 | — |
url_destination | string | 否 | — |
hash | string | 否 | — |
curl -G "https://api.urlz.li/url/list" \
--data-urlencode "apikey=YOUR_API_KEY" \
--data-urlencode "limit=25" \
--data-urlencode "order=desc"
{
"result": {
"filters": { "limit": 25, "offset": 0, "order": "desc" },
"total": 42,
"count": 25,
"items": [
{
"id": 1204,
"date": "2026-11-02",
"time": "14:32:10",
"destination": "https://example.com/report.pdf",
"hash": "7b3c2e5a",
"hash_retour": "https://urlz.li/7b3c2e5a"
}
]
}
}
账户接口
账户链接、上传、点击统计和删除。
/mobile/v1/auth/login.php打开账户会话
将账户凭据换取 Bearer 令牌。
无需身份验证参数
| 参数 | 类型 | 必填 | 默认值 |
|---|---|---|---|
email | 是 | — | |
password | string | 是 | — |
curl -X POST "https://api.urlz.li/mobile/v1/auth/login.php" \
-H "Content-Type: application/json" \
-d '{"email":"developer@example.com","password":"YOUR_PASSWORD"}'
{
"token": "SESSION_TOKEN",
"user": {
"id": 42,
"email": "developer@example.com",
"apiKey": "ACCOUNT_API_KEY",
"planActive": true
}
}
/mobile/v1/shorten.php创建账户链接
创建普通或密码保护链接;使用密码时必须登录。
可选 Bearer 令牌参数
| 参数 | 类型 | 必填 | 默认值 |
|---|---|---|---|
url | URL | 是 | — |
password | string (min. 4) | 否 | — |
curl -X POST "https://api.urlz.li/mobile/v1/shorten.php" \
-H "Authorization: Bearer SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/private","password":"safe-pass"}'
{
"shortUrl": "https://urlz.li/Ab3dE91x",
"destination": "https://example.com/private",
"hash": "Ab3dE91x",
"protected": true
}
/mobile/v1/upload.php上传文件或照片
上传不超过 10 MB 的支持文件并返回短网址。
可选 Bearer 令牌参数
| 参数 | 类型 | 必填 | 默认值 |
|---|---|---|---|
file | multipart file | 是 | — |
kind | photo | document | 否 | document |
password | string (min. 4) | 否 | — |
curl -X POST "https://api.urlz.li/mobile/v1/upload.php" \
-H "Authorization: Bearer SESSION_TOKEN" \
-F "file=@./photo.jpg" \
-F "kind=photo"
{
"shortUrl": "https://urlz.li/P8kLm21q",
"destination": "https://urlz.li/cloud/app/photo_….jpg",
"hash": "P8kLm21q",
"protected": false
}
/mobile/v1/links.php列出账户链接
列出链接、点击、保护和变现状态。
Bearer参数
| 参数 | 类型 | 必填 | 默认值 |
|---|---|---|---|
limit | integer (1–100) | 否 | 100 |
offset | integer | 否 | 0 |
curl "https://api.urlz.li/mobile/v1/links.php?limit=25&offset=0" \
-H "Authorization: Bearer SESSION_TOKEN"
{
"items": [
{
"id": 1204,
"shortUrl": "https://urlz.li/7b3c2e5a",
"destination": "https://example.com/report.pdf",
"protected": false,
"monetized": true,
"clicks": 18
}
],
"total": 42,
"summary": { "totalLinks": 42, "totalClicks": 304, "clicksLast7Days": 28 }
}
/mobile/v1/clicks.php查看点击统计
返回点击、独立访客、国家和访问记录。
Bearer参数
| 参数 | 类型 | 必填 | 默认值 |
|---|---|---|---|
linkId | integer | 是 | — |
limit | integer (1–100) | 否 | 100 |
offset | integer | 否 | 0 |
curl "https://api.urlz.li/mobile/v1/clicks.php?linkId=1204&limit=25" \
-H "Authorization: Bearer SESSION_TOKEN"
{
"link": { "id": 1204, "shortUrl": "https://urlz.li/7b3c2e5a" },
"summary": {
"totalClicks": 18,
"uniqueVisitors": 14,
"clicksLast24Hours": 2,
"clicksLast7Days": 9
},
"countries": [{ "country": "France", "countryCode": "FR", "clicks": 8 }],
"items": []
}
/mobile/v1/delete-link.php删除链接
仅删除已登录账户拥有的链接。
Bearer参数
| 参数 | 类型 | 必填 | 默认值 |
|---|---|---|---|
hash | string | 是 | — |
curl -X DELETE "https://api.urlz.li/mobile/v1/delete-link.php" \
-H "Authorization: Bearer SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"hash":"7b3c2e5a"}'
{
"ok": true,
"message": "Link deleted."
}
URLZ Chat & Request
Add private conversations, collect requested documents, schedule reminders and track submissions.
/mobile/v1/collaboration/configure.phpEnable URLZ Chat or URLZ Request
Attach a private conversation and/or a document request to an existing account link. A Bearer session token or API key is accepted.
Bearer or API key参数
| 参数 | 类型 | 必填 | 默认值 |
|---|---|---|---|
hash | string | 是 | — |
chat.enabled | boolean | 否 | false |
request.enabled | boolean | 否 | false |
request.title | string | 否 | — |
request.items | string[] | 否 | [] |
request.recipients | email[] | 否 | [] |
request.deadline | ISO datetime | 否 | — |
request.paymentRequired | boolean | 否 | false |
curl -X POST "https://api.urlz.li/mobile/v1/collaboration/configure.php" \
-H "Authorization: Bearer SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"hash":"7b3c2e5a","chat":{"enabled":true},"request":{"enabled":true,"title":"Accounting documents","items":["Invoices","Bank statement"]}}'
{"featureId":14,"hash":"7b3c2e5a","chatEnabled":true,"requestEnabled":true}
/mobile/v1/collaboration/chats.phpList link conversations
Return chat-enabled links and message totals. Add id to retrieve messages.
Bearer参数
| 参数 | 类型 | 必填 | 默认值 |
|---|---|---|---|
id | integer | 否 | — |
after | integer | 否 | 0 |
curl "https://api.urlz.li/mobile/v1/collaboration/chats.php?id=14" \
-H "Authorization: Bearer SESSION_TOKEN"
{"items":[{"id":14,"hash":"7b3c2e5a","messageCount":3,"messages":[]}]}
/mobile/v1/collaboration/requests.phpTrack document requests
List requests, expected items, recipients, submissions and secure files. Add id for full detail.
Bearer参数
| 参数 | 类型 | 必填 | 默认值 |
|---|---|---|---|
id | integer | 否 | — |
curl "https://api.urlz.li/mobile/v1/collaboration/requests.php?id=14" \
-H "Authorization: Bearer SESSION_TOKEN"
{"items":[{"id":14,"title":"Accounting documents","recipients":1,"submissions":1,"files":2}]}
付费链接接口
创建付费访问并读取销售数据。
/mobile/v1/monetization/links.php创建或转换付费链接
创建付费网址或转换现有链接。
Bearer参数
| 参数 | 类型 | 必填 | 默认值 |
|---|---|---|---|
destination | URL | 否 | — |
existingLinkId | integer | 否 | — |
title | string (max. 180) | 是 | — |
description | string (max. 3000) | 否 | — |
price | decimal | 是 | — |
currency | EUR | USD | 是 | USD |
accessPolicy | permanent | timed | limited | 否 | permanent |
accessDurationHours | integer (1–8760) | 否 | 24 |
maxAccesses | integer (1–1000) | 否 | 1 |
locale | ISO 639-1 | 否 | en |
curl -X POST "https://api.urlz.li/mobile/v1/monetization/links.php" \
-H "Authorization: Bearer SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"destination":"https://example.com/private-course",
"title":"Private course access",
"description":"One-time access to the course.",
"price":"9.90",
"currency":"EUR",
"accessPolicy":"permanent",
"locale":"en"
}'
{
"id": 91,
"hash": "cd3ed9a4",
"shortUrl": "https://urlz.li/cd3ed9a4",
"paywallUrl": "https://urlz.li/en/pay/cd3ed9a4/",
"converted": false
}
/mobile/v1/monetization/upload.php创建付费文件或照片
私密保存文件并创建付费链接,最大 50 MB。
Bearer参数
| 参数 | 类型 | 必填 | 默认值 |
|---|---|---|---|
file | multipart file | 是 | — |
kind | photo | file | 否 | file |
title | string (max. 180) | 是 | — |
description | string (max. 3000) | 否 | — |
price | decimal | 是 | — |
currency | EUR | USD | 是 | USD |
accessPolicy | permanent | timed | limited | 否 | permanent |
locale | ISO 639-1 | 否 | en |
curl -X POST "https://api.urlz.li/mobile/v1/monetization/upload.php" \
-H "Authorization: Bearer SESSION_TOKEN" \
-F "file=@./premium-photo.jpg" \
-F "kind=photo" \
-F "title=Premium event photo" \
-F "price=4.90" \
-F "currency=EUR"
{
"id": 92,
"hash": "e71f8a20",
"shortUrl": "https://urlz.li/e71f8a20",
"paywallUrl": "https://urlz.li/en/pay/e71f8a20/"
}
/mobile/v1/monetization/links.php列出付费链接
返回付费链接、销售额、毛收入、净收入和状态。
Bearercurl "https://api.urlz.li/mobile/v1/monetization/links.php" \
-H "Authorization: Bearer SESSION_TOKEN"
{
"items": [
{
"id": 91,
"shortUrl": "https://urlz.li/cd3ed9a4",
"kind": "url",
"priceMinor": 990,
"currency": "EUR",
"status": "active",
"sales": 4,
"grossMinor": 3960,
"netMinor": 3374
}
]
}
/mobile/v1/monetization/transactions.php列出付费销售
返回订单、处理费、URLZ 费用、净收入和资金释放日期。
Bearercurl "https://api.urlz.li/mobile/v1/monetization/transactions.php" \
-H "Authorization: Bearer SESSION_TOKEN"
{
"items": [
{
"orderNumber": "LNK-20261102-8F3C21",
"grossMinor": 990,
"platformFeeMinor": 69,
"processorFeeMinor": 45,
"netMinor": 876,
"currency": "EUR",
"status": "paid",
"fundsAvailableAt": "2026-11-16 14:32:10",
"fundsStatus": "held"
}
]
}
错误与 HTTP 状态码
现代接口返回 message,API 密钥接口返回 error。请始终根据 HTTP 状态处理。
{ "message": "A valid link is required." }{ "error": "Invalid API key" }请求已完成。
链接或文件已创建。
JSON 或语法无效。
令牌缺失或已过期。
密钥、套餐或账户无权限。
资源不存在。
请求状态发生冲突。
字段缺失或无效。
降低频率后重试。
稍后以幂等方式重试。
安全与限制
生产集成请遵守以下规则。
- 仅使用 HTTPS。
- 请妥善保管 API 密钥并定期轮换。
- 验证并编码用户提供的参数。
- 列表和日志请求请使用分页。
- 建议上限:每个密钥每秒 10 个请求。
