Перейти до основного вмісту

Scoutello API

API Scoutello — це 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Переглядати список прийнятих учасників, отримуючи лише Customer ID, User ID і відображуване ім’я учасника.
events.readПереглядати список і отримувати дані подій та основних розкладів.
events.writeПеревіряти й застосовувати операції додавання або оновлення подій.
mails.readПереглядати історію вихідних листів, надісланих організацією або таких, що не вдалося доставити.
mail-drafts.readПереглядати окремі чернетки електронних листів цієї інтеграції, що очікують погодження, і статус їхньої доставки.
mail-drafts.writeГотувати або редагувати чернетки електронних листів для погодження людиною; ніколи не погоджувати й не надсилати їх.
tags.readВизначати доступні для вибору теги для підтримуваних типів сутностей.

Цей API ніколи не повертає приватні завдання та протоколи. Відсутня область доступу повертає помилку авторизації, а не розглядається як порожній результат.

Контакт CRM, який не є учасником, можна прочитати та використовувати в посиланнях, навіть якщо його пов’язано з обліковим записом Scoutello. Відповідь містить лише поля CRM організації, без даних про User або поля доступу. Контакти з роллю, дозволами, запрошенням, прийняттям запрошення чи статусом облікового запису організації залишаються прихованими. Редагування контакту, пов’язаного з обліковим записом, заборонене (protected_contact), зокрема редагування полів CRM, які інакше не змінюються. Щоб послатися на наявний доступний для читання контакт із завдання або протоколу, contacts.write може встановити його зовнішній зв’язок, використовуючи лише externalId, scoutelloId і необов’язковий externalUpdatedAt. Подальші оновлення лише метаданих зв’язку використовують externalId і необов’язковий externalUpdatedAt; після встановлення зв’язку параметр початкового налаштування scoutelloId потрібно не вказувати. Це ніколи не змінює контакт або його User. Призначення прийнятого учасника здійснюється через окреме представлення members.read.

Нові ключі використовують префікс sctl_api_ і починаються лише з contacts.write. Усі інші області доступу явно надаються за вибором; їх має надати адміністратор організації під час створення або ротації ключа. Наявні облікові дані зберігають поточні області доступу й залишаються чинними.

Контакти, пов’язані з проєктами, і чернетки електронних листів​

Операції upsert для контактів приймають необов’язкові пари 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 лише для створення, а для змін — поточну повернуту версію. Контекст і особа, яка погоджує, є незмінними; для перевірених або відправлених чернеток зміна вмісту відхиляється. Ідентичні повторні запити повертають оригінальну чернетку.

Чернетки відображаються на вкладках електронної пошти проєктів і контактів та в сповіщеннях про схвалення на панелі керування. Підготовка через API не надсилає листів, зокрема сповіщень; наявна поведінка поштових сповіщень робочих процесів не змінюється. Відповідальна особа може змінити одержувачів, тему, текст і підтримувані вкладення, зберегти версію та вибрати Схвалити й надіслати. Інтеграції не можуть схвалювати чи надсилати. Невдалі або невизначені доставки ніколи не слід повторювати без перевірки. Під час перетворення чернеток на основі протоколів зберігайте протоколи й додавайте взаємні посилання на їхні заміни.

Доступ через MCP​

Той самий ключ Scoutello API і ті самі області доступу можна використовувати з кінцевою точкою MCP для streamable HTTP:

https://admin.scoutello.com/api/v1/mcp

Налаштуйте клієнт MCP на надсилання Authorization: Bearer YOUR_API_KEY. Старий URL /api/mcp залишається псевдонімом сумісності шляху, але нові клієнти мають використовувати версійну кінцеву точку. Попередні облікові дані sctl_mcp_ не приймаються; замініть їх ключем інтеграції Scoutello API.

Інструменти 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 отримує інструмент пакетного upsert, але не інструменти читання. 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 читання, коли запис пов’язано цією інтеграцією.

Відповідь зі списком має таку оболонку:

{
"data": [],
"page": {
"nextCursor": null,
"hasMore": false,
"snapshotAt": "2026-09-01T12:00:00.000Z"
},
"requestId": "request-id"
}

limit має бути від 1 до 100. Результати впорядковуються за ефективним часом зміни їхнього загальнодоступного API-представлення, а потім за ідентифікатором Scoutello. Цей ефективний час може бути пізнішим за час updatedAt повернутої сутності, якщо змінилися метадані integration-link. Курсори є непрозорими: зберігайте та надсилайте їх без змін і не намагайтеся визначати їхній зміст.

Перша відповідь фіксує snapshotAt для цього проходу. Виконуйте nextCursor, доки hasMore не матиме значення false, перш ніж починати інше інкрементне читання. Це запобігає нестабільності поточного проходу через зміну записів під час пагінації.

Для інкрементної синхронізації обробіть усі сторінки курсора, а потім збережіть snapshotAt цього проходу як часову позначку верхньої межі. Передайте її як значення updatedSince у форматі ISO 8601 під час наступного проходу. Нижня межа є включною, тому повторна спроба виконати завершений знімок може повернути записи на межі, але не може пропустити їх.

Відповідь для одного запису має таку оболонку:

{
"data": {},
"requestId": "request-id"
}

Відповіді для окремого контакту також містять масив relations. Кожен зв’язок зберігає ідентифікатор зв’язку Scoutello, час створення, тип, нотатки, а також посилання connectedFrom і connectedTo на контакти. Посилання на контакти містять ідентифікатор Scoutello та зовнішній ідентифікатор цієї інтеграції, якщо він існує. Контакти, виключені з межі конфіденційності доступу організації API, не відображаються через зв’язки. Відповідь зі списком контактів залишається компактною та не містить зв’язків; якщо потрібні відомості про зв’язки, використовуйте відповідний маршрут для окремого контакту.

Робочі фільтри та область дії курсора​

Списки контактів приймають search, type (person, company, supplier, other), status і tagIds. Пошук обрізається, не враховує регістр і обмежений 200 символами / 10 токенами, розділеними пробілами. Кожен токен має траплятися принаймні в одному з firstName, lastName або companyName, зокрема в застарілих назвах компаній, збережених у lastName. Такі символи, як % і _, зіставляються буквально. Для тегів використовується зіставлення any-of з 1–50 ідентифікаторами. Усі передані фільтри поєднуються оператором AND. REST кодує ідентифікатори тегів як повторювані параметри, а 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 очищає контакт лише за умови, що контекст проєкту/етапу зберігається. Тому внутрішні нотатки проєкту можна створювати й читати без зазначення клієнта. Draft/final описує стан нотатки й ніколи не надсилає повідомлення. Приватні завдання та протоколи залишаються недоступними.

Учасники проєкту​

Проєкт 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 (ідентифікатор/назва), а також ідентифікатори учасників, контакти, роль, нотатки та ідентифікатор групи. Видалення учасників або створення груп наразі доступне в інформаційній панелі.

Масове оновлення записів​

Записуйте до 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 без зміни запиту.

Рекомендований цикл двосторонньої синхронізації​

  1. Викликати /whoami під час налаштування та перевірити очікувану організацію і дозволи.
  2. Прочитати кожну сторінку, змінену після останньої завершеної контрольної позначки, і застосувати ці зміни до зовнішньої системи ідемпотентно.
  3. Надіслати зовнішні зміни до /batch-upsert, використовуючи стабільні зовнішні ідентифікатори та часові позначки зміни джерела.
  4. Зберігати контрольні точки лише після обробки всіх сторінок і результатів для окремих елементів.
  5. Вирішувати конфлікти відповідно до правил належності даних у вихідній системі; не імітувати видалення надсиланням порожніх записів.

У цій першій версії Scoutello навмисно не надає публічного маршруту для видалення. До появи документованої операції життєвого циклу обробляти політики видалення або архівування за межами API.

Публікації в соціальних мережах для перевірки людиною​

Соціальний API готує публікації для визначеної відповідальної особи. Він не може схвалювати або публікувати їх. REST і MCP використовують однакові дозволи та сервіс.

ДозвілКінцеві точки в /api/v1
social-channels.readGET /social-channels
social-posts.readGET /social-posts, GET /social-posts/{scoutelloId}
social-post-drafts.readGET /social-post-drafts, GET /social-post-drafts/{scoutelloId}, GET /social-post-drafts/external/{externalId}
social-post-drafts.writePOST /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 . Кожен варіант каналу містить повний текст, налаштування та впорядковані ID медіа. Виявлення каналів повертає підтримувані формати, ліміти й налаштування. Наразі підтримуються профілі/сторінки LinkedIn, Facebook, Instagram і Threads. Instagram потребує медіа. Варіант приймає до десяти зображень або відео.

Пакети приймають до 100 унікальних зовнішніх ID у межах наявного ліміту запиту 1 MiB. mode: "validate" перевіряє посилання й версії без збереження чернеток, завантаження ресурсів, створення сповіщень чи додавання роботи до черги. Результати застосування містять ID, посилання для перевірки, версії та результати для кожного запису. Часткові помилки не скасовують успішні записи. Помилка сповіщення повертає попередження та збережений URL для перевірки.

Перед зміною чернетки, що очікує перевірки, прочитайте поточну draftVersion . Ідентичні повтори ідемпотентні й зберігають пізніші людські зміни. Особу, що перевіряє, не можна змінити в тій самій чернетці. Після схвалення або відхилення використовуйте новий зовнішній ID для нової пропозиції. Чернетки читає лише інтеграція, що викликає API. Історія публікацій охоплює всі сталі кампанії Scoutello в організації, зокрема публікації з панелі керування, скриптів і попередніх версій Scoutello. Історія зовнішніх каналів не імпортується.

Списки використовують стандартні параметри limit , cursor і updatedSince . Публікації та чернетки також приймають channelId , status , after , before і search ; зберігайте всі фільтри на наступних сторінках курсора. Фільтри дати стосуються часу публікації, або часу створення для чернеток з негайною публікацією. status чернетки фільтрує стан схвалення; status публікації відповідає стану доставки кампанії чи каналу. Читання повертає останній відомий стан доставки, помилки каналів, публічні посилання й часові позначки узгодження. Інкрементальне читання чернеток також відображає зміни доставки кампанії.

Завантаження медіа​

  1. Викликати POST /social-media/uploads із clientUploadId, filename, contentType, size у байтах і sha256 оригінальних байтів у нижньому регістрі шістнадцяткової системи. Підтримуються типи PNG, JPEG, WebP, MP4, WebM, QuickTime і M4V. Максимальний розмір завантаження — 500 MiB.
  2. Надіслати оригінальні байти за допомогою HTTP PUT на повернений upload.url, використовуючи його заголовки. URL-адреси завантаження дійсні протягом 15 хвилин. Повторно використовувати clientUploadId для повторних спроб завантаження того самого файлу; для прострочених сеансів або інших файлів потрібен новий ідентифікатор.
  3. Викликати POST /social-media/uploads/{assetId}/finalize із JSON-тілом {}. Під час фіналізації перевіряються розмір, тип, сигнатура та контрольна сума, створюється незмінна приватна копія, а також повертається ідентифікатор ресурсу для mediaIds. Повторна фіналізація безпечна.

Право власності на завантаження визначається організацією та інтеграцією. Чернетки можуть посилатися на фіналізовані ресурси своєї організації. URL-адреси попереднього перегляду тимчасові; для їх оновлення потрібно знову отримати чернетку. URL-адреси завантаження ніколи не надаються для фіналізованих об’єктів.

Перевірка людиною та доставка​

Рецензент отримує сповіщення на інформаційній панелі та може відкрити публікацію в розділі Postings або за URL-адресою перевірки. Редагування створює ще одну незмінну версію. Схвалення використовує відображену версію та хеш вмісту, повторно перевіряє членство, канали й ресурси та атомарно створює одну довготривалу кампанію. Якщо запропонований час уже минув, рецензент має зберегти явно вказаний новий час або вибрати публікацію після схвалення.

Повторні спроби в черзі використовують ту саму кампанію та квитанції платформи. Схвалені кампанії не можна редагувати на місці. Скасування через інформаційну панель зберігає історію схвалення та медіафайли; скасування не може перервати активне надсилання. Потрібно опитувати чернетку або кампанію, щоб відрізнити схвалення від фактичної доставки на платформу.