Scoutello API
API Scoutello — это API для взаимодействия между серверами, предназначенное для двусторонней синхронизации контактов, задач, протоколов, возможностей, проектов, этапов и событий организации. API также предоставляет доступ только для чтения к истории исходящей почты, поиску участников, которым можно назначать задачи, и обнаружению тегов с учетом типа сущности. Инкрементальные маршруты GET/list и идемпотентные пакетные операции upsert — основные примитивы синхронизации в этой версии. Операции удаления и вебхуки не поддерживаются.
Базовый URL API:
https://admin.scoutello.com/api/v1
Он также указан в разделе Настройки организации → Разработчик/API. Документ OpenAPI доступен по адресу:
https://admin.scoutello.com/api/v1/openapi.json
Создание и защита ключа
Для модульных организаций в дополнение к обязательным областям доступа ключа должен быть активен модуль CRM. Действительный ключ не может активировать отсутствующий модуль. Если доступ к CRM недоступен, запросы возвращают HTTP 403 с кодом ошибки module_not_active. Лицо с правами администрирования организации может проверить статус или активировать CRM в разделе Подписка; после активации доступа повторите запрос.
Лицо с правами администрирования организации может создать интеграцию и API-ключ в разделе Настройки организации → Разработчик/API. Полный ключ отображается только один раз. Скопируйте его в менеджер секретов до закрытия диалогового окна; Scoutello не сможет снова показать полный ключ.
- Использовать отдельную интеграцию и ключ для каждой внешней системы и среды.
- Предоставлять только те области доступа, которые необходимы системе.
- Никогда не размещать ключ в коде браузера, URL, системе контроля версий, журналах, сообщениях в службу поддержки или клиентском хранилище.
- Регулярно ротировать ключи. При ротации активной интеграции новый ключ начинает работать сразу, а предыдущий остается действительным не более 15 минут, чтобы внешняя система могла переключиться без простоя. При этом сохраняется ранее установленный срок действия, поэтому предыдущий ключ может перестать работать раньше.
- Если ключ мог быть раскрыт, приостановить интеграцию перед ротацией. Приостановка временно отклоняет все ключи интеграции. Ротация во время приостановки не создает периода перекрытия: предыдущий ключ остается отключенным, а новый ключ остается отключенным до возобновления работы интеграции.
- Окончательно отозвать всю интеграцию при отключении внешней системы. Отзыв отключает все ее ключи и не может быть отменен.
Передавать ключ в каждом аутентифицированном запросе:
Authorization: Bearer YOUR_API_KEY
Предпочтительно использовать Bearer-аутентификацию. Клиенты, которые не могут установить Authorization, могут использовать вместо него x-api-key. Не отправляйте оба заголовка: запросы с разными значениями в обоих заголовках отклоняются.
API предназначен для серверных клиентов и не разрешает междоменный доступ из браузера.
После настройки ключа используйте GET /whoami, чтобы проверить интеграцию, организацию, области доступа и ограничения ключа без получения персональных данных пользователей.
Области доступа
| Область действия | Разрешает |
|---|---|
contacts.read | Просматривать список контактов и получать сведения о них. Контакты организаций и участники с правами доступа не включаются. |
contacts.write | Проверять и применять операции создания или обновления контактов. |
tasks.read | Просматривать список несекретных задач и получать сведения о них. |
tasks.write | Проверять и применять операции создания или обновления задач. |
protocols.read | Просматривать список несекретных протоколов и получать сведения о них. |
protocols.write | Проверять и применять операции создания или обновления протоколов. |
opportunities.read | Просматривать список возможностей и получать сведения о них. |
opportunities.write | Проверять и применять операции создания или обновления возможностей. |
projects.read | Просматривать список проектов и получать сведения о них. |
projects.write | Проверять и применять операции создания или обновления проектов и участников. |
milestones.read | Просматривать список контрольных точек проектов и получать сведения о них. |
milestones.write | Проверять и применять операции создания или обновления контрольных точек. |
members.read | Просматривать список принятых участников, включая только идентификатор клиента участника, идентификатор пользователя и отображаемое имя. |
events.read | Просматривать список событий и основных расписаний и получать сведения о них. |
events.write | Проверять и применять операции создания или обновления событий. |
mails.read | Читать историю отправленных и не доставленных исходящих писем, принадлежащих организации. |
mail-drafts.read | Читать отдельные черновики писем для согласования и статус доставки этой интеграции. |
mail-drafts.write | Создавать или изменять черновики писем для согласования человеком; утверждение и отправка не выполняются. |
tags.read | Находить доступные для выбора теги поддерживаемых типов сущностей. |
Эта API никогда не возвращает закрытые задачи и протоколы. При отсутствии области действия возвращается ошибка авторизации, а не пустой результат.
Контакт CRM, не являющийся участником, можно читать и указывать в ссылках, даже если он связан с учётной записью Scoutello. Ответ содержит только поля CRM организации — идентификационные данные пользователя и поля доступа никогда не передаются. Контакты с ролью, разрешениями, приглашением, подтверждённым приглашением или статусом учётной записи организации остаются скрытыми. Редактирование контакта, связанного с учётной записью, запрещено (protected_contact), включая поля CRM, значения которых не меняются. Чтобы указать существующий доступный для чтения контакт в задаче или протоколе, contacts.write может установить внешнюю ссылку только с помощью externalId, scoutelloId и необязательного externalUpdatedAt. Последующие обновления только метаданных ссылки выполняются с помощью externalId и необязательного externalUpdatedAt; после создания ссылки начальный scoutelloId следует опускать. Это никогда не изменяет контакт или его пользователя. Для назначения принятого участника используется отдельное представление members.read.
Новые ключи используют префикс sctl_api_ и начинаются только с contacts.write. Для всех остальных областей доступа требуется явное предоставление прав администратором организации при создании или ротации ключа. Существующие учётные данные сохраняют текущие области доступа и остаются действительными.
Контакты, связанные с проектами, и черновики писем
Операции добавления и обновления контактов принимают необязательные пары projectScoutelloId / projectExternalId и companyScoutelloId / companyExternalId (выбирать по одному элементу из каждой пары). Контакт, связь с компанией и участие в проекте сохраняются для каждого элемента атомарно. Для добавления участия в проекте требуется projects.write; при отсутствии ссылок остальные связи и участия сохраняются. При чтении сведений о контакте возвращается projectParticipations, если предоставлен projects.read. Агенты проектов продаж должны явно указывать ссылку на проект, даже при повторном использовании контакта.
Для отдельных черновиков используется существующая система подтверждения человеком без запуска рабочего процесса:
| Метод | Путь | Назначение |
|---|---|---|
| GET | /mail-drafts | Черновики с постраничной выдачей, принадлежащие интеграции; необязательные фильтры projectScoutelloId и status. |
| GET | /mail-drafts/{scoutelloId} | Текущая версия, ссылка на проверку, хеш содержимого, статус подтверждения/отправки и конечный идентификатор письма. |
| GET | /mail-drafts/external/{externalId} | Поиск по стабильному внешнему идентификатору интеграции. |
| POST | /mail-drafts/batch-upsert | Проверка или применение подготовки черновика. |
Для подготовки черновика требуются mail-drafts.write, contacts.read и projects.write. Указанный контакт становится участником проекта. Подтверждающим лицом должен быть принятый участник организации с правом редактирования электронной почты. Выбор отправителя выполняется на основе существующих разрешённых настроек отправителя организации или личного отправителя этого участника; произвольные адреса в поле From не принимаются.
{
"mode": "validate",
"records": [{
"externalId": "sales:indoor:outreach:museum:v1",
"expectedVersion": 0,
"project": { "externalId": "sales:indoor" },
"contact": { "externalId": "sales:indoor:museum:person" },
"approverScoutelloUserId": "ACCEPTED_MEMBER_USER_ID",
"senderScope": "organization",
"content": {
"to": ["verified-recipient@example.com"],
"subject": "Indoor tour proposal",
"body": "The intended email copy only.",
"notes": "Internal research and review context; not sent."
}
}]
}
Проверять каждый результат валидации перед повторной отправкой с помощью mode: "apply". Читать возвращённый идентификатор, чтобы получить reviewUrl, draftVersion, contentHash, status, dispatchStatus и mailScoutelloId. Использовать expectedVersion: 0 только при создании, а для изменений — текущую возвращённую версию. Контекст и подтверждающее лицо неизменяемы; проверенные или отправленные черновики отклоняют изменённое содержимое. Идентичные повторные запросы возвращают исходный черновик.
Черновики отображаются во вкладках Email проекта/контакта и в уведомлениях панели управления об утверждении. Подготовка через API не отправляет электронные письма, включая уведомления; существующее поведение уведомлений по электронной почте в рабочих процессах не меняется. Назначенный сотрудник может изменить получателей, тему, текст и поддерживаемые вложения, сохранить версию, а затем выбрать Approve & send. Интеграции не могут выполнять утверждение или отправку. Ошибочная или неоднозначная доставка никогда не повторяется автоматически без проверки. При преобразовании черновиков на основе протоколов сохраняйте протоколы и добавляйте перекрёстные ссылки на их замены.
Доступ к MCP
Тот же ключ API Scoutello и те же области доступа можно использовать с потоковой HTTP-конечной точкой MCP:
https://admin.scoutello.com/api/v1/mcp
Настройте клиент MCP для отправки Authorization: Bearer YOUR_API_KEY. Устаревший URL /api/mcp остаётся псевдонимом пути для совместимости, но в новых клиентах следует использовать версионированную конечную точку. Учётные данные sctl_mcp_ больше не принимаются; замените их интеграционным ключом API Scoutello.
Инструменты MCP напрямую соответствуют REST-контракту и используют те же схемы времени выполнения, проверки арендатора, жизненный цикл интеграции, ограничения частоты запросов и сервисные методы. Например, contacts_list, contacts_get, contacts_get_by_external_id и contacts_batch_upsert соответствуют четырём маршрутам контактов. Та же схема применяется к задачам, протоколам, возможностям, проектам, вехам и событиям; для почты доступны mails_list и mails_get, для участников — members_list, а для тегов — tags_list.
Сервер публикует только инструменты, разрешённые областями доступа текущего ключа. Ключ с областью contacts.read может обнаруживать инструменты чтения контактов, но не contacts_batch_upsert; ключ с областью contacts.write получает инструмент пакетного обновления или создания, но не инструменты чтения. whoami доступен всегда. Инструменты записи имеют те же немедленные эффекты, что и их REST-эквиваленты, поэтому используйте mode: "validate", когда вызывающей стороне нужно проверить пакет, не применяя его.
MCP также работает по схеме «сервер — сервер» и не предоставляет браузеру доступ между источниками. Для транспорта JSON-RPC требуется отдельный URL, поэтому MCP не может использовать URL отдельного REST-ресурса, хотя аутентификация и поведение данных совпадают.
Полные инструкции по настройке и проверке клиента, сопоставлению инструментов и устранению неполадок см. в руководстве по интеграции MCP.
Чтение записей
Для контактов, задач, протоколов, возможностей, проектов, вех и событий используются одни и те же маршруты чтения:
GET /contacts?limit=50&updatedSince=2026-09-01T00:00:00.000Z
GET /contacts/{scoutelloId}
GET /contacts/external/{externalId}
Замените contacts на tasks, protocols, opportunities, projects, milestones или events для других ресурсов синхронизации. externalId появляется в DTO чтения, если запись была связана этой интеграцией.
Eine Listenantwort hat diesen Umschlag:
{
"data": [],
"page": {
"nextCursor": null,
"hasMore": false,
"snapshotAt": "2026-09-01T12:00:00.000Z"
},
"requestId": "request-id"
}
limit должен быть от 1 до 100. Результаты упорядочиваются по фактическому времени изменения их публичного представления в API, затем по ID Scoutello. Это время может быть позже поля updatedAt возвращённой сущности, если изменились метаданные связи интеграции. Курсоры непрозрачны: сохраняйте и передавайте их без изменений и не извлекайте смысл из их содержимого.
Первый ответ фиксирует snapshotAt для текущего прохода. Следуйте по nextCursor, пока hasMore не станет false, прежде чем начинать следующее инкрементальное чтение. Это сохраняет стабильность прохода, даже если записи меняются во время постраничного просмотра.
Для инкрементальной синхронизации обработайте каждую страницу курсора, затем сохраните snapshotAt этого прохода как отметку последнего обработанного времени. В следующем проходе передайте её в updatedSince в формате ISO-8601. Нижняя граница включается: повтор завершённого снимка может вернуть граничные записи снова, но не пропустить их.
Eine Einzelantwort hat diesen Umschlag:
{
"data": {},
"requestId": "request-id"
}
Ответ для отдельного контакта также содержит массив relations. Каждая связь включает ID связи Scoutello, время создания, тип, заметки и ссылки на контакты connectedFrom и connectedTo. Ссылки содержат ID Scoutello и внешний ID этой интеграции, если он есть. Контакты, исключённые из API границей конфиденциальности организационного доступа, не раскрываются через связи.
Ответ списка контактов остаётся компактным и не включает связи. Для получения подробностей связей используйте один из маршрутов отдельного контакта.
Фильтры работы и область действия курсора
Списки контактов принимают search, type (person, company, supplier, other), status и tagIds. Поиск удаляет пробелы по краям, не учитывает регистр и ограничен 200 символами или 10 токенами, разделёнными пробелами. Каждый токен должен встречаться хотя бы в одном из полей firstName, lastName или companyName, включая прежние названия компаний в lastName. Символы вроде % и _ сопоставляются буквально. Для тегов действует совпадение с любым из выбранных по 1–50 ID. Все заданные фильтры объединяются через AND. REST передаёт ID тегов повторяющимися параметрами, MCP — массивом:
GET /contacts?search=Hamburg%20Hotel&type=company&status=prospect&tagIds=tag-one&tagIds=tag-two
Курсоры контактов привязаны к организации, интеграции и каждому фильтру. Сохраняйте фильтры на каждой странице; изменение фильтра отклоняет курсор. Порядок и дубликаты тегов, а также порядок, регистр и пробелы токенов поиска не изменяют эффективный фильтр.
Маршруты списков работ принимают следующие дополнительные фильтры; другие сочетания ресурсов и полей отклоняются:
| Ресурс | Фильтры |
|---|---|
| Задачи | projectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter |
| Протоколы | projectScoutelloId, milestoneScoutelloId, status (draft или final) |
| Возможности | projectScoutelloId, stage, ownerScoutelloUserId |
| Проекты | status, assignedContactScoutelloId |
| Этапы | projectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter |
dueBefore — исключающий фильтр; dueAfter — включающий. Они сравнивают срок выполнения задачи или дату окончания этапа; записи без такой даты не соответствуют фильтру. Передавайте даты и время в формате ISO с указанием часового пояса. Все фильтры применяются до разбиения на страницы. Продолжайте работу с курсором, используя в точности те же фильтры, включая updatedSince, а также ту же организацию и интеграцию. Размер страницы можно изменять. После этого выпуска старые курсоры без области действия необходимо перезапустить с сохранённой временной отметки верхней границы.
Проекты, этапы, назначения и заметки
GET /members (MCP members_list) использует стандартное разбиение на страницы и требует members.read. Он возвращает scoutelloId (идентификатор участника Customer), scoutelloUserId (идентификатор User) и displayName. Отображаются только принятые участники организации, у которых указана роль; этот поиск не раскрывает адреса электронной почты или разрешения.
Для задач принимается assignedScoutelloUserIds; для возможностей используется ownerScoutelloUserId. Для проектов и этапов используется assignedContacts: [{"scoutelloId":"member-customer-id"}]. Для назначений требуются принятые участники организации, к которой относится учётные данные. Если назначения не указаны, они остаются без изменений; [] удаляет их. Импорт проектов, этапов, задач и протоколов выполняется без уведомлений: уведомления о назначениях и другие сообщения не отправляются.
Событие assignedContacts поддерживает читаемые контакты CRM и принятых участников, переданных по идентификатору участника Customer. Принятые участники недоступны в качестве обычных ссылок на контакты CRM или целей внешних ссылок; для указания ответственности команды используйте поле назначения участника.
Создавайте этапы с name и одним из projectScoutelloId или projectExternalId. Поддерживаются description (Markdown), status (open, in_progress, completed, closed), nullable startDate/endDate, order (по умолчанию — 0) и assignedContacts. Даты окончания не могут предшествовать датам начала. У каждого этапа есть стабильная внешняя ссылка в рамках интеграции. Проект этапа нельзя изменить через API. При создании и обновлении имя и описание локализуются на языке организации.
Задачи и протоколы принимают ссылки на проект, этап и возможность в виде <entity>ScoutelloId или <entity>ExternalId, например milestoneExternalId. Для каждой связи указывайте только один вариант написания, в том числе при очистке с помощью null. Все связи должны принадлежать организации, указанной в учётных данных. Ссылка только на этап позволяет определить проект; противоречащий проект или явная очистка проекта при сохранении его этапа отклоняются. Связанная возможность с проектом должна соответствовать проекту работы. Пропущенные связи сохраняют текущие значения; явное null очищает связь, если оставшийся контекст корректен. При чтении возвращаются оба варианта написания идентификаторов и назначения задач.
Планирование задач и рабочие процессы
status задачи — это неизменяемый ключ статуса в эффективном рабочем процессе задачи, а не фиксированное значение перечисления. Доступные рабочие процессы организации и проекта можно получить с помощью GET /task-workflows, используя область tasks.read. Каждый статус содержит ключ, метку, жизненный цикл type (backlog, unstarted, started, completed или cancelled), цвет, порядок, признак статуса по умолчанию и состояние архива. Записи проектов указывают, унаследован ли рабочий процесс организации. Настройка рабочих процессов по-прежнему выполняется через панель управления.
Задачи принимают nullable priority (low, medium, high или urgent) и estimatedEffortMinutes, а также nullable startDate и dueDate. При чтении задачи возвращаются денормализованный statusType, ссылка на родительскую задачу, компактные ссылки на подзадачи и ссылки blockedBy / blocks.
Создавайте или обновляйте подзадачу одного уровня с помощью parentTaskScoutelloId или parentTaskExternalId; null переводит её в задачу верхнего уровня. Зависимости задаются массивами ссылок { "scoutelloId": "..." } или { "externalId": "..." } в blockedBy и blocks. Если поля связей не указаны, существующие связи сохраняются, а пустой массив зависимостей очищает соответствующее направление. API отклоняет вложенные подзадачи, зависимости между родителем и дочерним элементом, зависимости между организациями, дубликаты, ссылки на самих себя, а также прямые и транзитивные циклы.
Фильтры списка задач принимают точные значения для рабочего процесса status, жизненного цикла statusType, priority, parentState (top_level, subtask или parent) и blockedState (blocked, blocking или unblocked).
Протоколы дополнительно принимают status: "draft" | "final" (для новых записей по умолчанию используется final). Для нового протокола требуются type, date и контакт либо действительный контекст проекта или этапа. contactExternalId: null очищает контакт только при сохранении контекста проекта или этапа. Поэтому внутренние заметки проекта можно создавать и читать без фиктивного клиента. Значения «черновик» и «финал» описывают состояние заметки и не инициируют отправку сообщения. Приватные задачи и протоколы остаются недоступными.
Участники проекта
participants проекта содержит аддитивные операции upsert, идентифицируемые ссылкой contact, например:
{
"externalId": "gtm:hotels",
"participants": [{
"contact": {"scoutelloId": "prospect-contact-id"},
"role": "Potential pilot",
"notes": "Existing warm lead; qualify the next step.",
"groupScoutelloId": null
}]
}
Участники описывают потенциальных и существующих клиентов, связанных с проектом; ответственные участники команды указываются через назначения. Если участники не указаны, передан пустой массив или отдельные поля участника не указаны, существующие данные сохраняются. null очищает role, notes или groupScoutelloId. Дублирующиеся разрешённые контакты в одном запросе отклоняются. Группы уже должны принадлежать выбранному проекту; при чтении возвращаются participantGroups (идентификатор/название), а также идентификаторы участников, контакты, роль, заметки и идентификатор группы. Удаление участников и создание групп в настоящее время доступны на панели управления.
Пакетная операция upsert для записей
Записывайте до 100 записей с помощью пакетного маршрута ресурса:
POST /contacts/batch-upsert
Content-Type: application/json
{
"mode": "apply",
"records": [
{
"externalId": "record-123",
"externalUpdatedAt": "2026-09-01T11:45:00.000Z",
"type": "person",
"firstName": "Alex",
"lastName": "Example",
"email": "alex@example.com"
}
]
}
В пакетах задач записи задач разрешаются до применения связей с родителями и зависимостей. Такая двухэтапная обработка позволяет родительской задаче, блокирующей или заблокированной задаче ссылаться на другую задачу, созданную в том же пакете, по её внешнему идентификатору независимо от порядка записей.
Используйте документ OpenAPI для определения полей и ограничений валидации каждого ресурса. Каждая запись должна содержать стабильный externalId длиной от 1 до 200 символов. Рассматривайте его как непрозрачный технический идентификатор: не используйте адрес электронной почты, имя, секрет API или другие персональные данные. externalUpdatedAt необязателен, но настоятельно рекомендуется, если исходная система предоставляет надёжную временную метку изменения.
Размер тела запроса ограничен 1 МиБ. mode по умолчанию равен apply:
applyпроверяет и записывает принятые записи.validateвыполняет ту же проверку и сопоставление без записи данных, возвращая результатыwould_*.
Для импорта контактов в запросе можно задать matchByEmail равным true. По умолчанию используется false; внешний идентификатор является более безопасной границей идентичности.
Пропущенные поля сохраняют текущее значение. Явный null очищает поле, допускающее значение null, а переданный пустой массив назначений или тегов очищает соответствующую связь. Проектные participants выполняются по принципу аддитивного upsert: пустой массив оставляет список участников без изменений. При записи тегов контактов, задач, возможностей и событий используются идентификаторы тегов Scoutello. Внешние идентификаторы связей сопоставляются только через связи, принадлежащие текущей интеграции, а идентификаторы пользователей Scoutello, используемые для владения или ответственности, должны соответствовать принятым участникам текущей организации.
Для создания возможности требуется аккаунт или контакт, а для проигранной возможности необходимо указать причину проигрыша. Денежные суммы указываются в целых центах. Названия и описания проектов и событий читаются и записываются на языке, настроенном в организации. Запись событий поддерживает явные даты, а также ежедневное, еженедельное или ежемесячное повторение с исключениями; уровни видимости опубликованных событий по-прежнему зависят от требований Scoutello к юридической готовности. API не предоставляет доступ к продаже билетов на события, участникам, медиафайлам, шаблонам, рассылкам, совместной работе и другим расширенным средствам управления событиями.
Поиск тегов
Используйте эндпоинт тегов перед передачей tagIds:
GET /tags?entity=events&type=category
entity обязателен и принимает contacts, tasks, opportunities или events. Он сопоставляется с соответствующей сохранённой релевантностью тега. type необязателен и принимает category или attribute. Выбираемые категории могут принадлежать организации или быть глобальными; выбираемые атрибуты берутся из глобального набора атрибутов, сформированного Scoutello. Результаты содержат scoutelloId, название на языке организации, type и relevancy. Идентификаторы тегов из другой организации, с неверной релевантностью или недоступные для выбора отклоняют соответствующий элемент пакета.
Чтение истории исходящей почты
История почты доступна только для чтения:
GET /mails?updatedSince=2026-09-01T00:00:00.000Z
GET /mails/{scoutelloId}
Возвращается только почта, принадлежащая организации, со статусом sent или failed. Ответы содержат общие сохранённые заголовки и тело письма, BCC, статус и временные метки, ссылки на проекты/мероприятия/рассылки, идентификаторы и типы вложений, а также сводную статистику доставки, открытий, переходов, возвратов, жалоб и отклонений по получателям. Черновики, письма в очереди или запланированные письма, записи по отдельным получателям, отрендеренные снимки, необработанные ошибки провайдера и URL для скачивания вложений никогда не предоставляются. Более позднее обновление доставки получателю изменяет эффективную временную метку синхронизации письма, поэтому письмо снова появляется при инкрементальном чтении. Маршрутов для записи почты нет.
Результат применения может быть created, updated, linked, unchanged, stale_ignored или rejected. Для проверки используются would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale или rejected. Корректный пакетный запрос возвращает HTTP 200, даже если отдельные записи отклонены, поэтому всегда проверяйте каждый элемент и сводку ответа. Сохраняйте ответ requestId при обращении в службу поддержки Scoutello для расследования сбоя.
Временные метки и конфликты
Если присутствует externalUpdatedAt, Scoutello использует его, чтобы отклонить устаревшие изменения, не прерывая обработку остальной части пакета. Результат stale_ignored является окончательным для этой устаревшей версии данных; прежде чем отправлять новую версию, получите текущую запись.
Рассматривайте временные метки как значения UTC в формате ISO 8601. Сохраняйте исходную точность и не подставляйте время выполнения задания синхронизации вместо времени изменения исходной записи.
Идемпотентность
Граница идемпотентности определяется интеграцией и externalId. Scoutello сравнивает хеш канонического содержимого и необязательное значение externalUpdatedAt, поэтому повторная отправка той же записи не создаёт дубликаты и может вернуть unchanged.
При наличии externalUpdatedAt одинаковые временная метка и содержимое получают результат unchanged, более старая временная метка — результат stale_ignored, а одинаковая временная метка с другим содержимым приводит к конфликту версий. Для ссылки, которая ещё не принимала временную метку, неизменённое содержимое без временной метки остаётся unchanged, а изменённое содержимое применяется в порядке поступления. После того как ссылка приняла временную метку, изменённое содержимое без externalUpdatedAt отклоняется как конфликт версий, поэтому данные без версии не могут перезаписать состояние с версией. Поэтому настоятельно рекомендуется использовать временные метки изменения исходных данных.
Журнал аудита
Принятые API-действия по созданию, обновлению и синхронизации только ссылок отображаются в журналах изменений Scoutello с источником Public API и связываются с ответственной интеграцией. Сводки результатов выполнения операций сохраняют идентификаторы запросов и агрегированные результаты для устранения неполадок; данные записей и секреты API не сохраняются.
Ошибки и повторные попытки
Ошибки на уровне запроса используют следующий конверт:
{
"error": {
"code": "error_code",
"message": "Safe error message",
"requestId": "request-id",
"details": {}
}
}
Повторяйте запросы при ответах HTTP 429 и временных ответах 5xx, используя экспоненциальную задержку и случайное смещение. При наличии соблюдайте Retry-After. Сетевой сбой мог произойти после того, как Scoutello принял запрос; повторная отправка той же группы безопасна, поскольку каждая запись идемпотентна по внешнему идентификатору и канонической структуре данных. Не повторяйте автоматически запросы после ошибок аутентификации, авторизации, валидации, конфликта версий или отдельных результатов rejected без изменения запроса.
Рекомендуемый цикл двусторонней синхронизации
- Вызвать
/whoamiпри настройке и проверить ожидаемую организацию и области доступа. - Прочитать все страницы, изменённые после последней завершённой контрольной точки, и идемпотентно применить эти изменения во внешней системе.
- Отправить внешние изменения в
/batch-upsert, используя стабильные внешние идентификаторы и временные метки изменения источника. - Сохранять контрольные точки только после обработки всех страниц и результатов по отдельным элементам.
- Разрешать конфликты в соответствии с правилами владения исходной системы; не имитировать удаление, отправляя пустые записи.
В этой первой версии Scoutello намеренно не предоставляет общедоступный маршрут удаления. До появления документированной операции жизненного цикла обрабатывайте политики удаления или архивирования за пределами API.
Публикации в социальных сетях для проверки человеком
Социальный API подготавливает публикации для назначенного проверяющего. Он не может одобрять или публиковать их. REST и MCP используют одинаковые области доступа и сервис.
| Область доступа | Конечные точки в рамках /api/v1 |
|---|---|
social-channels.read | GET /social-channels |
social-posts.read | GET /social-posts, GET /social-posts/{scoutelloId} |
social-post-drafts.read | GET /social-post-drafts, GET /social-post-drafts/{scoutelloId}, GET /social-post-drafts/external/{externalId} |
social-post-drafts.write | POST /social-post-drafts/batch-upsert, POST /social-media/uploads, POST /social-media/uploads/{assetId}/finalize |
Новые области доступа необходимо предоставлять явно. Существующие учётные данные не получают дополнительных прав. Используйте members.read, чтобы определить идентификаторы пользователей-участников, и выберите проверяющего с разрешением на публикацию (newsletter.edit). Для черновиков не требуется контакт в CRM или проект.
{
"mode": "apply",
"records": [{
"externalId": "campaign:autumn:launch",
"expectedVersion": 0,
"approverScoutelloUserId": "REVIEWER_USER_ID",
"content": {
"title": "Autumn launch",
"publishMode": "schedule",
"scheduledAt": "2026-10-01T09:00:00+02:00",
"variants": [{
"channelId": "CHANNEL_SCOUTELLO_ID",
"content": "Explore the autumn collection.",
"settings": {},
"mediaIds": ["FINALIZED_ASSET_ID"]
}]
}
}]
}
Используйте publishMode: "now" и scheduledAt: null для публикации после утверждения. Каждый вариант для канала содержит полный текст, настройки и упорядоченные идентификаторы медиафайлов.
Обнаружение каналов возвращает поддерживаемые форматы, ограничения и настройки. В настоящее время поддерживаются профили и страницы LinkedIn, Facebook, Instagram и Threads.
Для Instagram требуются медиафайлы. Вариант может содержать до десяти изображений или видео.
Пакет может содержать до 100 уникальных внешних идентификаторов в пределах действующего ограничения размера запроса в 1 МиБ. mode: "validate" проверяет ссылки и версии, не сохраняя черновики, не загружая ресурсы, не создавая уведомления и не добавляя задачи в очередь. Результаты применения содержат идентификаторы, ссылки на проверку, версии и результаты для каждой записи. Частичные сбои не отменяют успешно обработанные связанные записи. При сбое уведомления возвращается предупреждение с сохранённым URL проверки.
Перед изменением ожидающего черновика получите его текущую версию с помощью draftVersion. Идентичные повторные запросы идемпотентны и сохраняют последующие изменения, внесённые людьми. Изменить проверяющих без создания новой записи невозможно. После утверждения или отклонения используйте новый внешний идентификатор для другого предложения.
Чтение черновиков ограничено вызываемой интеграцией; история публикаций охватывает все сохранённые кампании, созданные в Scoutello в организации, включая публикации из панели управления, скрипта и устаревших версий Scoutello. История внешних каналов не импортируется.
Для списков используются стандартные параметры limit, cursor и updatedSince. Публикации и черновики также принимают channelId, status, after, before и search; сохраняйте все фильтры при последующих запросах страниц по курсору. Фильтры по датам применяются ко времени публикации (ко времени создания для ожидающих немедленных черновиков). Фильтр черновиков status отбирает записи по статусу утверждения; фильтр публикаций status сопоставляет статус кампании или доставки в канале. В результатах чтения отображаются последнее известное состояние доставки, сбои по каналам, публичные ссылки и временные метки сверки. Инкрементальное чтение черновиков также отражает изменения в доставке кампании.
Загрузка медиафайлов
- Вызвать
POST /social-media/uploadsс параметрамиclientUploadId,filename,contentType,sizeв байтах иsha256исходных байтов в нижнем регистре шестнадцатеричного формата. Поддерживаются типы PNG, JPEG, WebP, MP4, WebM, QuickTime и M4V. Максимальный размер загрузки — 500 МиБ. - Отправить исходные байты методом HTTP
PUTна возвращённый адресupload.url, используя его заголовки. Срок действия URL для загрузки — 15 минут. Для повторных попыток загрузки того же файла использоватьclientUploadId; для истёкших сессий или других файлов требуется новый идентификатор. - Вызвать
POST /social-media/uploads/{assetId}/finalizeс телом JSON{}. При финализации проверяются размер, тип, сигнатура и контрольная сумма, после чего создаётся неизменяемая частная копия и возвращается идентификатор ресурса дляmediaIds. Повторная финализация безопасна.
Право собственности на загрузку определяется организацией и интеграцией. Черновики могут ссылаться на финализированные ресурсы своей организации. URL для предпросмотра временные; для их обновления нужно снова получить черновик. URL для загрузки никогда не выдаются для финализированных объектов.
Проверка человеком и публикация
Рецензент получает уведомление на панели управления и может открыть публикацию в разделе Postings или по URL для проверки. При редактировании создаётся ещё одна неизменяемая версия. Одобрение использует отображаемую версию и хеш содержимого, повторно проверяет членство, каналы и ресурсы и атомарно создаёт одну постоянную кампанию. Если предложенное время уже прошло, рецензенту необходимо сохранить новое время или выбрать публикацию после одобрения.
При повторных попытках в очереди используются та же кампания и квитанции платформы. Одобренные кампании нельзя редактировать на месте. Отмена через панель управления сохраняет историю одобрения и медиафайлы; отмена не может прервать активную отправку. Для различения одобрения и фактической публикации на платформе нужно опрашивать черновик или кампанию.