Přeskočit na hlavní obsah

Scoutello API

Scoutello API je server-to-server API pro obousměrnou synchronizaci kontaktů, úkolů, protokolů, příležitostí, projektů, milníků a událostí organizace. Zpřístupňuje také historii odchozí pošty pouze pro čtení, vyhledávání členů, kterým lze přiřazovat položky, a vyhledávání štítků podle typu entity. Paginované GET/list trasy a idempotentní dávkové upsert operace jsou v této verzi základními prvky synchronizace. API neumožňuje mazání ani nepodporuje webhooky.

Základní URL API je:

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

Je uvedena také v Nastavení organizace → Vývojářské rozhraní/API. Dokument OpenAPI je k dispozici na adrese:

https://admin.scoutello.com/api/v1/openapi.json

Vytvoření a zabezpečení klíče​

U modulárních organizací musí být kromě požadovaných oprávnění klíče aktivní také modul CRM. Platný klíč nemůže aktivovat chybějící modul. Pokud přístup k CRM není dostupný, požadavky vracejí HTTP 403 s kódem chyby module_not_active. Přístup k CRM lze zkontrolovat nebo aktivovat v části Předplatné; po aktivaci přístupu požadavek zopakovat.

Integraci a klíč API lze vytvořit v Nastavení organizace → Vývojářské rozhraní/API. Celý klíč se zobrazí pouze jednou. Před zavřením dialogu jej zkopírovat do správce tajných údajů; Scoutello již celý klíč znovu nezobrazí.

  • Pro každý externí systém a prostředí používat samostatnou integraci a klíč.
  • Udělit pouze oprávnění, která daný systém potřebuje.
  • Klíč nikdy nevkládat do kódu prohlížeče, URL, správy zdrojového kódu, protokolů, zpráv podpoře ani úložiště na straně klienta.
  • Klíče pravidelně obměňovat. Při obměně aktivní integrace začne náhradní klíč fungovat okamžitě a předchozí klíč zůstane platný nejvýše 15 minut, aby externí systém mohl přejít bez výpadku. Nadále platí dříve nastavený čas vypršení platnosti, takže předchozí klíč může přestat fungovat dříve.
  • Pokud mohlo dojít k odhalení klíče, před jeho obměnou integraci pozastavit. Pozastavení dočasně odmítá všechny klíče integrace. Při obměně během pozastavení nevzniká překryv: předchozí klíč zůstane deaktivovaný a náhradní klíč zůstane deaktivovaný až do obnovení integrace.
  • Při odpojování externího systému celou integraci trvale odvolat. Odvolání deaktivuje všechny její klíče a nelze je vrátit zpět.

Klíč odesílat při každém ověřeném požadavku:

Authorization: Bearer YOUR_API_KEY

Preferováno je ověřování pomocí Bearer. Klienti, kteří nemohou nastavit Authorization, mohou místo něj použít x-api-key. Neodesílat obě hlavičky; požadavky s rozdílnými hodnotami v obou hlavičkách jsou odmítnuty.

API je určeno backendovým klientům a nepovoluje přístup prohlížečů napříč původy.

Po nastavení klíče použít GET /whoami k ověření integrace, organizace, oprávnění a limitů klíče bez načítání osobních údajů uživatelů.

Oprávnění​

RozsahUmožňuje
contacts.readVýpis a načítání kontaktů. Kontakty organizačního účtu a kontakty členů s přístupem jsou vyloučeny.
contacts.writeOvěření a použití upsertů kontaktů.
tasks.readVýpis a načítání neveřejných úkolů.
tasks.writeOvěření a použití upsertů úkolů.
protocols.readVýpis a načítání neveřejných protokolů.
protocols.writeOvěření a použití upsertů protokolů.
opportunities.readVýpis a načítání obchodních příležitostí.
opportunities.writeOvěření a použití upsertů obchodních příležitostí.
projects.readVýpis a načítání projektů.
projects.writeOvěření a použití upsertů projektů a účastníků.
milestones.readVýpis a načítání milníků projektů.
milestones.writeOvěření a použití upsertů milníků.
members.readVýpis přijatých členů pouze s ID zákazníka člena, ID uživatele a zobrazovaným jménem.
events.readVýpis a načítání událostí a hlavních kalendářů.
events.writeOvěření a použití upsertů událostí.
mails.readČtení historie odeslaných a neúspěšných odchozích e-mailů vlastněných organizací.
mail-drafts.readČtení samostatných návrhů e-mailů této integrace čekajících na schválení a stavu doručení.
mail-drafts.writePříprava nebo úprava návrhů e-mailů ke schválení osobou; nikdy neschvaluje ani neodesílá.
tags.readZjištění volitelných štítků pro podporované typy entit.

Soukromé úkoly a protokoly toto API nikdy nevrací. Chybějící rozsah vrací chybu autorizace; není považován za prázdný výsledek.

Kontakt v CRM, který není členem, lze načíst a použít jako odkaz, i když je propojen s přihlášením do Scoutello. Odpověď obsahuje pouze pole CRM organizace, nikdy identitu uživatele ani údaje o přístupu. Kontakty s rolí, oprávněními, pozvánkou, přijetím nebo stavem organizačního účtu zůstávají skryté. Úprava kontaktu propojeného s přihlášením zůstává zakázaná (protected_contact), včetně jinak nezměněných polí CRM. Pro odkazování na existující čitelný kontakt z úkolu/protokolu lze pomocí contacts.write vytvořit jeho externí propojení pouze s externalId, scoutelloId a volitelným externalUpdatedAt. Pozdější aktualizace pouze metadat propojení používají externalId a volitelný externalUpdatedAt; po propojení vynechat bootstrap scoutelloId. Tím se kontakt ani jeho uživatel nijak nezmění. Přiřazení přijatého člena používá samostatnou projekci members.read.

Nové klíče používají prefix sctl_api_ a začínají pouze s contacts.write. Každý další rozsah je výslovně volitelný a při vytváření nebo rotaci klíče ho musí udělit osoba s administrátorskými právy v organizaci. Stávající přihlašovací údaje si zachovávají své současné rozsahy a zůstávají platné.

Kontakty a koncepty e-mailů propojené s projektem​

Upsert operace kontaktů přijímají volitelné dvojice projectScoutelloId / projectExternalId a companyScoutelloId / companyExternalId (z každé dvojice zvolit jednu možnost). Kontakt, vazba na společnost a členství v projektu se pro každou položku ukládají atomicky. Přidání členství v projektu vyžaduje projects.write; vynechané reference zachovávají ostatní vazby a členství. Načtené podrobnosti kontaktu obsahují projectParticipations, pokud je udělen projects.read. Agenti pro obchodní projekty musí referenci projektu uvést výslovně, i při opětovném použití kontaktu.

Samostatné koncepty používají stávající systém schvalování osobami bez spuštění workflow:

MetodaCestaÚčel
GET/mail-draftsStránkované koncepty vlastněné integrací; volitelné filtry projectScoutelloId a status.
GET/mail-drafts/{scoutelloId}Aktuální verze, odkaz ke kontrole, hash obsahu, stav schválení/odeslání a výsledné ID e-mailu.
GET/mail-drafts/external/{externalId}Vyhledání stabilního externího ID integrace.
POST/mail-drafts/batch-upsertOvěření nebo použití přípravy konceptu.

Příprava konceptu vyžaduje mail-drafts.write, contacts.read a projects.write. Odkazovaný kontakt se stává účastníkem projektu. Schvalující osobou musí být přijatý člen organizace s oprávněním upravovat e-maily. Výběr odesílatele používá stávající povolená nastavení organizace nebo osobního odesílatele daného člena; libovolné adresy v poli From nejsou přijímány.

{
"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."
}
}]
}

Před opakováním požadavku pomocí mode: "apply" zkontrolovat každý výsledek ověření. Načtením výsledného ID získat reviewUrl, draftVersion, contentHash, status, dispatchStatus a mailScoutelloId. expectedVersion: 0 používat pouze pro vytvoření a pro úpravy používat aktuální vrácenou verzi. Kontext a schvalující osoba jsou neměnné; u zkontrolovaných nebo odeslaných konceptů se změněný obsah zamítá. Totožné opakované požadavky vracejí původní koncept.

Koncepty se zobrazují na kartách E-mail projektu/kontaktu a v oznámeních řídicího panelu o schválení. Příprava přes API neodesílá žádné e-maily včetně oznamovacích e-mailů; stávající chování oznamovacích e-mailů v pracovních postupech zůstává beze změny. Přiřazená osoba může upravit příjemce, předmět, tělo a podporované přílohy, uložit verzi a poté zvolit Schválit a odeslat. Integrace nemohou provést schválení ani odeslání. Neúspěšné nebo nejednoznačné doručení se nikdy neopakuje bez ověření. Při převodu konceptů založených na protokolech zachovejte protokoly a uveďte křížové odkazy na jejich náhrady.

Přístup MCP​

Stejný klíč API Scoutello a stejné obory lze použít s koncovým bodem MCP streamable HTTP:

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

Nakonfigurujte klienta MCP tak, aby odesílal Authorization: Bearer YOUR_API_KEY. Starší URL /api/mcp zůstává aliasem cesty pro kompatibilitu, ale nové klienty by měly používat verzovanou koncovou adresu. Pověření sctl_mcp_ se již nepřijímají; nahraďte je integračním klíčem API Scoutello.

Nástroje MCP přímo odpovídají kontraktu REST a používají stejná běhová schémata, kontroly tenanta, životní cyklus integrace, limity rychlosti a servisní metody. Například contacts_list, contacts_get, contacts_get_by_external_id a contacts_batch_upsert odpovídají čtyřem trasám kontaktů. Stejný vzor platí pro úkoly, protokoly, příležitosti, projekty, milníky a události; pošta zpřístupňuje mails_list a mails_get, členové zpřístupňují members_list a štítky zpřístupňují tags_list.

Server zpřístupňuje pouze nástroje povolené obory aktuálního klíče. Klíč s oborem contacts.read může vyhledat nástroje pro čtení kontaktů, ale nikoli contacts_batch_upsert; klíč s oborem contacts.write získá nástroj pro hromadné upsertování, ale nikoli nástroje pro čtení. whoami je vždy k dispozici. Nástroje pro zápis mají stejné okamžité účinky jako jejich protějšky REST, proto použijte mode: "validate", pokud má volající zkontrolovat dávku bez jejího použití.

MCP také funguje mezi servery a nepovoluje přístup z prohlížeče napříč zdroji. Jeho přenos JSON-RPC vyžaduje vyhrazenou URL, takže ji nelze sdílet s konkrétní URL prostředku REST, přestože ověřování i chování dat jsou společné.

Úplné pokyny ke konfiguraci klienta, ověřování, mapování nástrojů a řešení potíží najdete v příručce k integraci MCP.

Čtení záznamů​

Kontakty, úkoly, protokoly, příležitosti, projekty, milníky a události používají stejné trasy pro čtení:

GET /contacts?limit=50&updatedSince=2026-09-01T00:00:00.000Z
GET /contacts/{scoutelloId}
GET /contacts/external/{externalId}

contacts nahraďte tasks, protocols, opportunities, projects, milestones nebo events pro ostatní synchronizované prostředky. externalId se zobrazí v DTO pro čtení, pokud byl záznam propojen touto integrací.

Odpověď se seznamem má tento obálkový formát:

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

limit musí být v rozmezí 1 až 100. Výsledky jsou seřazeny podle efektivního času, kdy se změnila jejich veřejná reprezentace v API, a poté podle ID Scoutello. Tento efektivní čas může být pozdější než vrácená entita updatedAt, pokud se změnila metadata integrační vazby. Kurzorové hodnoty jsou neprůhledné: ukládejte je a odesílejte beze změny a nevyvozujte z jejich obsahu žádný význam.

První odpověď určuje snapshotAt pro daný průchod. Pokračujte pomocí nextCursor, dokud hasMore nebude false, a teprve poté začněte další přírůstkové čtení. Tím se zabrání tomu, aby změny záznamů během stránkování narušily stabilitu aktuálního průchodu.

Při přírůstkové synchronizaci zpracujte všechny stránky kurzoru a poté uložte snapshotAt daného průchodu jako časové razítko high-water mark. V dalším průchodu ho předejte jako hodnotu updatedSince ve formátu ISO 8601. Dolní mez je včetně, takže opakování dokončeného snímku může vrátit záznamy na hranici, ale nemůže je přeskočit.

Odpověď s jedním záznamem má tento obálkový formát:

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

Odpovědi s jedním kontaktem obsahují také pole relations. Každá relace zachovává své ID relace Scoutello, čas vytvoření, typ, poznámky a odkazy na kontakty connectedFrom a connectedTo. Odkazy na kontakty obsahují ID Scoutello a externí ID této integrace, pokud existuje. Kontakty vyloučené z důvodu omezení přístupu organizace k osobním údajům prostřednictvím API nejsou v relacích zpřístupněny. Odpověď se seznamem kontaktů zůstává stručná a relace neobsahuje; pokud jsou potřeba podrobnosti o vztazích, použijte jednu z tras pro jednotlivý kontakt.

Práce s filtry a rozsah kurzoru​

Seznamy kontaktů přijímají search, type (person, company, supplier, other), status a tagIds. Vyhledávání odstraňuje okolní mezery, nerozlišuje velká a malá písmena a je omezeno na 200 znaků / 10 tokenů oddělených bílými znaky. Každý token se musí nacházet alespoň v jednom z firstName, lastName nebo companyName, včetně starších názvů společností uložených v lastName. Znaky jako % a _ se porovnávají doslovně. U štítků se používá porovnávání any-of s 1–50 ID. Všechny zadané filtry se kombinují pomocí AND. REST kóduje ID štítků jako opakované parametry; MCP předává pole:

GET /contacts?search=Hamburg%20Hotel&type=company&status=prospect&tagIds=tag-one&tagIds=tag-two

Kurzory kontaktů jsou vázané na organizaci, integraci a každý filtr. Filtry ponechávejte na každé stránce; změna filtru vede k zamítnutí kurzoru. Pořadí a duplicity štítků ani pořadí tokenů vyhledávání, velikost písmen či mezery nemění výsledný filtr.

Trasy seznamů práce přijímají následující dodatečné filtry; ostatní kombinace prostředků a polí jsou odmítnuty:

ProstředekFiltry
ÚkolyprojectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter
ProtokolyprojectScoutelloId, milestoneScoutelloId, status (draft nebo final)
PříležitostiprojectScoutelloId, stage, ownerScoutelloUserId
Projektystatus, assignedContactScoutelloId
MilníkyprojectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter

dueBefore je výhradní; dueAfter je včetně hranice. Porovnávají termín úkolu nebo datum ukončení milníku; záznamy bez tohoto data se neshodují. Používat časová razítka ISO s uvedeným časovým pásmem. Všechny filtry se uplatňují před stránkováním. Pokračovat v kurzoru se stejnými filtry, včetně updatedSince, a se stejnou organizací/integrací. Velikost stránky se může změnit. Staré kurzory bez vymezení je po tomto vydání nutné restartovat od uloženého časového razítka high-water.

Projekty, milníky, přiřazení a poznámky​

GET /members (MCP members_list) používá standardní stránkování a vyžaduje members.read. Vrací scoutelloId (ID člena Customer), scoutelloUserId (ID User) a displayName. Zobrazují se pouze přijatí členové organizace s přiřazenou rolí; vyhledávání nezpřístupňuje e-mailové adresy ani oprávnění.

Úkoly přijímají assignedScoutelloUserIds; příležitosti používají ownerScoutelloUserId. Projekty a milníky používají assignedContacts: [{"scoutelloId":"member-customer-id"}]. Přiřazení vyžadují přijaté členy organizace příslušné přihlašovací údaje. Neuvedená přiřazení zůstávají beze změny; [] je zruší. Importy projektů, milníků, úkolů a protokolů probíhají bez upozornění: neposílají oznámení ani jinou komunikaci o přiřazení.

Událost assignedContacts podporuje čitelné CRM kontakty a přijaté členy zadané pomocí ID člena Customer. Přijatí členové zůstávají nedostupní jako běžné odkazy na kontakty CRM nebo cíle externích odkazů; pro týmovou odpovědnost použít pole přiřazení člena.

Vytváření milníků vyžaduje name a buď projectScoutelloId, nebo projectExternalId. Podporují description (Markdown), status (open, in_progress, completed, closed), nullable startDate/endDate, order (výchozí hodnota je 0) a assignedContacts. Datum ukončení nesmí předcházet datu zahájení. Každý milník má stabilní externí odkaz vymezený danou integrací. Jeho projekt nelze prostřednictvím API změnit. Při vytváření a aktualizaci se název a popis lokalizují do jazyka organizace.

Úkoly a protokoly přijímají odkazy na projekty, milníky a příležitosti jako <entity>ScoutelloId nebo <entity>ExternalId, například milestoneExternalId. Pro každý vztah uveďte pouze jednu variantu zápisu, a to i při jeho vymazání pomocí null. Všechny vztahy musí patřit do organizace dané přihlašovacími údaji. Odkaz pouze na milník odvodí projekt; konfliktní projekt nebo výslovné vymazání projektu při zachování jeho milníku bude zamítnuto. Propojená příležitost s projektem musí odpovídat projektu dané práce. Neuvedené vztahy zachovávají aktuální hodnoty; explicitní null vymaže vztah, pokud je zbývající kontext platný. Odpovědi obsahují oba zápisy ID a přiřazení úkolů.

Plánování úkolů a pracovní postupy​

status úkolu je neměnný klíč stavu v efektivním pracovním postupu úkolu, nikoli pevně daná výčtová hodnota. Dostupné pracovní postupy organizace a projektů lze načíst pomocí GET /task-workflows s rozsahem tasks.read. Každý stav obsahuje svůj klíč, popisek, životní cyklus type (backlog, unstarted, started, completed nebo cancelled), barvu, pořadí, příznak výchozího stavu a stav archivace. Položky projektů uvádějí, zda je zděděn pracovní postup organizace. Konfigurace pracovních postupů se nadále spravuje v dashboardu.

Úkoly přijímají nullable priority (low, medium, high nebo urgent) a estimatedEffortMinutes, dále nullable startDate a dueDate. Odpovědi úkolů obsahují denormalizovaný statusType, odkaz na nadřazený úkol, kompaktní odkazy na podúkoly a odkazy blockedBy / blocks.

Vytvoření nebo aktualizace podúkolu o jednu úroveň pomocí parentTaskScoutelloId nebo parentTaskExternalId; null jej převede na úkol nejvyšší úrovně. Závislosti používají pole odkazů { "scoutelloId": "..." } nebo { "externalId": "..." } v blockedBy a blocks. Vynechaná pole vztahů zachovají stávající hodnoty, zatímco prázdné pole závislostí daný směr vymaže. API odmítá vnořené podúkoly, závislosti mezi nadřazeným úkolem a podúkoly, závislosti napříč organizacemi, duplicity, odkazy na sebe sama a přímé i tranzitivní cykly.

Filtry seznamu úkolů přijímají přesný pracovní postup status, životní cyklus statusType, priority, parentState (top_level, subtask nebo parent) a blockedState (blocked, blocking nebo unblocked).

Protokoly navíc přijímají status: "draft" | "final" (nové záznamy mají ve výchozím nastavení final). Nový protokol vyžaduje type, date a buď kontakt, nebo platný kontext projektu či milníku. contactExternalId: null vymaže kontakt pouze tehdy, pokud zůstane zachován kontext projektu či milníku. Interní poznámky k projektům proto lze vytvářet a číst bez vymýšlení zákazníka. Stav konceptu či finální verze popisuje stav poznámky a nikdy nespouští komunikaci. Soukromé úkoly a protokoly zůstávají nepřístupné.

Účastníci projektu​

Projekt participants obsahuje aditivní upserty identifikované odkazem contact, například:

{
"externalId": "gtm:hotels",
"participants": [{
"contact": {"scoutelloId": "prospect-contact-id"},
"role": "Potential pilot",
"notes": "Existing warm lead; qualify the next step.",
"groupScoutelloId": null
}]
}

Účastníci představují potenciální zákazníky nebo zákazníky spojené s projektem; za jejich správu odpovídají členové přiřazení k úkolům. Vynechání účastníků, prázdné pole i vynechaná pole účastníků zachovávají stávající data. null vymaže role, notes nebo groupScoutelloId. Duplicitní vyřešené kontakty v jednom datovém vstupu jsou odmítnuty. Skupiny již musí patřit k vybranému projektu; načtená data obsahují participantGroups (ID/název) a ID účastníků, kontakty, roli, poznámky a ID skupiny. Odebrání účastníků nebo vytváření skupin je v současnosti dostupné na nástěnce.

Hromadné upsertování záznamů​

Pomocí hromadné trasy daného zdroje lze zapsat až 100 záznamů:

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"
}
]
}

Dávky úkolů nejprve vyřeší záznamy úkolů a teprve poté použijí vztahy nadřazených úkolů a závislostí. Toto dvoufázové zpracování umožňuje, aby nadřazený úkol, blokující úkol nebo blokovaný úkol odkazoval podle externího ID na jiný úkol vytvořený ve stejné dávce, bez ohledu na pořadí záznamů.

Pro pole jednotlivých zdrojů a validační omezení použijte dokument OpenAPI. Každý záznam musí mít stabilní externalId o délce 1 až 200 znaků. Nakládejte s ním jako s neprůhledným technickým identifikátorem: nepoužívejte e-mailovou adresu, jméno, tajný klíč API ani jiné osobní údaje. externalUpdatedAt je volitelný, ale důrazně doporučený, pokud zdrojový systém poskytuje spolehlivé časové razítko změny.

Tělo požadavku je omezeno na 1 MiB. mode má výchozí hodnotu apply:

  • apply ověří a zapíše přijaté záznamy.
  • validate provede stejnou validaci a párování bez zápisu a vrátí výsledky would_*.

U importů kontaktů lze v požadavku nastavit matchByEmail na true. Výchozí hodnota je false; externí ID představuje bezpečnější hranici identity.

Vynechaná pole zachovají aktuální hodnotu. Explicitní null vymaže pole s podporou hodnoty null a prázdné pole přiřazení/štítků vymaže danou vazbu. Projektové participants používají aditivní upsert: prázdné pole ponechá seznam beze změny. Zápisy štítků u kontaktů, úkolů, příležitostí a událostí používají ID štítků Scoutello. Externí ID vazeb se vyhledávají pouze prostřednictvím odkazů patřících k aktuální integraci, zatímco ID uživatelů Scoutello použitá pro vlastnictví nebo odpovědnost musí identifikovat přijaté členy aktuální organizace.

Při vytváření příležitostí je vyžadován účet nebo kontakt a u ztracených příležitostí také důvod ztráty. Peněžní částky se zadávají v celých centech. Názvy a popisy projektů a událostí se čtou a zapisují v jazyce nastaveném pro organizaci. Zápisy událostí podporují konkrétní data a denní, týdenní nebo měsíční opakování s výjimkami; úrovně viditelnosti publikovaných událostí se stále řídí podmínkami Scoutello pro právní připravenost. API nezpřístupňuje prodej vstupenek na události, účastníky, média, šablony, newslettery, spolupráce ani další pokročilé ovládací prvky správy událostí.

Zjišťování štítků​

Před zadáním tagIds použijte endpoint štítků:

GET /tags?entity=events&type=category

entity je povinný a přijímá hodnoty contacts, tasks, opportunities nebo events. Mapuje se na odpovídající uloženou relevanci štítku. type je volitelný a přijímá hodnoty category nebo attribute. Volitelné kategorie mohou patřit organizaci nebo být globální; volitelné atributy pocházejí z pečlivě spravované globální sady atributů Scoutello. Výsledky obsahují scoutelloId, název lokalizovaný do jazyka organizace, type a relevancy. ID štítků z jiné organizace, s nesprávnou relevancí nebo ID nevolitelných štítků zamítnou příslušnou položku dávky.

Čtení historie odchozí pošty​

Historie e-mailů je pouze pro čtení:

GET /mails?updatedSince=2026-09-01T00:00:00.000Z
GET /mails/{scoutelloId}

Vrací se pouze e-maily vlastněné organizací se stavem sent nebo failed. Odpovědi obsahují běžné uložené hlavičky a tělo, skryté kopie, stav a časová razítka, odkazy na projekty, události a newslettery, ID a typy příloh a souhrnné statistiky doručení, otevření, kliknutí, nedoručení, stížností a odmítnutí příjemců. Koncepty, e-maily ve frontě nebo naplánované e-maily, řádky jednotlivých příjemců, vykreslené náhledy, nezpracované chyby poskytovatele ani URL pro stažení příloh se nikdy nezpřístupňují. Pozdější aktualizace doručení příjemci posune efektivní časové razítko synchronizace e-mailu, takže se e-mail znovu objeví v přírůstkových načteních. Pro zápis e-mailů nejsou k dispozici žádné routy.

Výsledek operace apply může být created, updated, linked, unchanged, stale_ignored nebo rejected. Ověření používá would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale nebo rejected. Platný dávkový požadavek vrací HTTP 200, i když jsou jednotlivé záznamy odmítnuty, proto vždy zkontrolovat každou položku i souhrn odpovědi. Při žádosti o prošetření chyby podporou Scoutello ponechat odpověď requestId.

Časová razítka a konflikty​

Pokud je přítomno externalUpdatedAt, Scoutello ho použije k odmítnutí zastaralých změn, aniž by selhala zbylá část dávky. Výsledek stale_ignored je pro starší datovou část konečný; před rozhodnutím o odeslání novější verze načíst aktuální záznam.

Časová razítka považovat za hodnoty UTC ve formátu ISO 8601. Zachovat jejich původní přesnost a nenahrazovat časem spuštění synchronizační úlohy čas poslední změny zdrojového záznamu.

Idempotence​

Hranici idempotence tvoří integrace a externalId. Scoutello porovnává kanonický hash datové části a volitelnou hodnotu externalUpdatedAt, takže opakované odeslání stejného záznamu nevytvoří duplicity a může vrátit unchanged.

Se externalUpdatedAt platí, že stejné časové razítko a datová část znamenají unchanged, starší časové razítko znamená stale_ignored a stejné časové razítko s odlišnou datovou částí představuje konflikt verzí. U odkazu, který nikdy nepřijal časové razítko, zůstává stejná datová část bez časového razítka ve stavu unchanged, zatímco změněná datová část se použije v pořadí přijetí. Jakmile odkaz přijme časové razítko, změněná datová část bez externalUpdatedAt se odmítne jako konflikt verzí, aby neverzovaná data nemohla přepsat verzovaný stav. Proto se důrazně doporučuje používat časová razítka změn zdroje.

Auditní stopa​

Přijaté akce API pro vytvoření, aktualizaci a synchronizaci pouze odkazů se zobrazují v changelozích Scoutello se zdrojem Public API a jsou propojené s odpovědnou integrací. Souhrny provozních běhů zachovávají ID požadavků a souhrnné počty výsledků pro řešení problémů; neuchovávají datové obsahy záznamů ani tajné údaje API.

Chyby a opakování​

Chyby na úrovni požadavku používají tento obal:

{
"error": {
"code": "error_code",
"message": "Safe error message",
"requestId": "request-id",
"details": {}
}
}

Při odpovědích HTTP 429 a dočasných odpovědích 5xx použít exponenciální čekání s náhodným rozptylem. Pokud je přítomno Retry-After, řídit se jím. K selhání sítě mohlo dojít až poté, co Scoutello požadavek přijal; opětovné odeslání stejné dávky je bezpečné, protože každý záznam je idempotentní podle externího ID a kanonického datového obsahu. Bez změny požadavku automaticky neopakovat požadavky s chybami autentizace, oprávnění, validace, konfliktu verze ani individuální výsledky rejected.

Doporučená smyčka obousměrné synchronizace​

  1. Během nastavení zavolat /whoami a ověřit očekávanou organizaci a rozsahy oprávnění.
  2. Načíst každou stránku změněnou od poslední dokončené horní meze a idempotentně tyto změny použít v externím systému.
  3. Odeslat externí změny do /batch-upsert s použitím stabilních externích ID a časových razítek úprav ve zdrojovém systému.
  4. Uložit kontrolní body až po zpracování všech stránek a výsledků jednotlivých položek.
  5. Konflikty řešit podle pravidel vlastnictví zdrojového systému; nemažte záznamy odesláním prázdných záznamů.

Scoutello v této první verzi záměrně neposkytuje veřejnou trasu pro mazání. Dokud nebude zavedena a zdokumentována operace životního cyklu, řešit zásady mazání nebo archivace mimo API.

Příspěvky na sociální sítě ke kontrole lidmi​

Sociální API připravuje příspěvky pro určenou osobu provádějící kontrolu. Nemůže je schválit ani zveřejnit. REST a MCP používají stejné rozsahy oprávnění a stejnou službu.

Rozsah oprávněníKoncové body pod /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

Nové rozsahy oprávnění je nutné výslovně udělit. Stávající přihlašovací údaje nezískají žádný další přístup. Pomocí members.read zjistit ID uživatelů členů a vybrat osobu provádějící kontrolu s oprávněním zveřejňovat příspěvky (newsletter.edit). Koncepty nevyžadují kontakt v CRM ani projekt.

{
"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"]
}]
}
}]
}

Po schválení použít publishMode: "now" a scheduledAt: null k publikování. Každá varianta kanálu obsahuje kompletní text, nastavení a seřazená ID médií. Zjištění kanálů vrací podporované formáty, limity a nastavení. Aktuálně jsou podporovány profily a stránky LinkedIn, Facebook, Instagram a Threads. Instagram vyžaduje média. Varianta přijímá až deset obrázků nebo videí.

Dávky přijímají až 100 jedinečných externích ID v rámci stávajícího limitu požadavku 1 MiB. mode: "validate" kontroluje reference a verze bez ukládání konceptů, nahrávání assetů, vytváření oznámení nebo zařazování úloh do fronty. Výsledky aplikace obsahují ID, odkazy na kontrolu, verze a výsledky pro jednotlivé záznamy. Částečná selhání nevracejí úspěšně zpracované sourozící záznamy. Selhání oznámení vrací varování s uloženou URL ke kontrole.

Před úpravou čekajícího konceptu načíst aktuální draftVersion. Totožná opakování jsou idempotentní a zachovávají pozdější ruční úpravy. Kontrolující osoby nelze změnit přímo. Po schválení nebo zamítnutí použít pro další návrh nové externí ID. Čtení konceptů je omezeno na volající integraci; historie publikování zahrnuje všechny uložené kampaně vytvořené v Scoutello v organizaci, včetně příspěvků z řídicího panelu, skriptu a staršího Scoutello. Neimportuje externí historii kanálů.

Seznamy používají standardní parametry limit, cursor a updatedSince. Příspěvky a koncepty také přijímají channelId, status, after, before a search; zachovat všechny filtry na následujících stránkách kurzoru. Filtry data se vztahují k času publikování (u čekajících konceptů k času vytvoření). Filtry konceptů status filtrují stav schválení; status příspěvku odpovídá stavu doručení kampaně nebo kanálu. Čtení zpřístupňuje poslední známý stav doručení, selhání jednotlivých kanálů, veřejné odkazy a časová razítka sladění. Přírůstková čtení konceptů také odrážejí změny v doručení kampaní.

Nahrát média​

  1. Zavolejte POST /social-media/uploads s parametry clientUploadId, filename,
    contentType, size v bajtech a s malými hexadecimálními znaky sha256
    původních bajtů. Podporované typy jsou PNG, JPEG, WebP, MP4, WebM, QuickTime a
    M4V. Limit velikosti nahrávání je 500 MiB.
  2. Odešlete původní bajty metodou HTTP PUT na vrácenou adresu upload.url a použijte
    její hlavičky. Platnost adres pro nahrávání vyprší po 15 minutách. Pro opakované pokusy se stejným souborem použijte
    clientUploadId; relace s prošlou platností nebo jiné soubory vyžadují nové ID.
  3. Zavolejte POST /social-media/uploads/{assetId}/finalize s JSON tělem {}.
    Finalizace ověří velikost, typ, podpis a kontrolní součet, zmrazí soukromou kopii
    a vrátí ID assetu pro mediaIds. Opakovaná finalizace je bezpečná.

Vlastnictví nahrávání je svázáno s organizací a integrací. Koncepty mohou odkazovat
na finalizované assety ze své organizace. Náhledové adresy jsou dočasné; pro jejich obnovení
znovu načtěte koncept. Adresy pro nahrávání se pro finalizované objekty nikdy nevydávají.

Kontrola člověkem a doručení​

Kontrolující obdrží oznámení na nástěnce a může příspěvek otevřít v sekci Příspěvky
nebo prostřednictvím adresy pro kontrolu. Úprava vytvoří další neměnnou verzi. Schválení použije
zobrazenou verzi a hash obsahu, znovu ověří členství, kanály a assety a atomicky vytvoří
jednu trvalou kampaň. Pokud navržený čas již uplynul, kontrolující musí uložit výslovně nový čas
nebo zvolit publikování po schválení.

Opakované pokusy fronty znovu použijí kampaň a potvrzení platformy. Schválené kampaně
nelze upravovat na místě. Zrušení prostřednictvím nástěnky zachová historii schválení
i média; zrušení nemůže přerušit aktivní odesílání. Dotazujte se na koncept nebo kampaň,
abyste rozlišili schválení od skutečného doručení na platformu.