API антиплагиата Адвего

На запросы отвечает сервис по адресу https://api.advego.com/json/antiplagiat/

Важно! Для разных методов необходимо использовать разные адреса для запроса:

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 

Токен для API антиплагиата (рекомендуем обновить перед первым использованием): https://advego.com/antiplagiat/api/

Токен должен передаваться в каждом запросе. Токен не имеет срока действия и может быть перегенерирован на той же странице.

-------

API доступен пользователям, на символьном счету которых находится не менее 100 тысяч символов. Пополнение символьного счета: https://advego.com/antiplagiat/buy/

-------

В качестве протокола используется json-rpc 2.0. Стандартный запрос выглядит следующим образом:

{"jsonrpc": "2.0", "method": "...", "params": { …. }, "id": 1 }

id используется для сопоставления запроса с ответом.

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 — текст не найден;
-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
 }
}