Текущая версия: v1
API «Ту.Клик» представляет собой REST-подобный набор методов, позволяющий программно управлять ссылками и другими ресурсами сервиса с помощью запросов в формате JSON по HTTP-протоколу.
Клиент взаимодействует с сервером по https-протоколу посредством набора методов, доступность которых определяется токеном, указываемом в заголовках каждого запроса.
В настоящий момент поддерживаются заголовки Accept: application/json
, Content-Type: application/json
, X-Auth-Token: <ваш_токен>
, другие заголовки будут проигнорированы, а в последующих версиях вызовут ошибку.
Все ответы возвращаются в виде JSON-структуры за исключением случаев, когда в этом нет необходимости, например, после удаления ссылки, тогда посылается только HTTP-заголовок c кодом состояния запроса и поясняющей фразой.
URL для запросов конструируется следующим образом: https://to.click/api/v1/links
https
to.click
api
v1
links
Старайте указывайть URL в нижнем регистре. Наличие завершающие слешей на текущий момент не имеет значения, но с практической точки зрения лучше не использовать их, так вы сэкономите один редирект.
Для аутентификации используется токен, передаваемый в заголовке запроса X-Auth-Token: <ваш_токен>
. Получить доступ к генерации токенов вы можете в личном кабинете в разделе «API токены».
Токен указывается для каждого запроса и определяет уровнь доступа к API. В случае если доступ отсутствует по причине истечения подписки, вы получите ответ с HTTP-кодом 402
, но если токен по каким-то причинам отозван, тогда код ответа будет 403
.
Вместе с ответом на запрос API также возвращает HTTP статус коды, включая коды ошибок. В случае возникновения проблем статус код будет содержать код ошибки, а тело ответа дополнительную информацию о проблеме.
Код | Обозначение | Описание |
---|---|---|
200 | Запрос обработан | Запрос был корректно разобран и выполнен без синтаксических ошибок. |
204 | Запрос обработан | Запрос успешен, но тело сообщения отсутствует. Например, при удалении какого-либо ресурса. |
400 | Ошибка в запросе | Запрос не разобран из-за синтаксической ошибки в теле запроса. |
402 | Требуется оплата | Запрос отклонен из-за истечения срока действия подписки на тарифный план. |
403 | Запрос отклонен | Запрос отклонен из-за ограничения доступа к API. Возможно, токен был отозван. |
404 | Ресурс не найден | Запрос успешно выполнен, но требуемого ресурса не существует. Возможно, токен от другого аккаунта. |
405 | Метод не разрешен | Запрос не выполнен из-за обращения к несуществующему методу. |
406 | Ресурс недоступен | Нам пришлось заблокировать ресурс, работа с ним невозможна. |
429 | Лимит превышен | Вы превысили лимит обращений к API, определенный вашим тарифным планом. |
50x | Ошибка сервера | Запрос не может быть выполнен из-за внутренней ошибки сервера. |
В случае если ошибка относится к ошибкам заполнения полей, то в ответе возвращается HTTP-код 200
с телом, в котором присутствует объект errors
, содержащий перечень атрибутов с описанием ошибок.
Пример:
{
"errors": {
"short_url": [
"has already been taken"
],
"web_url": [
"should be filled"
]
}
}
В случае если объем данных превышает лимит, который клиент способен обработать, используется разбивка на страницы. Для удобства навигации вы можете самостоятельно указать в запросе параметры разбивки:
page
— числовое значение, определяющее порядковый номер страницы данных.perpage
— числовое значение, определяющее количество данных на одной странице.GET
https://to.click/api/v1/health
Метод предназначен для регулярной проверки работоспособности API. В ответе возвращается ключ time
, содержащий текущее значение времени на сервере в UTC в формате Unix timestamp.
Пример запроса:
curl --request GET \
--url 'https://to.click/api/v1/health' \
--header 'Content-Type: application/json' \
--header 'X-AUTH-TOKEN: <ваш токен>'
Пример ответа:
{
"time": 1610155745148
}
«Ссылка» в данном контексте означает сокращенную (короткую) ссылку. Вы можете создавать, удалять, обновлять и получать информацию о ваших ссылках в соответствии с тарифным планом вашего аккаунта.
POST
https://to.click/api/v1/links
Тело запроса:
{
"data":{
"type":"link",
"attributes":{
"short_url":"short_word",
"web_url":"my-shop.buy",
"domain_id":1,
"kind_of":"short",
"pixel_ids":[
1
]
}
}
}
Перечень возможных атрибутов запроса:
Атрибут | Тип | Описание | Обязательный |
---|---|---|---|
short_url | Строка | Короткое слово: от 5 до 30 символов | Нет (будет сгенерирован автоматически) |
web_url | Строка | Целевой ресурс для перехода Desktop-пользователя | Да |
ios_url | Строка | Целевой ресурс для перехода Android-пользователя | Нет если указан web_url или android_url |
android_url | Строка | Целевой ресурс для перехода iOS-пользователя | Нет если указан ios_url или web_url |
domain_id | Целое число | Идентификатор домена, подключенного к аккаунту | Нет (будет использован домен по-умолчанию) |
kind_of | Строка | Тип ссылки: target или short | Нет (будет использован short по-умолчанию) |
pixel_ids | Массив целых чисел | Перечень идентификаторов ранее созданных пикселей | Нет |
Тело ответа:
{
"data":{
"id":"13473139",
"type":"link",
"attributes":{
"full_url":"https://clc.to/dPr4Xg",
"short_url":"dPr4Xg",
"web_url":"https://to.click",
"ios_url":null,
"android_url":null,
"created_at":"2021-08-10T20:47:34.860Z",
"kind_of":"target",
"domain_id":1,
"pixel_ids":[]
}
}
}
Пример запроса:
curl --request POST \
--url 'https://to.click/api/v1/links' \
--header 'Content-Type: application/json' \
--header 'X-AUTH-TOKEN: <ваш_токен>' \
--data '{ "data": { "type": "link", "attributes": { ... } }}'
GET
https://to.click/api/v1/links/<id>
Чтобы получить детальную информацию о ссылке, необходимо отправить GET запроc на URL, последний сегмент которого содержит идентификатор ссылки. В ответ вернется структура data, содержащая полную информацию о атрибутах ссылки.
Пример запроса:
curl --request GET \
--url 'https://to.click/api/v1/links/123456' \
--header 'Content-Type: application/json' \
--header 'X-AUTH-TOKEN: <ваш_токен>'
Тело ответа:
{
"data":{
"id":"13473139",
"type":"link",
"attributes":{
"full_url":"https://clc.to/dPr4Xg",
"short_url":"dPr4Xg",
"web_url":"https://to.click",
"ios_url":null,
"android_url":null,
"created_at":"2021-08-10T20:47:34.860Z",
"kind_of":"target",
"domain_id":1,
"pixel_ids":[]
}
}
}
PUT
https://to.click/api/v1/links/<id>
Обновление ссылки осуществляется аналогично созданию: запрос отправляется методом PUT
на URL, последним сегментом которого является идентификатор ссылки. В теле запросе указываются атрибуты, которые необходимо обновить (числовой идентификатор ссылки обновить нельзя). В ответ также всегда возвращается полный набор атрибутов обновленной ссылки.
Пример запроса:
curl --request POST \
--url 'https://to.click/api/v1/links/123456' \
--header 'Content-Type: application/json' \
--header 'X-AUTH-TOKEN: <ваш_токен>' \
--data '{ "data": { "type": "link", "attributes": { "short_url": "updated_short_link" } }}'
DELETE
https://to.click/api/v1/links/<id>
Удаление ссылки осуществляется с помощью отправки запроса методом DELETE
на URL, последним сегментом которого является идентификатор ссылки. После успешного удаления ссылки возвращается HTTP-код 204
и пустое тело ответа.
Пример запроса:
curl --request DELETE \
--url 'https://to.click/api/v1/links/123456' \
--header 'Content-Type: application/json' \
--header 'X-AUTH-TOKEN: <ваш токен>'
GET
https://to.click/api/v1/links
Чтобы получить список ссылок необходимо отправить GET
-запрос к методу API links
. В теле ответа вернется структура с ключем data
, содержащая массив объектов существующих ссылок.
Пример запроса:
curl --request GET \
--url 'https://to.click/api/v1/links' \
--header 'Content-Type: application/json' \
--header 'X-AUTH-TOKEN: <ваш токен>'
Пример ответа:
{
"data":[
{
"id":"13473139",
"type":"link",
"attributes":{
"full_url":"https://clc.to/dPr4Xg",
"short_url":"dPr4Xg",
"web_url":"https://to.click",
"ios_url":null,
"android_url":null,
"created_at":"2021-08-10T20:47:34.860Z",
"kind_of":"target",
"domain_id":1,
"pixel_ids":[]
}
},
{ ... }
]
}
«Домены» в данном контексте означают подключенные к аккаунту или общедоступные домены сервиса, с помощью которых можно создавать ссылки. В настоящий момент доступен только просмотр информации о доменах. Создание, обновление и удаление через API не предусмотрено.
GET
https://to.click/api/v1/domains
Чтобы получить список доменов необходимо отправить GET
-запрос к методу API domains
. В теле ответа вернется структура с ключем data
, содержащая массив объектов существующих доменов.
Перечень атрибутов домена:
Атрибут | Тип | Описание |
---|---|---|
id | Целое число | Идентификтор домена |
cert_expires | Строка | Дата окончания действия SSL-сертификата |
root_page | Строка | Ссылка, на которую осуществляется редирект при переходе в корень домена |
not_found_page | Строка | Ссылка, на которую осуществляется редирект при переходе на несуществующую короткую ссылку |
full_name | Строка | Полное имя домена включая поддомены |
Пример запроса:
curl --request GET \
--url 'https://to.click/api/v1/domains' \
--header 'Content-Type: application/json' \
--header 'X-AUTH-TOKEN: <ваш токен>'
Пример ответа:
{
"data":[
{
"id":"86",
"type":"domain",
"attributes":{
"id":86,
"cert_expires":"2021-08-10 00:00:00",
"root_page":"https://to.click",
"not_found_page":"https://to.click/404.html",
"full_name":"https://clc.am"
}
},
{ ... }
]
}
GET
https://to.click/api/v1/domains/<id>
Чтобы получить детальную информацию о ссылке необходимо отправить GET
-запроc на URL, последний сегмент которого содержит идентификатор домена. В ответ вернется структура data
, содержащая полную информацию об атрибутах домена.
Пример запроса:
curl --request GET \
--url 'https://to.click/api/v1/domains/86' \
--header 'Content-Type: application/json' \
--header 'X-AUTH-TOKEN: <ваш токен>'
Пример ответа:
{
"data": {
"id": "86",
"type": "domain",
"attributes": {
"id":86,
"cert_expires":"2021-08-10 00:00:00",
"root_page":"https://to.click",
"not_found_page":"https://to.click/404.html",
"full_name":"https://clc.am"
}
}
}
«Пиксель» — это фрагмент кода внешней рекламной системы, добавляемый при создании или редактировании короткой ссылки. Пиксель используется в механизме ретаргетинга, помечая пользователя, который перешел по ссылке для того, чтобы в дальнейшем показать ему рекламу.
POST
https://to.click/api/v1/pixels
Чтобы добавить пиксель необходимо отправить POST
-запроc к методу API pixels
. В ответ вернется структура data
, содержащая полную информацию о созданном пикселе.
Перечень атрибутов пикселя:
Атрибут | Тип | Описание |
---|---|---|
name | Строка | Название пикселя |
pixel_text | Строка | Код пикселя |
Пример запроса:
curl --request POST
--url https://to.click/api/v1/pixels \
--header 'Content-Type: application/json' \
--header 'X-AUTH-TOKEN: <ваш токен>' \
--data '{ "data": { "type": "pixel", "attributes": { "name": "VK", "pixel_text": "<javascript>...</javascript>" } }}'
Пример ответа:
{
"data": {
"id": "1",
"type": "pixel",
"attributes": {
"name": "VK",
"pixel_text": "<javascript>...</javascript>",
"created_at": "2018-03-01T15:34:46.362+03:00"
}
}
}
PUT
https://to.click/api/v1/pixels/<id>
Обновление пикселя осуществляется аналогично созданию: запрос отправляется методом PUT
на URL, последним сегментом которого является идентификатор пикселя. В теле запроса указываются атрибуты, которые необходимо обновить (числовой идентификатор пикселя обновить нельзя). В ответ возвращается полный набор атрибутов обновленного пикселя.
Пример запроса:
curl --request PUT \
--url https://to.click/api/v1/pixels/1 \
--header 'Content-Type: application/json' \
--header 'X-AUTH-TOKEN: <ваш токен>' \
--data '{ "data": { "type": "pixel", "attributes": { "pixel_text": "<javascript>...</javascript>" } }}'
Пример ответа:
{
"data": {
"id": "1",
"type": "pixel",
"attributes": {
"name": "VK",
"pixel_text": "<javascript>...</javascript>",
"created_at": "2018-03-01T15:34:46.362+03:00"
}
}
}
GET
https://to.click/api/v1/pixels/<id>
Чтобы получить детальную информацию о пикселе необходимо отправить GET
-запроc на URL, последний сегмент которого содержит идентификатор пикселя. В ответ вернется структура data
, содержащая полную информацию об атрибутах пикселя.
Пример запроса:
curl --request GET \
--url https://to.click/api/v1/pixels/1 \
--header 'Content-Type: application/json' \
--header 'X-AUTH-TOKEN: <ваш токен>'
Пример ответа:
{
"data": {
"id": "1",
"type": "pixel",
"attributes": {
"name": "Test pixel",
"pixel_text": "<javascript>...</javascript>",
"created_at": "2018-03-01T15:34:46.362+03:00"
}
}
}
DELETE
https://to.click/api/v1/pixels/<id>
Удаление ссылки осуществляется с помощью отправки запроса методом DELETE
на URL, последним сегментом которого является идентификатор пикселя. После успешного удаления пикселя возвращается HTTP-код 204
и пустое тело ответа.
Пример запроса:
curl --request DELETE \
--url 'https://click.to/api/v1/pixels/1' \
--header 'Content-Type: application/json' \
--header 'X-AUTH-TOKEN: <ваш токен>'
GET
https://to.click/api/v1/pixels
Чтобы получить список ссылок необходимо отправить GET
-запрос к методу API pixels
. В теле ответа вернется структура с ключем data
, содержащая массив объектов существующих пикселей.
Пример запроса:
curl --request PUT \
--url 'https://to.click/api/v1/pixels/1' \
--header 'Content-Type: application/json' \
--header 'X-AUTH-TOKEN: <ваш токен>' \
--data '{ "data": { "type": "pixel", "attributes": { "pixel_text": "<javascript>...</javascript>" } }}'
Пример ответа:
{
"data": [
{
"id": "1",
"type": "pixel",
"attributes": {
"name": "Test pixel",
"pixel_text": "<javascript>...</javascript>",
"created_at": "2018-03-01T15:34:46.362+03:00"
}
},
{
"id": "2",
"type": "pixel",
"attributes": {
"name": "Test pixel 2",
"pixel_text": "<javascript>...</javascript>",
"created_at": "2018-03-01T15:43:10.894+03:00"
}
}
]
}
Статистика — это объем данных, накапливаемый для каждой ссылки отдельно и для аккаунта в целом. Вы можете запрашивать как сводную информацию, так и отдельные срезы по каждой ссылке вашего аккаунта, но не можете изменять их.
Сводная информация содержит агрегированные данные по конкретной ссылке.
GET
https://to.click/api/v1/links/<id>/stat
Пример запроса:
curl --request GET \
--url 'https://to.click/api/v1/links/<id>/stat' \
--header 'Content-Type: application/json' \
--header 'X-AUTH-TOKEN: <ваш токен>'
Пример ответа:
{
"data": {
"clicks": 153,
"countries": 21,
"referers": 3,
"platforms": 7,
"languages": 10,
"sharings": 1
}
}
Метод возвращает количество переходов по конкретной ссылке, сгруппированных по дате. Данные отсортированы по дате по убывающей: от наиболее поздней к наиболее ранней.
GET
https://to.click/api/v1/links/<id>/stat/clicks
Пример запроса:
curl --request GET
--url https://to.click/api/v1/links/<id>/stat/clicks
--header 'Content-Type: application/json'
--header 'X-AUTH-TOKEN: <ваш токен>'
Пример ответа:
{
"data": {
"clicks": {
"2022-02-08": 24,
"2022-02-07": 28,
"2022-02-06": 25,
"2022-02-05": 20,
"2022-02-04": 23,
"2021-07-09": 19,
"2021-07-08": 13,
"2019-12-19": 1,
"2019-03-03": 2
}
}
}
Метод возвращает количество переходов по конкретной ссылке, сгруппированный по странам, из которых был осуществлен переход. Страны указываются в виде двух символов по стандарту ISO 3166-1 alpha-2 и отсортированны по количеству переходов по убывающей.
GET
https://to.click/api/v1/links/<id>/stat/countries
Пример запроса:
curl --request GET \
--url https://to.click/api/v1/links/<id>/stat/countries \
--header 'Content-Type: application/json' \
--header 'X-AUTH-TOKEN: <ваш токен>'
Пример ответа:
{
"data": {
"countries": {
"NL": 4311,
"CN": 2551,
"US": 461,
"HK": 134,
"MY": 25,
"CA": 16,
"RU": 15,
"JP": 8,
"DE": 6,
"FR": 2,
"GB": 2,
"UA": 1,
"RO": 1,
"HU": 1,
"LV": 1,
"TH": 1,
"IE": 1
}
}
}
Метод возвращает список рефереров, усеченных до хоста и отсортированных по количеству переходов по убыванию.
GET
https://to.click/api/v1/links/<id>/stat/referers
Пример запроса:
curl --request GET \
--url 'https://to.click/api/v1/links/<id>/stat/referers' \
--header 'Content-Type: application/json' \
--header 'X-AUTH-TOKEN: <ваш токен>' \
Пример ответа:
{
"data": {
"referers": {
"bing.com": 4,
"google.com": 3,
"youtu.be": 1,
}
}
}
Метод возвращает список платформ, отсортированных по количеству переходов по убыванию.
GET
https://to.click/api/v1/links/<id>/stat/platforms
Пример запроса:
curl --request GET \
--url 'https://to.click/api/v1/links/<id>/stat/platforms' \
--header 'Content-Type: application/json' \
--header 'X-AUTH-TOKEN: <ваш токен>' \
Пример ответа:
{
"data": {
"platforms": {
"Mac": 156,
"GNU/Linux": 43,
"Ubuntu": 8,
"iOS": 6,
"FreeBSD": 3,
"Fedora": 2,
}
}
}
Метод возвращает список предпочитаемых языков браузера пользователя, отсортированных по количеству переходов по убыванию.
GET
https://to.click/api/v1/links/<id>/stat/languages
Пример запроса:
curl --request GET \
--url 'https://to.click/api/v1/links/<id>/stat/languages' \
--header 'Content-Type: application/json' \
--header 'X-AUTH-TOKEN: <ваш токен>' \
Пример ответа:
{
"data": {
"platforms": {
"RU": 2957,
"EN": 20,
"NL": 1
}
}
}
Метод возвращает список роботов, которые запрашивали ссылку.
GET
https://to.click/api/v1/links/<id>/stat/sharings
Пример запроса:
curl --request GET \
--url 'https://to.click/api/v1/links/<id>/stat/sharings' \
--header 'Content-Type: application/json' \
--header 'X-AUTH-TOKEN: <ваш токен>' \
Пример ответа:
{
"data": {
"sharings": {
"Petal Bot": 22,
"Generic Bot": 14,
"BingBot": 7,
}
}
}