Описание API

API Linkum предназначено для заказчиков, у которых есть своя CRM, откуда им бы хотелось создавать заказы на крауд, соц.ссылки или отзывы, не используя при этом интерфейс Linkum.

Чтобы выполнить одну из функций ниже, вам нужно сделать POST запрос на адрес https://api.linkum.ru/json/v1/{функция}/ с параметрами $initial в виде JSON-строки.

Например, чтобы получить список созданных заказов за 1 января 2019 года, вам нужно сделать POST запрос на адрес https://api.linkum.ru/json/v1/orders_list/ с отправленной в POST параметрах JSON-строкой {"date_create_from":"2019-01-01","date_create_to":"2019-01-02"}

Авторизация:

Во всех запросах нужно отправлять заголовок с токеном, который предварительно должен быть сгенерирован на странице настроек API. Authorization: Bearer {токен}

Функции:

• (struct) user_data() — Данные пользователя. Возвращается словарь с логином, email и балансом.
• (struct) regions_list() — Список доступных регионов. Возвращается словарь с id и названием региона.
• (struct) orders_list($initial) — Список созданных заказов. Возвращается список со словарями - параметрами заказов (возможные поля см. в методе order_create). Плюс в каждом словаре заказа есть ключ placements, значение которого это словарь, где в ключе статус, а в значении список выполненных размещений по заказу в этом статусе. В параметрах функции должен быть передан хотя бы один атрибут.
  • [(array/int) order_id] — id заказа (или список id заказов),
  • [(string) tag] — пользовательский тег для заказа, не более 30 символов; позволяет привязать к заказу любой удобный вам идентификатор,
  • [(string) status] — статус заказа: new (запущено), stop (остановлено) (необязательный параметр; по-умолчанию, new),
  • [(string) date_create_from] — дата создания заказа, от (формат YYYY-MM-DD [HH:mm:ii]),
  • [(string) date_create_to] — дата создания заказа, до (формат YYYY-MM-DD [HH:mm:ii]).
  
  

  Формат данных в возвращаемом списке:

  • (int) id — id заказа,
  • (string) date_create — дата создания заказа (формат YYYY-MM-DD [HH:mm:ii]),
  • (string) url — домен или урл для размещения, не более 2000 символов,
  • (string) message — текст для размещения,
  • (float) price — цена для заказчика,
  • (boolean) is_concrete_url — размещать ли на конкретную страницу, если false - то на любую с сайта,
  • (string) placement_type — тип размещения, возможные значения,
  • (string) status — статус заказа: new (запущено), stop (остановлено), done (успешно выполнено),
  • (string) date_change_status — дата последнего изменения статуса (формат YYYY-MM-DD [HH:mm:ii]),
  • (int) num_placements_order — сколько нужно выполнить работ в заказе,
  • (int) num_placements_work — сколько работ выполняется исполнителями,
  • (int) num_placements_complete — сколько работ выполнено исполнителями,
  • (string) order_comment — комментарий к заказу для исполнителя,
  • (string) order_comment_hidden — скрытый комментарий к заказу для исполнителя.
  • (int) min_age — нужный возраст при покупке в соц.сетях, от,
  • (int) max_age — нужный возраст при покупке в соц.сетях, до,
  • (string) gender — нужный пол при покупке в соц.сетях,
  • (string) marital_status — нужное семейное положение при покупке в соц.сетях,
  • (int) min_friends_count — нужное кол-во друзей при покупке в соц.сетях, от,
  • (int) max_friends_count — нужное кол-во друзей при покупке в соц.сетях, до,
  • (array) region_ids — регион заказа (см. метод regions_list),
  • (array/string) categories — требуемые тематики (необязательный параметр, свободная строка; по-умолчанию, без тематики),
  • (string) order_card_data — поле используется для обеспечения индивидуальности исполнителей в рамках разных заказов. Если создано несколько заказов с одинаково заполненным полем order_card_data, каждый исполнитель сможет выполнить только по одному заказу из этого набора,
  • (int) custom_lifetime_execute — срок выполнения заказа, указывается в днях в случае если необходимо указать срок, отличный от стандартного (3 дня),
  • (array) placements — словарь размещений по заказу.
• (int) order_create($initial) — Создать заказ. Возвращается id заказа.
  • (string) url — домен или урл для размещения, не более 2000 символов,
  • (int) num_placements — сколько нужно выполнить работ в заказе,
  • (float) price — цена для заказчика,
  • (string) placement_type — тип размещения, возможные значения,
  • (boolean) is_concrete_url — размещать ли на конкретную страницу, если false - то на любую с сайта,
  • [(string) status] — статус заказа: new (запущено), stop (остановлено) (необязательный параметр; по-умолчанию, new),
  • [(array/string) categories] — требуемые тематики (необязательный параметр, свободная строка; по-умолчанию, без тематики),
  • [(string) tag] — пользовательский тег для заказа, не более 30 символов; позволяет привязать к заказу любой удобный вам идентификатор,
  • [(string) message] — текст для размещения,
  • [(string) order_comment] — комментарий к заказу для исполнителя,
  • [(string) order_comment_hidden] — скрытый комментарий к заказу для исполнителя.
  • [(array/int) region_ids] — регион заказа (см. метод regions_list),
  • [(string) date_start] — дата со временем, когда заказ нужно отдать исполнителям (формат YYYY-MM-DD [HH:mm:ii]),
  • [(int) min_age] — нужный возраст при покупке в соц.сетях, от,
  • [(int) max_age] — нужный возраст при покупке в соц.сетях, до,
  • [(string) gender] — нужный пол при покупке в соц.сетях, (male, female)
  • [(string) marital_status] — нужное семейное положение при покупке в соц.сетях,
  • [(int) min_friends_count] — нужное кол-во друзей при покупке в соц.сетях, от,
  • [(int) max_friends_count] — нужное кол-во друзей при покупке в соц.сетях, до,
  • [(int) daily_limit] — кол-во выполнений, которые можно разместить в один день,
  • [(int) review_len] — минимальное кол-во символов для отзыва,
  • [(string) order_card_data] — поле используется для обеспечения индивидуальности исполнителей в рамках разных заказов. Если создано несколько заказов с одинаково заполненным полем order_card_data, каждый исполнитель сможет выполнить только по одному заказу из этого набора,
  • [(int) custom_lifetime_execute] — срок выполнения заказа, указывается в днях в случае если необходимо указать срок, отличный от стандартного (3 дня),
  • [(boolean) is_need_crowd_text] — При включении данной опции исполнитель должен будет указать не только URL выполнения, но и текст размещения ссылки (опция всегда включена и не отключается для типов размещения 16 и 17).
  • [(array/string) allow_placement_urls] — Список страниц или доменов на которых разрешено размещение ссылок.
  • [(array/string) taboo_placement_urls] — Список страниц или доменов на которых запрещено размещение ссылок.
  • [(boolean) only_old_topics] — При включении данной опции у исполнителя не будет приниматься работа в свеже созданных темах и обсуждениях.
  • [(array) link_view] — При включении данной опции, ссылка будет кликабельна (передавать можно следующие параметры: no_click, redirect, short, что соответствует "Не кликабельным", "Редиректным" и "Сокращенным" ссылкам.)
  • [(boolean) is_need_screenshot] — При включении данной опции исполнитель предоставит скриншот выполненной работы
  • [(array) regions_ids] — Выбор "Географии размещения" (передавать можно следующие параметры: 225, 187, 159, 149 что соответствует "Россия", "Украина", "Казахстан", "Беларусь", а для 19-типа "Сабмиты" можно добавить 84 - США)
  • [(string) quality] — Качество размещения (!!! только) для крауд ссылок. 3 варианта: standart, plus, premium.
  • [(string) category_type] — Уровень соблюдения тематики. 2 варианта:"Соблюдать на уровне обсуждения" - topic_only, "Соблюдать на уровне площадки и обсуждения(только для премиум)" - topic_site.
  • [(int) age_of_discussion] — Давность обсуждения (!!! только для крауд ссылок), доступно только 2, 4 и 6 месяцев.
  • [(string) new_topics_type] — Разрешать новые темы (!!! только для крауд ссылок). 4 варианта: "Запрещены новые темы" - decline, "Можно создавать новые темы со ссылкой в 1-м сообщении" - allow_1, "Можно создавать новые темы со ссылкой в 3-м сообщении" - allow_3, "Можно создавать новые темы со ссылкой в 4-5-м сообщении (Премиум - качество размещения)" - allow_4
• (struct) order_change_status($initial) — Изменение статуса заказа. Возвращается словарь с параметрами заказа (возможные поля см. в методе order_create).
  • (int) order_id — id заказа,
  • (string) status — статус заказа: new (запущено), stop (остановлено), deleted (удалено).
• (struct) placements_list($initial) — Список выполненных размещений. Возвращается список со словарями - параметрами размещений. В параметрах функции должен быть передан хотя бы один атрибут.
  • [(list) placement_ids] — id размещений,
  • [(list) orders_ids] — id заказов,
  • [(string) date_create_from] — дата создания выполнения, от (формат YYYY-MM-DD [HH:mm:ii]),
  • [(string) date_create_to] — дата создания выполнения, до (формат YYYY-MM-DD [HH:mm:ii]).
  
  

  Формат данных в возвращаемом списке:

  • (int) id — id выполнения,
  • (int) order_id — id заказа,
  • (string) date_create — дата создания выполнения (формат YYYY-MM-DD [HH:mm:ii]),
  • (string) date_place — дата размещения выполнения (формат YYYY-MM-DD [HH:mm:ii]),
  • (string) date_change_status — дата изменения статуса выполнения (формат YYYY-MM-DD [HH:mm:ii]),
  • (string) url_site_place — адрес выполненного размещения,
  • (string) url_fact_placement — адрес фактически размещенной ссылки заказчика,
  • (string) url_wall_place — адрес профиля исполнителя (для размещений в соц.сетях),
  • (string) review_text — текст отзыва (для размещений отзывов),
  • (string) crowd_text — текст размещения ссылки (если для заказа есть соответствующая опция),
  • (string) status — статус выполнения, возможные значения,
  • (boolean) is_auto_approve_link — ссылка была принята автоматически спустя 7 дней.
• (struct) placement_change_status($initial) — Модерация выполнения заказчиком. Модерировать можно только выполнение в статусе wait_advertiser. Возвращается словарь с параметрами выполнения.
  • (int) placement_id — id выполнения,
  • (string) status — статус выполнения: approved (одобрить), rework (отправить на доработку), decline (отказать в приеме работы, доступно только после хотя бы одной доработки)
  • [(string) reason] — причина доработки или отклонения, не более 1000 символов (обязателен, если статус rework или decline).

Типы размещений:

• 5 — Любой форум, блог, сервис вопросов и ответов и т.п., кроме соц. сетей.
  7 — Только форумы и блоги
  6 — В любой системе вопросов и ответов
  8 — В любой системе вопросов и ответов, кроме Mail.ru
  1 — Только в системе вопросов и ответов Mail.ru
  19 — Сабмиты в каталогах и справочниках
  20 — Сабмиты на сайтах поиска работы
  21 — Сабмиты на сайтах отзывов
  22 — Сабмиты на сайтах фриланс с портфолио
  23 — Сабмиты на профилях соц-сетей
  24 — Сабмиты на профилях форумов и блогов
  25 — Любая соцсеть
  2 — Пост в ленте ВКонтакте
  12 — Пост в ленте МойМир@Mail.ru
  11 — Репост в ленте ВКонтакте
  13 — Репост в ленте МойМир@Mail.ru
  16 — Отзывы с премодерацией текста
  17 — Отзывы без премодерации текста
  18 — Отзывы с предзагруженными текстами
  

Виды статусов (со списком статусов, куда можно перейти из данного):

• new (взят исполнителем в работу),
  • wait_moderation (исполнитель выполнил работу)
  • cancelled (исполнитель отказался / не успел)
• wait_moderation (ожидает проверки модератором),
  • wait_advertiser (модератор принял, теперь проверяет заказчик)
  • refinement (модератор отправил в доработку исполнителю)
  • declined (модератор отменяет после 3 доработок)
• refinement (отправлено на доработку),
  • wait_moderation (исполнитель выполнил работу)
  • cancelled (исполнитель отказался / не успел)
• wait_advertiser (ожидает модерации заказчиком),
  • approved (приняли работу типа "Крауд")
  • wait_placement (работы с типом "Отзыв": одобрили текст отзыва и он пошел к исполнителю)
  • check_advertiser (модератор проверяет корректность отмены заказчиком)
• check_advertiser (на проверке модератором),
  • wait_advertiser (модератор принял, теперь проверяет заказчик)
  • refinement (модератор отправил в доработку исполнителю)
  • declined (модератор отменяет после 3 доработок)
• wait_placement (ожидает размещения одобренного текста отзыва),
  • check_placement (исполнитель сообщил о том что текст размещен; но текст еще может быть не виден)
  • cancelled (за 7 дней исполнитель не разместил одобренный текст)
• check_placement (на проверке размещения ботом, только для отзывов),
  • approved (бот нашел текст и подтвердил placement)
  • declined (за 7 дней бот не нашел текста)
• approved (одобрено),
  • billed (гарантийный срок прошел, списали деньги и выплатили исполнителю)
  • refinement (бот не нашел текст и отправил на доработку исполнителю, нарушен гарантийный срок в 7 дней)
• billed (пробиллено. Конечный статус),
• cancelled (отменено исп. Конечный статус),
• declined (отклонено модератором. Конечный статус),

Виды ошибок:

• 1000 — Service is temporarily inactive
  1001 — Available version API is one of {value}
  1002 — Function name not received
  1003 — Header Authorization is required
  1004 — Unsupported initial data. JSON is required
  1005 — Unsupported initial data. Array is required
  1006 — Authorization access token can not be empty
  1007 — Unknown function name {value}
  1008 — Initial key {value} is required
  1009 — Any initial key is required
  1010 — Token is invalid
  1011 — Initial key {value} is required for selected status
  2001 — No order {value}
  2002 — Order already have status {value}
  2003 — Unknown status {value}
  2004 — Initials date_create_from and date_create_to can be used only together
  2005 — Range date_create_from and date_create_to can not be more then one month
  2006 — Initial date_create_to should be greater than date_create_from
  2007 — List ids for placements should be array of integers or integer
  2008 — Wrong placement status {value}
  2009 — Wrong placement type {value}
  2010 — Need rework before decline
  2011 — List ids for orders should be array of integers or integer
  2012 — Order has been canceled