Как подключить API-методы для работы с персональными списками

 

API для управления Персональными списками. Интерфейс для работы доступен по ссылке cleantalk.org/my/show_private инструкция к интерфейсу cleantalk.org/ru/help/blacklist-usage

 

Содержание:

Общие сведения API методы для работы с персональными списками

Метод private_list_get API методы для работы с персональными списками

Метод private_list_add API методы для работы с персональными списками

Метод private_list_delete API методы для работы с персональными списками

Метод private_list_update API методы для работы с персональными списками

Общие сведения

Протокол - https

Имя хоста - api.cleantalk.org

Метод private_list_get

Входные параметры

Методы передачи параметров GET и POST

 

Обязательные

method_name допустимые значения: private_list_get

user_token допустимые значения: можно получить в ПУ на странице профиля пользователя

service_type допустимые значения: antispam, spamfirewall, securityfirewall

Пример:

https://api.cleantalk.org/?method_name=private_list_get&user_token=USER_TOKEN&service_type=antispam

 

Необязательные

service_id фильтрация списка по указанному сайту, значение можно получить на главной ПУ Анти-Спам или главной ПУ Безопасность сайта

Пример:

https://api.cleantalk.org/?method_name=private_list_get&user_token=USER_TOKEN&service_type=antispam&service_id=314956

record_type фильтрация списка по типу записи, допустимые значения:

  • для service_type=antispam - 1, 2, 3, 4, 5, 7, 8, 9
  • для service_type=spamfirewall - 6, 10
  • для service_type=securityfirewall - 1, 3, 7

Пример:

https://api.cleantalk.org/?method_name=private_list_get&user_token=USER_TOKEN&service_type=antispam&record_type=1

record_ids фильтрация списка по record ID

  • Массив данных, например record_ids[]=3985411&record_ids[]=3985397
  • Строка, с разделителем запятой, например record_ids=3985411,3985397

status фильтрация списка по статусу записи, допустимые значения: allow, deny

created[lte] и created[gte] фильтрация списка по дате создания записи, допустимые значения: время в формате unix timestamp

updated[lte] и updated[gte] фильтрация списка по дате обновления записи, допустимые значения: время в формате unix timestamp

search[value] поиск по полю record, полное или частичное совпадение

start смещение для первой записи списка, 0 по умолчанию

length ограничение количества записей в ответе, 100 по умолчанию, допустимые значения: 10, 25, 50, 100

order[0][dir] направление сортировки записей в списке, допустимые значения: asc, desc

order[0][column] индекс поля, по которому происходит сортировка записей

columns[0][data] название поля для сортировки записей, допустимые значения: record, record_type, created, updated, hits, status, product_id, hostname, note

draw произвольное значение, будет передано в ответе, для асинхронных запросов.

mode если значение csv, ответ в виде csv файла

Пример:

https://api.cleantalk.org/?method_name=private_list_get&user_token=USER_TOKEN&service_type=antispam&mode=csv

Выходные параметры

recordsTotal кол-во записей без учета фильтрации

recordsFiltered кол-во записей с учетом фильтрации

draw произвольное значение, это значение из входных параметров

data массив записей:

  • record_id идентификатор записи
  • service_id идентификатор сайта
  • hostname имя хоста сайта
  • record значение записи
  • countrycode код страны
  • countryname название страны
  • hits кол-во хитов за последние 7 дней
  • created время создания записи
  • updated время обновления записи
  • status статус записи
  • record_type тип записи
  • product_id тип продукта
  • note заметка записи
  • expired срок жизни записи

Пример:

https://api.cleantalk.org/?method_name=private_list_get&user_token=USER_TOKEN&draw=10&columns[0][data]=hits&columns[1][data]=record&columns[2][data]=record_type&columns[3][data]=created&order[0][column]=3&order[0][dir]=asc&start=0&length=10&service_type=antispam&service_id=314956&record_type=1
{"data":[{"record_id":"3689885","service_id":"314956","hostname":"example.com","record":"1.2.3.3","countrycode":"US","countryname":"United States","hits":null,"created":"2019-10-28 12:14:41","updated":"2019-10-28 12:14:41","status":"deny","record_type":"1","product_id":"1","note":"123","expired":null},{"record_id":"3890626","service_id":"314956","hostname":"example.com","record":"1.2.3.4","countrycode":"US","countryname":"United States","hits":null,"created":"2019-11-19 15:19:26","updated":"2019-11-19 15:19:26","status":"deny","record_type":"1","product_id":"1","note":"","expired":null}],"draw":"10","recordsTotal":"8","recordsFiltered":"2","currentPage":0}

Возможные ошибки

https://api.cleantalk.org/?method_name=private_list_get
{"data":{"result":"FAIL","notice":"User token not found","operation_code":"51"}}

 

https://api.cleantalk.org/?method_name=private_list_get&user_token=USER_TOKEN
{"data":{"result":"FAIL","notice":"service_type is required and value must be in (antispam,spamfirewall,securityfirewall)","operation_code":"31"}}

Метод private_list_add

Входные параметры

 

Обязательные

method_name допустимые значения: private_list_add

user_token допустимые значения: можно получить в ПУ на странице профиля пользователя

service_id идентификатор сайта, all для добавления на все сайты аккаунта

service_type тип сервиса, допустимые значения: antispam, spamfirewall, securityfirewall

product_id идентификатор продукта, допустимые значения: 1 для service_type=antispam или service_type=spamfirewall, 4 для service_type=securityfirewall

record_type тип записи, допустимые значения:

  • для service_type=antispam:
    • 1 IP-адрес
    • 2 E-mail
    • 3 Страна
    • 4 Домен
    • 5 Домен 1 уровня
    • 7 IP-сеть
    • 8 Стоп слово
    • 9 Язык
  • для service_type=spamfirewall:
    • 6 IP-сеть
    • 10 Страна
  • для service_type=securityfirewall:
    • 1 IP-адрес
    • 3 Страна
    • 7 IP-сеть

records

  • Массив данных, например records[]=192.168.1.1&records[]=192.168.1.2
  • Строка, с разделителем запятой, например records=192.168.1.1,192.168.1.2
  • Файл в csv формате

 

Пример:

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1&records=192.168.1.1
{"data":{"records":[{"record_id":3985397,"record":"192.168.1.1","created":"2019-12-13 18:08:41","updated":"2019-12-13 18:08:41","service_id":"314956","service_type":"antispam","record_type":"1","product_id":"1","status":"deny","note":"","expired":"","countrycode":"","operation_status":"SUCCESS"}]}}

 

Необязательные

note заметка для записи, не более 2048 знаков

status статус записи, допустимые значения: allow, deny (значение по умолчанию), deny_except (доступно только для стран, исключает все кроме указанной)

expired строка с датой на английском языке, время жизни записи

Пример:

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1&records=192.168.1.2&status=allow&note=note&expired=2019-12-13 17:10:00
{"data":{"records":[{"record_id":3985411,"record":"192.168.1.2","created":"2019-12-13 19:11:02","updated":"2019-12-13 19:11:02","service_id":"314956","service_type":"antispam","record_type":"1","product_id":"1","status":"allow","note":"note","expired":"''2019-12-14 17:10:00''","countrycode":"","operation_status":"SUCCESS"}]}}

Выходные параметры

records массив записей:

  • record_id идентификатор записи
  • service_id идентификатор сайта
  • hostname имя хоста сайта
  • record значение записи
  • countrycode код страны
  • created время создания записи
  • updated время обновления записи
  • status статус записи
  • record_type тип записи
  • product_id тип продукта
  • note заметка записи
  • expired срок жизни записи
  • operation_status статус операции

Пример:

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1&records=192.168.1.2&status=allow&note=note&expired=2019-12-13 17:10:00
{"data":{"records":[{"record_id":3985411,"record":"192.168.1.2","created":"2019-12-13 19:11:02","updated":"2019-12-13 19:11:02","service_id":"314956","service_type":"antispam","record_type":"1","product_id":"1","status":"allow","note":"note","expired":"''2019-12-14 17:10:00''","countrycode":"","operation_status":"SUCCESS"}]}}

Возможные ошибки

https://api.cleantalk.org/?method_name=private_list_add
{"data":{"result":"FAIL","notice":"User token not found","operation_code":"51"}}

 

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN
{"data":{"result":"FAIL","notice":"service_id is required","operation_code":"2"}}

 

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all
{"data":{"result":"FAIL","notice":"service_type is required and value must be in (antispam,spamfirewall,securityfirewall)","operation_code":"3"}}

 

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam
{"data":{"result":"FAIL","notice":"product_id is required and value must be in (1,4)","operation_code":"4"}}

 

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1
{"data":{"result":"FAIL","notice":"record_type is required and value must be in (1,2,3,4,5,7,8,9)","operation_code":"5"}}

 

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=spamfirewall&product_id=1
{"data":{"result":"FAIL","notice":"record_type is required and value must be in (6,10)","operation_code":"5"}}

 

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=securityfirewall&product_id=4
{"data":{"result":"FAIL","notice":"record_type is required and value must be in (1,3,7)","operation_code":"5"}}

 

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1
{"data":{"result":"FAIL","notice":"records is required","operation_code":"6"}}

 

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1&records=mail@example.com
{"data":{"records":[{"record":"mail@example.com","service_id":"314956","service_type":"antispam","record_type":"1","product_id":"1","operation_status":"FAILED","operation_message":"Wrong format","operation_code":"7"}]}}

 

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1&records=1.1.1.4
{"data":{"records":[{"record":"1.1.1.4","service_id":"314956","service_type":"antispam","record_type":"1","product_id":"1","operation_status":"FAILED","operation_message":"This IP address belongs to networks of payment systems, searching systems or other important services. It is forbidden to add such address to your personal lists.","operation_code":"10"}]}}

 

https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1&records=192.168.1.1
{"data":{"records":[{"record_id":"3985397","record":"192.168.1.1","created":"2019-12-13 18:08:41","updated":"2019-12-13 18:08:41","service_id":"314956","service_type":"antispam","record_type":"1","product_id":"1","status":"deny","note":"","expired":"","countrycode":"","operation_status":"FAILED","operation_message":"Record already exists","operation_code":"9"}]}}

Метод private_list_delete

Входные параметры

method_name допустимые значения: private_list_delete

user_token допустимые значения: можно получить в ПУ на странице профиля пользователя

record_ids

  • Массив данных, например record_ids[]=3985411&record_ids[]=3985397
  • Строка, с разделителем запятой, например record_ids=3985411,3985397

Пример:

https://api.cleantalk.org/?method_name=private_list_delete&user_token=USER_TOKEN&record_ids=3985411,3985397
{"data":{"records":[{"record_id":"3985411","operation_status":"SUCCESS"},{"record_id":"3985397","operation_status":"SUCCESS"}]}}

Выходные параметры

records массив записей:

  • record_id идентификатор записи
  • operation_status статус операции

Пример:

https://api.cleantalk.org/?method_name=private_list_delete&user_token=USER_TOKEN&record_ids=3985411,3985397
{"data":{"records":[{"record_id":"3985411","operation_status":"SUCCESS"},{"record_id":"3985397","operation_status":"SUCCESS"}]}}

Возможные ошибки

https://api.cleantalk.org/?method_name=private_list_delete&user_token=USER_TOKEN
{"data":{"result":"FAIL","notice":"record_ids is required","operation_code":"22"}}
https://api.cleantalk.org/?method_name=private_list_delete&user_token=USER_TOKEN&record_ids=3985411,3985397
{"data":{"records":[{"record_id":"3985411","operation_status":"FAILED","operation_message":"Record not found","operation_code":"21"},{"record_id":"3985397","operation_status":"FAILED","operation_message":"Record not found","operation_code":"21"}]}}

Метод private_list_update

Входные параметры

method_name допустимые значения: private_list_update

user_token допустимые значения: можно получить в ПУ на странице профиля пользователя

status[record_id] где record_id идентификатор записи, возможные значения: allow и deny

note[record_id] где record_id идентификатор записи, максимальная длина значения 2048 знаков

Пример:

https://api.cleantalk.org/?method_name=private_list_update&user_token=USER_TOKEN&status[3803794]=deny&status[3982786]=deny
{"data":{"records":[{"record_id":"3803794","operation_status":"SUCCESS"},{"record_id":"3982786","operation_status":"SUCCESS"}]}}

Выходные параметры

records массив записей:

  • record_id идентификатор записи
  • operation_status статус операции

Пример:

https://api.cleantalk.org/?method_name=private_list_update&user_token=USER_TOKEN&status[3803794]=deny&note[3803794]=test
{"data":{"records":[{"record_id":"3803794","operation_status":"SUCCESS"}]}}

Возможные ошибки

https://api.cleantalk.org/?method_name=private_list_update&user_token=USER_TOKEN
{"data":{"result":"FAIL","notice":"record list is empty","operation_code":"43"}}
https://api.cleantalk.org/?method_name=private_list_update&user_token=USER_TOKEN&note[3985397]=note
{"data":{"records":[{"record_id":"3985397","operation_status":"FAILED","operation_message":"Record not found","operation_code":"42"}]}}
https://api.cleantalk.org/?method_name=private_list_update&user_token=USER_TOKEN&status[3803794]=allow
{"data":{"records":[{"record_id":"3803794","operation_status":"FAILED","operation_message":"status allow disabled for record_type in (3,8,6,10)","operation_code":"41"}]}}

 

 


Возможно, будет так же интересно