Preskočiť na hlavný obsah

Scoutello API

Scoutello API je server-to-server API na obojsmernú synchronizáciu kontaktov, úloh, protokolov, príležitostí, projektov, míľnikov a udalostí organizácie. Sprístupňuje aj históriu odchádzajúcich e-mailov iba na čítanie, vyhľadávanie členov, ktorým možno priradiť položky, a zisťovanie tagov podľa typu entity. Inkrementálne trasy GET/list a idempotentné dávkové upsert operácie sú v tejto verzii základnými mechanizmami synchronizácie. Operácie odstránenia ani webhooky nie sú k dispozícii.

Základná URL adresa API je:

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

Zobrazuje sa aj v časti Nastavenia organizácie → Vývojár/API. Dokument OpenAPI je k dispozícii na adrese:

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

Vytvorenie a zabezpečenie kľúča​

V modulárnych organizáciách musí byť okrem požadovaných oprávnení kľúča aktívny aj modul CRM. Platný kľúč nedokáže aktivovať chýbajúci modul. Požiadavky vracajú HTTP 403 s kódom chyby module_not_active, keď prístup k CRM nie je k dispozícii. Osoba s administrátorskými právami v organizácii môže skontrolovať alebo aktivovať CRM v časti Predplatné; po aktivácii prístupu skúsiť požiadavku znova.

Osoba s administrátorskými právami v organizácii môže vytvoriť integráciu a API kľúč v časti Nastavenia organizácie → Vývojár/API. Celý kľúč sa zobrazí iba raz. Pred zatvorením dialógového okna ho skopírujte do správcu tajomstiev; Scoutello už celý kľúč znova nezobrazí.

  • Pre každý externý systém a prostredie používajte samostatnú integráciu a kľúč.
  • Udeľte iba oprávnenia, ktoré daný systém potrebuje.
  • Kľúč nikdy nevkladajte do kódu v prehliadači, URL adresy, správy zdrojového kódu, logov, správ pre podporu ani úložiska na strane klienta.
  • Kľúče pravidelne obmieňajte. Pri obmene aktívnej integrácie začne náhradný kľúč fungovať okamžite a predchádzajúci kľúč zostane platný najviac 15 minút, aby externý systém mohol prejsť na nový kľúč bez výpadku. Naďalej platí pôvodný skorší dátum vypršania platnosti, takže predchádzajúci kľúč môže prestať fungovať aj skôr.
  • Ak mohol byť kľúč odhalený, pred jeho obmenou integráciu pozastavte. Pozastavenie dočasne odmietne všetky kľúče danej integrácie. Obmena počas pozastavenia nemá obdobie súbežnej platnosti: predchádzajúci kľúč zostane deaktivovaný a náhradný kľúč zostane deaktivovaný až do obnovenia integrácie.
  • Pri odpájaní externého systému natrvalo zrušte celú integráciu. Zrušenie deaktivuje všetky jej kľúče a nedá sa vrátiť späť.

Kľúč odosielajte pri každej overenej požiadavke:

Authorization: Bearer YOUR_API_KEY

Preferované je overovanie pomocou Bearer. Klienti, ktorí nedokážu nastaviť Authorization, môžu namiesto toho použiť x-api-key. Neodosielajte obe hlavičky; požiadavky s odlišnými hodnotami v oboch hlavičkách sú odmietnuté.

API je určené pre backendových klientov a nepovoľuje prístup z prehliadača medzi rôznymi zdrojmi.

Po nastavení kľúča použite GET /whoami na overenie integrácie, organizácie, oprávnení a limitov kľúča bez získania osobných údajov používateľov.

Oprávnenia​

RozsahUmožňuje
contacts.readZobrazovať zoznam kontaktov a získavať ich údaje. Kontakty účtu organizácie a kontakty členov s oprávneniami na prístup sú vylúčené.
contacts.writeOverovať a uplatňovať upserty kontaktov.
tasks.readZobrazovať zoznam neverejných úloh a získavať ich údaje.
tasks.writeOverovať a uplatňovať upserty úloh.
protocols.readZobrazovať zoznam neverejných protokolov a získavať ich údaje.
protocols.writeOverovať a uplatňovať upserty protokolov.
opportunities.readZobrazovať zoznam príležitostí a získavať ich údaje.
opportunities.writeOverovať a uplatňovať upserty príležitostí.
projects.readZobrazovať zoznam projektov a získavať ich údaje.
projects.writeOverovať a uplatňovať upserty projektov a účastníkov.
milestones.readZobrazovať zoznam míľnikov projektov a získavať ich údaje.
milestones.writeOverovať a uplatňovať upserty míľnikov.
members.readZobrazovať zoznam prijatých členov iba s ID zákazníka člena, ID používateľa a zobrazovaným menom.
events.readZobrazovať zoznam udalostí a základných plánov a získavať ich údaje.
events.writeOverovať a uplatňovať upserty udalostí.
mails.readČítať históriu odoslanej a neúspešnej odchádzajúcej pošty vo vlastníctve organizácie.
mail-drafts.readČítať samostatné návrhy e-mailov na schválenie a stav doručenia tejto integrácie.
mail-drafts.writePripravovať alebo upravovať návrhy e-mailov na schválenie osobou; nikdy ich neschvaľovať ani odosielať.
tags.readVyhľadávať dostupné značky pre podporované typy entít.

Súkromné úlohy a protokoly toto API nikdy nevracia. Chýbajúci rozsah spôsobí chybu autorizácie; nepovažuje sa za prázdny výsledok.

Kontakt v CRM, ktorý nie je členom, možno čítať a odkazovať naň aj v prípade, že je prepojený s prihlásením do Scoutello. Odpoveď obsahuje iba polia CRM organizácie, nikdy nie identitu používateľa ani polia súvisiace s prístupom. Kontakty s rolou, oprávneniami, pozvánkou, prijatím alebo stavom účtu organizácie zostávajú skryté. Úprava kontaktu prepojeného s prihlásením zostáva zakázaná (protected_contact) vrátane inak nezmenených polí CRM. Ak chcete v úlohe/protokole odkázať na existujúci čitateľný kontakt, contacts.write môže vytvoriť jeho externé prepojenie iba pomocou externalId, scoutelloId a voliteľného externalUpdatedAt. Neskoršie aktualizácie obsahujúce iba metadáta prepojenia používajú externalId a voliteľný externalUpdatedAt; po prepojení vynechať zavádzací scoutelloId. Týmto sa kontakt ani jeho používateľ nikdy nezmení. Priradenie prijatého člena používa samostatnú projekciu members.read.

Nové kľúče používajú prefix sctl_api_ a začínajú iba s contacts.write. Každý ďalší rozsah je explicitné povolenie, ktoré musí administrátor organizácie udeliť pri vytváraní alebo rotácii kľúča. Existujúce prihlasovacie údaje si zachovávajú aktuálne rozsahy a zostávajú platné.

Kontakty prepojené s projektom a koncepty e-mailov​

Operácie upsert kontaktov prijímajú voliteľné dvojice projectScoutelloId / projectExternalId a companyScoutelloId / companyExternalId (z každej dvojice vyberte jednu možnosť). Kontakt, vzťah so spoločnosťou a členstvo v projekte sa pre každú položku uložia atómovo. Pridanie členstva v projekte vyžaduje projects.write; vynechané odkazy zachovajú ostatné vzťahy a členstvá. Pri načítaní podrobností kontaktu sa zahrnie projectParticipations, ak je udelený projects.read. Agenti pre obchodné projekty musia odkaz na projekt uviesť explicitne, aj pri opätovnom použití kontaktu.

Samostatné koncepty používajú existujúci systém schvaľovania osobou bez spustenia pracovného postupu:

MetódaCestaÚčel
GET/mail-draftsKoncepty vlastnené integráciou s podporou stránkovania; voliteľné filtre projectScoutelloId a status.
GET/mail-drafts/{scoutelloId}Aktuálna verzia, odkaz na kontrolu, hash obsahu, stav schválenia/odoslania a prípadné ID e-mailu.
GET/mail-drafts/external/{externalId}Vyhľadanie stabilného externého ID integrácie.
POST/mail-drafts/batch-upsertOverenie alebo použitie prípravy konceptu.

Príprava konceptu vyžaduje mail-drafts.write, contacts.read a projects.write. Odkazovaný kontakt sa stane účastníkom projektu. Schvaľujúca osoba musí byť prijatým členom organizácie s oprávnením upravovať e-maily. Výber odosielateľa používa existujúce povolené nastavenia organizácie alebo osobného odosielateľa daného člena; ľubovoľné adresy v poli From nie sú akceptované.

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

Pred opakovaním pomocou mode: "apply" skontrolujte každý výsledok overenia. Načítaním výsledného ID získate reviewUrl, draftVersion, contentHash, status, dispatchStatus a mailScoutelloId. expectedVersion: 0 používajte iba na vytvorenie a pri úpravách použite aktuálnu vrátenú verziu. Kontext a schvaľujúca osoba sú nemenné; pri konceptoch, ktoré už boli skontrolované alebo odoslané, sa zmenený obsah odmietne. Identické opakované požiadavky vrátia pôvodný koncept.

Koncepty sa zobrazujú na kartách E-mail projektu/kontaktu a v upozorneniach na schválenie na dashboarde. Príprava prostredníctvom API neposiela žiadne e-maily vrátane e-mailových upozornení; existujúce správanie e-mailových upozornení vo workflow zostáva nezmenené. Poverená osoba môže upraviť príjemcov, predmet, telo správy a podporované prílohy, uložiť verziu a následne vybrať Schváliť a odoslať. Integrácie nemôžu vykonať schválenie ani odoslanie. Neúspešné alebo nejednoznačné doručenie sa nikdy automaticky neopakuje bez overenia. Pri konverzii konceptov založených na protokoloch zachovajte protokoly a uveďte krížové odkazy na ich náhrady.

Prístup MCP​

S rovnakým kľúčom API Scoutello a rovnakými rozsahmi možno používať streamovateľný HTTP endpoint MCP:

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

Nakonfigurujte klienta MCP tak, aby odosielal Authorization: Bearer YOUR_API_KEY. Staršia adresa URL /api/mcp zostáva aliasom cesty na zachovanie kompatibility, no noví klienti by mali používať verzovaný endpoint. Pôvodné poverenia sctl_mcp_ sa neprijímajú; nahraďte ich integračným kľúčom API Scoutello.

Nástroje MCP priamo zodpovedajú zmluve REST a používajú rovnaké runtime schémy, kontroly tenanta, životný cyklus integrácie, limity požiadaviek a servisné metódy. Napríklad contacts_list, contacts_get, contacts_get_by_external_id a contacts_batch_upsert zodpovedajú štyrom trasám kontaktov. Rovnaký princíp platí pre úlohy, protokoly, príležitosti, projekty, míľniky a udalosti; pošta sprístupňuje mails_list a mails_get, členovia sprístupňujú members_list a značky sprístupňujú tags_list.

Server zverejňuje iba nástroje povolené rozsahmi aktuálneho kľúča. Kľúč s rozsahom contacts.read môže objavovať nástroje na čítanie kontaktov, ale nie contacts_batch_upsert; kľúč s rozsahom contacts.write získava nástroj na hromadné upsertovanie, ale nie nástroje na čítanie. whoami je vždy k dispozícii. Nástroje na zápis majú rovnaké okamžité účinky ako ich ekvivalenty REST, preto použite mode: "validate", keď má volajúca strana skontrolovať dávku bez jej aplikovania.

MCP funguje tiež medzi servermi a nepovoľuje prístup z prehliadača medzi rôznymi pôvodmi. Jeho prenos JSON-RPC vyžaduje vyhradenú URL, preto nemôže zdieľať individuálnu URL zdroja REST, hoci autentifikácia a správanie údajov sú spoločné.

Kompletné pokyny na konfiguráciu klienta, overenie, mapovanie nástrojov a riešenie problémov nájdete v sprievodcovi integráciou MCP.

Čítanie záznamov​

Kontakty, úlohy, protokoly, príležitosti, projekty, míľniky a udalosti používajú rovnaké trasy na čítanie:

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

Nahraďte contacts hodnotou tasks, protocols, opportunities, projects, milestones alebo events pre ostatné synchronizačné zdroje. externalId sa zobrazí v DTO na čítanie, keď bol záznam prepojený touto integráciou.

Odpoveď zoznamu má tento obal:

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

limit musí byť v rozsahu od 1 do 100. Výsledky sú zoradené podľa efektívneho času, keď sa zmenila ich verejná reprezentácia API, a následne podľa ID Scoutello. Tento efektívny čas môže byť neskorší než vrátená entita updatedAt, ak sa zmenili metadáta integračného prepojenia. Kurzory sú nepriehľadné: ukladajte ich a odosielajte bez zmien a nevyvodzujte význam z ich obsahu.

Prvá odpoveď určuje snapshotAt pre daný prechod. Postupujte podľa nextCursor, kým hasMore nebude mať hodnotu false, a až potom začnite ďalšie inkrementálne čítanie. Tým sa zabráni tomu, aby zmeny záznamov počas stránkovania narušili stabilitu aktuálneho prechodu.

Pri inkrementálnej synchronizácii spracujte každú stránku kurzora a potom uložte snapshotAt daného prechodu ako hornú hranicu časovej pečiatky. V ďalšom prechode ju odošlite ako hodnotu updatedSince vo formáte ISO 8601. Dolná hranica je inkluzívna, takže opakovanie dokončenej snímky môže vrátiť hraničné záznamy, ale nemôže ich preskočiť.

Odpoveď jedného záznamu má tento obal:

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

Odpovede pre jeden kontakt obsahujú aj pole relations. Každý vzťah zachováva svoje ID vzťahu Scoutello, čas vytvorenia, typ, poznámky a odkazy na kontakty connectedFrom a connectedTo. Odkazy na kontakty obsahujú ID Scoutello a externé ID tejto integrácie, ak existuje. Kontakty vylúčené z dôvodu ochrany súkromia na hranici prístupu organizácie cez API sa vo vzťahoch nezobrazujú. Odpoveď zoznamu kontaktov zostáva kompaktná a neobsahuje vzťahy; ak sú potrebné podrobnosti o vzťahu, použite jednu z trás pre jednotlivé kontakty.

Pracovné filtre a rozsah kurzora​

Zoznamy kontaktov prijímajú search, type (person, company, supplier, other), status a tagIds. Vyhľadávanie odstraňuje okolité medzery, nerozlišuje veľké a malé písmená a je obmedzené na 200 znakov / 10 tokenov oddelených medzerami. Každý token sa musí nachádzať aspoň v jednom z polí firstName, lastName alebo companyName vrátane starších názvov spoločností uložených v lastName. Znaky ako % a _ sa porovnávajú doslovne. Značky používajú porovnávanie any-of s 1 až 50 ID. Všetky zadané filtre sa kombinujú pomocou AND. REST kóduje ID značiek ako opakované parametre; MCP poskytuje pole:

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

Kurzory kontaktov sú viazané na organizáciu, integráciu a každý filter. Filtre ponechávajte na každej stránke; zmena filtra spôsobí odmietnutie kurzora. Poradie a duplicity značiek ani poradie, veľkosť písmen či medzery medzi tokenmi vyhľadávania nemenia efektívny filter.

Trasy zoznamu práce akceptujú nasledujúce dodatočné filtre; ostatné kombinácie zdrojov a polí sú zamietnuté:

ZdrojFiltre
ÚlohyprojectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter
ProtokolyprojectScoutelloId, milestoneScoutelloId, status (draft alebo final)
PríležitostiprojectScoutelloId, stage, ownerScoutelloUserId
Projektystatus, assignedContactScoutelloId
MilníkyprojectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter

dueBefore je výhradný; dueAfter je vrátane hranice. Porovnávajú termín dokončenia úlohy alebo dátum ukončenia milníka; záznamy bez príslušného dátumu sa nezhodujú. Zadávajte časové údaje ISO s uvedeným časovým pásmom. Všetky filtre sa uplatňujú pred stránkovaním. Pokračovanie pomocou kurzora vyžaduje presne tie isté filtre vrátane updatedSince a rovnakú organizáciu/integráciu. Veľkosť stránky sa môže zmeniť. Staré kurzory bez rozsahu treba po tomto vydaní spustiť znova od uloženého najvyššieho časového údaja.

Projekty, milníky, priradenia a poznámky​

GET /members (MCP members_list) používa štandardné stránkovanie a vyžaduje members.read. Vracia scoutelloId (ID člena Customer), scoutelloUserId (ID User) a displayName. Zobrazia sa iba prijatí členovia organizácie s pridelenou rolou; vyhľadávanie nesprístupňuje e-mailové adresy ani povolenia.

Úlohy akceptujú assignedScoutelloUserIds; príležitosti používajú ownerScoutelloUserId. Projekty a milníky používajú assignedContacts: [{"scoutelloId":"member-customer-id"}]. Priradenia vyžadujú prijatých členov organizácie patriacej k povereniu. Vynechané priradenia zostávajú nezmenené; [] ich vymaže. Importy projektov, milníkov, úloh a protokolov prebiehajú bez upozornení: neposielajú upozornenia ani inú komunikáciu súvisiacu s priradeniami.

Udalosť assignedContacts podporuje čitateľné CRM kontakty a prijatých členov zadaných pomocou ID člena Customer. Prijatí členovia zostávajú nedostupní ako bežné odkazy na CRM kontakty alebo ciele externých odkazov; na určenie zodpovednosti v tíme použite pole priradenia člena.

Vytvárajte míľniky pomocou name a buď projectScoutelloId, alebo projectExternalId. Podporujú description (Markdown), status (open, in_progress, completed, closed), startDate/endDate s možnosťou null, order (predvolene 0) a assignedContacts. Dátum ukončenia nesmie predchádzať dátumu začatia. Každý míľnik má stabilný externý odkaz platný v rámci integrácie. Jeho projekt nie je možné zmeniť prostredníctvom API. Vytváranie a aktualizácia lokalizujú názov a popis do jazyka organizácie.

Úlohy a protokoly prijímajú odkazy na projekty, míľniky a príležitosti ako <entity>ScoutelloId alebo <entity>ExternalId, napríklad milestoneExternalId. Pre každý vzťah uveďte iba jeden zápis, a to aj pri jeho vymazávaní pomocou null. Všetky vzťahy musia patriť do organizácie priradenej povereniu. Odkaz iba na míľnik odvodí projekt; konfliktný projekt alebo explicitné vymazanie projektu pri zachovaní jeho míľnika bude zamietnuté. Prepojená príležitosť s projektom musí zodpovedať projektu práce. Neuvedené vzťahy zachovávajú aktuálne hodnoty; explicitný null vymaže vzťah, ak je zostávajúci kontext platný. Odpovede obsahujú oba zápisy identifikátorov a priradenia úloh.

Plánovanie úloh a pracovné postupy​

status úlohy je nemenný kľúč stavu v efektívnom pracovnom postupe úlohy, nie pevne stanovená hodnota enumu. Dostupné pracovné postupy organizácie a projektu načítate pomocou GET /task-workflows s rozsahom tasks.read. Každý stav obsahuje svoj kľúč, označenie, životný cyklus type (backlog, unstarted, started, completed alebo cancelled), farbu, poradie, príznak predvoleného stavu a stav archivácie. Záznamy projektu uvádzajú, či sa dedí pracovný postup organizácie. Konfigurácia pracovných postupov zostáva spravovaná v dashboarde.

Úlohy prijímajú priority s možnosťou null (low, medium, high alebo urgent) a estimatedEffortMinutes, ako aj startDate a dueDate s možnosťou null. Odpovede úloh obsahujú denormalizovaný statusType, odkaz na nadradenú úlohu, kompaktné odkazy na podúlohy a odkazy blockedBy / blocks.

Vytvorenie alebo aktualizácia podúlohy na jednej úrovni pomocou parentTaskScoutelloId alebo parentTaskExternalId; null ju povýši na úlohu najvyššej úrovne. Závislosti používajú polia obsahujúce referencie { "scoutelloId": "..." } alebo { "externalId": "..." } v blockedBy a blocks. Vynechané polia vzťahov zachovajú existujúce hodnoty, zatiaľ čo prázdne pole závislostí zruší príslušný smer. API odmieta vnorené podúlohy, závislosti medzi nadradenou a podriadenou úlohou, závislosti medzi organizáciami, duplicity, odkazy na seba samú aj priame alebo tranzitívne cykly.

Filtre zoznamu úloh prijímajú presný pracovný postup status, životný cyklus statusType, priority, parentState (top_level, subtask alebo parent) a blockedState (blocked, blocking alebo unblocked).

Protokoly navyše prijímajú status: "draft" | "final" (nové záznamy majú predvolene final). Nový protokol vyžaduje type, date a buď kontakt, alebo platný kontext projektu/míľnika. contactExternalId: null vymaže kontakt iba vtedy, keď zostane zachovaný kontext projektu/míľnika. Interné poznámky k projektu tak možno vytvárať a čítať bez vymýšľania zákazníka. Označenie konceptu/konečnej verzie opisuje stav poznámky a nikdy neodošle komunikáciu. Súkromné úlohy a protokoly zostávajú neprístupné.

Účastníci projektu​

participants projektu obsahuje dopĺňané upserty identifikované referenciou contact, naprí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 predstavujú potenciálnych zákazníkov/zákazníkov spojených s projektom; zodpovedné osoby sa určujú prostredníctvom priradení. Vynechaní účastníci, prázdne pole a vynechané polia účastníkov zachovajú existujúce údaje. null vymaže role, notes alebo groupScoutelloId. Duplicitné vyriešené kontakty v jednom dátovom obsahu sa odmietnu. Skupiny už musia patriť k vybranému projektu; načítané údaje obsahujú participantGroups (ID/názov), ID účastníkov, kontakty, rolu, poznámky a ID skupiny. Odstránenie účastníkov alebo vytváranie skupín je momentálne dostupné na dashboarde.

Hromadný upsert záznamov​

Pomocou hromadnej trasy zdroja možno zapísať až 100 záznamov:

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

Hromadné operácie s úlohami najprv vyriešia záznamy úloh a až potom použijú vzťahy nadradenosti a závislostí. Toto dvojfázové spracovanie umožňuje, aby nadradená úloha, blokujúca úloha alebo blokovaná úloha odkazovala na inú úlohu vytvorenú v tej istej hromadnej operácii pomocou jej externého ID bez ohľadu na poradie záznamov.

Pre polia a validačné obmedzenia jednotlivých zdrojov použite dokument OpenAPI. Každý záznam musí obsahovať stabilný externalId s dĺžkou od 1 do 200 znakov. Zaobchádzajte s ním ako s nepriehľadným technickým identifikátorom: nepoužívajte e-mailovú adresu, meno, tajný kľúč API ani iné osobné údaje. externalUpdatedAt je voliteľný, no dôrazne odporúčaný, keď zdrojový systém poskytuje spoľahlivú časovú pečiatku zmeny.

Telo požiadavky je obmedzené na 1 MiB. mode má predvolenú hodnotu apply:

  • apply overí a zapíše prijaté záznamy.
  • validate vykoná rovnaké overenie a párovanie bez zápisu a vráti výsledky would_*.

Pri importe kontaktov možno v požiadavke nastaviť matchByEmail na true. Predvolená hodnota je false; externé ID predstavuje bezpečnejšiu hranicu identity.

Vynechané polia zachovajú aktuálnu hodnotu. Explicitné null vymaže pole s povolenou hodnotou null a prázdne pole priradení/značiek vymaže daný vzťah. Projektové participants sú aditívne upserty: prázdne pole ponechá zoznam nezmenený. Zápisy značiek pri kontaktoch, úlohách, príležitostiach a udalostiach používajú ID značiek Scoutello. Externé ID vzťahov sa vyhľadávajú iba prostredníctvom prepojení patriacich aktuálnej integrácii, zatiaľ čo ID používateľov Scoutello použité na vlastníctvo alebo zodpovednosť musia identifikovať schválené členstvo v aktuálnej organizácii.

Pri vytváraní príležitosti je potrebný účet alebo kontakt a pri stratených príležitostiach aj dôvod straty. Peňažné sumy sa uvádzajú v celých centoch. Názvy a opisy projektov a udalostí sa čítajú a zapisujú v jazyku nastavenom pre organizáciu. Zápisy udalostí podporujú konkrétne dátumy a denné, týždenné alebo mesačné opakovanie s výnimkami; úrovne viditeľnosti zverejnených udalostí naďalej podliehajú kontrolám právnej pripravenosti Scoutello. API neposkytuje funkcie predaja vstupeniek na udalosti, účastníkov, médií, šablón, newsletterov, spoluprác ani iných pokročilých ovládacích prvkov správy udalostí.

Vyhľadanie značiek​

Pred zadaním tagIds použite endpoint značiek:

GET /tags?entity=events&type=category

entity je povinné a prijíma hodnoty contacts, tasks, opportunities alebo events. Mapuje sa na príslušnú uloženú relevanciu značky. type je voliteľné a prijíma hodnotu category alebo attribute. Vyberateľné kategórie môžu patriť organizácii alebo byť globálne; vyberateľné atribúty pochádzajú z globálnej, kurátorovanej množiny atribútov Scoutello. Výsledky obsahujú scoutelloId, názov lokalizovaný do jazyka organizácie, type a relevancy. ID značiek patriace inej organizácii, s nesprávnou relevanciou alebo nevyberateľné ID značiek zamietnu príslušnú položku dávky.

Čítanie histórie odoslanej pošty​

História pošty je len na čítanie:

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

Vracajú sa iba správy patriace organizácii so stavom sent alebo failed. Odpovede obsahujú bežné uložené hlavičky a telo správy, skrytú kópiu (BCC), stav a časové pečiatky, odkazy na projekty/udalosti/newslettery, ID a typy príloh a súhrnné štatistiky doručenia, otvorení, kliknutí, nedoručení, sťažností a odmietnutí podľa príjemcov. Koncepty, správy vo fronte alebo naplánované správy, údaje po jednotlivých príjemcoch, vykreslené náhľady, nespracované chyby poskytovateľa a URL na stiahnutie príloh sa nikdy nesprístupňujú. Neskoršia aktualizácia doručenia príjemcovi posunie efektívnu časovú pečiatku synchronizácie správy, takže sa správa znova objaví v prírastkových načítaniach. Trasy na zápis pošty neexistujú.

Výsledok použitia môže byť created, updated, linked, unchanged, stale_ignored alebo rejected. Pri overovaní sa používajú would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale alebo rejected. Platná dávková požiadavka vráti HTTP 200 aj vtedy, keď sú jednotlivé záznamy zamietnuté, preto vždy skontrolovať každú položku aj súhrn odpovede. Pri žiadosti o preskúmanie zlyhania podporou Scoutello ponechať odpoveď requestId.

Časové pečiatky a konflikty​

Ak je prítomné externalUpdatedAt, Scoutello ho použije na odmietnutie zastaraných zmien bez zlyhania zvyšku dávky. Výsledok stale_ignored je pre staršie údaje konečný; pred rozhodnutím o odoslaní novšej verzie načítať aktuálny záznam.

Časové pečiatky považovať za hodnoty UTC vo formáte ISO 8601. Zachovať ich pôvodnú presnosť a nenahrádzať časom spustenia synchronizačnej úlohy čas úpravy zdrojového záznamu.

Idempotencia​

Hranicu idempotencie tvorí integrácia a externalId. Scoutello porovnáva kanonický hash dát a voliteľnú hodnotu externalUpdatedAt, takže opakované odoslanie rovnakého záznamu nevytvorí duplicity a môže vrátiť unchanged.

Pri externalUpdatedAt je rovnaká časová pečiatka a obsah unchanged, staršia časová pečiatka stale_ignored a rovnaká časová pečiatka s odlišným obsahom predstavuje konflikt verzií. Pri prepojení, ktoré nikdy neprijalo časovú pečiatku, zostáva obsah bez časovej pečiatky pri nezmenenom obsahu unchanged, zatiaľ čo zmenený obsah sa použije v poradí príchodu. Po prijatí časovej pečiatky prepojením sa zmenený obsah bez externalUpdatedAt odmietne ako konflikt verzií, aby údaje bez verzie nemohli prepísať stav s verziou. Preto sa časové pečiatky úprav v zdroji dôrazne odporúčajú.

Auditná stopa​

Prijaté akcie API na vytváranie, aktualizáciu a synchronizáciu iba odkazov sa zobrazujú v changelogoch Scoutello so zdrojom Public API a sú prepojené s príslušnou integráciou. Súhrny prevádzkových behov uchovávajú ID požiadaviek a agregované počty výsledkov na účely riešenia problémov; neuchovávajú dátové obsahy záznamov ani tajné kľúče API.

Chyby a opakovanie požiadaviek​

Chyby na úrovni požiadaviek používajú túto obálku:

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

Pri odpovediach HTTP 429 a dočasných odpovediach 5xx použite exponenciálne oneskorenie s náhodným rozptylom. Ak je prítomné Retry-After, rešpektujte ho. Sieťové zlyhania mohli nastať až po prijatí požiadavky systémom Scoutello; opätovné odoslanie rovnakej dávky je bezpečné, pretože každý záznam je idempotentný podľa externého ID a kanonického dátového obsahu. Bez zmeny požiadavky automaticky neopakujte požiadavky s chybami autentifikácie, oprávnení, validácie, konfliktu verzií ani jednotlivé výsledky rejected.

Odporúčaný cyklus obojsmernej synchronizácie​

  1. Počas nastavovania zavolajte /whoami a overte očakávanú organizáciu a rozsahy oprávnení.
  2. Načítajte každú stránku zmenenú od poslednej dokončenej hornej hranice a aplikujte tieto zmeny v externom systéme idempotentne.
  3. Externé zmeny odošlite do /batch-upsert s použitím stabilných externých ID a časových pečiatok úprav zo zdrojového systému.
  4. Kontrolné body uložte až po spracovaní všetkých stránok a výsledkov jednotlivých položiek.
  5. Konflikty riešte podľa pravidiel vlastníctva zdrojového systému; neimitujte mazanie odosielaním prázdnych záznamov.

Scoutello v tejto prvej verzii zámerne neposkytuje verejnú trasu na mazanie. Pravidlá mazania alebo archivácie riešte mimo API, kým nebude zavedená zdokumentovaná operácia životného cyklu.

Príspevky na sociálne siete na kontrolu osobou​

Sociálne API pripravuje príspevky pre konkrétnu osobu poverenú kontrolou. Nedokáže ich schváliť ani publikovať. REST a MCP používajú rovnaké rozsahy oprávnení a službu.

Rozsah oprávnení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ávnení je potrebné udeliť explicitne. Existujúce prihlasovacie údaje nezískajú žiadny ďalší prístup. Použite members.read na zistenie ID používateľov v členskom zozname a vyberte osobu poverenú kontrolou s oprávnením na publikovanie (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"]
}]
}
}]
}

Na publikovanie po schválení použite publishMode: "now" a scheduledAt: null. Každý variant kanála obsahuje kompletný text, nastavenia a zoradené ID médií. Vyhľadávanie kanálov vráti podporované formáty, limity a nastavenia. V súčasnosti sú podporované kanály profily a stránky LinkedIn, Facebook, Instagram a Threads. Instagram vyžaduje médiá. Variant môže obsahovať najviac desať obrázkov alebo videí.

Dávky môžu obsahovať najviac 100 jedinečných externých ID v rámci existujúceho limitu 1 MiB pre požiadavku. mode: "validate" kontroluje referencie a verzie bez ukladania konceptov, nahrávania prostriedkov, vytvárania upozornení alebo zaraďovania úloh do frontu. Výsledky použitia obsahujú ID, odkazy na kontrolu, verzie a výsledky pre jednotlivé záznamy. Čiastočné zlyhania nevracajú späť úspešné susediace operácie. Zlyhanie upozornenia vráti varovanie s uloženou URL adresou kontroly.

Pred úpravou čakajúceho konceptu načítajte aktuálny draftVersion. Identické opakované požiadavky sú idempotentné a zachovávajú neskoršie manuálne úpravy. Kontrolujúcich nie je možné meniť priamo. Po schválení alebo zamietnutí použite pre ďalší návrh nové externé ID. Čítanie konceptov je obmedzené na integračné riešenie, ktoré požiadavku odoslalo; história publikovania zahŕňa všetky pretrvávajúce kampane vytvorené v Scoutello v rámci organizácie vrátane príspevkov z nástenky, skriptu a staršieho Scoutello. História externých kanálov sa neimportuje.

Zoznamy používajú štandardné parametre limit, cursor a updatedSince. Príspevky a koncepty tiež prijímajú channelId, status, after, before a search; všetky filtre zachovajte aj na nasledujúcich stránkach kurzora. Filtre dátumov sa vzťahujú na čas publikovania (na čas vytvorenia v prípade čakajúcich konceptov s okamžitým publikovaním). Filter konceptov status filtruje stav schválenia; filter príspevkov status zodpovedá stavu doručenia kampane alebo kanála. Načítania zobrazujú posledný známy stav doručenia, zlyhania jednotlivých kanálov, verejné odkazy a časové pečiatky zosúladenia. Prírastkové načítania konceptov tiež odrážajú zmeny v doručovaní kampane.

Nahrať médiá​

  1. Zavolajte POST /social-media/uploads s parametrami clientUploadId, filename, contentType, size v bajtoch a sha256 pôvodných bajtov v hexadecimálnom formáte s malými písmenami. Podporované typy sú PNG, JPEG, WebP, MP4, WebM, QuickTime a M4V. Maximálna veľkosť nahrávaného súboru je 500 MiB.
  2. Odošlite pôvodné bajty pomocou HTTP PUT na vrátenú adresu upload.url a použite jej hlavičky. Platnosť nahrávacích adries je 15 minút. Pri opakovaní nahrávania toho istého súboru znova použite clientUploadId; po uplynutí platnosti relácie alebo pri inom súbore je potrebné nové ID.
  3. Zavolajte POST /social-media/uploads/{assetId}/finalize s telom JSON obsahujúcim {}. Finalizácia overí veľkosť, typ, podpis a kontrolný súčet, uzamkne súkromnú kópiu a vráti ID aktíva pre mediaIds. Opakovaná finalizácia je bezpečná.

Vlastníctvo nahrávania je viazané na organizáciu a integráciu. Koncepty môžu odkazovať na finalizované aktíva zo svojej organizácie. Adresy URL náhľadov sú dočasné; na ich obnovenie znova načítajte koncept. Adresy URL na nahrávanie sa pre finalizované objekty nikdy nevydávajú.

Kontrola osobou a doručenie​

Kontrolujúcej osobe sa zobrazí oznámenie na nástenke a príspevok môže otvoriť v časti Postings alebo prostredníctvom adresy URL na kontrolu. Úprava vytvorí ďalšiu nemennú verziu. Schválenie používa zobrazenú verziu a hash obsahu, znova overí členstvo, kanály a aktíva a atómovo vytvorí jednu trvalú kampaň. Ak navrhovaný čas už uplynul, kontrolujúca osoba musí uložiť nový konkrétny čas alebo vybrať publikovanie po schválení.

Opakované pokusy vo fronte znova použijú kampaň a potvrdenia platformy. Schválené kampane nie je možné upravovať priamo. Zrušenie prostredníctvom nástenky zachová históriu schválení aj médiá; zrušenie nemôže prerušiť aktívne odosielanie. Na rozlíšenie schválenia od skutočného doručenia na platformu načítajte koncept alebo kampaň.