Интерфейс API-функций FinAsset позволяет выполнять большую часть действий вебмастера и поставщика, реализованных на сайте. Чтобы подключить API, зайдите на страницу своего профиля в системе. Взаимодействие с сервисом осуществляется по протоколу HTTP/HTTPS. Формат запроса - чистый POST. Формат результата - JSON. Ограничений на количество запросов нет.
Чтобы начать работу с API-интерфейсом, необходимо получить API-токен. Он доступен в разделе «Профиль» системы. Авторизуйтесь на сайте, чтобы видеть свой токен.
Данные для запроса передаются в POST-части запроса в чистом виде. Их не нужно каким-либо образом кодировать, не нужно помещать в JSON или XML-представление. Но если очень хочется, вы можете использовать JSON POST с заголовком Content-type: application/json
.
Функции веб-мастера позволяют работать с потоками и получать статистическую информацию аккаунта.
Добавление лида
URL: https://my.finasset.ru/api/wm/push.json?id={token}
Функция позволяет добавить новый лид от имени вебмастера. Данные нового лида передаются в POST-запросе.
На входе функция принимает следующие данные о лиде:
Поле | Описание |
---|---|
flow * |
Идентификатор потока, к которому привязывается заказ (обязательный параметр) |
offer * |
Идентификатор оффера из списка (обязательный параметр) |
ip * |
IP-адрес покупателя (обязательный параметр) |
name |
ФИО или имя покупателя |
last |
Фамилия покупателя |
phone * |
Телефон покупателя в международном формате с кодом страны, например 79876543210 (обязательный параметр) |
phonecc |
Код страны телефона в формате +7 (необязательный параметр). При указании этого параметра, номер телефона в phone всё равно должен передаваться с кодом страны. |
email |
Электронная почта покупателя |
ua |
User-Agent браузера покупателя |
country |
Двухбуквенный ISO-код страны покупателя, если не передан - вычисляется на основании IP-адреса. |
currency |
Трёхбуквенный код валюты покупателя, например RUB или BYR, по умолчанию вычисляется на основании страны покупателя |
comment |
Дополнительный комментарий по заказу. |
utm_source |
Метка utm_source до 255 символов, подходит для статистики |
utm_campaign |
Метка utm_campaign до 255 символов, подходит для статистики |
utm_content |
Метка utm_content до 255 символов, подходит для статистики |
utm_term |
Метка utm_term до 255 символов, подходит для статистики |
utm_medium |
Метка utm_medium до 255 символов, подходит для статистики |
subid |
Метка subid до 255 символов, только для трекеров - не видна в статистике |
uuid |
Метка uuid до 255 символов, только для трекеров - не видна в статистике |
sub1 |
Метка sub1 до 255 символов, только для трекеров - не видна в статистике |
sub2 |
Метка sub2 до 255 символов, только для трекеров - не видна в статистике |
sub3 |
Метка sub3 до 255 символов, только для трекеров - не видна в статистике |
sub4 |
Метка sub4 до 255 символов, только для трекеров - не видна в статистике |
sub5 |
Метка sub5 до 255 символов, только для трекеров - не видна в статистике |
index |
Почтовый индекс адреса доставки в формате 127000 |
addr |
Адрес доставки. Может содержать в себе полный адрес без индекса, если не используются поля ниже. В противном случае содержит только номер дома, корпуса, квартиры или офиса. |
area |
Регион доставки, например, Московская обл. |
city |
Город доставки, например Москва |
street |
Улица по адресу доставки, например ул. Мира |
base |
Цена единицы товара в валюте заказа. |
count |
Количество товара. |
discount |
Скидка на товар в процентах. |
more |
Сумма добавочной стоимости заказа, например, наценки за экспресс-доставку. |
mobile |
Укажите 0 для десктоп-трафика и 1 для мобильного трафика |
Результатом выполнения функции является ассоциативный массив:
Поле | Описание |
---|---|
status |
Результат выполнения операции: ok в случае успешного выполнения, error в случае ошибки |
id |
Идентификатор добавленного лида (в случае успеха) |
pin |
Внутренний пароль лида для уточнения данных, можете игнорировать. |
url |
Ссылка входа в личный кабинет пользователя (autologin). Если отсутствует - автологин не используется для данного оффера. |
message |
Сообщение об ошибке, которое можно показать покупателю. |
error |
Идентификатор ошибки:
|
bad |
Список обязательных полей, которые не были указаны при отправке. |
info |
Уточнение причины блокировки заказа для ban , access и traffic :
|
Пример успешного ответа функции:
{ "status" : "ok", "id" : 1234 }
Пример ответа функции при возникновении ошибки:
{ "status" : "error", "error" : "nooffer" }
Импорт цены клика
URL: https://my.finasset.ru/api/wm/cost.json?id={token}
Функция задаёт цену клика для потока по указанным условиям. Позволяет использовать функционал расчёта ROI. Данные могут передаваться как в GET, так и в POST-запросе. В запросе обязательно должны присутствовать параметры cpc
или cost
и хотя бы одно условие (даты, поток, UTM-метки). Цена присваивается только тем кликам, которые система считает входящими - уникальеым кликам на прелендингах и уникальным кликам на лендингах без использования прелендинга.
На входе функция принимает следующие данные о цене клика:
Поле | Описание |
---|---|
cpc * |
Стоимость за один клик |
cost * |
Общая стоимость всех кликов по указанным условиям |
currency |
ISO-код валюты цены, например, USD |
from и to |
Даты начала и окончания периода, по которому задавать цену. Может передаваться как в формате UNIX Timestamp, так и в виде ГГГГ-ММ-ДД ЧЧ:ММ:СС или другом стандартном формате. |
flow |
Идентификатор потока |
utms |
Метка utm_source |
utmc |
Метка utm_campaign |
utmn |
Метка utm_content |
utmt |
Метка utm_term |
utmm |
Метка utm_medium |
extu |
Метка "Идентификатор" для агентств |
exts |
Метка "Источник" для агентств |
Вы также можете одновременно обновлять несколько ценников одним запросом, для этого объедините все запросы в массив batch
и отправьте его через POST, например:
{
"batch": [
{
"flow": 42,
"cost": 1984,
"currency": "usd"
},
{
"from": "2020-04-04 00:00:00",
"to": "2020-04-07 23:59:59",
"cpc": 1.337,
"currency": "eur"
}
]
}
Результатом выполнения функции является ассоциативный массив:
Поле | Описание |
---|---|
status |
Результат выполнения операции: ok в случае успешного выполнения, error в случае ошибки |
ok и bad |
Количество успешных и неудачных запросов на установку цены. Обычно, содержит ответ ok=1 |
Пример успешного ответа функции:
{ "status" : "ok", "ok" : 1, "bad": 0 }
Пример ответа функции при возникновении ошибки:
{ "status" : "error", "error" : "nooffer" }
Статистика по лидам
URL: https://my.finasset.ru/api/wm/lead.json?id={token}
ID функции - lead
. Функция предоставляет список лидов и их статус по списку идентификаторов или за указанную дату.
Поле | Описание |
---|---|
ids |
Список идентификаторов лидов через запятую. Рекомендуется проверять не более 20 лидов за один запрос. |
day |
Дата статистики в формате ГГГГ-ММ-ДД . Необязательный параметр. По умолчанию используется сегодняшний день. Игнорируется при указании списка идентификаторов. |
from to |
Отбор заказов по дате с from до to . Дата указывается в формате ГГГГ-ММ-ДД. Могут использоваться как оба параметра одновременно, так и один из параметров по отдельности. |
offer |
ID оффера для получения статистики. Необязательный параметр. По умолчанию статистика выводится для всех офферов. |
flow |
ID потока для получения статистики. Необязательный параметр. По умолчанию статистика выводится для всех потоков. |
site |
Идентификатор сайта-источника. Список сайтов можно получить с помощью функции sites. |
status |
Статус заказа:
|
Результатом выполнения функции является массив лидов. Каждый элемент включает в себя следующие поля:
Поле | Описание |
---|---|
id |
Идентификатор заказа |
time |
Время поступления заказа в формате UNIX-timestamp |
stage |
Символьный статус заказа:
|
phase |
Числовой статус заказа:
|
custom |
Оргинальный текстовый статус заказа из CRM-системы рекламодателя (при наличии) |
reason |
Идентификатор причины отказа:
|
reason_text |
Текстовое значение причины отказа |
offer |
Идентификатор оффера |
offer_name |
Название оффера |
flow |
Идентификатор потока |
site |
Идентификатор лендинга |
site_url |
URL лендинга |
space |
Идентификатор прелендинга |
space_url |
URL прелендинга |
ip |
IP-адрес покупателя |
utm_* |
UTM-метки заказа: utm_source, utm_content, utm_campaign, utm_medium, utm_term |
Пример ответа функции:
[ { "id": 10101, "time": "1498127780", "stage": "trash", "phase": 5, "reason": 1, "reason_text": "Некорректный номер", "hold": 0, "comment": null, "cash": 700, "offer": 234, "offer_name": "Shiny test offer", "flow": 4838, "site": 123, "site_url": "land.cpa/test-offer", "space": 0, "space_url": false, "ip": "12.34.56.78", "utm_source": "google", "utm_content": "321012", "utm_campaign": "321", "utm_medium": "cpc", "utm_term": "neverland" } ]
Статистика по датам
URL: https://my.finasset.ru/api/wm/stats.json?id={token}
Функция предоставляет статистику по кликам и заказам, разбитую по датам, аналогично разделу «Статистика».
На входе функция получает следующие параметры:
Поле | Описание |
---|---|
from |
Дата начала статистики в формате ГГГГ-ММ-ДД . Необязательный параметр. По умолчанию используется дата неделю назад. |
to |
Дата окончания статистики в формате ГГГГ-ММ-ДД . Необязательный параметр. По умолчанию используется сегодняшний день. |
offer |
ID оффера для получения статистики. Необязательный параметр. По умолчанию статистика выводится для всех офферов. |
flow |
ID потока для получения статистики. Необязательный параметр. По умолчанию статистика выводится для всех потоков. |
Результатом выполнения функции является ассоциативный массив. Идентификатором каждого элемента служит дата статистики в формате ГГГГММДД
. Каждый элемент включает в себя следующие поля:
Поле | Описание |
---|---|
id |
Дата статистики в формате ГГГГММДД |
spaces |
Количество кликов по прелендингам |
suni |
Количество уникальных кликов по прелендингам |
sgood |
Количество успешных визитов на прелендинг |
stime |
Среднее время пользователя на прелендинге в секундах |
clicks |
Количество кликов по лендингам |
unique |
Количество уникальных кликов по лендингам |
good |
Количество успешных визитов на лендинг |
time |
Среднее время пользователя на лендинге в секундах |
ct |
Общее количество заказов без учёта треша |
mt |
Общая сумма по лидам без учёта треша |
ca |
Количество заказов в статусе «Принят» |
ma |
Сумма по лидам в статусе «Принят» |
cc |
Количество заказов в статусе «Отменён» без учёта треша |
mc |
Сумма по лидам в статусе «Отменён» без учёта треша |
cw |
Количество заказов в статусе «Ожидает» |
mw |
Сумма по лидам в статусе «Ожидает» |
ch |
Количество заказов в статусе «Холд» |
mh |
Сумма по лидам в статусе «Холд» |
cx |
Количество невалидных заказов (треш) |
mx |
Сумма по невалидным лидам (треш) |
Пример ответа функции:
{ "20241211": { "id": "20241211", "space": 321, "suni": 291, "sgood": 153, "stime": 23.45, "clicks": 113, "unique": 93, "time": 34.56, "good": 80, "ct": 13, "mt": 9100, "ca": 5, "ma": 3500, "cc": 3, "mc": 2100, "cw": 5, "mw": 3500, "cw": 1, "mw": 1000, "cx": 2, "mx": 1400 } }
Статистика по кликам
URL: https://my.finasset.ru/api/wm/click.json?id={token}
Функция предоставляет статистику по кликам и заказам, сгруппированную по выбранному параметру. Данная функция доступна как веб-мастерам, так и агентствам.
На входе функция получает следующие параметры:
Поле | Описание |
---|---|
item * |
Обязательный параметр. Поле, по которому производится группировка статистики:
|
from |
Дата начала статистики в формате ГГГГ-ММ-ДД . По умолчанию используется дата неделю назад. |
to |
Дата окончания статистики в формате ГГГГ-ММ-ДД . По умолчанию используется сегодняшний день. |
offer |
Фильтрация по ID оффера. |
flow |
Фильтрация по ID потока. |
site |
Фильтрация по ID сайта. |
utms |
Фильтрация по UTM-метке utm_source. |
utmc |
Фильтрация по UTM-метке utm_campaign. |
utmn |
Фильтрация по UTM-метке utm_content. |
utmt |
Фильтрация по UTM-метке utm_term. |
utmm |
Фильтрация по UTM-метке utm_medium. |
extu |
Фильтрация по внешнему ИД на стороне агентства. |
exts |
Фильтрация по ИД вебмастера на стороне агентства. |
Результатом выполнения функции является ассоциативный массив. Идентификатором каждого элемента служит идентификатор выбранного элемента группировки. Каждый элемент включает в себя следующие поля:
Поле | Описание |
---|---|
id |
Идентификатор элемента группировки |
name |
Название элемента группировки, если применимо |
spaces |
Количество кликов по прелендингам |
suni |
Количество уникальных кликов по прелендингам |
sgood |
Количество успешных визитов на прелендинг |
stime |
Среднее время пользователя на прелендинге в секундах |
clicks |
Количество кликов по лендингам |
unique |
Количество уникальных кликов по лендингам |
good |
Количество успешных визитов на лендинг |
time |
Среднее время пользователя на лендинге в секундах |
ct |
Общее количество заказов без учёта треша |
mt |
Общая сумма по лидам без учёта треша |
ca |
Количество заказов в статусе «Принят» |
ma |
Сумма по лидам в статусе «Принят» |
cc |
Количество заказов в статусе «Отменён» без учёта треша |
mc |
Сумма по лидам в статусе «Отменён» без учёта треша |
cw |
Количество заказов в статусе «Ожидает» |
mw |
Сумма по лидам в статусе «Ожидает» |
ch |
Количество заказов в статусе «Холд» |
mh |
Сумма по лидам в статусе «Холд» |
cx |
Количество невалидных заказов (треш) |
mx |
Сумма по невалидным лидам (треш) |
Пример ответа функции:
{ "123": { "id": "123", "name": "Shiny test offer", "space": 321, "suni": 291, "sgood": 153, "stime": 23.45, "clicks": 113, "unique": 93, "time": 34.56, "good": 80, "ct": 13, "mt": 9100, "ca": 5, "ma": 3500, "cc": 3, "mc": 2100, "cw": 5, "mw": 3500, "cw": 1, "mw": 1000, "cx": 2, "mx": 1400 } }
Список офферов
URL: https://my.finasset.ru/api/wm/offers.json?id={token}
Функция позволяет получить список активных офферов, их описание и данные о конверсии. Чтобы показать информацию только по одному офферу, укажите его идентификатор в параметре offer
.
Результатом выполнения функции является ассоциативный массив списка офферов со следующими полями:
Поле | Описание |
---|---|
id |
Идентификатор оффера в системе |
name |
Полное название оффера |
short |
Краткое название оффера |
cid |
Идентификатор категории оффера |
cat |
Название категории оффера |
epc |
EPC - цена клика (EPC) |
cr |
Convert Ratio, соотношение уникальных посетителей к количеству успешных заказов |
approve |
Процент подтверждения заказов с сайта |
geo goal |
Список географических или обычных целей по офферу с указанием цен и отчислений, содержит поля:
|
land space |
Список лендингов и прелендингов оффера, аналогично списка сайтов:
|
Пример ответа сервера:
{ "31": { "id": 31, "name": "Shiny test offer", "short": "Testing", "cid": 2, "cat": "Health and beauty", "epc": 262.5, "cr": 150, "appr": 42.9, "geo": { "ru": { "code": "ru", "name": "Россия", "price": 990, "currency": "rub", "cr": 6.2, "epc": 18.4, "approve": 71.2, "desktop": { "base": 600, "upsale": 30, "crossale": 30, "percent": 0, "currency": "rub" }, "mobile": { "base": 500, "upsale": 25, "crossale": 25, "percent": 0, "currency": "rub" } }, }, "land": { "123": { "id": 123, "url": "http://land.cpa/test-land/", "epc": 23.4, "cr": 5.6, "approve": 78.9, "mobile": 1, "default": true }, }, "space": { "234": { "id": 234, "url": "http://blog.cpa/test-space/", "epc": 12.3, "cr": 4.5, "approve": 67.8, "mobile": 0, "default": false }, } } }
Сайты оффера
URL: https://my.finasset.ru/api/wm/sites.json?id={token}
Функция позволяет получить список сайтов, прикреплённых к указанному офферу. На входе функция получает один параметр: offer
- идентификатор оффера, для которого требуется получить список сайтов.
Результатом выполнения функции является ассоциативный массив с двумя полями: land
и space
. Первое содержит список лендингов данного оффера, второе - список доступных преленлингов. По каждому из сайтов представлена следующая информация:
Поле | Описание |
---|---|
id |
Идентификатор сайта в системе |
url |
Полный адрес сайта |
epc |
EPC - Earn Per Click, средний доход за каждый клик |
cr |
Convert Ratio, соотношение уникальных посетителей к количеству успешных заказов |
approve |
Процент подтверждения заказов с сайта |
mobile |
Оптимизация сайта под мобильные устройства:
|
Пример ответа сервера
{ "land": { "123": { "id": 123, "url": "http://land.cpa/test-land/", "epc": 23.4, "cr": 5.6, "approve": 78.9, "mobile": 1 }, }, "space": { "234": { "id": 234, "url": "http://blog.cpa/test-space/", "epc": 12.3, "cr": 4.5, "approve": 67.8, "mobile": 0 }, } }
Список потоков
URL: https://my.finasset.ru/api/wm/flows.json?id={token}
Функция возвращает список потоков, созданных веб-мастером. На входе функция получает один параметр: offer
- идентификатор оффера, для которого требуется получить список существующих потоков.
Результатом выполнения функции является ассоциативный массив со списком потоков:
Поле | Описание |
---|---|
id |
Идентификатор потока в системе |
url |
Полная ссылка потока |
offer |
ID оффера потока |
offername |
Название оффера потока |
name |
Название потока |
epc |
EPC - Earn Per Click, средний доход за каждый клик |
cr |
Convert Ratio, соотношение уникальных посетителей к количеству успешных заказов |
total |
Общий заработок по потоку |
site |
Идентификатор лендинга |
siteurl |
URL лендинга |
space |
Идентификатор прелендинга (ноль - не используется) |
spaceurl |
URL прелендинга (false - не используется) |
traffback |
Ссылка трафбека, куда перенаправляются пользователи, не подходящие по ГЕО |
postback |
Ссылка для отправки PostBack-запросов |
metrika |
Идентификатор счётчика Яндекс.Метрика |
google |
Идентификатор счётчика Google Tag Manager |
vkcom |
Идентификатор пикселя VKcom |
facebook |
Идентификатор пикселя Facebook |
utm_* |
UTM-метки: utm_source, utm_campaign, utm_content, utm_term, utm_medium |
Пример ответа функции:
{ "123": { "id": 123, "url": "http://blog.cpa/test-space/?flow=123&l=234", "offer": 45, "offername": "Shiny test offer", "name": "Still shiny 45", "epc": 12.3, "cr": 4.5, "total": 550, "site": 234, "siteurl": "land.cpa/test-site", "space": 345, "spaceurl": "blog.cpa/test-space", "traffback": "", "postback": "http://help.me/iamtrapped.php?key=inroom&number=5&status={stage}", "metrika": "123456789", "google": "123-ABDC", "vkcom": "VK-ABCD-1234", "facebook": "1234-56-7890", "utm_source": "google", "utm_campaign": "343", "utm_content": "987652", "utm_term": "helloworld", "utm_medium": "cpc" }, }
Создание потока
URL: https://my.finasset.ru/api/wm/add.json?id={token}
Функция создаёт новый поток по офферу.
На входе функция получает идентификатор оффера, по которому требуется создать поток. Идентификатор оффера передаётся в параметре offer
, список идентификаторов можно получить в функции offers.
Результатом выполнения функции является ассоциативный массив:
Поле | Описание |
---|---|
status |
Результат выполнения операции: ok в случае успешного выполнения, error в случае ошибки |
id |
Идентификатор созданного потока |
error |
Идентификатор ошибки: offer-inactive при работе с неактивным оффером, request-error в случае внутренней ошибки системы |
Пример успешного ответа функции:
{ "status" : "ok", "id" : 1234 }
Пример ответа функции при возникновении ошибки:
{ "status" : "error", "error" : "offer-inactive" }
Редактирование потока
URL: https://my.finasset.ru/api/wm/edit.json?id={token}
Функция позволяет изменить настройки потока. Идентификатор потока является обязательным параметром, остальные параметры не обязательны для передачи.
На входе функция получает следующие параметры:
Поле | Описание |
---|---|
flow * |
ID потока для изменения |
name |
Новое название потока |
site |
Идентификатор лендинга |
space |
Идентификатор прелендинга (ноль - не требуется) |
drt |
Идентификатор паркованного домена для перенаправления (ноль - не требуется) |
dst |
Идентификатор паркованного домена лендингов (ноль - не требуется) |
dsp |
Идентификатор паркованного домена прелендингов (ноль - не требуется) |
url |
Ссылка трафбека, куда перенаправляются пользователи, не подходящие по ГЕО |
pbu |
Ссылка для отправки PostBack-запросов |
mtrk |
Идентификатор счётчика Яндекс.Метрика |
ga |
Идентификатор счётчика Google Tag Manager |
vk |
Идентификатор пикселя VKcom |
fb |
Идентификатор пикселя Facebook |
utms |
UTM-метка utm_source |
utmc |
UTM-метка utm_campaign |
utmn |
UTM-метка utm_content |
utmt |
UTM-метка utm_term |
utmm |
UTM-метка utm_medium |
Результатом выполнения функции является ассоциативный массив:
Поле | Описание |
---|---|
status |
Результат выполнения операции: ok в случае успешного выполнения, error в случае ошибки |
error |
Идентификатор ошибки: access-denied при работе с недоступным потоком, request-error в случае внутренней ошибки системы |
Пример успешного ответа функции:
{ "status" : "ok" }
Пример ответа функции при возникновении ошибки:
{ "status" : "error", "error" : "access-denied" }
Удаление потока
URL: https://my.finasset.ru/api/wm/del.json?id={token}
Функция удаляет поток. На входе она получает идентификатор потока, который требуется удалить. Идентификатор оффера передаётся в параметре flow
.
Результатом выполнения функции является ассоциативный массив:
Поле | Описание |
---|---|
status |
Результат выполнения операции: ok в случае успешного выполнения, error в случае ошибки |
error |
Идентификатор ошибки: access-denied при работе с недоступным потоком, request-error в случае внутренней ошибки системы |
Пример успешного ответа функции:
{ "status" : "ok" }
Пример ответа функции при возникновении ошибки:
{ "status" : "error", "error" : "access-denied" }
API-интерфейс поставщика позволяет произвести интеграцию вашего собственного интерфейса с нашей системой обработки заказов.
Добавление заказа
URL: https://my.finasset.ru/api/comp/add.json?id={token}
Функция позволяет добавить новый лид от имени компании, без указания источника поступления лида. Данные нового лида передаются в POST-запросе.
На входе функция принимает следующие данные о лиде:
Поле | Описание |
---|---|
offer * |
Идентификатор оффера из списка (обязательный параметр) |
ip * |
IP-адрес покупателя (обязательный параметр) |
name |
ФИО или имя покупателя |
last |
Фамилия покупателя |
phone * |
Телефон покупателя в международном формате с кодом страны, например 79876543210 (обязательный параметр) |
phonecc |
Код страны телефона в формате +7 (необязательный параметр). При указании этого параметра, номер телефона в phone всё равно должен передаваться с кодом страны. |
email |
Электронная почта покупателя |
ua |
User-Agent браузера покупателя |
country |
Двухбуквенный ISO-код страны покупателя, если не передан - вычисляется на основании IP-адреса. |
currency |
Трёхбуквенный код валюты покупателя, например RUB или BYR, по умолчанию вычисляется на основании страны покупателя |
comment |
Дополнительный комментарий по заказу. |
utm_source |
Метка utm_source до 255 символов, подходит для статистики |
utm_campaign |
Метка utm_campaign до 255 символов, подходит для статистики |
utm_content |
Метка utm_content до 255 символов, подходит для статистики |
utm_term |
Метка utm_term до 255 символов, подходит для статистики |
utm_medium |
Метка utm_medium до 255 символов, подходит для статистики |
subid |
Метка subid до 255 символов, только для трекеров - не видна в статистике |
uuid |
Метка uuid до 255 символов, только для трекеров - не видна в статистике |
sub1 |
Метка sub1 до 255 символов, только для трекеров - не видна в статистике |
sub2 |
Метка sub2 до 255 символов, только для трекеров - не видна в статистике |
sub3 |
Метка sub3 до 255 символов, только для трекеров - не видна в статистике |
sub4 |
Метка sub4 до 255 символов, только для трекеров - не видна в статистике |
sub5 |
Метка sub5 до 255 символов, только для трекеров - не видна в статистике |
index |
Почтовый индекс адреса доставки в формате 127000 |
addr |
Адрес доставки. Может содержать в себе полный адрес без индекса, если не используются поля ниже. В противном случае содержит только номер дома, корпуса, квартиры или офиса. |
area |
Регион доставки, например, Московская обл. |
city |
Город доставки, например Москва |
street |
Улица по адресу доставки, например ул. Мира |
base |
Цена единицы товара в валюте заказа. |
count |
Количество товара. |
discount |
Скидка на товар в процентах. |
more |
Сумма добавочной стоимости заказа, например, наценки за экспресс-доставку. |
mobile |
Укажите 0 для десктоп-трафика и 1 для мобильного трафика |
Результатом выполнения функции является ассоциативный массив:
Поле | Описание |
---|---|
status |
Результат выполнения операции: ok в случае успешного выполнения, error в случае ошибки |
id |
Идентификатор добавленного заказа (в случае успеха) |
pin |
Внутренний пароль лида для уточнения данных, можете игнорировать. |
url |
Ссылка входа в личный кабинет пользователя (autologin). Если отсутствует - автологин не используется для данного оффера. |
message |
Сообщение об ошибке, которое можно показать покупателю. |
error |
Идентификатор ошибки:
|
bad |
Список обязательных полей, которые не были указаны при отправке. |
info |
Уточнение причины блокировки заказа для ban , access и traffic :
|
Пример ответа функции:
{ "status" : "ok", "id" : 1234 }
Список заказов
URL: https://my.finasset.ru/api/comp/list.json?id={token}
Функция позволяет получить список заказов. Параметры отбора могут передаваться в GET или POST-запросе.
На входе функция может использовать следующие параметры для отбора заказов:
Поле | Описание |
---|---|
oid |
Внутренний идентификатор заказа FinAsset или список идентификаторов через запятую |
ids[] |
Массив внутренних идентификатор заказа FinAsset. |
eid |
Внешний идентификатор заказа в интерфейсе поставщика или список идентификаторов через запятую |
eids[] |
Массив внешних идентификатор заказа из интерфейса поставщика. |
status |
Статус заказа:
|
from to |
Отбор заказов по времени с from до to . Время указывается в формате UNIX-timestamp. Могут использоваться как оба параметра одновременно, так и один из параметров по отдельности. Полезно для формирования выгрузки заказов в свой интерфейс, но для этой задачи рекомендуется использовать поле ниже. |
after |
Идентификатор последнего полученного заказа, после которого начинать выдачу. Полезно для выгрузки заказов в свой интерфейс - список заказов запрашивается каждый раз с указанием ID последнего полученного заказа, и в результате выводятся только новые заказы, пришедшие после указанного. |
Результатом выполнения функции является массив элементов со следующими полями:
Поле | Описание |
---|---|
id |
Идентификатор заказа в рамках FinAsset |
ext |
Внешний идентификатор заказа (в случае интеграции интерфейсов) |
offer |
Идентификатор оффера (см. список) |
wm |
Идентификатор вебмастера |
stage |
Символьный статус заказа для вебмастера:
|
phase |
Числовой статус заказа для вебмастера:
|
status |
Статус заказа в CRM. Принимает одно из следующих значений:
|
reason |
Код причины отказа. Принимает одно из следующих значений:
|
check |
Флаг постановки заказа на проверку службой безопасности. 1 - заказ подозрительный и находится на проверке. |
site |
Адрес сайта, с которого был выполнен заказ |
ip |
IP-адрес покупателя |
time |
Время получения заказа в формате UNIX-timestamp |
name |
ФИО покупателя |
gender |
Пол покупателя. 1 - мужчина, 2 - женщина. Определяется автоматически. |
phone |
Телефон покупателя в формате 79876543210 |
country |
Двухбуквенный код страны покупателя, вычисляется на основании IP-адреса |
index |
Почтовый индекс адреса доставки в формате 127000 |
addr |
Адрес доставки. Может содержать в себе полный адрес без индекса, если не используются поля ниже. В противном случае содержит только номер дома, корпуса, квартиры или офиса. |
area |
Регион доставки, например, Московская обл. |
city |
Город доставки, например Москва |
street |
Улица по адресу доставки, например ул. Мира |
count |
Количество товара. |
items |
Состав заказа, количество тех или иных вариантов товара. Массив, в котором ключ - идентификатор варианта, значение - количество товара данного вида и цена за единицу товара. |
delivery |
Идентификатор службы доставки |
discount |
Скидка на товар в процентах. |
currency |
ISO-код валюты товара |
base |
Цена за единицу товара в валюте заказа |
delpr |
Цена за доставку в валюте заказа |
more |
Сумма добавочной стоимости заказа, например, наценки за экспресс-доставку. |
price |
Общая стоимость заказа. |
comment |
Дополнительный комментарий по заказу. |
Пример ответа функции:
[ { "id": 13131, "ext": 2424, "offer": 15, "offername": "Shiny test offer", "wm": 59, "stage": "approve", "phase": 3, "status": 8, "reason": 0, "check": 0, "site": 12, "siteurl": "land.cpa/test-offer", "space": 23, "spaceurl": "blog.cpa/test-space", "ip": "12.34.56.78", "time": 1733866064, "name": "John Doe", "gender": 0, "phone": "123456789000", "country": "ru", "index": "100000", "area": "", "city": "Moscow", "street": "Lenina street", "addr": "1", "comment": "Заберет у курьера в течение 2-5 дней", "count": 6, "items": { "12": [ 3, 665 ], "23": [ 1, 665 ], "34": [ 2, 665 ] }, "delivery": 1, "discount": 0, "currency": "rub", "base": "0.00", "more": "0.00", "delpr": "350.00", "price": "4340.00" } ]
Смена статуса заказа
URL: https://my.finasset.ru/api/comp/status.json?id={token}
Функция позволяет обновить статус существующего заказа и изменить некоторые его поля. Все параметры могут передаваться как в POST, так и в GET-части запроса. Функция оптимальна для использования в PostBack-запросах.
На входе функция получает следующие параметры:
Поле | Описание |
---|---|
oid eid |
Идентификатор заказа, над которым ведётся работа. Поле oid используется для указания внутреннего идентификатора заказа в рамках FinAsset, поле eid используется для работы с идентификатором заказа на стороне поставщика. Обязательное поле запроса. Может передаваться в GET. |
status |
Текстовое поле со статусом заказа, привязанное к параметрам st* или распознаваемое автоматически по списку:
|
sta |
Значение статуса, которое будет распознано как аппрув |
stc |
Значение статуса, которое будет распознано как отмена |
stt |
Значение статуса, которое будет распознано как треш |
sth |
Значение статуса, которое будет распознано как холд |
stw |
Значение статуса, которое будет распознано как заказ в обработке |
name |
ФИО покупателя |
phone |
Телефон покупателя в формате 79876543210 (только цифры) |
email |
Адрес электронной почты покупателя |
comment |
Дополнительный комментарий по заказу. |
country |
Двухбуквенный ISO-код страны |
currency |
Трёхбуквенный ISO-код валюты |
base |
Цена за единицу товара или стоимость конверсии в валюте заказа |
count |
Количество товара в заказе |
delpr |
Стоимость доставки товара в валюте заказа |
Обязательным являются только идентификатор заказа и статус, остальные поля используются по мере надобности. Результатом выполнения функции является ассоциативный массив:
Поле | Описание |
---|---|
status |
Результат выполнения операции: ok в случае успешного выполнения, error в случае ошибки |
error |
Идентификатор ошибки: orderid при отсутствии идентификатора заказа, edit в случае отсутствия полей для обновления (например, если информация не изменялась), access-denied при работе с недоступным заказом, request-error в случае внутренней ошибки системы. |
Пример успешного ответа функции:
{ "status" : "ok" }
Пример ответа функции при возникновении ошибки:
{ "status" : "error", "error" : "access-denied" }
Редактирование заказа
URL: https://my.finasset.ru/api/comp/edit.json?id={token}
Функция позволяет отредактировать поля существующего заказа, обновить его статус. Часть параметров может передаваться в GET-части запроса.
На входе функция получает следующие параметры:
Поле | Описание |
---|---|
oid eid |
Идентификатор заказа, над которым ведётся работа. Поле oid используется для указания внутреннего идентификатора заказа в рамках FinAsset, поле eid используется для работы с идентификатором заказа на стороне поставщика. Обязательное поле запроса. Может передаваться в GET. |
accept |
Флаг приёма заказа. Устанавливается в 1 если заказ в данный момент одобряется на стороне поставщика. Может передаваться в GET. |
status |
Идентификатор нового статуса заказа. Может передаваться в GET. Принимает одно из следующих значений:
reason . Важно! Для подтверждения заказа используйте поле accept=1 , а не смену статуса заказа!
|
reason |
Код причины отказа, обязателен для указания при установке статуса status=5 . Может передаваться в GET. Принимает одно из следующих значений:
|
check |
Флаг постановки заказа на проверку службой безопасности. 1 - отправить на проверку, 0 - снять с проверки. Может передаваться в GET. |
track |
Трек-код отправленной посылки. Может передаваться в GET. |
name |
ФИО покупателя |
phone |
Телефон покупателя в формате 79876543210 (только цифры) |
email |
E-mail покупателя |
index |
Почтовый индекс адреса доставки в формате 127000 (только цифры) |
addr |
Адрес доставки. Может содержать в себе полный адрес без индекса, если не используются поля ниже. В противном случае должен содержать только номер дома, корпуса, квартиры или офиса. |
area |
Регион доставки, например, Московская обл. |
city |
Город доставки, например Москва |
street |
Улица по адресу доставки, например ул. Мира |
delivery |
Используемая идентификатор службы доставки |
base |
Стоимость единицы товара в валюте заказа |
delpr |
Стоимость доставки в валюте заказа |
discount |
Скидка на товар в процентах. Целое число от 0 до 99. |
count |
Количество товара, используется для товаров без дополнительных вариантов оформления, размера, цвета и пр. |
items |
Состав заказа, количество тех или иных вариантов товара. Принимает на входе массив, в котором ключ - идентификатор товара, значение - количество товара данного вида и его цена. Идентификаторы вариантов для своего товара уточните у администрации во время настройки интеграции. В случае указания поля items , передавать count не нужно. |
more |
Сумма добавочной стоимости заказа, например, наценки за экспресс-доставку. Прибавляется к основной сумме заказа после учёта всех скидок. |
comment |
Дополнительный комментарий по заказу. |
Обязательным является только поле идентификатора заказа, остальные поля используются по мере надобности. Результатом выполнения функции является ассоциативный массив:
Поле | Описание |
---|---|
status |
Результат выполнения операции: ok в случае успешного выполнения, error в случае ошибки |
error |
Идентификатор ошибки: orderid при отсутствии идентификатора заказа, edit в случае отсутствия полей для обновления (например, если информация не изменялась), access-denied при работе с недоступным заказом, request-error в случае внутренней ошибки системы. |
Пример успешного ответа функции:
{ "status" : "ok" }
Пример ответа функции при возникновении ошибки:
{ "status" : "error", "error" : "access-denied" }
Аналитика заказов
URL: https://my.finasset.ru/api/comp/stats.json?id={token}
Функция предоставляет статистику по заказам, сгруппированную по выбранному параметру. Данная функция даёт подробную статистику по количеству заказов в каждом из статусов.
На входе функция получает следующие параметры:
Поле | Описание |
---|---|
item * |
Обязательный параметр. Поле, по которому производится группировка статистики:
|
from |
Дата начала статистики в формате ГГГГ-ММ-ДД . По умолчанию используется дата неделю назад. |
to |
Дата окончания статистики в формате ГГГГ-ММ-ДД . По умолчанию используется сегодняшний день. |
offer |
Фильтрация по ID оффера. |
site |
Фильтрация по ID лендинга. |
space |
Фильтрация по ID прелендинга. |
stage |
Фильтрация по идентификатору (не названию!) стадии. |
status |
Фильтрация по статусу заказа. |
hour |
Фильтрация по часу поступления лида. |
geo |
Фильтрация по ISO-коду страны. |
Результатом выполнения функции является ассоциативный массив. Идентификатором каждого элемента служит идентификатор выбранного элемента группировки. Каждый элемент включает в себя следующие поля:
Поле | Описание |
---|---|
id |
Идентификатор элемента группировки |
name |
Название элемента группировки, если применимо |
count |
Общее количество заказов |
pay |
Общая сумма отчислений |
app |
Процент аппрува без учёта заказов в треше |
apps |
Процент аппрува с учётом заказов в треше |
cash |
Распределение количества заказов и общей суммы чека по валютам. Массив, в котором ключ - ISO-код валюты, а значение - пара [ количество лидов, сумма ]. |
status |
Распределение заказов по статусам. Массив, в котором ключ - код статуса, а значение содержит следующие поля:
|
Пример ответа функции:
{ "20190801": { "id": 20190801, // ИД элемента "name": "2019-08-01" // Название элемента "count": 24, // Количество "pay": 11150, // Сумма отчисления "app": 100, // Процент аппрува "apps": 100, // Процент аппрува при учёте треша "cash": { // Распределение по валютам "usd": [ // ISO-код валюты 23, // Количество заказов 40477 // Сумма по заказам ], "rub": [ 1, 13990 ] }, "status": { // Распределение по статусам "6": { // ИД статуса "count": 24, // Количество заказов в этом статусе "pay": 11150, // Сумма отчислений "cash": { // Распределение по валютам "usd": [ 23, 40477 ], "rub": [ 1, 13990 ] } } }, }, }
API-интерфейс агентства позволяет сторонним партнёрским сетям и арбитражным командам загружать лиды в систему и проверять статус их обработки с помощью выгрузки.
Добавление лида
URL: https://my.finasset.ru/api/ext/add.json?id={token}
Функция позволяет добавить новый лид от имени агентства. Данные нового лида передаются в POST-запросе.
На входе функция принимает следующие данные о лиде:
Поле | Описание |
---|---|
extu * |
Уникальный идентификатор заказа в рамках агентства (обязательный параметр) Если указать в этом поле значение auto , идентификатор создатся автоматически.
|
exts |
Идентификатор вебмастера или другого источника на стороне агентства |
offer * |
Идентификатор оффера из списка (обязательный параметр) |
ip * |
IP-адрес покупателя (обязательный параметр) |
name |
ФИО или имя покупателя |
last |
Фамилия покупателя |
phone * |
Телефон покупателя в международном формате с кодом страны, например 79876543210 (обязательный параметр) |
phonecc |
Код страны телефона в формате +7 (необязательный параметр). При указании этого параметра, номер телефона в phone всё равно должен передаваться с кодом страны. |
email |
Электронная почта покупателя |
ua |
User-Agent браузера покупателя |
country |
Двухбуквенный ISO-код страны покупателя, если не передан - вычисляется на основании IP-адреса. |
currency |
Трёхбуквенный код валюты покупателя, например RUB или BYR, по умолчанию вычисляется на основании страны покупателя |
comment |
Дополнительный комментарий по заказу. |
utm_source |
Метка utm_source до 255 символов, подходит для статистики |
utm_campaign |
Метка utm_campaign до 255 символов, подходит для статистики |
utm_content |
Метка utm_content до 255 символов, подходит для статистики |
utm_term |
Метка utm_term до 255 символов, подходит для статистики |
utm_medium |
Метка utm_medium до 255 символов, подходит для статистики |
subid |
Метка subid до 255 символов, только для трекеров - не видна в статистике |
uuid |
Метка uuid до 255 символов, только для трекеров - не видна в статистике |
sub1 |
Метка sub1 до 255 символов, только для трекеров - не видна в статистике |
sub2 |
Метка sub2 до 255 символов, только для трекеров - не видна в статистике |
sub3 |
Метка sub3 до 255 символов, только для трекеров - не видна в статистике |
sub4 |
Метка sub4 до 255 символов, только для трекеров - не видна в статистике |
sub5 |
Метка sub5 до 255 символов, только для трекеров - не видна в статистике |
index |
Почтовый индекс адреса доставки в формате 127000 |
addr |
Адрес доставки. Может содержать в себе полный адрес без индекса, если не используются поля ниже. В противном случае содержит только номер дома, корпуса, квартиры или офиса. |
area |
Регион доставки, например, Московская обл. |
city |
Город доставки, например Москва |
street |
Улица по адресу доставки, например ул. Мира |
base |
Цена единицы товара в валюте заказа. |
count |
Количество товара. |
discount |
Скидка на товар в процентах. |
more |
Сумма добавочной стоимости заказа, например, наценки за экспресс-доставку. |
mobile |
Укажите 0 для десктоп-трафика и 1 для мобильного трафика |
Результатом выполнения функции является ассоциативный массив:
Поле | Описание |
---|---|
status |
Результат выполнения операции: ok в случае успешного выполнения, error в случае ошибки |
id |
Идентификатор добавленного заказа (в случае успеха) |
uid |
Внешний идентификатор заказа из поля extu |
pin |
Внутренний пароль лида для уточнения данных, можете игнорировать. |
url |
Ссылка входа в личный кабинет пользователя (autologin). Если отсутствует - автологин не используется для данного оффера. |
message |
Сообщение об ошибке, которое можно показать покупателю. |
error |
Идентификатор ошибки:
|
bad |
Список обязательных полей, которые не были указаны при отправке. |
info |
Уточнение причины блокировки заказа для ban , access и traffic :
|
Пример ответа функции:
{ "status" : "ok", "id" : 1234, "uid" : 123456 }
Проверка статуса лидов
URL: https://my.finasset.ru/api/ext/list.json?id={token}
Функция позволяет получить информацию о статусе обработки отправленных лидов.
На входе функция может использовать следующие параметры для отбора заказов:
Поле | Описание |
---|---|
ids |
Список ваших идентификаторов лидов через запятую. Здесь указывается идентификатор, отправленный в поле id в запросе на добавление или полученный в поле uid при ответе на этот запрос (если ID выдаётся автоматически). Рекомендуется не более 100 штук за раз. |
oid |
Внутренний идентификатор заказа FinAsset или список идентификаторов через запятую. Он отображается в поле id при добавлении лида. Рекомендуется не более 100 штук за раз. |
status |
Статус заказа:
|
from to |
Отбор заказов по дате с from до to . Дата указывается в формате ГГГГ-ММ-ДД. Могут использоваться как оба параметра одновременно, так и один из параметров по отдельности. |
Результатом выполнения функции является массив статусов лидов. Ключевой параметр - идентификатор заказа на стороне агентства. Для каждого лида указываются следующие параметры:
Поле | Описание |
---|---|
id |
Идентификатор заказа на стороне агентства |
src |
Идентификатор вебмастера (источника) на стороне агентства |
uid |
Идентификатор заказа на стороне нашей системы |
stage |
Символьный статус заказа:
|
phase |
Числовой статус заказа:
|
custom |
Оргинальный текстовый статус заказа из CRM-системы рекламодателя (при наличии) |
status |
Расширенный статус заказа, доступен только по запросу. Принимает одно из следующих значений:
|
reason |
Код причины отказа для статуса 5. Принимает одно из следующих значений:
|
cash |
Сумма отчисления по лиду |
comment |
Текстовый комментарий к заказу (при наличии) |
Пример ответа функции:
[
1234 : {
"id": 1234, // ID заказа на стороне агентства
"uid": 432, // ID заказа на стороне нашей системы
"phase": 5, // Код статуса заказа
"stage": "trash", // Статус заказа
"reason": 2, // Код причины отказа
"comment: "Мур-мур-мур-мур", // Комментарий по заказу
},
2345 : {
"id": 2345, // ID заказа на стороне агентства
"uid": 543, // ID заказа на стороне нашей системы
"phase": 3, // Код статуса заказа
"stage": "approved", // Статус заказа
"count: 2, // Количество товара в заказе
}
]