Интеграция по API

Введение

Клиент взаимодействует с сервером по 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 — числовое значение, определяющее количество данных на одной странице.

Состояние API

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,
    }
  }
}

Service API API Сервиса

Введение

Аутентификация

Коды ответов

Ошибки валидации

Постраничное разбиение

Состояние API

Ссылки

Создание ссылки

Детальная информация о ссылке

Обновление ссылки

Удаление ссылки

Список ссылок

Домены

Список доменов

Детальная информация о домене

Пиксели

Создание пикселя

Обновление пикселя

Детальная информация о пикселе

Удаление пикселя

Список пикселей

Статистика

Сводная информация

Переходы

Страны

Рефереры

Платформы

Языки

Шеринги (трафик роботов)