СПРАВОЧНИК РАЗРАБОТЧИКА

Документация API URLZ.li

Аутентификация, короткие ссылки, загрузка файлов и фото, статистика кликов и API платных ссылок с готовыми примерами.

01

Обзор

Создавайте короткие ссылки, загрузки, статистику и платный доступ через API URLZ. Здесь отдельно описаны серверные интеграции по API-ключу и авторизованные сессии аккаунта.

Сервер-сервер

Используйте активный ключ в backend, автоматизации или внутреннем инструменте.

apikey=YOUR_API_KEY

Сессия аккаунта

Используйте Bearer для ссылок, загрузок, статистики и монетизации.

Authorization: Bearer …
02

Быстрый старт

Создайте первую короткую ссылку за три шага, затем используйте полную справку.

  1. 1
    Создайте аккаунт

    Откройте панель и активируйте тариф API.

  2. 2
    Скопируйте API-ключ

    Храните его на сервере, а не в открытом коде.

  3. 3
    Отправьте запрос

    Передайте адрес и прочитайте result.short_url из JSON.

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-ключ

Для backend. Передайте apikey в URL или форме; ключ и подписка должны быть активны.

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 МБ.

Необязательный 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 в ближайшие дни. Спасибо за ваше терпение.