Подключите свои системы к Marcomm AI

1. 1
   Подайте заявку на доступ

   Опишите свою систему и выберите нужные данные. Мы рассматриваем каждую заявку.

2. 2
   Создайте ключ

   После одобрения создайте ключ в разделе «Настройки, API». Ключ показывается один раз, поэтому сохраните его в своей системе.

3. 3
   Отправьте запрос

   Передайте ключ в заголовке Authorization и вызовите любой из перечисленных ниже эндпоинтов.

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

curl https://app.marcomm.works/api/v1/news/digest?days=7 \
  -H "Authorization: Bearer mc_live_..."

Передавайте ключ как токен Bearer в каждом запросе. Персональный ключ действует от имени создавшего его человека, поэтому может читать согласования и одобрять или отклонять их от его имени. Ключ рабочего пространства создаёт администратор, и он работает только на чтение. Ключи могут иметь срок действия, быть ограничены IP-адресами и заменяться: после ротации прежний ключ продолжает работать ещё 24 часа.

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

news

Дайджест новостей, статьи и СМИ.

crisis

Критические новости и кризисные инциденты.

approvals

Ожидающие согласования, а также их одобрение или отклонение персональным ключом.

content

Чтение пресс-релизов и записей блога.

Пути начинаются с /api/v1. Эндпоинты чтения используют GET и принимают параметры запроса. Ответ приходит в формате JSON вида {"data": ...}.

Отправьте {"decision": "approve"} или {"decision": "reject", "comment": "..."} на адрес материала. Для отклонения нужен комментарий. Вердикт подчиняется тем же правилам, что и в приложении и Slack, и записывается на владельца ключа. Если в тексте есть формулировки, требующие подтверждения, вы получите ответ 409 confirmation_required с предупреждениями и сможете повторить запрос с "force": true.

curl -X POST https://app.marcomm.works/api/v1/approvals/press-releases/<id> \
  -H "Authorization: Bearer mc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"decision":"reject","comment":"Please fix the headline."}'

Лимиты задаются для рабочего пространства на минуту и на сутки (UTC). Каждый ответ содержит приведённые ниже заголовки. При превышении лимита вы получите ответ 429 с заголовком Retry-After. Чтобы увеличить лимит, отправьте запрос в разделе «Настройки, API». Его рассмотрит наша команда.

X-RateLimit-Limit

Допустимое число запросов в минуту.

X-RateLimit-Remaining

Оставшееся число запросов в текущей минуте.

X-RateLimit-Reset

Время Unix, когда окно минуты сбрасывается.

X-RateLimit-Day-Limit

Допустимое число запросов в сутки.

X-RateLimit-Day-Remaining

Оставшееся число запросов на сегодня.

Retry-After

Сколько секунд подождать перед повторной попыткой. Только при 429.

Ошибки возвращаются в формате JSON вида {"error": {"code": ..., "message": ...}}.

Оповещения, запросы на согласование и утренний брифинг можно также отправлять в вашу систему. Добавьте получателя в разделе «Настройки, API, Вебхуки». Каждый запрос представляет собой JSON с полями event (alert, approval или briefing), workspace, title, text, url, data и sentAt. Запрос на согласование содержит data.kind (press_release, blog или event) и data.id, по которым можно прочитать материал и вынести вердикт через API.

Каждый запрос подписан. Вычислите HMAC-SHA256 от необработанного тела запроса с вашим секретом подписи и сравните результат с заголовком X-Marcomm-Signature вида sha256=<hex>. Отклоняйте запросы, которые не совпадают.

Проверка вебхука в Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

export function isFromMarcomm(rawBody: string, signature: string, secret: string) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && timingSafeEqual(a, b);
}