API скорочувача посилань: автоматизація коротких лінків

Робити посилання руками нормально рівно доти, доки це нормально. Щойно кожному замовленню потрібне посилання для відстеження, кожному користувачу — реферальне, а кожному оголошенню — QR-код, те саме доводиться робити програмно. Для цього й існує API скорочувача посилань — і поверхня в нього така невелика, що прикрутити його встигаєш за чашкою кави.

Що можна автоматизувати

• Посилання на замовлення чи на користувача, які створюються тієї миті, коли потрібні.
• Масові посилання для кампаній — по одному на канал, згенеровані з таблиці в циклі, а не вручну.
• QR-коди на льоту для квитків, рахунків, етикеток і накладних.
• Дані про кліки, підтягнуті у власну панель, щоб цифри жили там, куди ваша команда й так дивиться.

Якщо ви ще не певні, чи потрібен вам API, чесний тест — це обсяг і повторюваність: робите те саме в браузері частіше ніж кілька разів на тиждень — автоматизуйте.

Авторизація

Візьміть ключ на сторінці акаунта й надсилайте його заголовком X-Api-Key у кожному запиті. Два правила, які не обговорюються: тримайте ключ на сервері — усе, що потрапляє у фронтендний JavaScript, є публічним, а злитий ключ дозволяє чужим людям створювати посилання від вашого імені — і негайно ротуйте його, якщо він бодай раз опинився в репозиторії чи в логах.

Створення посилання

Один POST на /api/getLink.json з адресою призначення. Тим самим викликом можна передати аліас, режим, термін дії та пароль:

curl -X POST https://urlik.xyz/api/getLink.json -H "X-Api-Key: YOUR_KEY" -d "url=https://example.com/very/long/path" -d "alias=spring-sale"

У відповідь приходить JSON із коротким URL, адресою його QR і адресою його статистики. Посилання, створені з ключем, прив'язані до вашого акаунта: вони видно в кабінеті, і їх можна редагувати згодом.

Деталь, яку варто знати до того, як писати код: аліас унікальний у межах усього сервісу. Якщо spring-sale вже зайнятий, ви отримаєте помилку, а не тихий запасний варіант. Тож або обробляйте цей випадок, або додавайте до аліасів власний префікс (acme-spring-sale).

Генерація QR-коду

GET /api/qr.json приймає дані плюс необов'язкові format, fg, bg, ecc і size та повертає QR. Наводьте його на коротке посилання, а не на сирий довгий URL: код вийде чистішим і міцнішим, а адресу призначення можна буде редагувати потім. Це патерн динамічного QR-коду, зроблений із вашого бекенду.

Читання статистики

GET /api/stats.json повертає підсумки, часовий ряд, реферери, пристрої та країни для посилання — ті самі числа, що й на сторінці статистики, але у вигляді, придатному для вашої власної адмінки.

Опитуйте його за розкладом, а не на кожне завантаження сторінки. Статистика кліків — не система обліку реального часу, а довбати ендпоїнт заради перемальовування графіка, на який ніхто не дивиться, — найпростіший спосіб познайомитися з обмежувачем частоти.

Зробіть так, щоб воно не ламалося о третій ночі

Ендпоїнти прості; падають ті інтеграції, які вважають, що нічого ніколи не піде не так. Чотири звички, які окупаються:

• Завжди перевіряйте відповідь. Кожен виклик повертає статус — читайте його. Класичний баг: припустити успіх і зберегти тіло помилки так, ніби це коротке посилання, а потім виявити його на надрукованому рахунку.
• Ніколи не тримайте користувача заручником посилання. Якщо скорочення відбувається всередині оформлення замовлення, повільний API стає повільним чекаутом. Виносьте це у фонову задачу або відкочуйтеся на довгий URL і повторюйте спробу пізніше. Довгий URL працює завжди — це ваша страховка.
• Кешуйте те, що не змінюється. Ту саму адресу не треба скорочувати двічі — збережіть короткий URL поруч із вихідним записом і використовуйте повторно. Дешевше, швидше, а кабінет лишається читабельним.
• Відступайте на помилках. Повторюйте спробу зі зростаючими паузами, а не в щільному циклі. Обмеження частоти, у відповідь на яке влаштували шторм ретраїв, лишається обмеженням частоти.

Де API закінчується

Дві чесні межі. Обмеження частоти існують, і «щедро» не означає «нескінченно» — пакетні задачі треба ритмізувати, а не запускати залпом. І ще: API створює посилання, але не вирішує, що в них має бути. Мітьте посилання UTM-параметрами під час створення (див. гід з UTM), інакше ви автоматизуєте виробництво тисяч посилань, які потім не розрізните в аналітиці, — а це гірше, ніж робити все руками.

Коротко

Один ендпоїнт на створення, один на QR, один на статистику, заголовок на авторизацію. Тримайте ключ на сервері, перевіряйте кожну відповідь, виносьте роботу з критичного шляху, кешуйте повторюване й мітьте одразу під час створення. Повний перелік параметрів, коди помилок і приклади живуть у документації API; якщо спершу хочете концептуального підґрунтя, почніть із того, що таке скорочувач посилань.