开发者参考

URLZ.li API 文档

完整介绍身份验证、短链接、文件与照片上传、点击统计和付费链接 API,并提供可直接使用的示例。

01

概览

使用 URLZ API 构建短链接、文件上传、访问统计和付费访问流程。本参考将服务器 API 密钥集成与已登录账户会话分开说明。

服务器到服务器

在后端、自动化或内部工具中使用有效 API 密钥。

apikey=YOUR_API_KEY

账户会话

使用 Bearer 会话管理账户链接、上传、统计和变现。

Authorization: Bearer …
02

快速开始

三步创建第一个短链接,然后查阅完整生产参考。

  1. 1
    创建账户

    打开控制面板并启用 API 套餐。

  2. 2
    复制 API 密钥

    仅保存在服务器上,切勿写入公开代码。

  3. 3
    发送请求

    发送目标地址,并从 JSON 响应读取 result.short_url。

Curl
curl -X POST "https://api.urlz.li/url/create" \
  --data-urlencode "apikey=YOUR_API_KEY" \
  --data-urlencode "fullUrl=https://example.com/private-report"
03

身份验证

URLZ 支持两种身份验证方式,请选择适合的方式。

A

API 密钥

用于后端集成。在 URL 或表单中发送 apikey,密钥和订阅必须有效。

apikey=YOUR_API_KEY
B

Bearer 会话

用于账户功能。从登录接口获取令牌,并在 Authorization 请求头中发送。

Authorization: Bearer SESSION_TOKEN
凭据仅保存在服务器

切勿在浏览器 JavaScript、移动日志、版本控制或公开仓库中发布密钥、密码或令牌。

04

接口索引

选择接口查看参数和请求、响应示例。

05

API 密钥接口

用于创建和搜索短链接的稳定服务器接口。

06

账户接口

账户链接、上传、点击统计和删除。

POST/mobile/v1/auth/login.php

打开账户会话

将账户凭据换取 Bearer 令牌。

无需身份验证

参数

参数类型必填默认值
emailemail是—
passwordstring是—
请求
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
  }
}
POST/mobile/v1/shorten.php

创建账户链接

创建普通或密码保护链接;使用密码时必须登录。

可选 Bearer 令牌

参数

参数类型必填默认值
urlURL是—
passwordstring (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
}
POST/mobile/v1/upload.php

上传文件或照片

上传不超过 10 MB 的支持文件并返回短网址。

可选 Bearer 令牌

参数

参数类型必填默认值
filemultipart file是—
kindphoto | document否document
passwordstring (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
}
GET/mobile/v1/clicks.php

查看点击统计

返回点击、独立访客、国家和访问记录。

Bearer

参数

参数类型必填默认值
linkIdinteger是—
limitinteger (1–100)否100
offsetinteger否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": []
}
07

URLZ Chat & Request

Add private conversations, collect requested documents, schedule reminders and track submissions.

POST/mobile/v1/collaboration/configure.php

Enable 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

参数

参数类型必填默认值
hashstring是—
chat.enabledboolean否false
request.enabledboolean否false
request.titlestring否—
request.itemsstring[]否[]
request.recipientsemail[]否[]
request.deadlineISO datetime否—
request.paymentRequiredboolean否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}
GET/mobile/v1/collaboration/chats.php

List link conversations

Return chat-enabled links and message totals. Add id to retrieve messages.

Bearer

参数

参数类型必填默认值
idinteger否—
afterinteger否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":[]}]}
GET/mobile/v1/collaboration/requests.php

Track document requests

List requests, expected items, recipients, submissions and secure files. Add id for full detail.

Bearer

参数

参数类型必填默认值
idinteger否—
请求
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}]}
08

错误与 HTTP 状态码

现代接口返回 message,API 密钥接口返回 error。请始终根据 HTTP 状态处理。

{ "message": "A valid link is required." }{ "error": "Invalid API key" }
200
成功

请求已完成。

201
已创建

链接或文件已创建。

400
请求无效

JSON 或语法无效。

401
需要身份验证

令牌缺失或已过期。

403
禁止访问

密钥、套餐或账户无权限。

404
未找到

资源不存在。

409
冲突

请求状态发生冲突。

422
验证失败

字段缺失或无效。

429
请求过多

降低频率后重试。

500/503
服务器不可用

稍后以幂等方式重试。

09

安全与限制

生产集成请遵守以下规则。

  • 仅使用 HTTPS。
  • 请妥善保管 API 密钥并定期轮换。
  • 验证并编码用户提供的参数。
  • 列表和日志请求请使用分页。
  • 建议上限:每个密钥每秒 10 个请求。
需要集成帮助?

请提供接口、HTTP 状态和已删除凭据的请求示例。

URLZ iPHONE 版

全新 iOS 版本即将推出

新版 URLZ iPhone 应用正在进行最后完善,并将在未来几天内登陆 App Store。感谢您的耐心等待。