API антиплагиата Адвего
На запросы отвечает сервис по адресу https://api.advego.com/json/antiplagiat/
API доступен пользователям, на символьном счету которых находится не менее 100 тысяч символов. Пополнение символьного счета: https://advego.com/antiplagiat/buy/
Токен для API антиплагиата (рекомендуем обновить перед первым использованием): https://advego.com/antiplagiat/api/
Токен должен передаваться в каждом запросе. Токен не имеет срока действия и может быть перегенерирован на той же странице.
-------
В качестве протокола используется json-rpc 2.0. Стандартный запрос выглядит следующим образом (id используется для сопоставления запроса с ответом):
{"jsonrpc": "2.0", "method": "...", "params": { …. }, "id": 1 }
-------
Важно! Для разных методов необходимо использовать разные адреса для запроса:
https://api.advego.com/json/antiplagiat/add/
- unique_text_add
https://api.advego.com/json/antiplagiat/get/
- unique_check
https://api.advego.com/json/antiplagiat/
- unique_recheck
- unique_get_text
- unique_get_list
- unique_set_public_refs
- unique_get_money_symbols
- unique_buy_symbols
- unique_get_symbols_packs
- unique_buy_symbols_pack
- unique_set_money_auto
-------
Форматирование текста для проверки:
- Для передачи переноса строк необходимо использовать тег \n
- HTML-теги автоматически удаляются при проверке, в проверяемом объеме не учитываются и на качество проверки не влияют, но остаются видны в полном тексте проверки на сайте.
Важно! Если в проверяемом тексте встречаются кавычки вида "", их необходимо экранировать:
"слово" -> \"слово\"
Также нужно экранировать символ обратного слеша \, если он используется сам по себе:
\слово -> \\слово
Не нужно экранировать символ \, если он экранирует кавычки или является частью тега переноса строки \n.
-------
Методы
-------
1. Добавление текста на проверку
-- unique_text_add
-- адрес для запроса: https://api.advego.com/json/antiplagiat/add/
Параметры:
• token — токен для авторизации;
• text — текст для проверки; Важно! Если в тексте есть переносы строк (абзацы, списки и т. п.) их нужно заменить на символ "\n" без кавычек.
• title — (необязательно) название проверки. Используется для отображения в веб-интерфейсе.
• lang - 2-значный код языка (ISO 639-1):
- "ru" - русский;
- "en" - английский;
- "uk" - украинский;
- "es" - испанский;
- "de" - немецкий;
- "fr" - французский;
- "zh" - китайский.
• options — (необязательно) параметры проверки:
-- ignore_rules — (необязательно) перечень правил, по которым будут игнорироваться сайты при проверки.
Доступные правила:
- "url" - проверка уникальности будет игнорировать данный url вместе с вложенными страницами, на текущем домене и всех поддоменах, в том числе на страницах с www;
- "!url" - проверка уникальности будет игнорировать только указанный URL.
Примеры исключений:
- site.com - будут исключены все страницы указанного домена и всех поддоменов любого уровня (в том числе с www).
- site.com/list/ - будет исключена указанная страница и все вложенные в нее.
- site.com/list/page.html - будет исключена указанная страница и все ее модификации с любыми параметрами (?, #, &).
Если нужно исключить только конкретную страницу, не затронув другие страницы сайта, укажите в начале строки символ "!":
- !site.com - будет исключена только главная страница указанного сайта.
- !site.com/list/ - будет исключена только указанная страница, а вложенные и страницы сайта из других директорий исключены не будут.
- !site.com/list/page.html - будет исключена только указанная страница, а ее модификации с любыми параметрами исключены не будут (?, #, &).
В запросе:
"options":
{
"ignore_rules":
[
"site.com"
]
}
Несколько исключений:
"options":
{
"ignore_rules":
[
"site.com",
"site2.com",
"site3.com"
]
}
---
Пример вызова:
POST https://api.advego.com/json/antiplagiat/add/
{
"id": "1",
"jsonrpc": "2.0",
"method": "unique_text_add",
"params":
{
"token": "токен",
"text": "текст",
"title":"название работы",
"options":
{
"ignore_rules":
[
"site.com",
"site2.com",
"site3.com"
]
}
}
}
-------
Ответ:
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"key": "NNN"
}
}
Где NNN - номер созданной проверки.
Если попытка создания неудачная:
{
"jsonrpc": "2.0",
"result": {
"error": "-1", "error_msg": "сообщение об ошибке"
},
"id": 1
}
проверка не была добавлена.
Error — код ошибки. Возможные коды ошибки:
-1 — не хватает символов на счету;
-2 — не хватает денежных средств на счету;
-5 — ошибка подключения к БД;
-10 — получен неверный ключ;
-11 — ошибка авторизации по токену;
-13 — ошибка при проверке поля text;
-14 — ошибка при проверке поля title;
-17 — ошибка добавления работы;
-21 — текст не найден;
-63 — no text – отправляется пустой текст, минимальный объем - 25 символов;
-64 — short text – слишком короткий текст, минимальный объем - 25 символов;
-67 — not enough symbols – недостаточно символов на счету, минимальное количество – 100 000.
-------
2. Состояние и результат проверки
-- unique_check
-- адрес для запроса: https://api.advego.com/json/antiplagiat/get/
Возвращает состояние проверки и отчет, если проверка выполнена.
Параметры:
• token — токен для авторизации;
• key — идентификатор проверки, полученный при добавлении;
• get_text - если указан, то вместе с отчетом будет возвращен проверенный текст;
• agent - тип проверки, указывается чтобы получить результат проверки работы или статьи.
• report_json - формат отчета, рекомендуется значение 1.
Возможные значения:
-- shopchecker - получить отчет о проверки статьи, key - id статьи;
-- jobchecker - получить отчет о проверки работы, key - id работы.
-------
Пример вызова:
POST https://api.advego.com/json/antiplagiat/get/
{
"jsonrpc": "2.0",
"method": "unique_check",
"params":
{
"token": "токен",
"key": "id проверки",
"get_text":"0 или 1",
"report_json":"0 или 1"
},
"id": 1
}
-------
Варианты ответов:
Проверка выполняется
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"msg": "",
"status": "in progress"
}
}
Проверка выполнена
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"status": "done",
"report": {
"equality": 100,
"rewrite": 100,
...
}
},
}
• "status" — состояние проверки.
Возможные состояния проверки:
• done - проверка завершена успешно;
• error - проверка завершена с ошибкой;
• not found - проверка с данным ключом не найдена;
• in progress - проверяется.
• "report" — отчёт о проверке в формате json (см. Формат отчета). Присылается в ответе, только если проверка закончена (статус "done").
• "msg" — сообщение с дополнительной информацией.
• text — проверенный текст
-------
Ошибка запроса
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"status": "error",
"msg": ""
},
}
Error — код ошибки. См. расшифровку кодов ошибок в методе unique_text_add
-------
Формат отчета:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"report": {
"layers_by_domain": [
{
"rewrite": 33,
"equality": 19,
"layers": [
{
"equality": 19,
"rewrite": 33,
"uri": "https://site/",
"words": [
7,
30,
31,
32
],
"shingles": [
31,
32,
33,
34,
35,
36,
37,
38
]
},
],
"len": 1050,
"bad_words": [],
"equal_words": [
0,
1,
3,
5,
7,
15,
19,
20,
22,
24,
25,
27,
28,
30
],
"word_count": 154,
"lang": "russian",
"error_pages": 0,
"rewrite": 82,
"progress": 100,
"text_fragments": [
"",
"Слово1",
" ",
"Слово2",
" ",
"Слово3",
" ",
"Слово4",
" ",
"Слово5",
". "
],
"captchas": 0,
"found_pages": 11,
"checked_pages": 48,
"equal_shingles": [
31,
32,
36,
37,
38,
40
],
"checked_phrases": 8,
},
"status": "done"
}
}
Расшифровка:
- layers_by_domain - найденные страницы с совпадениями, сгруппированные по доменам (если найдено несколько страниц на одном сайте),
- layers - найденные страницы линейным списком,
- equality - количество найденных совпадений по фразам в указанном источнике (uri), процентов,
- rewrite - количество найденных совпадений по словам в указанном источнике (uri), процентов,
- uri - адрес страницы с найденными совпадениями,
- words - слова, входящие в найденные совпадения по словам (см. text_fragments),
- shingles - слова, входящие в найденные совпадения по фразам (см. text_fragments),
- len - длина текста в символах с пробелами,
- bad_words - слова с подменой символов,
- equal_words - аналогично words, но для всего текста,
- equal_shingles - аналогично shingles, но для всего текста,
- word_count - количество слов в проверяемом тексте,
- text_fragments - фрагменты текста для восстановления совпадений по словам и фразам. Порядковый номер фрагмента вычисляется по формуле 2n + 1, где n = номеру, указанному в соответствущей секции words, shingles, equal_words и equal_shingles.
-------
Важно! Показатели equality и rewrite выражают процент совпадений, а не уникальности! Чтобы получить показатель уникальности, нужно отнять эти значения от 100%.
Например, если получен такой результат:
"equality": 19,
"rewrite": 33,
Это означает, что уникальность по фразам (первый показатель уникальности, такие совпадения выделяются желтым цветом) равна 100 - 19 = 81%, а уникальность по словам (второй показатель уникальности, такие совпадения выделяются голубым цветом) равна 100 - 33 = 67%.
Итого, уникальность: 81% / 67%.
-------
3. Перепроверка текста
-- unique_recheck
-- адрес для запроса: https://api.advego.com/json/antiplagiat/
Запускает новую проверку ранее добавленного текста. При этом удаляет предыдущие проверки этого текста из очереди.
-------
Пример вызова:
POST https://api.advego.com/json/antiplagiat/
{
"jsonrpc": "2.0",
"method": "unique_recheck",
"params":
{
"token": "токен",
"key": "id проверки"
},
"id": 1
}
Параметры:
• token — токен для авторизации;
• key — идентификатор проверки, полученный при добавлении.
-------
Варианты ответов:
Новая проверка добавлена:
{"jsonrpc":"2.0","id":1,"resul t":1}
Ошибка при выполнении:
{"jsonrpc": "2.0", "result": {"error": "-1", "error_msg": "сообщение об ошибке"}, "id": 1 }
Error — код ошибки. См. расшифровку кодов ошибок в методе unique_text_add
-------
4. Получение текста на проверке
-- unique_get_text
-- адрес для запроса: https://api.advego.com/json/antiplagiat/
Возвращает текст на проверке.
-------
Пример вызова:
POST https://api.advego.com/json/antiplagiat/
{
"jsonrpc": "2.0",
"method": "unique_get_text",
"params":
{
"token": "токен",
"key": "id проверки"
},
"id": 1
}
Параметры:
• token — токен для авторизации;
• key — идентификатор проверки, полученный при добавлении.
-------
Варианты ответов:
Успешный запрос:
{"jsonrpc":"2.0","id":1,"resul t":{"text":"текст"}}
Ошибка запроса:
{"jsonrpc": "2.0", "result": {"error": "-21", "error_msg": "сообщение об ошибке"}, "id": 1 }
Error — код ошибки. См. расшифровку кодов ошибок в методе unique_text_add
-------
5. Получение списка проверок за период
-- unique_get_list
-- адрес для запроса: https://api.advego.com/json/antiplagiat/
Возвращаемые данные:
- result — список ID проверок за указанный период (если указана только дата, то не включая конечный день периода).
-------
Пример вызова (список ID проверок с 1 по 17 мая 2021 включительно):
POST https://api.advego.com/json/antiplagiat/
{
"jsonrpc": "2.0",
"method": "unique_get_list",
"params":
{
"token": "TOKEN",
"date_from": "2021-05-01",
"date_to":"2021-05-18",
"report_json":"0"
},
"id": 1
}
Параметры:
- token — токен для авторизации;
- date_from — дата, с которой ищутся проверки
- date_to — дата, до которой ищутся проверки ( не входит )
даты указываются в формате "2020-03-31", можно указывать с точностью до секунд 2020-03-31 10:55:46".
Выгрузка с указанием времени до 18.05.2021 14:00:00:
"date_to":"2021-05-18 14:00:00",
-------
Варианты ответов:
Успешный запрос:
{"jsonrpc":"2.0","id":1,"result":{"id_jobs":"["ID1", "ID2", "ID3"]}}
-------
6. Включение публичного доступа к отчету проверки
-- unique_set_public_refs
-- адрес для запроса: https://api.advego.com/json/antiplagiat/
Возвращает ID проверки и уникальный хэш-код для URL ссылки на публичную версию отчета проверки.
Чтобы получить ссылку на публичный отчет проверки, нужно сформировать полный URL по следующей схеме:
https://advego.com/antiplagiat/HASH/
-------
Пример вызова:
POST https://api.advego.com/json/antiplagiat/
{
"jsonrpc": "2.0",
"method": "unique_set_public_refs",
"params":
{
"token": "TOKEN",
"id_job_list": ["ID1"],
"is_public":"1",
"report_json":"0"
},
"id": 1
}
Параметры:
- token — токен для авторизации;
- id_job_list — список ID онлайн проверок;
- is_public — 0 - убрать публичный доступ к проверке; 1 - открыть доступ.
Включение публичного доступа нескольких проверок:
"id_job_list": ["ID1", "ID2", "ID3"],
-------
Варианты ответов:
Успешный запрос:
{"jsonrpc": "2.0","id": 1,"result": {"result": [{"id_job": "ID1","hash_url": "HASH"}]}}
-------
7. Получение баланса символов и признака автопокупки
-- unique_get_money_symbols
-- адрес для запроса: https://api.advego.com/json/antiplagiat/
Возвращает имеющееся количество символов для онлайн-проверки и статус опции автопокупки символов (включена или отключена).
-------
Пример вызова:
POST https://api.advego.com/json/antiplagiat/
{
"jsonrpc": "2.0",
"method": "unique_get_money_symbols",
"params":
{
"token": "TOKEN",
"report_json":"0"
},
"id": 1
}
Параметры:
- token — токен для авторизации.
-------
Варианты ответов:
Успешный запрос:
{
"id": 1,
"result": {
"money_symbols_auto": 0,
"money_symbols": "680693"
},
"jsonrpc": "2.0"
}
-------
8. Покупка символов
-- unique_buy_symbols
-- адрес для запроса: https://api.advego.com/json/antiplagiat/
Позволяет купить символы для Антиплагиата Адвего - определенное количество или на определенную сумму (количество в последнем случае будет определено автоматически по стоимости 0,6 руб. или 0,01 у. е. / евро за 1000 символов).
Чтобы купить символы со скидкой, используйте метод unique_buy_symbols_pack.
-------
Пример вызова:
POST https://api.advego.com/json/antiplagiat/
{
"jsonrpc": "2.0",
"method": "unique_buy_symbols",
"params":
{
"token": "TOKEN",
"money_amount":"60",
"report_json":"0"
},
"id": 1
}
Параметры:
- token — токен для авторизации,
- money_amount - сумма, на которую нужно купить символы,
- symbols_amount - количество символов, которые нужно приобрести.
Параметры money_amount и symbols_amount могут указываться, как вместе, так и по отдельности.
-------
Варианты ответов:
Успешный запрос:
{
"id": 1,
"result": {
"symbols_amount": 100000,
"money_amount": "60",
"result": 1
},
"jsonrpc": "2.0"
}
-------
9. Варианты пакетов символов со скидкой
-- unique_get_symbols_packs
-- адрес для запроса: https://api.advego.com/json/antiplagiat/
Возвращает список доступных для покупки пакетов символов со скидкой.
Чтобы купить символы со скидкой, используйте метод unique_buy_symbols_pack.
-------
Пример вызова:
POST https://api.advego.com/json/antiplagiat/
{
"jsonrpc": "2.0",
"method": "unique_buy_symbols",
"params":
{
"token": "TOKEN",
"money_amount":"60",
"report_json":"0"
},
"id": 1
}
Параметры:
- token — токен для авторизации.
Возвращаемые значения:
packs - список пакетов.
Каждый пакет имеет поля:
pack - id пакета символов,
symbols - количество символов в пакете,
price - цена пакета символов,
currency - ISO 4217 код валюты (643 - RUB, 840 - USD и т. д.),
discount - Размер скидки в процентах.
По умолчанию стоимость пакета возвращается в той валюте, которая указана в настройках акканта, чей токен используется.
-------
10. Покупка пакета символов
-- unique_buy_symbols_pack
-- адрес для запроса: https://api.advego.com/json/antiplagiat/
Позволяет купить пакет символов для Антиплагиата Адвего со скидкой - из доступного списка (метод unique_get_symbols_packs).
-------
Пример вызова:
POST https://api.advego.com/json/antiplagiat/
{
"jsonrpc": "2.0",
"method": "unique_buy_symbols_pack",
"params":
{
"token": "TOKEN",
"pack":"39",
"report_json":"0"
},
"id": 1
}
Параметры:
- token — токен для авторизации,
- pack - номер пакета в соответствии со списком, возвращаемым в методе unique_get_symbols_packs.
-------
Варианты ответов:
Успешный запрос:
{
"result": {
"result": 1
},
"jsonrpc": "2.0",
"id": "1"
}
-------
11. Включение и отключение автопокупки символов
-- unique_set_money_auto
-- адрес для запроса: https://api.advego.com/json/antiplagiat/
Позволяет активировать или отключить опцию автопокупки символов.
-------
Пример вызова:
POST https://api.advego.com/json/antiplagiat/
{
"jsonrpc": "2.0",
"method": "unique_set_money_auto",
"params":
{
"token": "TOKEN",
"auto":"1",
"report_json":"0"
},
"id": 1
}
Параметры:
- token — токен для авторизации,
- auto - 0 - выключить автопокупку, 1 - включить.
-------
Варианты ответов:
Успешный запрос:
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"result": 1
}
}