Приём расхода по ключу

Расход Facebook Qubix выгружает сам. Расход любой другой площадки, у которой нет своей выгрузки в Qubix, можно присылать самим: внешней программой по ключу, через помощника или из скрипта Qubix. Эта статья — прежде всего о ключе: на странице MCP/API выпускается ключ, и ваша программа отправляет по нему почасовые суммы — по объявлениям или по сайту целиком. Помощник и скрипт пишут расход тем же приёмом — см. Передача расхода через помощника и Подача расхода из скрипта. Принятый расход виден в тех же отчётах, что и расход Facebook.

Что понадобится

Право Управление источниками трафика в шаблоне прав — чтобы выпустить ключ себе. Если этого права нет, ключ вам выпускает администратор.
Источник трафика для площадки — не на шаблоне площадки, чей расход Qubix выгружает сам (например, facebook). Подробнее — Создание источника.
Для расхода по объявлениям — идентификаторы объявлений площадки, а для объявлений, которых в Qubix ещё нет, — и идентификаторы их кампаний. Для расхода по сайту — сайт в разделе Сайты.

Как выпустить ключ

Откройте Мои настройки → Интеграции → MCP/API. Подробнее о странице — MCP/API.
Найдите блок Приём расхода по ключу. В строке Эндпоинт стоит адрес приёма с доменом вашей панели — его и вызывает программа.
Если вы администратор, выберите в раскрывающемся списке над кнопкой, на кого выпустить ключ: Себе (так список стоит по умолчанию) или другой человек. У остальных списка нет — ключ выпускается на себя.
Нажмите Выпустить ключ.
Скопируйте ключ кнопкой Скопировать и сохраните его: ключ нигде не хранится и больше не показывается.

Блок виден администраторам и тем, у кого в шаблоне прав есть Управление источниками трафика. Ниже кнопки — Тело запроса: образец запроса, в который после выпуска подставлен ваш ключ. Кнопка Выпустить ещё ключ выпускает ещё один ключ, а прежние при этом продолжают действовать.

Когда ключ перестаёт действовать:

на время — пока учётная запись его владельца отключена (выключен переключатель активен в карточке пользователя). Если учётную запись включить обратно, прежние ключи опять работают;
насовсем — после Сбросить все сессии в карточке этого пользователя (отзываются все ключи, выпущенные до сброса) и после Уволить. После сброса сессий выпустите новый ключ.

Подробнее о карточке пользователя — Пользователи.

Ключ пишет от имени владельца

Ключ записывает расход от имени человека, на которого выпущен, и с его правами записи: кто держит ключ, тот пишет в те источники, объявления и сайты, куда вправе писать этот человек. Храните ключ как пароль.

На недействующий ключ приём отвечает так же, как на принятую пачку, — числом строк в теле запроса, даже если пачка составлена с ошибками, — и ничего не записывает. Отказ с таким ключом приходит, только если тело не разобралось как JSON, в пачке больше 20 000 строк, тело больше предела размера или подписка неактивна: всё это проверяется раньше ключа. Поэтому результат проверяйте по отчётам — см. Что вы увидите после приёма.

Как прислать расход

Программа отправляет запрос POST на адрес из блока — вида https://<your-domain>/cost-intake — с телом в формате JSON. Тело запроса — это пачка: ключ, источник, валюта, часовой пояс и строки расхода. Входить в панель не нужно: отправителя опознаёт ключ в теле запроса.

Bash
curl -X POST 'https://your-domain.com/cost-intake' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "YOUR_INTAKE_KEY",
    "source": "a1b2c3d4-0000-4000-8000-000000000001",
    "currency": "EUR",
    "tz": "Europe/Berlin",
    "rows": [
      {"date": "2026-09-28", "hour": 10, "ad_id": "84512", "campaign_id": "3071",
       "campaign_name": "push RU 28.09 anna", "ad_name": "banner 1",
       "spend": 12.5, "impressions": 1000, "clicks": 40},
      {"date": "2026-09-28", "hour": 10, "website_id": "a1b2c3d4-0000-4000-8000-000000000002",
       "spend": 3}
    ]
  }'

В примере первая строка — расход объявления 84512, которого в Qubix ещё нет: оно заведётся этой же пачкой в кампании ext-3071, если у кампании будет владелец, в чьи объявления вы вправе писать, — например, в её названии стоит ваше правило привязки (в примере — anna). Как Qubix выбирает владельца такой кампании — в разделе Расход по объявлениям. Вторая строка — расход сайта целиком. Обе суммы — в евро за 10:00–11:00 по берлинскому времени.

Поля пачки

Поле	Обязательно	Что передать
`key`	да	Ключ приёма.
`source`	да	Идентификатор источника трафика, в который пишется расход.
`currency`	нет	Трёхбуквенный код валюты всех сумм пачки: `USD`, `EUR`, `RUB`… Не указан — доллары.
`tz`	нет	Часовой пояс, в котором записаны даты и часы строк, например `Europe/Moscow`. Не указан — UTC.
`rows`	да	Строки расхода — не больше 20 000 в одной пачке.

Идентификатор источника — длинная строка вида a1b2c3d4-…. Он стоит в адресе открытой карточки источника (раздел Источники), а по MCP его отдаёт метод get_traffic_sources_list. Если раздел источников вам не открыт, идентификатор вместе с ключом передаёт администратор. Идентификатор сайта так же стоит в адресе открытой карточки сайта.

Поля строки

Поле	Обязательно	Что передать
`date`	да	День в виде `ГГГГ-ММ-ДД` — в поясе пачки.
`hour`	да	Час, от 0 до 23, — в поясе пачки.
`ad_id`	одно из двух	Идентификатор объявления площадки.
`website_id`	одно из двух	Идентификатор сайта — если расход относится к сайту целиком, а не к его объявлениям.
`spend`	да	Сумма в валюте пачки. Отрицательной быть не может.
`impressions`	нет	Показы. Не указаны — 0. Попадают в колонку «Показы» отчётов.
`clicks`	нет	Клики площадки. Не указаны — 0. Хранятся вместе с расходом, но в колонку «Клики» отчётов не попадают: там клики, которые посчитал сам Qubix.
`campaign_id`	для нового объявления	Идентификатор кампании площадки. У объявления, которое Qubix уже знает, оставьте поле пустым или назовите его же кампанию.
`campaign_name`	нет	Название новой кампании.
`ad_name`	нет	Название нового объявления.

Каждая строка называет ровно одно из двух — ad_id или website_id. У строки сайта полей кампании и названия объявления быть не должно.

Час и клетка

Одна строка — одна клетка: час плюс объявление (или сайт). Две строки об одной клетке в одной пачке не принимаются.

Повтор заменяет, а не прибавляет. Та же клетка, присланная ещё раз тем же источником и в том же поясе, заменяет прежние числа. Поэтому пачку, на которую не пришёл ответ, можно отправить ещё раз — расход не задвоится.
Держите один пояс. Те же строки в другом поясе лягут в другие часы и посчитаются дважды.
Сумма только за сутки — одной строкой в 12 часов этих суток; за сегодняшние сутки — в час, который уже начался.
Сутки перевода часов присылайте в UTC: иначе два местных часа могут сойтись в одну клетку, и пачку отклонят.

Строки позже следующего часа и с датами раньше 1970 года не принимаются.

Валюта и курс

Суммы пересчитываются в доллары по курсу на дату, названную в строке. Курс закрепляется за клеткой при первом приёме: повторная отправка той же клетки в той же валюте берёт тот же курс, и сумма в долларах не сдвигается. Курс другого дня не подставляется:

курс на эту дату ещё не вышел (так бывает с сегодняшней датой) или источники курса не ответили — пачка отклоняется с просьбой прислать её позже;
курса на эту дату нет ни у одного источника — пришлите эти строки в долларах;
одна пачка может запросить курс не больше чем за 92 разных дня — большую пачку разбейте на несколько.

Для долларов пересчёта нет.

Расход по объявлениям

Объявление уже есть в Qubix — например, выгружено из Facebook или заведено прошлой пачкой. Присланный расход ложится рядом с тем, что уже есть: у объявления будет сумма обоих источников. Если строка называет campaign_id, это должна быть кампания самого объявления; у объявления, заведённого приёмом, её номер можно писать и с приставкой ext-, и без неё.

Объявления в Qubix ещё нет — его заводит первая же пачка, в которой оно встретилось:

во всех строках такого объявления одинаковы campaign_id (номер можно писать с приставкой ext- или без неё), campaign_name и ad_name: название, пропущенное в одной строке, пропускайте и в остальных;
кампания хранится под своим номером с приставкой ext-: так она не займёт номер кампании самой площадки. Номер, уже начинающийся с ext-, приставку второй раз не получает;
новое объявление в уже заведённой кампании получает название кампании из Qubix, присланное название не пишется;
идентификаторы новых объявлений и кампаний — только из латинских букв, цифр, _ и -; номер новой кампании без приставки ext- — не длиннее 124 знаков.

Владельца новой кампании Qubix определяет так же, как у кампаний Facebook: владелец, назначенный администратором номеру с приставкой ext-, а если назначения нет — человек, чьё правило привязки встречается в названии кампании (вкладка Правила в карточке пользователя). Если в названии встречаются правила нескольких людей, владельца у кампании нет. Кампания заводится, только если её владелец — человек, в чьи объявления вы вправе писать. Кампанию без владельца заводит только ключ администратора.

Приём откажет, если номер кампании (без приставки) уже принадлежит кампании другой площадки в Qubix, а также если кампания с этим номером уже заведена под другим источником.

Статуса у таких объявлений нет: включают и останавливают их только в кабинете самой площадки.

Расход на сайт целиком

Строка с website_id вместо ad_id — это расход на сайт целиком, который не делится по объявлениям. Сайт должен быть в разделе Сайты, а его владелец — человеком, в чьи объявления вы вправе писать.

У такого расхода нет объявления, а значит, нет и кампании. Поэтому он стоит отдельной строкой Расход сайтов — в списках кампаний, офферов и партнёрок, а также во вкладках Кампании и Партнёрки карточки источника. В строки Без кампании, Без оффера и Без партнёрки он не попадает, а в итог дашборда входит.

Этот расход видят владелец сайта и те, кому видны его данные. Видимость сайта в разделе Сайты на это не влияет.

Куда можно писать

Приём проверяет права человека, на которого выпущен ключ:

источник — тот, который этот человек вправе править, и не источник Facebook или другой площадки со своей выгрузкой: её расход Qubix получает сам, и присланный лёг бы рядом, удвоив его. Источник без владельца принимает расход только по ключу администратора;
объявление — если владелец его кампании из тех людей, в чьи объявления человек вправе писать;
сайт — если владелец сайта из тех же людей.

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

Что вы увидите после приёма

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

На вкладке Объявления раздела Facebook новые объявления площадки отмечены Внешний в колонке Источник; по той же колонке их можно отобрать. В колонке статуса у них прочерк, кнопки паузы нет.
В карточке такого объявления вместо статуса — прочерк с подсказкой Статус меняется в кабинете самой площадки: от неё Qubix получает только расход. Кнопок ⏸ Пауза, ▶ Запустить и ↻ Получить из FB нет. Так же выглядит карточка его рекламной кампании с номером ext-….
Если попросить помощника остановить или запустить такое объявление или кампанию, он получит отказ: объявление пришло с площадки, не подключённой к Qubix, и управлять им можно только в её кабинете.
Расход входит в итог дашборда и в показатели источника, названного в пачке, — в списке источников и в его карточке.
Расход на сайт целиком — строкой Расход сайтов (см. выше).

Расход объявления видят те же люди, что и у объявлений Facebook, — по владельцу его кампании.

Ответ и отказы

На принятую пачку приём отвечает числом записанных строк:

JSON
{"success": true, "data": {"written": 2}}

Отказ приходит с кодом ответа и текстом в поле error:

отказы самого приёма — коды 400, 403, 422, 503 и 413 по числу строк или дней курса — несут причину на английском; строки в ней нумеруются с нуля;
отказ 402 и отказ 413 по размеру тела — готовая фраза на языке из заголовка Accept-Language запроса (русский или английский; без заголовка — английский);
сбой 500 — готовая фраза на английском: «The spend was not stored: the server could not complete the request. The details are in the server log.»

JSON
{"success": false, "error": "cost intake: invalid batch: row 1 must name exactly one of ad_id and website_id"}

Код	Когда	Что делать
400	Пачка составлена неверно: тело не разобралось как JSON или поле пришло не того типа; у строки нет даты, часа или суммы; строка называет оба поля `ad_id` и `website_id` или ни одного; у строки сайта названы кампания или объявление; две строки об одной клетке; сумма отрицательная или больше предела, показов больше предела; сумма после пересчёта в доллары вышла за предел; код валюты не из трёх латинских букв; неизвестный часовой пояс; строка позже следующего часа или раньше 1970 года; идентификатор длиннее 128 знаков, с пробелами по краям, с управляющими знаками или с запятой; название кампании или объявления длиннее 512 байт (кириллическое — уже с 257 букв) или с управляющими знаками; новое объявление описано в разных строках по-разному; одна новая кампания названа по-разному в строках разных объявлений; у известного объявления названа чужая кампания; в идентификаторе нового объявления или кампании недопустимые знаки, либо номер новой кампании без приставки `ext-` длиннее 124 знаков.	Исправьте пачку по тексту отказа.
402	Подписка неактивна: пока она не продлена, Qubix не принимает никаких изменений, в том числе расход.	Продлите подписку в личном кабинете.
403	Запись вне ваших прав: источник вам не доступен для правки, не существует или это источник площадки со своей выгрузкой; объявление чужое или новое объявление названо в кампании, писать в которую вам нельзя; объявления нет в Qubix, а `campaign_id` не назван; сайт чужой или не существует; номер кампании принадлежит другой площадке или кампания заведена под другим источником; у новой кампании нет владельца, в чьи объявления вы вправе писать; Qubix назвал владельцем новой кампании не того человека, по которому проверялась запись.	Проверьте источник, идентификаторы и права владельца ключа.
413	Отказ приёма: в пачке больше 20 000 строк или курс нужен больше чем за 92 разных дня. Отказ по размеру: тело запроса больше предела Общий предел тела запроса, МБ из настроек системы.	Разбейте пачку на несколько.
422	Курса на дату строки нет ни у одного источника курсов.	Пришлите эти строки в долларах.
503	Курс на дату ещё не вышел, источники курса не ответили или отвечали дольше минуты. В ответе есть заголовок `Retry-After`.	Пришлите пачку позже: курсы, которые уже успели прийти, сохраняются.
500	Сбой на сервере.	Повторите пачку позже; причина — в журнале сервера.

При любом отказе расход не записывается. Новые объявления, которые пачка успела завести, при этом остаются, если отказ пришёл уже после их заведения: при отказе 403 из-за того, что Qubix назвал владельцем новой кампании не того человека, по которому проверялась запись (текст отказа говорит об этом прямо), и при сбое 500, случившемся после заведения объявлений.

Передача расхода через помощника

Тот же приём есть у встроенного помощника и у внешнего ИИ-клиента по MCP — средство Передать расход (cost_intake_submit). Оно открыто тем же людям, что и выпуск ключа себе: нужно право Управление источниками трафика. У кого этого права нет, тому средство не предлагается — ни встроенному помощнику, ни в поиске внешнего клиента, — и вызвать его нельзя; такой человек пишет расход только ключом, который выпустил администратор. В каталоге методов на странице MCP/API средство показано всем, как и остальные методы: каталог — справка, права проверяются при вызове.

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

источник называется полем traffic_source_id;
валюту называть обязательно — без неё запись не пройдёт;
часовой пояс можно не указывать — тогда берётся пояс вашего профиля (а если он не задан — UTC).

Средство записывает данные, поэтому встроенный помощник сперва показывает карточку подтверждения и пишет расход только после нажатия Подтвердить, а внешнему клиенту нужен явный признак подтверждения confirm=true. Отказы приходят тем же английским текстом, что и у запроса по ключу, а сбой сервера — фразой «Расход не записан: сервер не смог выполнить запрос…» на языке вашего профиля, если это русский или английский. Подробнее о подключении — Подключение внешнего AI (MCP).

Подача расхода из скрипта

Расход можно подавать и из скрипта Qubix: в скрипте, который работает по расписанию или запускается вручную, вызов QubixApp.submitSpend пишет расход тем же приёмом. Строки у него того же вида, что у запроса по ключу, а источник называется полем traffic_source_id, как у помощника. Как устроен вызов — в статье Написание скрипта.

Чем этот путь отличается:

Права — владельца скрипта. Расход пишется от имени владельца скрипта, кто бы ни запустил его: у владельца должно быть право Управление источниками трафика, а источник, объявления и сайты проверяются по его правам — так же, как у ключа. Если владельца больше нет среди пользователей или его учётная запись отключена, вызов отказывает.
Только код, сохранённый владельцем. Вызов работает, только если код скрипта последним изменил и сохранил его владелец или администратор — в панели или средством script_save через MCP. Код, который сохранил кто-то другой (например, тимлид в чужом скрипте), расход не подаёт, пока владелец или администратор не изменит его и не сохранит. По кнопке «Запустить» расход подаёт только код, совпадающий с последней подтверждённой версией, поэтому несохранённая правка расход не подаёт. Правка кода из Qubix Drive код не подтверждает.
Валюту и часовой пояс называют всегда. У запроса по ключу для обоих полей есть умолчания, у помощника — для часового пояса, а здесь умолчаний нет.
Число вызовов за запуск ограничено. Предел задаёт администратор: Настройки Qubix → JavaScript, группа Подача расхода (QubixApp.submitSpend), поле Вызовов submitSpend на запуск. Один вызов несёт один источник трафика.
Отказ приходит исключением в самом скрипте. Отказы приёма и отказы из-за владельца, его прав, сохранённого кода, предела вызовов и слишком длинного значения пишутся на языке владельца скрипта: по-русски, если в его профиле выбран русский, иначе по-английски. По-английски всегда приходят сообщение о неверном виде значения (TypeError) — например, rows не массив или поле не того типа — и отказ, когда владельца скрипта нет среди пользователей. У запроса по ключу и у средства помощника отказы самого приёма, напротив, приходят по-английски.
Системные скрипты расход не подают.

В отчётах способ подачи — ключ, помощник или скрипт — не показывается: такой расход виден по источнику, как и присланный любым другим путём.

Что понадобится​

Как выпустить ключ​

Как прислать расход​

Поля пачки​

Поля строки​

Час и клетка​

Валюта и курс​

Расход по объявлениям​

Расход на сайт целиком​

Куда можно писать​

Что вы увидите после приёма​

Ответ и отказы​

Передача расхода через помощника​

Подача расхода из скрипта​

Что дальше​

MCP/API

Источники

Объявления

Кампании