API заказов и магазина Адвего

Для работы с заказами и магазином Адвего используется POST HTTP API с протоколом XML-RPC.

Список методов: https://advego.com/info/api

Адрес для запросов: https://api.advego.com/xml

Ключ доступа к API (токен): https://advego.com/user/password/#tab-user-keyapi-hash

------

Ограничения при работе с API: https://advego.com/v2/support/customer/api/1384/

Служба поддержки: используйте форму запроса внизу страницы.

------

С помощью API могут выполняться следующие действия:

  • создание, запуск и остановка заказа, выгрузка работ, их оплата и др.;
  • поиск и покупка статей в магазине Адвего;
  • проверка баланса аккаунта.

Важно! В каждом методе предусмотрены обязательные параметры, которые нужно указывать при каждом запросе. Без указания обязательных параметров или при некорректном их значении запрос вернет ошибку: https://advego.com/info/api_err

Для всех запросов обязательным является параметр token.

-------

ПОЛУЧЕНИЕ ТОКЕНА

Скопируйте уникальный токен на странице: https://advego.com/user/password/#tab-user-keyapi-hash

В примерах запросов ниже необходимо подставить свой токен вместо TOKEN.

-------

СОЗДАНИЕ ЗАКАЗА

Для создания заказа нужно использовать метод advego.addOrder.

Обязательные параметры (минимальный набор):

1. Название заказа - параметр title

Опишите кратко суть задачи, например:

  • Статья для сайта о медицине
  • Поставить лайк
  • Нужен реферат о нефтепереработке
  • Установить приложение и поставить ему оценку

В названии допускается присутствие дополнительной нумерации или другой технической кодировки заказов для их поиска и отслеживания.

Максимальная длина заголовка - 120 символов с пробелами.

В названии запрещено:

  • указывать стоимость заказа (для этого предназначено отдельное поле);
  • размещать призывы выполнять заказ или обещать премии, бонусы и т. п. поощрения;
  • размещать контакты (e-mail, телефон и т. п.) или ссылки для связи вне Адвего (для общения с исполнителями отведено обсуждение заказа и работ).

---

2. Описание заказа - параметр description

Опишите подробно суть задачи и, при необходимости, пошаговый алгоритм ее выполнения.

Максимальный объем описания - 50 000 символов с пробелами.

Ознакомиться с примерами готовых описаний можно на странице https://advego.com/#order-add - нажмите на ссылку "Шаблоны заказов" под полем "Название заказа", после чего выберите в открывшемся меню подходящий для вашей задачи шаблон - загрузится форма заказа с шаблоном описания. Используйте его в качестве основы или напишите свое.

В описании может быть указаны данные о стоимости работы, но только для расшифровки стоимости работ, состоящих из нескольких действий или вариантов с разной стоимостью оплаты.

Общая стоимость работы указывается в отдельном поле (параметр cost).

В описании запрещено:

  • размещать призывы выполнять заказ или обещать премии, бонусы и т. п. поощрения;
  • размещать контакты (e-mail, телефон и т. п.) или ссылки для связи вне Адвего (для общения с исполнителями отведено обсуждение заказа и работ).

---

3. Количество работ - параметр jobs_total

В одном заказе можно заказывать от одной до нескольких работ - текстов, лайков, комментариев и т. д.

Укажите числом, сколько всего работ вам нужно.

---

4. Стоимость одной работы - параметр cost или cost_1000

Параметр cost удобно использовать для работ, связанных с выполнением действий (лайков, репостов и т. д.) - укажите, сколько вы готовы платить за выполнение одной работы.

Параметр cost_1000 удобен для текстовых работ - задайте цену за 1000 символов текста, а система автоматически рассчитает полную стоимость работы, исходя из заданного объема одной работы.

Важно! В Адвего установлены минимальные цены на контент и услуги исполнителей, например:

  • копирайтинг: 1,00 у.е. / 80 руб. / 0,90 € за 1000 символов с пробелами;
  • приглашение пользователей в группы: 0,60 у.е. / 52 руб. / 0,54 € за 40 приглашений;
  • лайки: 0,08 у.е. / 6 руб. / 0,07 €.

Если стоимость работы или цена за 1000 знаков окажется меньше минимальной, система вернет ошибку, и заказ не будет создан.

Актуальные минимальные цены на все виды работ и текстов: https://advego.com/v2/support/rules/#p9.3.1

---

5. Объем одной работы - параметр length.

Укажите размер одной работы в символах с пробелами.

Диапазон размера работы, например, от 3000 до 5000 знаков, задается по API с помощью дополнительного параметра pay_amount (тип boolean), который включает режим оплаты за объем.

При этом также нужно указать и максимальный объем - в параметре length_max (минимальный объем уже указан в параметре length).

Итого, в заказе должны быть три параметра:

pay_amount = 1
length = 3000
length_max = 5000

Для работ без объема (лайки, репосты, приглашения друзей в соцсетях и т. п.) рекомендуем указывать минимальный объем - 10 символов.

---

6. Тип работы: для удобства все работы в Адвего делятся на несколько типов - параметр order_type.

Описание всех типов работы: https://advego.com/v2/support/rules/#p2.10

Примеры типов работы (число - значение параметра order_type):

  • Статья, обзор, SEO-копирайтинг - 3.
  • Лайки в соцсетях - 18.
  • Отзовики, каталоги компаний - 12.
  • Тестирование, разметка данных, картинок - 19.
  • Расшифровка аудио и видео, сканов и фото - 13.
  • Фото и видео - 17.

Актуальный список типов работ можно узнать с помощью метода advego.getOrderTypes.

Важно! Если выбран тип работы "Статья, обзор, SEO-копирайтинг", нужно дополнительно указать тип текста (параметр text_type).

Примеры типов текста (число - значение параметра text_type):

  • Копирайтинг - 1.
  • Копирайтинг / SEO - 6.
  • Рерайтинг c сокращением (увеличением) текста - 10.

Актуальный список типов текста можно узнать с помощью метода advego.getOrderTextTypes.

--- 

7. Проект (кампания), к которому будет привязан заказ - параметр campaign_id.

По умолчанию в аккаунте уже создан проект "Новая кампания", чтобы узнать его ID, используйте метод advego.getMyCampaigns - в ответ придет значение campaign_id этого проекта.

Пример запроса:

<?xml version="1.0"?>
<methodCall>
<methodName>advego.getMyCampaigns</methodName>
<params>
<param><value>
<struct>
<member>
<name>token</name>
<value><string>TOKEN</string></value>
</member>
</struct>
</value></param>
</params>
</methodCall>

Также вы можете создать новый проект с помощью метода advego.addCampaign - обязательным параметром является название (параметр title).

Все проекты доступны для просмотра на странице https://advego.com/campaigns/my/

При добавлении нового проекта рекомендуем сразу указать его категорию (тематику), которая будет по умолчанию присваиваться всем новым заказам, привязанных к этому проекту (необязательный параметр category).

Если категория проекта не указана, то присваивается тематика "Другое".

Примеры тематик (число - значение параметра category):

  • IT, софт - 30,
  • Авто, мото - 44 и т. д.

Актуальный список тематик можно узнать с помощью метода advego.getCategories.

---

Пример запроса на создание заказа со следующими параметрами:

  • Название: Поиск информации.
  • Описание (задача): Найти информацию.
  • Тип работы: Поиск информации, полевые задания, чеки и бонусы (order_type - 6).
  • Категория (тематика): IT, софт (category - 30).
  • Объем одной работы (с пробелами): 1000 символов.
  • Стоимость одной работы: 100 руб. (если валюта аккаунта - у. е. или евро, то 1 у. е. или 1 евро).
  • Необходимое количество работ: 3
  • TOKEN и ID_CAMPAIGN: из данных аккаунта заказчика.

---

<?xml version="1.0"?>
<methodCall>
<methodName>advego.addOrder</methodName>
<params>
<param><value>
<struct>
<member>
<name>token</name>
<value><string>TOKEN</string></value>
</member>
<member>
<name>campaign_id</name>
<value><string>ID_CAMPAIGN</string></value>
</member>
<member>
<name>title</name>
<value><string>Поиск информации</string></value>
</member>
<member>
<name>description</name>
<value><string>Найти информацию</string></value>
</member>
<member>
<name>order_type</name>
<value><string>6</string></value>
</member>
<member>
<name>category</name>
<value><string>30</string></value>
</member>
<member>
<name>length</name>
<value><string>1000</string></value>
</member>
<member>
<name>cost</name>
<value><string>50</string></value>
</member>
<member>
<name>jobs_total</name>
<value><string>3</string></value>
</member>
</struct>
</value></param>
</params>
</methodCall>

------ 

СОЗДАНИЕ ЗАКАЗА С ТЕМАМИ

В одном заказе можно заказать работы на разные темы или для разных площадок, при этом указать индивидуальное количество работ для каждой темы.

Например, комментарии для разных постов, статьи на индивидуальные темы и т. д.

Для добавления тем в заказ необходимо использовать метод advego.editOrderThemes с параметрами, соответствующими доступным полям:

  • заголовок (название) (до 1000 символов),
  • обязательные ключевые фразы (до 2000 символов),
  • необходимое количество разных ключевых фраз из указанных,
  • URL - ссылка для выполнения работы (до 2000 символов, видят исполнители только после взятия в работу),
  • краткое примечание для исполнителя (до 50 000 символов),
  • секретное описание (до 45 000 символов), 
  • заметка про тему (видит только заказчик) (до 50 000 символов).
  • необходимое количество работ (по умолчанию одна).

Обязательно указывать в темах:

параметр status - active (если не указать, тема будет неактивной).
параметр all_count - количество работ по теме (если не указать, тема будет находиться в выполненных даже со статусом active).

Важно! После добавления тем в заказ нужно включить их запросом с командой advego.setOrderThemesOn: https://advego.com/info/api/#setOrderThemesOn

Пример запроса:

<?xml version="1.0"?>
<methodCall>
<methodName>advego.editOrderThemes</methodName>
<params>
<param><value>
<struct>
<member>
<name>token</name>
<value><string>TOKEN</string></value>
</member>
<member>
<name>id_order</name>
<value><string>ID_ORDER</string></value>
</member>
<member>
<name>themes</name>
<value>
<array>
<data>
<value>
<struct>
<member>
<name>title</name>
<value>TEMA 1</value>
</member>
<member>
<name>desc</name>
<value>Тестовая тема 1</value>
</member>
<member>
<name>tags</name>
<value>
<array>
<data>
<value>
<struct>
<member>
<name>tag</name>
<value>ключ1</value>
</member>
<member>
<name>count</name>
<value>2</value>
</member>
</struct>
</value>
<value>
<struct>
<member>
<name>tag</name>
<value>ключ2</value>
</member>
<member>
<name>count</name>
<value>4</value>
</member>
</struct>
</value>
<value>
<struct>
<member>
<name>tag</name>
<value>ключ3</value>
</member>
<member>
<name>count</name>
<value>7</value>
</member>
</struct>
</value>
</data>
</array>
</value>
</member>
<member>
<name>status</name>
<value>active</value>
</member>
<member>
<name>all_count</name>
<value>1</value>
</member>
</struct>
</value>
<value>
<struct>
<member>
<name>title</name>
<value>TEMA 2</value>
</member>
<member>
<name>desc</name>
<value>Тестовая тема 2</value>
</member>
<member>
<name>status</name>
<value>active</value>
</member>
<member>
<name>all_count</name>
<value>2</value>
</member>
</struct>
</value>
<value>
<struct>
<member>
<name>title</name>
<value>ТЕМА 3</value>
</member>
<member>
<name>desc</name>
<value>Тестовая тема 3</value>
</member>
<member>
<name>status</name>
<value>active</value>
</member>
<member>
<name>all_count</name>
<value>1</value>
</member>
</struct>
</value>
</data>
</array>
</value>
</member>
</struct>
</value></param>
</params>
</methodCall>

-------

ID ЗАКАЗА

Если все необходимые параметры указаны верно, в ответ на запрос система вернет ID заказа, по которому впоследствии можно будет проверять статус заказа, получать заявки, одобрять их, выгружать тексты работ и оплачивать их.

Все заказы доступны для просмотра на странице https://advego.com/campaigns/orders/all/

Внимание! 

Время на выполнение работы по умолчанию составляет 6 часов - этого достаточно для большинства простых задач: лайков, комментариев, текстов объемом до 2000 символов и т. п.

Если задача потенциально требует больше времени для выполнения, рекомендуем при создании заказа увеличить время на выполнение, указав дополнительно параметр job_do_time с допустимыми значениями от 0.5 до 120 часов (с шагом 0.1).

-------

ЗАПУСК И ОСТАНОВКА ЗАКАЗА

Для запуска заказа необходимо использовать метод advego.startOrder с обязательным параметром ID - ID заказа, полученным при его создании.

Для остановки заказа необходимо использовать метод advego.stopOrder с обязательным параметром ID - ID заказа, полученным при его создании.

---

Проверить статус заказа (запущен, на модерации, остановлен, остановлен администрацией и т. п.) можно с помощью метода advego.ordersGetState.

Пример запроса для проверки статуса заказа:

<?xml version="1.0"?>
<methodCall>
<methodName>advego.ordersGetState</methodName>
<params>
<param><value>
<struct>
<member>
<name>token</name>
<value><string>TOKEN</string></value>
</member>
<member>
<name>orders</name>
<value>
<array>
<data>
<value><i4>ID_ORDER_1</i4></value>
<value><i4>ID_ORDER_2</i4></value>
</data>
</array>
</value>
</member>
</struct>
</value></param>
</params>
</methodCall>

-------

РЕДАКТИРОВАНИЕ ЗАКАЗА

Для изменения параметров уже созданного заказа необходимо использовать метод advego.editOrder с обязательным параметром ID - ID заказа, полученным при его создании.

Дополнительно достаточно указать только те параметры, которые нужно изменить, например, стоимость одной работы или ее объем.

-------

ПОИСК ИСПОЛНИТЕЛЕЙ

По умолчанию заказ создается с Быстрым поиском для Любителей, то есть доступен всем пользователям Адвего с любым рейтингом. Исполнители берут заказ в работу и выполняют без подачи заявок и ожидания одобрения заказчика.

Это подходит для большинства простых задач, например, работы в соцсетях, на форумах, оценки приложений, написания простых текстов.

Но для более сложных и ответственных задач лучше использовать отбор исполнителей и ограничение по уровню (рейтингу).

1. Чтобы ограничить доступ к заказу по уровню для Быстрого поиска, при создании или редактировании заказа необходимо добавить в запрос параметр approved_lists со следующими значениями:

  • 46052 - Специалист (ТОП-10000);
  • 46051 - Профессионал (ТОП-2500);
  • 46050 - Эксперт (ТОП-500);
  • 45228 - Гуру (сертифицированные копирайтеры).

В таком случае взять заказ в работу смогут только исполнители с указанным уровнем.

Актуальный список системных уровней можно получить с помощью метода advego.getLevels.

Чтобы отключить быстрый поиск, нужно передать в параметре approved_lists пустое значение.

Если другие типы поиска неактивны, то после отключения быстрого поиска доступ к заказу останется только у исполнителей из основного списка заказа и исполнителей из БС, используемых в заказе.

---

Аналогичным образом можно ограничивать доступ к заказу для своего Белого списка (БС) исполнителей, указав id списка.

Чтобы получить список своих БС, используйте метод advego.getWhiteLists, не требующий обязательных параметров, кроме токена.

Чтобы создать новый БС, используйте метод advego.addToList с обязательными параметрами (через дефис - значение параметра):

  • list - new
  • new_list_name - желаемое название БС

После успешного создания система сообщит ID созданного списка.

Все свои БС доступны для просмотра на странице https://advego.com/list/

-----

Внимание! Чтобы создать заказ для Любителей, параметр approved_lists указывать НЕ НУЖНО, а чтобы изменить уровень на Любителей с любого другого, в параметре approved_lists нужно указать значение 0 (ноль).

Пример запроса для смены уровня на Любителей (если до этого заказ был создан для другого уровня):

<?xml version="1.0"?>
<methodCall>
<methodName>advego.editOrder</methodName>
<params>
<param><value>
<struct>
<member>
<name>token</name>
<value><string>TOKEN</string></value>
</member>
<member>
<name>ID</name>
<value><string>ID</string></value>
</member>
<member>
<name>approved_lists</name>
<value><string>0</string></value>
</member>
</struct>
</value></param>
</params>
</methodCall>

---

2. Чтобы активировать Ручной отбор исполнителей со сбором заявок, необходимо при создании или редактировании заказа добавить параметр is_tender со значением 1.

В таком случае исполнители смогут только подавать заявки, а приступить к выполнению заказа смогут только после одобрения заявки заказчиком.

Ручной поиск можно также ограничивать по уровню используя совместно с параметром is_tender дополнительный параметр allowed_lists со следующими значениями:

  • 46052 - Специалист (ТОП-10000);
  • 46051 - Профессионал (ТОП-2500);
  • 46050 - Эксперт (ТОП-500);
  • 45228 - Гуру (сертифицированные копирайтеры).

Важно! Ручной поиск нельзя использоваться для своих БС, он работает только с системными списками исполнителей по уровню.

Внимание! Чтобы создать заказ для Любителей, параметр allowed_lists указывать НЕ НУЖНО, а чтобы изменить уровень на Любителей с любого другого, в параметре allowed_lists нужно указать значение 0 (ноль).

-----

3. Также вы можете поручить отбор исполнителей системе - это хорошо подходит для типовых задач с несложным алгоритмом выполнения: написание SEO-текстов с готовым списком ключей, комментарии, отзывы и т. п.

Вам останется только проверять и оплачивать готовые работы.

Чтобы активировать автоматический поиск исполнителей с помощью нейросети, используйте совместно с параметром is_tender дополнительный параметр auto_accept_request со значением 1.

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

По умолчанию нейросеть выполняет одобрение исполнителей 1 раз в час, период поиска можно задать с помощью дополнительного параметра auto_accept_period с доступными значениями в часах: 0.25, 0.5, 1, 2, 3, 6, 12, 24, 48.

Таким образом, нейросеть может одобрять заявки с периодом от 15 минут (подходит для самых простых задач) до 2 суток (желательно для сложных действий или задач узкой направленности: переводы с редких языков, помощь узкого специалиста и т. п.).

Чем больше период поиска, тем больше заявок успеют подать исполнители, и тем лучше будет конечный выбор системы.

Важно! Автоматический поиск, как и ручной поиск, нельзя использоваться для своих БС, он работает только с системными списками исполнителей по уровню.

---

Внимание! Если задача требует вашей личной оценки опыта и квалификации исполнителя, рекомендуем использовать только Ручной поиск исполнителей, так как нейросеть может оценить успешную статистику исполнителя по определенному типу работы, но она ничего не знает о его навыках или знаниях, как специалиста определенного профиля.

Например, поиск исполнителей для написания стандартных SEO-текстов можно поручить нейросети, а вот копирайтера для создания рекламного лендинга или курсовой уже лучше выбирать вручную по примерам его работ.

-----

ПОЛУЧЕНИЕ ЗАЯВОК

Чтобы получить список поданных исполнителями заявок, используйте метод advego.getTenderRequests с параметром id_order - ID заказа, полученным после его создания.

В ответ система сообщит ID заявок и их тексты.

Для одобрения понравившихся заявок используйте метод advego.acceptTenderRequest, а для отклонения - advego.declineTenderRequest с обязательным параметром id_request - ID заявки, полученным ранее с помощью метода advego.getTenderRequests.

-------

ПОЛУЧЕНИЕ РАБОТ

Оплаченные работы - используйте метод advego.getJobsAccepted.

Неоплаченные работы, ожидающие проверки (на модерации) - используйте метод advego.getJobsCompleted,с теми же параметрами, что и у метода advego.getJobsAccepted.

Если дополнительно указать параметр campaign_id, то будут возвращены работы только по заказам из указанного проекта, а если указать параметр id_order - по конкретному заказу с таким ID.

По умолчанию система возвращает список работ, выполненных не более 7 дней назад.

Если нужно выгрузить работы за больший период, нужно добавить параметры date_from и date_to, чтобы выгрузить работы, выполненные, соответственно, С и ПО указанную дату (максимальный период выгрузки - 365 дней).

Важно!

Датой выполнения считается дата первого выполнения работы, в случае доработок эта дата может выйти за пределы указанного периода и работа не попадет в выгрузку по API.

По этой причине рекомендуем добавлять параметр date_type со значением "complete" - тогда будет возвращен список всех работ, но датой выполнения будет считаться дата именно последнего выполнения. Это особенно важно в случае выгрузки работ на модерации без указанного периода выгрузки.

---

Для оплаты работы используйте метод advego.acceptJob

Для отправки на доработкуadvego.returnJob с обязательным параметром comment - комментарием с причиной доработки не меньше 10 символов.

Для отказа в оплатеadvego.declineJob, также с обязательным параметром comment - комментарием с причиной отказа не меньше 10 символов.

Во всех методах, связанных с обработкой работ, необходимо указывать параметр ID - ID работы, полученный с помощью методов advego.getJobsCompleted или advego.getJobsAccepted.

 

Примеры запросов:

-------

1. Выгрузка оплаченных работ по заказу ID_ORDER за период с 2021-01-01 03:59:59 по 2021-01-30 12:00:00:

<?xml version="1.0"?>
<methodCall>
<methodName>advego.getJobsAccepted</methodName>
<params>
<param><value>
<struct>
<member>
<name>token</name>
<value><string>TOKEN</string></value>
</member>
<member>
<name>id_order</name>
<value><string>ID_ORDER</string></value>
</member>
<member>
<name>date_from</name>
<value><string>2021-01-01 03:59:59</string></value>
</member>
<member>
<name>date_to</name>
<value><string>2021-01-30 12:00:00</string></value>
</member>
<member>
<name>date_type</name>
<value><string>accept</string></value>
</member>
</struct>
</value></param>
</params>
</methodCall>



2. Загрузка массива данных в параметр (необходим в методах для получения данных по нескольким заказам, работам, статьям и т. п.):

<member>
<name>orders</name>
<value>
<array><data>
<value><int>2311</int></value>
<value><int>1253</int></value>
<value><int>235</int></value>
</data></array>
</value>
</member>



3. Загрузка массива параметров (необходим для создания нескольких тем и т. п.):

<member>
<name>themes</name>
<value>
<array>
<data>
<value>
<struct>
<member>
<name>title</name>
<value>test1</value>
</member>
<member>
<name>desc</name>
<value>Тестовая тема 1</value>
</member>
</struct>
</value>
<value>
<struct>
<member>
<name>title</name>
<value>test2</value>
</member>
<member>
<name>desc</name>
<value>Тестовая тема 2</value>
</member>
</struct>
</value>
<value>
<struct>
<member>
<name>title</name>
<value>test3</value>
</member>
<member>
<name>desc</name>
<value>Тестовая тема 3</value>
</member>
</struct>
</value>
</data>
</array>
</value>
</member>

Похожие статьи