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

Простой JSON-API для создания коротких ссылок с быстрым редиректом, опциональным промежуточным шагом и PNG-QR.

Обзор API

Базовый URL: https://pth.bz

Эндпоинт

POST https://pth.bz/api/shorten

Content-Type: application/json

Запрос

Body JSON:

{
                                                                          "url": "https://example.com/landing?utm_source=newsletter"
                                                                        }

Ответ

200 OK:

{
                                                                          "short_url_301": "https://pth.bz/AbC1234",
                                                                          "short_url_js": "https://pth.bz/i/AbC1234",
                                                                          "qr_301_png_url": "https://pth.bz/?qr=AbC1234",
                                                                          "qr_js_png_url": "https://pth.bz/?qi=AbC1234"
                                                                        }

Прочие статусы

400 Bad Request - неверный JSON, отсутствует url или неверный URL.
405 Method Not Allowed - используйте POST.
429 Too Many Requests - превышен лимит.
500 Internal error - внутренняя ошибка.

Выбор редиректа

Прямой (по умолчанию)

Быстрый прямой редирект: /CODE

Промежуточная (анти-бот)

Короткий JS-шаг и скрыт реферер: /i/CODE

QR-коды (PNG)

For 301: /?qr=CODE
For interstitial: /?qi=CODE
Необязательный размер в пикселях: (200–2048) &px=640

<img src="https://pth.bz/?qr=AbC1234&px=640" alt="QR" />

Ответы об ошибках

{
                                                                          "error": "Too many requests"
                                                                        }

Лимиты и правила

Лимит: 30 запросов за 10 минут на IP (HTTP 429 при превышении).
Разрешены только http:// и https://.
Максимальная длина URL: 2000 символов.
Только JSON: установите Content-Type: application/json.

Примеры

curl

curl -X POST "https://pth.bz/api/shorten" \
                                                                          -H "Content-Type: application/json" \
                                                                          -d '{"url": "https://example.com"}'

JavaScript (fetch)

const res = await fetch('https://pth.bz/api/shorten', {
                                                                          method: 'POST',
                                                                          headers: { 'Content-Type': 'application/json' },
                                                                          body: JSON.stringify({ url: 'https://example.com' })
                                                                        });
                                                                        const data = await res.json();
                                                                        console.log(data.short_url_301, data.short_url_js);

Python (requests)

import requests

                                                                        r = requests.post('https://pth.bz/api/shorten', json={'url': 'https://example.com'})
                                                                        print(r.status_code, r.json())

SDK

Python SDK

Официальная Python-библиотека для работы с Простой сократитель ссылок.

Установка

pip install pthbz

PyPI GitHub

Быстрый старт (синхронно)

from pthbz import PthBzClient

                                                                        client = PthBzClient(base_url="https://pth.bz")
                                                                        res = client.shorten("https://example.com/landing?utm_source=newsletter")
                                                                        print(res.short_url_301)   # https://pth.bz/AbC1234
                                                                        print(res.short_url_js)    # https://pth.bz/i/AbC1234
                                                                        print(res.qr_301_png_url)  # https://pth.bz/?qr=AbC1234
                                                                        print(res.qr_js_png_url)   # https://pth.bz/?qi=AbC1234
                                                                        client.close()

Асинхронный вариант

import asyncio
                                                                        from pthbz import AsyncPthBzClient

                                                                        async def main():
                                                                            async with AsyncPthBzClient(base_url="https://pth.bz") as client:
                                                                                res = await client.shorten("https://example.com")
                                                                                print(res.short_url_301)

                                                                        asyncio.run(main())

Валидатор URL в библиотеке совпадает с серверными правилами: только http/https, без userinfo, допускаются localhost и IP без точки, IDN → punycode.