API рекламодателя

Авторизация

Авторизация происходит с помощью ключа авторизации, который должен сопровождать каждый запрос к серверу в заголовке запроса Auth-Token. Для подключения к API необходимо связаться с нашей службой поддержки, после чего Ваш персональный ключ для авторизации в API будет доступен в настройках личного кабинета.

Формат запроса API

Запрос выполняется по базовой ссылке HTTP методом, указанным в описании к методу API. К базовой ссылке могут быть добавлены фильтры или параметр для сортировки.

Формат ответа API

Для передачи данных клиенту используются форматы XML и JSON. Выбор конкретного формата зависит от заголовка Accept в запросе к серверу. Для получения ответа в формате JSON значение этого заголовка должно содержать MIME тип "application/json", для XML - "application/xml". Все общение с сервером происходит по протоколу HTTPS. В ответе пользователь получает структуру данных, содержащую запрашиваемые данные, а также информацию о текущем количестве записей на страницу, текущему номеру страницы, общему количеству страниц при текущем количестве записей на страницу и общему количеству записей.

Получение списка действий

Метод: GET
Базовая ссылка: https://sellaction.net/api/actions
Возможные фильтры:

per-page - количество отдаваемых записей(по умолчанию 100, максимум 1000)
page - постраничное смещение
date-from - фильтр по начальной дате в формате YYYY-MM-DD
date-to - фильтр по конечной дате в формате YYYY-MM-DD
order_id - фильтр по ID заказа
campaign_id - фильтр по ID кампании
site_id - фильтр по ID площадки
status - фильтр по статусу действия:
- 0 - ожидает
- 1 - подтвержден
- 2 - отменен
- 3 - ожидает подтверждения
- 4 - ожидает отмены
- 5 - оплачен

Пример запроса: https://sellaction.net/api/actions?per-page=2&page=1&status=1&sort=-date

Ответ (в формате JSON):

{
    "data" : [
        {
            "referer" : null,
            "order_sum" : "1",
            "site_id" : "1323",
            "currency" : "RUR",
            "user_agent" : null,
            "tariff_id" : "234",
            "tariff_name": "Оплаченный заказ",
            "country" : "RU",
            "buy_sum" : "0.0000",
            "status_string" : "confirm",
            "comission" : 650,
            "ip" : "8.8.8.8",
            "payment_model" : "sale",
            "time" : "01:44:52",
            "click_date" : "2016-01-02",
            "campaign_id" : "68",
            "banner_id" : "0",
            "id" : "7511522",
            "click_time" : "01:43:06",
            "date" : "2016-01-02",
            "comment" : "",
            "order_id" : "555344939",
            "status" : 1,
            "url" : "http://shop.com/index.php?skin=3105",
            "additional" : "",
            "multi_tariff" : 0,
            "tariffs_positions" : [
                {
                   "id" : 234,
                   "name" : "Оплаченный заказ",
                   "value" : 1
                }
            ]
        },
        {
            "referer" : null,
            "order_sum" : "1",
            "site_id" : "1323",
            "currency" : "RUR",
            "user_agent" : null,
            "tariff_id" : "218",
            "tariff_name": "Подтвержденный заказ",
            "country" : "RU",
            "buy_sum" : "0.0000",
            "comission" : 550,
            "ip" : "9.9.9.9",
            "status_string" : "confirm",
            "payment_model" : "sale",
            "time" : "04:48:31",
            "click_date" : "2016-01-02",
            "campaign_id" : "62",
            "banner_id" : null,
            "id" : "7511347",
            "click_time" : "04:47:48",
            "date" : "2016-01-02",
            "comment" : "",
            "order_id" : "555443993",
            "status" : 1,
            "url" : "http://shop.com",
            "additional" : "",
            "multi_tariff" : 0,
            "tariffs_positions" : [
                {
                   "id" : 218,
                   "name" : "Оплаченный заказ",
                   "value" : 1
                }
            ]
        }

    ],
    "_links" : {
        "self" : {
            "href" : "https://sellaction.net/api/actions?per-page=2&page=1&status=1&sort=-date"
        },
        "last" : {
            "href" : "https://sellaction.net/api/actions?per-page=2&page=8&status=1&sort=-date"
        },
        "next" : {
            "href" : "https://sellaction.net/api/actions?per-page=2&page=2&status=1&sort=-date"
        }
    },
    "_meta" : {
        "perPage" : 2,
        "currentPage" : 1,
        "pageCount" : 8,
        "totalCount" : 16
    }
}

Получение действия по ID

Метод: GET
Базовая ссылка: https://sellaction.net/api/actions/{id}
,где {id} - ID запрашиваемого действия.

Пример запроса: https://sellaction.net/api/action/75158

Ответ (в формате JSON):

{
    "referer" : null,
    "order_sum" : "1",
    "site_id" : "1323",
    "currency" : "RUR",
    "user_agent" : null,
    "tariff_id" : "218",
    "tariff_name": "Оплаченный заказ",
    "country" : "RU",
    "buy_sum" : "0.0000",
    "comission" : 550,
    "ip" : "9.9.9.9",
    "status_string" : "confirm",
    "payment_model" : "sale",
    "time" : "04:48:31",
    "click_date" : "2016-01-02",
    "campaign_id" : "62",
    "banner_id" : null,
    "id" : "7511347",
    "click_time" : "04:47:48",
    "date" : "2016-01-02",
    "comment" : "",
    "order_id" : "555443993",
    "status" : 1,
    "url" : "http://shop.com",
    "additional" : "",
    "multi_tariff" : 0,
    "tariffs_positions" : [
        {
            "id" : 218,
            "name" : "Оплаченный заказ",
            "value" : 1
        }
    ]
}

Описание передаваемых параметров

id - ID действия
status - Статус действия. Может принимать значения:
- 0 - ожидает
- 1 - подтвержден
- 2 - отменен
- 3 - ожидает подтверждения
- 4 - ожидает отмены
- 5 - оплачен
status_string - Строковое представление статуса действия
tariff_id - ID тарифа
tariff_name - Название тарифа
date - Дата регистрации действия
time - Время регистрации действия
click_date - Дата перехода
click_time - Время перехода
order_id - ID заказа в системе рекламодателя
comment - Комментарий к действию
buy_sum - Сумма заказа (при процентном тарифе)
payment_model - Модель действия (lead, sale)
currency - Валюта (RUR, UAH, USD, EUR, KZT)
country - Двухбуквенный код страны
banner_id - ID баннера
site_id - ID сайта
url - Ссылка перехода
ip - IP клиента
referer - Реферер клиента
user_agent - Браузер клиента
comission - Комиссия
additional - Дополнительная информация
multi_tariff - 1 если действие сконвертировано по нескольким тарифам, 0 - если по одному
tariffs_positions - Массив тарифов и их параметров

Получение списка кампаний

Метод: GET
Базовая ссылка: https://sellaction.net/api/campaigns/my

Пример запроса:
GET https://sellaction.net/api/campaigns/my?per-page=10

Получение кампании по ID

Метод: GET
Базовая ссылка: https://sellaction.net/api/campaigns/{id}
,где {id} - ID запрашиваемой кампании.

Пример запроса:
GET https://sellaction.net/api/campaigns/751

Ответ (в формате JSON):

{
    "id" : "751",
    "name" : "Campaign Name",
    "url" : "https://example.com/ex",
    "logo" : "https://sellaction.net/resources/images/campaign/somefile.JPG",
    "tariffs" : [
        {
            "id" : "145",
            "name" : "Игры на PS3",
            "processing_days" : "7",
            "hold_days" : "7",
            "type" : "percent",
            "rate" : "5.0000"
        },
        {
            "id" : "149",
            "name" : "Подарки",
            "processing_days" : "7",
            "type" : "percent",
            "hold_days" : "7",
            "rate" : "5.0000"
        },
        {
            "id" : "153"
            "name" : "Активный отдых",
            "hold_days" : "7",
            "type" : "percent",
            "rate" : "5.0000",
            "processing_days" : "7",
        }
    ],
    "prelandings" : [
        {
            "id" : "8"
            "name" : "Сайт прокладка",
            "url" : "http://layer1.com",
        }
    ],
    "landings" : [
        {
            "id" : 4,
            "name" : "Основной лендинг",
            "url" : "http://land1.com"
        },
        {
            "id" : 5
            "name" : "Мобильный лендинг",
            "url" : "http://land2.com",
        }
    ],
    "coupons" : [
        {
            "id" : "1"
            "name" : "Coupon name",
            "description" : "Some description",
            "url" : "https://example.com/akcii/coupon1.html",
            "date_start" : "2016-12-27 14:05:00",
            "date_end" : "2017-02-15 01:25:00",
            "code" : "122daFX",
            "type" : "discount",
        },
    ],
    "exclusive" : null,
    "landing_price" : "0",
    "percent_confirm" : "0.00",
    "landing_currency" : "",
    "advantages_client" : "text...",
    "additional_info" : "text...",
    "description" : "text...",
    "CR" : "0.00",
    "eCPC" : "0.47",
    "domain_parking" : null,
    "exclusive_conditions" : null,
    "rules" : "Для этого оффера запрещены контекстная реклама по бренду, мотивированный трафик и кэшбэк.",
    "categories" : [
        {
            "name" : "Авто",
            "id" : "4"
        },
        {
            "name" : "Кредиты",
            "id" : "11"
        }
    ],
    "advantages_partner" : "text...",
    "audience" : "text...",
    "currency" : "UAH",
    "traffic_categories" : [
        {
            "id" : "1",
            "name" : "Cashback"
        },
        {
            "id" : "2",
            "name" : "Popup реклама"
        },
        {
            "id" : "3",
            "name" : "Контекстная реклама"
        },
    ],
    "countries" : [
        "AT",
        "AU",
        "BY",
        "UA"
    ],
    "short_description" : "text...",
    "postclick_days" : 30,
    "allow_partner_lead_gen" : 0,
    "has_xml" : "1",
}

Описание передаваемых параметров

id - ID кампании
name - Название
logo - Ссылка на лого кампании
url - Ссылка кампании.
description - ПОписание
audience - Аудитория
domain_parking - Парковка доменов
rules - Правила
exclusive - Эксклюзивная кампания
exclusive_conditions - Эксклюзивные условия
CR
eCPC
percent_confirm - Процент подтверждения
advantages_partner - Преимущества для вебмастера
currency Валюта
landing_price - Цена на лендинге
landing_currency - Валюта цены на лендинге
advantages_client - Преимущества для клиента
short_description - Короткое описание
traffic_categories - Категории трафика
categories - Категории
postclick_days - Время, в течении которого клик может быть сконвертирован в действие.
additional_info - Дополнительная информация
landings - Лендинги
prelandings - Прелендинги
tariffs - Тарифы
coupons - Купоны
allow_partner_lead_gen - Передача заявок вебмастером. 0 - запрещена, 1 - разрешена.
has_xml - Наличие товарных XML фидов. 0 - нет, 1 - есть.

Получение списка категорий кампаний

Метод: GET
Базовая ссылка: https://sellaction.net/api/campaign-categories

Пример запроса:
GET https://sellaction.net/api/campaign-categories

Описание передаваемых параметров

id - ID категории
parent_id - ID родительской категории
name - Название

Регистрация действия

Метод: POST
Базовая ссылка: https://sellaction.net/api/actions

Обязательные параметры:

sauid - SAuid параметр, с которым клиент перешел на сайт рекламодателя
tariffs - Массив тарифов и их параметров вида tariffs[TARIFF_ID]=TARIFF_PARAM, где
- TARIFF_ID - ИД тарифа.
- TARIFF_PARAM - параметр тарифа:
order_id - ID заказа

Необязательные параметры:

created - Дата и время действия в часовом поясе GMT в формате yyyy-MM-dd HH:mm:ss (ICU). Пример: 2011-11-22 18:34:12
ip - IP адрес клиента
country - Двухбуквенный код страны
user_agent - User_agent клиента
referrer - Реферер
client_id - ИД клиента

Пример запроса
POST https://sellaction.net/api/actions
POST data: sauid=1bfc900dab1f63123&tariffs[193]=200.50&tariffs[194]=15.00&order_id=123669&created=2016-07-21+12%3A00%3A03&country=KZ&ip=1.2.3.4

Успех операции определяет HTTP код ответа 201.
В случае возникновения ошибок, ответ с кодом 422 будет содержать поля, не прошедшие проверку.

Изменение действия

Метод: PUT
Базовая ссылка: https://sellaction.net/api/actions/{id}
{id} - ID действия в системе SellAction, статус которого нужно изменить, или ID заказа в системе рекламодателя. Во втором случае в теле запроса необходимо указать параметр campaign_id с ID кампании.

Обязательные параметры:

campaign_id - ИД кампании (параметр необходим только в случае, если {id} - это ID заказа в системе рекламодателя)
status - Статус действия:

wait - ожидает
confirm - подтверждено
cancel - отменено
delivery - доставляется (промежуточный статус, который может быть потом подтвержден или отменен)

Необязательные параметры:

comment - Комментарий в случае отмены действия
tariffs - Массив тарифов и их параметров (см. описание из п."Регистрация действия"). Передается в случае, если сумма заказа изменилась.
payment - Сумма платежа (вознаграждения) системе за подтверждённое действие.

Пример запроса:
PUT https://sellaction.net/api/actions/745515
PUT data: campaign_id=123&status=cancel&comment=отказ+клиента

Пример запроса с изменением суммы заказа:
PUT https://sellaction.net/api/actions/745515
PUT data: campaign_id=123&status=confirm&tariffs[111]=110.00

Успех операции определяет HTTP код ответа 200.
В случае возникновения ошибок, ответ с кодом 422 будет содержать поля, не прошедшие проверку.

Получение списка потерянных заказов

Метод: GET
Базовая ссылка: https://sellaction.net/api/lost-orders
Возможные фильтры:

per-page - количество отдаваемых записей(по умолчанию 100, максимум 1000)
page - постраничное смещение
date-from - фильтр по дате совершения заказа в формате YYYY-MM-DD (начало диапазона поиска)
date-to - фильтр по дате совершения заказа в формате YYYY-MM-DD (конец диапазона поиска)
order_id - фильтр по ID заказа
campaign_id - фильтр по ID кампании
site_id - фильтр по ID площадки
status - фильтр по статусу действия:
- 0 - ожидает
- 1 - подтверждено
- 2 - отклонено

Пример запроса: https://sellaction.net/api/lost-orders?per-page=2&page=1&status=1&sort=-date

Ответ (в формате JSON):

{
   "data" : [
      {
         "files" : [
            "https://sellaction.net/resources/images/lost_order/bcf42da6a67a4aa33b54e1d00843eea3.png"
         ],
         "created" : "2017-08-08 19:00:53",
         "status" : 1,
         "campaign_id" : 29,
         "date" : "2017-08-09 17:00:00",
         "buy_sum" : 1000,
         "action_id" : 0,
         "tariff_id" : 153,
         "order_id" : "sd123132",
         "sauid" : "",
         "comment" : "test",
         "reason" : "",
         "site_id" : 1,
         "id" : 4
      },
      {
         "id" : 14,
         "site_id" : 1,
         "reason" : "",
         "comment" : "test",
         "sauid" : "",
         "order_id" : "23423r23r",
         "tariff_id" : 0,
         "buy_sum" : 1112,
         "action_id" : 0,
         "date" : "2017-08-17 19:00:00",
         "campaign_id" : 29,
         "status" : 0,
         "created" : "2017-08-14 16:58:54",
         "files" : [
            "https://sellaction.net/resources/images/lost_order/2c86b673b413705d54a017ff86cc23ac.png",
            "https://sellaction.net/resources/images/lost_order/98d15e70a5e94b784f824d7b9a0344e1.png"
         ]
      }
   ],
   "_meta" : {
      "perPage" : 2,
      "currentPage" : 1,
      "totalCount" : 3,
      "pageCount" : 2
   },
   "_links" : {
      "last" : {
         "href" : "https://sellaction.net/api/lost-orders?per-page=2&page=2"
      },
      "next" : {
         "href" : "https://sellaction.net/api/lost-orders?per-page=2&page=2"
      },
      "self" : {
         "href" : "https://sellaction.net/api/lost-orders?per-page=2&page=1"
      }
   }
}

Получение потерянного заказа по ID

Метод: GET
Базовая ссылка: https://sellaction.net/api/lost-orders/{id}
,где {id} - ID запрашиваемого потерянного заказа.

Пример запроса: https://sellaction.net/api/lost-orders/75158

Ответ (в формате JSON):

{
   "id" : 4,
   "order_id" : "AZ777888999",
   "status" : 1,
   "created" : "2017-08-08 19:00:53",
   "comment" : "test",
   "action_id" : 0,
   "files" : [
      "https://sellaction.net/resources/images/lost_order/bcf42da6a67a4aa33b54e1d00843eea3.png"
   ],
   "site_id" : 1,
   "date" : "2017-08-09 17:00:00",
   "tariff_id" : 153,
   "buy_sum" : 1000,
   "sauid" : "",
   "reason" : "",
   "campaign_id" : 29
}

Подтверждиние или отклонение потерянного заказа

Метод: PUT
Базовая ссылка: https://sellaction.net/api/lost-orders/{id}
{id} - ID потерянного заказа в системе SellAction, статус которого нужно изменить.

Обязательные параметры:

status - Статус заявки:

1 - Подтвердить
2 - Отклонить

tariff_id - ID тарифа (в случае подтверждения заявки)
payment_sum - Сумма выплаты за действие (в случае подтверждения заявки по тарифу, зависящему от этой суммы)
action_status - Статус действия (в случае подтверждения заявки):

0 - Ожидает
3 - Подтвердить
4 - Отклонить

reason - Причина (в случае отклонения заявки)

Пример запроса:
PUT https://sellaction.net/api/lost-orders/123456
PUT data: status=2&reason=неверный+ID+заказа

Описание передаваемых параметров

id - ID потерянного заказа (в системе SellAction)
status - Статус действия. Может принимать значения:
- 0 - ожидает
- 1 - подтверждено
- 2 - отклонено
order_id - ID заказа в системе рекламодателя
comment - Комментарий к потерянному заказу
reason - Комментарий рекламодателя (заполняется при отклонении заявки)
tariff_id - ID тарифа
date - Дата совершения заказа
created - Дата создания заявки вебмастером
buy_sum - Сумма заказа (при процентном тарифе)
site_id - ID сайта
campaign_id - ID кампании
sauid - ID перехода
files - Ссылки на прикрепленные вебмастером скриншоты.
action_id - ID действия в системе SellAction (создается при подтверждении потерянного заказа).

Форматы ошибок API

О статусе выполнения запроса свидетельствует код ответа сервера с соответствующим статусом. В случае, если ошибка требует более детального описания, в теле ответа может находится список с параметром message. значение которого будет расширенным описанием ошибки. Сводный список кодов состояния HTTP, используемых в ответах API:

200: OK. Все сработало именно так, как и ожидалось.
201: Ресурс был успешно создан в ответ на POST-запрос. Заголовок Location содержит URL, указывающий на только что созданный ресурс.
204: Запрос обработан успешно, и в ответе нет содержимого.
304: Ресурс не изменялся. Можно использовать закэшированную версию.
400: Неверный запрос. Может быть связано с разнообразными проблемами на стороне пользователя, такими как неверные JSON-данные в теле запроса, неправильные параметры действия, и т.д.
401: Аутентификация завершилась неудачно.
403: Аутентифицированному пользователю не разрешен доступ к указанной точке входа API.
404: Запрошенный ресурс не существует.
405: Метод не поддерживается. Сверьтесь со списком поддерживаемых HTTP-методов в заголовке Allow.
415: Неподдерживаемый тип данных. Запрашивается неправильный тип данных или номер версии.
422: Проверка данных завершилась неудачно (в ответе на POST-запрос, например). Подробные сообщения об ошибках смотрите в теле ответа.
429: Слишком много запросов. Запрос отклонен из-за превышения ограничения частоты запросов.
500: Внутренняя ошибка сервера. Возможная причина — ошибки в самой программе.