Scoutello API
A Scoutello API szerverek közötti API, amely lehetővé teszi egy szervezet kapcsolatainak, feladatainak, jegyzőkönyveinek, lehetőségeinek, projektjeinek, mérföldköveinek és eseményeinek kétirányú szinkronizálását. Emellett csak olvasásra elérhető kimenőlevél-előzményeket, hozzárendelhető tagok keresését és entitásalapú címkefelderítést is biztosít. A növekményes GET/list útvonalak és az idempotens kötegelt upsert műveletek jelentik a szinkronizálás alapját ebben a verzióban. Törlési műveletek és webhookok nem érhetők el.
Az API alap-URL-je:
https://admin.scoutello.com/api/v1
Ez az Szervezeti beállítások → Fejlesztői/API részen is megjelenik. Az OpenAPI-dokumentum itt érhető el:
https://admin.scoutello.com/api/v1/openapi.json
Kulcs létrehozása és védelme
Moduláris szervezetek esetén a kulcshoz szükséges hatókörökön felül a CRM-modulnak is aktívnak kell lennie. Érvényes kulccsal sem aktiválható hiányzó modul. A kérések HTTP 403-as választ adnak a module_not_active hibakóddal, ha a CRM-hozzáférés nem érhető el. A szervezeti adminisztráció a CRM állapotát a Előfizetés részen ellenőrizheti vagy aktiválhatja; a hozzáférés aktiválása után újra kell próbálni.
A szervezeti adminisztráció integrációt és API-kulcsot hozhat létre az Szervezeti beállítások → Fejlesztői/API részen. A teljes kulcs csak egyszer jelenik meg. A párbeszédablak bezárása előtt másolja egy titokkezelőbe; a Scoutello később nem tudja újra megjeleníteni a teljes kulcsot.
- Külön integrációt és kulcsot használni minden külső rendszerhez és környezethez.
- Csak az adott rendszer által szükséges hatóköröket engedélyezni.
- Kulcsot soha nem szabad böngészőkódban, URL-ben, forráskódban, naplókban, támogatási üzenetekben vagy kliensoldali tárolóban elhelyezni.
- A kulcsokat ütemezetten cserélni. Aktív integráció kulcscseréjekor az új kulcs azonnal működik, a korábbi kulcs pedig legfeljebb 15 percig marad érvényes, hogy a külső rendszer leállás nélkül átállhasson. A korábban beállított lejárat továbbra is érvényes, ezért a korábbi kulcs hamarabb is leállhat.
- Ha egy kulcs illetéktelenekhez kerülhetett, a kulcscsere előtt szüneteltetni kell az integrációt. A szüneteltetés ideiglenesen elutasítja az integráció összes kulcsát. Szüneteltetett állapotban végzett csere esetén nincs átfedési időszak: a korábbi kulcs letiltva marad, az új kulcs pedig az integráció folytatásáig letiltva marad.
- Külső rendszer leválasztásakor véglegesen vissza kell vonni a teljes integrációt. A visszavonás letiltja az összes hozzá tartozó kulcsot, és nem vonható vissza.
Minden hitelesített kérésben küldje el a kulcsot:
Authorization: Bearer YOUR_API_KEY
A Bearer-hitelesítés ajánlott. Azok az ügyfelek, amelyek nem tudják beállítani a Authorization értéket, helyette a x-api-key használhatják. A két fejlécet nem szabad egyszerre küldeni; a két fejléc eltérő értékei esetén a kérések elutasításra kerülnek.
Az API backendügyfelek számára készült, és nem engedélyezi a böngészőkből indított, keresztirányú hozzáférést.
Kulcs beállítása után használja a GET /whoami értéket az integráció, a szervezet, a hatókörök és a kulcskorlátok ellenőrzésére, felhasználói személyes adatok lekérése nélkül.
Hatókörök
| Hatókör | Engedélyezett műveletek |
|---|---|
contacts.read | Kapcsolatok listázása és lekérése. A szervezeti fiókhoz tartozó, valamint hozzáféréssel rendelkező tagok kapcsolatai ki vannak zárva. |
contacts.write | Kapcsolat-létrehozások és -frissítések ellenőrzése és alkalmazása. |
tasks.read | Nem privát feladatok listázása és lekérése. |
tasks.write | Feladat-létrehozások és -frissítések ellenőrzése és alkalmazása. |
protocols.read | Nem privát protokollok listázása és lekérése. |
protocols.write | Protokoll-létrehozások és -frissítések ellenőrzése és alkalmazása. |
opportunities.read | Lehetőségek listázása és lekérése. |
opportunities.write | Lehetőség-létrehozások és -frissítések ellenőrzése és alkalmazása. |
projects.read | Projektek listázása és lekérése. |
projects.write | Projekt- és résztvevő-létrehozások és -frissítések ellenőrzése és alkalmazása. |
milestones.read | Projektmérföldkövek listázása és lekérése. |
milestones.write | Mérföldkő-létrehozások és -frissítések ellenőrzése és alkalmazása. |
members.read | Elfogadott tagok listázása, kizárólag a tag Customer ID-azonosítójával, User ID-azonosítójával és megjelenített nevével. |
events.read | Események és alapvető ütemezések listázása és lekérése. |
events.write | Esemény-létrehozások és -frissítések ellenőrzése és alkalmazása. |
mails.read | A szervezet tulajdonában lévő kimenő levelek elküldött és sikertelen kézbesítési előzményeinek olvasása. |
mail-drafts.read | Az integráció önálló e-mail-jóváhagyási piszkozatainak és kézbesítési állapotának olvasása. |
mail-drafts.write | E-mail-piszkozatok előkészítése vagy módosítása emberi jóváhagyáshoz; jóváhagyás és küldés soha nem végezhető. |
tags.read | A támogatott entitástípusokhoz választható címkék felderítése. |
Privát feladatokat és protokollokat ez az API soha nem ad vissza. Hiányzó hatókör esetén engedélyezési hiba jelenik meg; a rendszer ezt nem kezeli üres eredményként.
Nem tag CRM-kapcsolata olvasható és hivatkozható akkor is, ha Scoutello-bejelentkezéshez van kapcsolva. A válasz kizárólag a szervezet CRM-mezőit tartalmazza, a User-identitást és a hozzáférési mezőket soha. A szerepkörrel, jogosultságokkal, meghívással, elfogadással vagy szervezeti fiókállapottal rendelkező kapcsolatok rejtve maradnak. A bejelentkezéshez kapcsolt kapcsolat szerkesztése továbbra is tiltott (protected_contact), beleértve az egyébként változatlan CRM-mezőket is. Egy meglévő, olvasható kapcsolat feladathoz vagy protokollhoz való hivatkozásához a contacts.write csak a externalId, a scoutelloId és opcionálisan a externalUpdatedAt megadásával hozhatja létre a külső kapcsolatot. A későbbi, kizárólag a kapcsolati metaadatokat érintő frissítésekhez a externalId és opcionálisan a externalUpdatedAt használható; a kapcsolás után a rendszerből elhagyható a kezdeti scoutelloId. Ez soha nem módosítja a kapcsolatot vagy a hozzá tartozó Usert. Az elfogadott tag hozzárendelése külön members.read leképezést használ.
Az új kulcsok az sctl_api_ előtagot használják, és kizárólag contacts.write jogosultsággal indulnak. Minden további hatókört a szervezet adminisztrációjára jogosult személynek kell kifejezetten megadnia a kulcs létrehozásakor vagy cseréjekor. A meglévő hitelesítő adatok megtartják jelenlegi hatóköreiket és érvényesek maradnak.
Projekthez kapcsolt kapcsolatok és e-mail-piszkozatok
A kapcsolat-upsert műveletek elfogadják a választható projectScoutelloId / projectExternalId és companyScoutelloId / companyExternalId párokat (páronként egyet válasszon). A kapcsolat, a vállalati kapcsolat és a projekttagság elemenként egyetlen atomi műveletben mentődik. Projekttagság hozzáadásához projects.write szükséges; a kihagyott hivatkozások megőrzik a többi kapcsolatot és tagságot. A kapcsolat részleteinek olvasása tartalmazza a projectParticipations mezőt, ha a projects.read engedélyezett. Az értékesítési projektügynököknek meglévő kapcsolat újrafelhasználásakor is kifejezetten meg kell adniuk a projekthivatkozást.
Az önálló piszkozatok a meglévő emberi jóváhagyási rendszert használják munkafolyamat-futtatás nélkül:
| Módszer | Útvonal | Cél |
|---|---|---|
| GET | /mail-drafts | Lapozható, az integráció tulajdonában álló piszkozatok; választható projectScoutelloId és status szűrők. |
| GET | /mail-drafts/{scoutelloId} | Aktuális verzió, ellenőrzési hivatkozás, tartalomhash, jóváhagyási/küldési állapot és esetleges e-mail-azonosító. |
| GET | /mail-drafts/external/{externalId} | Az integráció stabil külső azonosítójának keresése. |
| POST | /mail-drafts/batch-upsert | A piszkozat előkészítésének ellenőrzése vagy alkalmazása. |
A piszkozat előkészítéséhez mail-drafts.write, contacts.read és projects.write szükséges. A hivatkozott kapcsolat projektrésztvevővé válik. A jóváhagyó elfogadott szervezeti tag kell legyen e-mail-szerkesztési jogosultsággal. A feladó kiválasztása a tag meglévő, engedélyezett szervezeti vagy személyes feladóbeállításait használja; tetszőleges feladócím nem adható meg.
{
"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."
}
}]
}
A mode: "apply" módú ismétlés előtt ellenőrizze minden validálás eredményét. A létrejött azonosítóval olvassa vissza a reviewUrl, draftVersion, contentHash, status, dispatchStatus és mailScoutelloId értékeket. A expectedVersion: 0 csak létrehozáshoz használható; módosításkor a visszakapott aktuális verziót adja meg. A kontextus és a jóváhagyó nem változtatható; az ellenőrzött vagy elküldött piszkozatok elutasítják a módosított tartalmat. Az azonos ismétlések az eredeti piszkozatot adják vissza.
A tervezetek a projekt-/kapcsolattartói E-mail-lapokon, valamint a vezérlőpult jóváhagyási értesítéseiben jelennek meg. Az API-előkészítés nem küld e-mailt, az értesítő e-maileket is beleértve; a meglévő munkafolyamat-értesítő e-mailek működése változatlan marad. A kijelölt személy szerkesztheti a címzetteket, a tárgyat, a törzsszöveget és a támogatott mellékleteket, mentheti a verziót, majd kiválaszthatja az Approve & send lehetőséget. Az integrációk nem végezhetnek jóváhagyást és nem indíthatják el a küldést. Sikertelen vagy nem egyértelmű kézbesítés esetén a rendszer soha nem próbálkozik vakon újra. Protokollalapú tervezetek konvertálásakor meg kell őrizni a protokollokat, és kereszthivatkozással kell ellátni azok helyettesítőit.
MCP-hozzáférés
Ugyanaz a Scoutello API-kulcs és hatókörök használhatók a streamelhető HTTP MCP-végponttal is:
https://admin.scoutello.com/api/v1/mcp
Az MCP-klienst úgy kell konfigurálni, hogy Authorization: Bearer YOUR_API_KEY értéket küldjön. A régi /api/mcp URL továbbra is útvonal-kompatibilitási alias marad, az új klienseknek azonban a verziózott végpontot kell használniuk. A korábbi sctl_mcp_ hitelesítő adatok nem fogadhatók el; helyettük Scoutello API-integrációs kulcsot kell használni.
Az MCP-eszközök közvetlenül a REST-szerződéshez igazodnak, és ugyanazokat a futásidejű sémákat, bérlő-ellenőrzéseket, integrációs életciklust, sebességkorlátozást és szolgáltatásmetódusokat használják. Például a contacts_list, a contacts_get, a contacts_get_by_external_id és a contacts_batch_upsert a négy kapcsolattartói útvonalat tükrözik. Ugyanez a minta érvényes a feladatokra, protokollokra, lehetőségekre, projektekre, mérföldkövekre és eseményekre; a levelezés a mails_list és a mails_get eszközöket teszi elérhetővé, a tagok a members_list eszközt, a címkék pedig a tags_list eszközt.
A szerver csak az aktuális kulcs hatókörei által engedélyezett eszközöket hirdeti meg. A contacts.read hatókörrel rendelkező kulcs felfedezheti a kapcsolattartói olvasási eszközöket, de a contacts_batch_upsert eszközt nem; a contacts.write hatókörrel rendelkező kulcs megkapja a kötegelt felülírási eszközt, de az olvasási eszközöket nem. A whoami mindig elérhető. Az írási eszközök ugyanazokat az azonnali hatásokat váltják ki, mint a REST-megfelelőik, ezért a mode: "validate" használata javasolt, amikor a hívónak alkalmazás nélkül kell megvizsgálnia egy köteget.
Az MCP szintén szerverek közötti használatra szolgál, és nem teszi lehetővé a böngészők közötti, több eredetre kiterjedő hozzáférést. A JSON-RPC-átvitelhez dedikált URL szükséges, ezért az MCP nem oszthatja meg egy REST-erőforrás egyedi URL-jét, még akkor sem, ha a hitelesítés és az adatok kezelése közös.
A teljes ügyfélkonfigurációs, ellenőrzési, eszközleképezési és hibaelhárítási útmutatóért tekintse meg az MCP-integrációs útmutatót.
Rekordok olvasása
A kapcsolattartók, feladatok, protokollok, lehetőségek, projektek, mérföldkövek és események ugyanazokat az olvasási útvonalakat használják:
GET /contacts?limit=50&updatedSince=2026-09-01T00:00:00.000Z
GET /contacts/{scoutelloId}
GET /contacts/external/{externalId}
A többi szinkronizációs erőforrás esetében cserélje le a contacts értéket a tasks, protocols, opportunities, projects, milestones vagy events értékre. A externalId egy olvasási DTO-ban jelenik meg, amikor a rekordot ez az integráció kapcsolta össze.
Egy listaválasz burka:
{
"data": [],
"page": {
"nextCursor": null,
"hasMore": false,
"snapshotAt": "2026-09-01T12:00:00.000Z"
},
"requestId": "request-id"
}
A limit értéke 1 és 100 között lehet. Az eredmények először az alapján vannak rendezve, hogy mikor változott meg a nyilvános API-reprezentációjuk ténylegesen, majd Scoutello-azonosító szerint. Ez a tényleges időpont későbbi lehet a visszaadott entitás updatedAt értékénél, ha az integrációs hivatkozás metaadatai megváltoztak. A kurzorok átláthatatlanok: változatlanul kell tárolni és elküldeni őket, tartalmukból pedig nem szabad jelentést levezetni.
Az első válasz rögzíti a snapshotAt értékét az adott bejáráshoz. Követni kell a nextCursor értékét addig, amíg a hasMore értéke false nem lesz, és csak ezután szabad újabb inkrementális olvasást indítani. Ez megakadályozza, hogy a lapozás közben módosuló rekordok instabillá tegyék az aktuális bejárást.
Inkrementális szinkronizáláskor fel kell dolgozni minden kurzoroldalt, majd a bejárás snapshotAt értékét perzisztálni kell felső vízszintű időbélyegként. A következő bejáráskor ezt kell megadni ISO 8601 formátumú updatedSince értékként. Az alsó határ inkluzív, ezért egy befejezett pillanatkép újrapróbálása visszaadhat határértékhez tartozó rekordokat, de nem hagyhatja ki őket.
Egyetlen rekordot visszaadó válasz burka:
{
"data": {},
"requestId": "request-id"
}
Az egyetlen kontaktust visszaadó válaszok egy relations tömböt is tartalmaznak. Minden kapcsolat megőrzi a Scoutello-kapcsolatazonosítót, a létrehozás időpontját, a típust, a megjegyzéseket, valamint a connectedFrom és connectedTo kontaktushivatkozásokat. A kontaktushivatkozások a Scoutello-azonosítót és – ha létezik – az adott integráció külső azonosítóját tartalmazzák. Az API szervezeti hozzáférési adatvédelmi határa által kizárt kontaktusok nem jelennek meg a kapcsolatokon keresztül.
A kontaktuslista-válasz tömör marad, és nem tartalmaz kapcsolatokat; kapcsolat részleteinek lekéréséhez a két egyetlen kontaktust visszaadó útvonal egyikét kell használni.
Munkaszűrők és kurzortartomány
A kontaktuslisták elfogadják a search, a type (person, company, supplier, other), a status és a tagIds értéket. A keresés elején és végén levágja a szóközöket, nem különbözteti meg a kis- és nagybetűket, és legfeljebb 200 karakterre / 10, szóközzel elválasztott tokenre korlátozódik. Minden tokennek szerepelnie kell legalább a firstName, a lastName vagy a companyName egyikében, beleértve a lastName értékében tárolt korábbi cégneveket is. Az olyan karaktereket, mint a % és a _, szó szerint kell egyeztetni. A címkék bármelyiknek megfelelő egyeztetést használnak 1–50 azonosítóval. Minden megadott szűrő AND kapcsolatban áll egymással. A REST ismétlődő paraméterekként kódolja a címkeazonosítókat; az MCP tömböt biztosít:
GET /contacts?search=Hamburg%20Hotel&type=company&status=prospect&tagIds=tag-one&tagIds=tag-two
A kontaktuskurzorok a szervezethez, az integrációhoz és minden szűrőhöz kötődnek. A szűrőket minden oldalon változatlanul kell hagyni; egy szűrő módosítása elutasítja a kurzort. A címkék sorrendje és az ismétlődések, valamint a keresési tokenek sorrendje, kis- és nagybetűje, illetve szóközei nem módosítják a tényleges szűrőt.
A munkalistát kezelő útvonalak az alábbi további szűrőket fogadják el; az egyéb erőforrás-/mezőkombinációkat elutasítják:
| Erőforrás | Szűrők |
|---|---|
| Feladatok | projectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter |
| Jegyzőkönyvek | projectScoutelloId, milestoneScoutelloId, status (draft vagy final) |
| Lehetőségek | projectScoutelloId, stage, ownerScoutelloUserId |
| Projektek | status, assignedContactScoutelloId |
| Mérföldkövek | projectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter |
A dueBefore kizáró, a dueAfter pedig beleértő feltétel. A feladat esedékességi dátumát vagy a mérföldkő záró dátumát hasonlítják össze; a megfelelő dátummal nem rendelkező rekordok nem felelnek meg. Időzónát is tartalmazó ISO dátum-idő értékeket kell megadni. Minden szűrő alkalmazása a lapozás előtt történik. A kurzort pontosan ugyanazokkal a szűrőkkel – beleértve a updatedSince értéket is –, valamint ugyanazzal a szervezettel/integrációval kell folytatni. Az oldalméret módosulhat. A hatókör nélküli régi kurzoroknak a kiadás után a mentett legutóbbi feldolgozási időbélyegtől kell újraindulniuk.
Projektek, mérföldkövek, hozzárendelések és jegyzetek
A GET /members (MCP members_list) szabványos lapozást használ, és megköveteli a members.read értéket. A válasz tartalmazza a scoutelloId (a Customer-tag azonosítója), a scoutelloUserId (User-azonosító) és a displayName értékét. Csak a szerepkörrel rendelkező, elfogadott szervezeti tagok jelennek meg; a keresés nem tesz közzé e-mail-címeket vagy jogosultságokat.
A feladatok elfogadják a assignedScoutelloUserIds értéket; a lehetőségek a ownerScoutelloUserId értéket használják. A projektek és a mérföldkövek a assignedContacts: [{"scoutelloId":"member-customer-id"}] értéket használják. A hozzárendelésekhez a hitelesítő adathoz tartozó szervezet elfogadott tagjai szükségesek. A kihagyott hozzárendelések változatlanok maradnak; a [] törli őket. A projekt-, mérföldkő-, feladat- és jegyzőkönyvimportok csendesek: nem küldenek hozzárendelési értesítéseket vagy egyéb kommunikációt.
A assignedContacts esemény olvasható CRM-kapcsolatokat, valamint a tag Customer-azonosítója alapján megadott, elfogadott tagokat támogat. Az elfogadott tagok nem érhetők el normál CRM-kapcsolathivatkozásként vagy külső hivatkozás célpontjaként; a csapaton belüli felelősség hozzárendeléséhez a taghozzárendelési mezőt kell használni.
Mérföldkövek létrehozásához használjon egy name értéket, valamint a projectScoutelloId vagy a projectExternalId egyikét. Támogatják a description (Markdown), a status (open, in_progress, completed, closed), a nullable startDate/endDate, a order (alapértelmezés szerint 0), valamint a assignedContacts értéket. A dátumok befejezése nem lehet a kezdés előtt. Minden mérföldkőhöz az integráció hatókörében stabil külső hivatkozás tartozik. A mérföldkőhöz tartozó projekt nem módosítható az API-n keresztül. A létrehozási és frissítési műveletek a nevet és a leírást a szervezet nyelvére lokalizálják.
A feladatok és a protokollok a projekt-, mérföldkő- és lehetőség-hivatkozásokat <entity>ScoutelloId vagy <entity>ExternalId formában fogadják el, például: milestoneExternalId. Kapcsolatonként csak az egyik írásmódot adja meg, a null használatával végzett törléskor is. Minden kapcsolatnak a hitelesítő adataihoz tartozó szervezethez kell tartoznia. A csak mérföldkövet tartalmazó hivatkozásból a rendszer kikövetkezteti a projektet; az egymásnak ellentmondó projekt, illetve a projekt explicit törlése a mérföldkő megtartása mellett elutasításra kerül. A projekthez kapcsolódó lehetőségnek egyeznie kell a munka projektjével. A kihagyott kapcsolatok megőrzik aktuális értékeiket; az explicit null törli a kapcsolatot, ha a fennmaradó kontextus érvényes. A válaszok mindkét azonosító-írásmódot és a feladat-hozzárendeléseket is tartalmazzák.
Feladattervezés és munkafolyamatok
A feladat status értéke a feladat érvényes munkafolyamatában szereplő állapot megváltoztathatatlan kulcsa, nem pedig rögzített enum. Az elérhető szervezeti és projektmunkafolyamatok a tasks.read hatókörrel, a GET /task-workflows használatával olvashatók be. Minden állapot tartalmazza a kulcsát, címkéjét, életciklusának type értékét (backlog, unstarted, started, completed vagy cancelled), színét, sorrendjét, alapértelmezett jelzőjét és archiválási állapotát. A projektbejegyzések jelzik, hogy a szervezeti munkafolyamat öröklődik-e. A munkafolyamat konfigurációját továbbra is a vezérlőpulton, adminisztrációs jogosultsággal kell kezelni.
A feladatok elfogadják a nullable priority értéket (low, medium, high vagy urgent) és a estimatedEffortMinutes értéket, továbbá a nullable startDate és dueDate értéket. A feladatok olvasási válaszai tartalmazzák a denormalizált statusType értéket, a szülőhivatkozást, a részfeladatok tömörített hivatkozásait, valamint a blockedBy / blocks hivatkozásokat.
Hozzon létre vagy frissítsen egy egyszintű részfeladatot a(z) parentTaskScoutelloId vagy parentTaskExternalId használatával; a(z) null legfelső szintű feladattá emeli. A függőségek tömbökben megadott { "scoutelloId": "..." } vagy { "externalId": "..." } hivatkozásokat használnak a(z) blockedBy és blocks mezőkben. A kihagyott kapcsolatmezők megőrzik a meglévő kapcsolatokat, az üres függőségtömb pedig törli az adott irányt. Az API elutasítja a beágyazott részfeladatokat, a szülő-gyermek függőségeket, a szervezetek közötti függőségeket, a duplikátumokat, az önhivatkozásokat, valamint a közvetlen vagy tranzitív ciklusokat.
A feladatlista szűrői elfogadnak pontos munkafolyamat-értéket a(z) status mezőben, életciklusértéket a(z) statusType mezőben, a(z) priority mezőt, a(z) parentState mezőt (top_level, subtask vagy parent), valamint a(z) blockedState mezőt (blocked, blocking vagy unblocked).
A protokollok ezenfelül elfogadják a(z) status: "draft" | "final" mezőt (az új rekordok alapértelmezés szerint final értéket kapnak). Új protokoll létrehozásához szükség van a(z) type és date mezőre, valamint egy kapcsolatra vagy érvényes projekt-/mérföldkő-kontextusra. A(z) contactExternalId: null csak akkor törli a kapcsolatot, ha a projekt-/mérföldkő-kontextus megmarad. Így belső projektjegyzetek is létrehozhatók és olvashatók anélkül, hogy ügyfelet kellene kitalálni. A piszkozat/végleges állapot a jegyzet állapotát írja le, és soha nem indít kommunikációt. A privát feladatok és protokollok továbbra sem érhetők el.
Projektrésztvevők
A projekt participants mezője egy contact hivatkozás alapján kulcsolt, hozzáadó jellegű upsert műveleteket tartalmaz, például:
{
"externalId": "gtm:hotels",
"participants": [{
"contact": {"scoutelloId": "prospect-contact-id"},
"role": "Potential pilot",
"notes": "Existing warm lead; qualify the next step.",
"groupScoutelloId": null
}]
}
A résztvevők a projekthez kapcsolódó érdeklődőket/ügyfeleket írják le; a felelős személyeket hozzárendelésekkel kell megadni. A kihagyott résztvevők, az üres tömb és a kihagyott résztvevőmezők megőrzik a meglévő adatokat. A(z) null törli a(z) role, notes vagy groupScoutelloId mezőt. Egy adathalmazon belül az azonosított kapcsolatok duplikátumait a rendszer elutasítja. A csoportoknak már a kiválasztott projekthez kell tartozniuk; a lekérdezések tartalmazzák a(z) participantGroups mezőt (azonosító/név), valamint a résztvevőazonosítókat, kapcsolatokat, szerepkört, jegyzeteket és a csoportazonosítót. A résztvevők eltávolítása és csoportok létrehozása jelenleg az irányítópulton érhető el.
Rekordok kötegelt upsert művelete
Legfeljebb 100 rekord írható az erőforrás kötegelt útvonalán:
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"
}
]
}
A feladatkötegek a szülő- és függőségi kapcsolatok alkalmazása előtt feloldják a hozzájuk tartozó feladatrekordokat. Ez a kétfázisú feldolgozás lehetővé teszi, hogy egy szülő-, blokkoló- vagy blokkolt feladat a rekordok sorrendjétől függetlenül külső azonosító alapján egy ugyanabban a kötegben létrehozott másik feladatra hivatkozzon.
Használja az OpenAPI-dokumentumot az egyes erőforrások mezőinek és érvényesítési korlátainak meghatározásához. Minden rekordnak tartalmaznia kell egy stabil externalId értéket 1 és 200 karakter között. Kezelje átlátszatlan technikai azonosítóként: ne használjon e-mail-címet, nevet, API-titkot vagy más személyes adatot. A externalUpdatedAt opcionális, de erősen ajánlott, ha a forrásrendszer megbízható módosítási időbélyeget biztosít.
A kérés törzsének mérete legfeljebb 1 MiB lehet. A mode alapértelmezett értéke: apply:
- A
applyellenőrzi és elmenti az elfogadott rekordokat. - A
validateugyanazt az ellenőrzést és egyeztetést végzi el mentés nélkül, éswould_*eredményeket ad vissza.
A kapcsolatok importálásakor a kérésben a matchByEmail értéke true lehet. Alapértelmezett értéke false; a külső azonosító biztonságosabb alapértelmezett identitáshatár.
A kihagyott mezők megőrzik az aktuális értéket. A kifejezetten megadott null törli a null értéket elfogadó mezőt, a megadott üres hozzárendelési- vagy címketömb pedig törli az adott kapcsolatot. A projekt participants hozzáadó jellegű upsert-műveletek: az üres tömb változatlanul hagyja a névsort. A kapcsolatok, feladatok, lehetőségek és események címkeírásai Scoutello-címkeazonosítókat használnak. A kapcsolatok külső azonosítói csak az aktuális integrációhoz tartozó hivatkozásokon keresztül oldhatók fel, míg a tulajdonláshoz vagy felelősséghez használt Scoutello-felhasználói azonosítóknak az aktuális szervezet elfogadott tagjait kell azonosítaniuk.
A lehetőségek létrehozásához fiók vagy kapcsolat szükséges, az elvesztett lehetőségekhez pedig elvesztési ok is kell. A pénzösszegek egész centben értendők. A projektek és események neveit, valamint leírásait a szervezet beállított nyelvén kell olvasni és írni. Az események írása támogatja a konkrét dátumokat, valamint a kizárásokkal megadott napi, heti vagy havi ismétlődést; a közzétett láthatósági szintekre továbbra is vonatkoznak a Scoutello jogi megfelelőségi korlátai. Az API nem biztosít hozzáférést az eseményjegy-kezeléshez, a résztvevőkhöz, a médiához, a sablonokhoz, a hírlevelekhez, az együttműködésekhez és más speciális eseménykezelési vezérlőkhöz.
Címkék felderítése
A tagIds megadása előtt használja a címkék végpontját:
GET /tags?entity=events&type=category
A entity kötelező, és a következő értékeket fogadja el: contacts, tasks, opportunities vagy events. Ez a megfelelően tárolt címkerelevanciára képeződik le. A type opcionális, és a category vagy attribute értéket fogadja el. A kiválasztható kategóriák a szervezet tulajdonában lehetnek, illetve globálisak lehetnek; a kiválasztható attribútumok a Scoutello gondozott globális attribútumkészletéből származnak. Az eredmények tartalmazzák a scoutelloId értéket, a szervezet nyelvére lokalizált nevet, a type értéket és a relevancy értéket. A szervezetek között használt, nem megfelelő relevanciájú vagy nem kiválasztható címkeazonosítók elutasítják az érintett kötegelemeket.
Kimenő levelek előzményeinek olvasása
A levelezési előzmények csak olvashatók:
GET /mails?updatedSince=2026-09-01T00:00:00.000Z
GET /mails/{scoutelloId}
Csak a szervezet tulajdonában lévő, sent vagy failed állapotú levelek jelennek meg. A válaszok a gyakran tárolt fejléceket és a törzset, a BCC-címzetteket, az állapotot és az időbélyegeket, a projektekre/eseményekre/hírlevelekre mutató hivatkozásokat, a mellékletek azonosítóit és típusait, valamint a címzettek kézbesítési, megnyitási, kattintási, visszapattanási, panasz- és elutasítási statisztikáinak összesített adatait tartalmazzák. A piszkozatok, a várólistán lévő vagy ütemezett levelek, a címzettenkénti sorok, a renderelt pillanatképek, a szolgáltatói nyers hibaüzenetek és a mellékletek letöltési URL-jei soha nem jelennek meg. Egy későbbi címzetti kézbesítési frissítés előrébb hozza a levél tényleges szinkronizálási időbélyegét, ezért a levél ismét megjelenik a növekményes olvasásokban. Levelek írására nincsenek végpontok.
Egy alkalmazási eredmény lehet created, updated, linked, unchanged, stale_ignored vagy rejected. Az ellenőrzés a következőket használja: would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale vagy rejected. Egy érvényes kötegelt kérés HTTP 200 választ ad akkor is, ha egyes rekordokat elutasít a rendszer, ezért mindig ellenőrizni kell minden elemet és a válasz összegzését. A választ requestId változatlanul meg kell őrizni, amikor egy hiba kivizsgálásához a Scoutello támogatási csapatához fordulnak.
Időbélyegek és ütközések
Ha jelen van a externalUpdatedAt, a Scoutello ezt használja az elavult módosítások elutasítására anélkül, hogy a köteg többi részét sikertelenné tenné. A stale_ignored eredmény véglegesnek számít az adott régebbi adatcsomag esetében; az újabb verzió beküldésének eldöntése előtt le kell kérni az aktuális rekordot.
Az időbélyegeket UTC szerinti ISO 8601-értékekként kell kezelni. Meg kell őrizni az eredeti pontosságukat, és a szinkronizálási feladat futásának ideje nem helyettesítheti a forrásrekord módosítási idejét.
Idempotencia
Az idempotencia határa az integráció és a externalId. A Scoutello összeveti a kanonikus adatcsomag kivonatát és az opcionális externalUpdatedAt értéket, ezért ugyanazon rekord újrapróbálkozása nem hoz létre duplikátumokat, és unchanged eredményt adhat.
externalUpdatedAt esetén az azonos időbélyeg és adatcsomag unchanged, a régebbi időbélyeg stale_ignored, az azonos időbélyeg eltérő adatcsomaggal pedig verzióütközés. Olyan kapcsolat esetén, amely még soha nem fogadott időbélyeget, ugyanaz az időbélyeg nélküli adatcsomag továbbra is unchanged, míg a módosított adatcsomagot a beérkezés sorrendjében alkalmazza a rendszer. Miután egy kapcsolat elfogadott egy időbélyeget, a módosított adatcsomagot, amelyből hiányzik a externalUpdatedAt, a rendszer verzióütközésként elutasítja, így a verzió nélküli adatok nem írhatják felül a verziózott állapotot. Ezért kifejezetten ajánlott a forrás módosítási időbélyegeinek használata.
Auditnapló
A hyväksített API-létrehozási, frissítési és csak hivatkozást végző szinkronizálási műveletek Scoutello-változásnaplóiban Public API forrásként jelennek meg, és a felelős integrációhoz kapcsolódnak. A műveleti futások összesítői a hibakereséshez megőrzik a kérésazonosítókat és az összesített eredményszámokat; rekordtartalmakat vagy API-titkokat nem tárolnak.
Hibák és újrapróbálkozások
A kérésszintű hibák az alábbi burkot használják:
{
"error": {
"code": "error_code",
"message": "Safe error message",
"requestId": "request-id",
"details": {}
}
}
A 429-es HTTP-válaszokat és az átmeneti 5xx-válaszokat exponenciális visszalépéssel és jitterrel kell újrapróbálni. Ha jelen van, be kell tartani a következő értéket: Retry-After. Hálózati hiba azután is történhetett, hogy a Scoutello elfogadta a kérést; ugyanazon köteg újbóli elküldése biztonságos, mert minden rekord idempotens a külső azonosító és a kanonikus adatok alapján. Hitelesítési, jogosultsági, érvényesítési, verzióütközési vagy egyedi rejected eredményeket a kérés módosítása nélkül nem szabad automatikusan újrapróbálni.
Ajánlott kétirányú szinkronizálási ciklus
- A beállítás során meg kell hívni a következőt:
/whoami, majd ellenőrizni kell a várt szervezetet és hatóköröket. - Az utolsó befejezett magasvíz-jelző óta módosult minden oldalt be kell olvasni, és a módosításokat idempotensen kell alkalmazni a külső rendszerben.
- A külső módosításokat a következőhöz kell küldeni:
/batch-upsert, stabil külső azonosítók és a forrás módosítási időbélyegeinek használatával. - Ellenőrzési pontokat csak az összes oldal és elemeredmény feldolgozása után szabad menteni.
- Az ütközéseket a forrásrendszer tulajdonjogi szabályai szerint kell feloldani; a törléseket nem szabad üres rekordok küldésével utánozni.
A Scoutello ebben az első verzióban szándékosan nem biztosít nyilvános törlési útvonalat. A törlési vagy archiválási szabályokat az API-n kívül kell kezelni, amíg dokumentált életciklus-művelet nem válik elérhetővé.
Közösségi bejegyzések emberi ellenőrzéshez
A közösségi API bejegyzéseket készít egy név szerint megadott ellenőrző személy számára. Jóváhagyni vagy közzétenni nem tudja őket. A REST és az MCP ugyanazokat a hatóköröket és szolgáltatást használja.
| Hatókör | Végpontok a következő alatt: /api/v1 |
|---|---|
social-channels.read | GET /social-channels |
social-posts.read | GET /social-posts, GET /social-posts/{scoutelloId} |
social-post-drafts.read | GET /social-post-drafts, GET /social-post-drafts/{scoutelloId}, GET /social-post-drafts/external/{externalId} |
social-post-drafts.write | POST /social-post-drafts/batch-upsert, POST /social-media/uploads, POST /social-media/uploads/{assetId}/finalize |
Az új hatóköröket kifejezetten engedélyezni kell. A meglévő hitelesítő adatok nem kapnak további hozzáférést. A következővel lehet lekérni a tagok felhasználói azonosítóit: members.read, majd olyan ellenőrző személyt kell kiválasztani, aki rendelkezik közzétételi jogosultsággal (newsletter.edit). Piszkozatokhoz nincs szükség CRM-kapcsolatra vagy projektre.
{
"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"]
}]
}
}]
}
Jóváhagyás után a publishMode: "now" és a scheduledAt: null használatával lehet közzétenni. Minden
csatornaváltozat tartalmazza a teljes szöveget, a beállításokat és a médiumazonosítók
sorrendjét. A csatornafelderítés a támogatott formátumokat, korlátozásokat és
beállításokat adja vissza. Jelenleg a LinkedIn-profilok és -oldalak, a Facebook, az
Instagram és a Threads támogatott. Az Instagram médiát igényel. Egy változathoz
legfeljebb tíz kép vagy videó adható meg.
A kötegek legfeljebb 100 egyedi külső azonosítót fogadhatnak az érvényes 1 MiB-os
kéréskorláton belül. A mode: "validate" ellenőrzi a hivatkozásokat és a verziókat piszkozatok mentése,
eszközök feltöltése, értesítések létrehozása vagy feladatok várólistára helyezése
nélkül. Az alkalmazás eredményei azonosítókat, ellenőrzési hivatkozásokat, verziókat
és rekordonkénti kimeneteleket tartalmaznak. A részleges hibák nem vonják vissza a
sikeres testvérek eredményeit. Értesítési hiba esetén a rendszer figyelmeztetést ad
vissza a mentett ellenőrzési URL-lel.
Módosítás előtt kérje le az aktuális draftVersion értéket. Az azonos
újrapróbálkozások idempotensek, és megőrzik a későbbi emberi módosításokat. Az
ellenőrzők helyben nem módosíthatók. Jóváhagyás vagy elutasítás után új külső
azonosító használata szükséges egy újabb javaslathoz. A piszkozatok olvasása csak a
hívó integráció számára engedélyezett; a közzétételi előzmények a szervezetben
megőrzött, Scoutello által létrehozott összes kampányt lefedik, beleértve az
irányítópulton, szkripttel és a régi Scoutello-folyamatokkal létrehozott bejegyzéseket.
A rendszer nem importálja a külső csatornák előzményeit.
A listák a szabványos limit, cursor és updatedSince paramétereket használják. A bejegyzések és a
piszkozatok emellett elfogadják a channelId, status, after, before és search paramétereket; az
összes szűrőt meg kell őrizni a további kurzoroldalakon. A dátumszűrők a közzététel
idejére vonatkoznak (azonnali piszkozatok esetén a létrehozás idejére). A piszkozatok
status szűrője a jóváhagyási állapotot vizsgálja; a bejegyzések
status szűrője a kampány vagy a csatorna kézbesítési állapotára
illeszkedik. A lekérdezések a legutóbbi ismert kézbesítési állapotot, a csatornánkénti
hibákat, a nyilvános hivatkozásokat és az egyeztetés időbélyegeit teszik elérhetővé.
A piszkozatok inkrementális lekérdezései a kampány kézbesítési változásait is tükrözik.
Média feltöltése
- Hívja meg a
POST /social-media/uploadsaclientUploadId,filename,contentType,sizebájtokban, és a eredeti bájtok lowercase hexadecimálissha256értékével. Támogatott típusok: PNG, JPEG, WebP, MP4, WebM, QuickTime és M4V. A feltöltés plafonja 500 MiB. - Küldje el az eredeti bájtokat HTTP
PUTcímen a visszakapottupload.url-hez, a fejlécek felhasználásával. A feltöltési URL-ek 15 percen belül lejárnak. Ismételje megclientUploadIda ugyanazon fájl újbóli kísérleteit; lejárt munkamenetek vagy különböző fájlok esetén új azonosító szükséges. - Hívja meg
POST /social-media/uploads/{assetId}/finalize-et egy{}JSON törzzével. A véglegesítés méretet, típust, aláírást és ellenőrző összeg-bizonyítékot vizsgálja, lefagyaszt egy zárt példányt, és visszaadja az eszközazonosítót amediaIdsszámára. Ismételt véglegesítés biztonságos.
A feltöltés tulajdonjoga a szervezethez és az integrációhoz kötött. A tervezetek hivatkozhatnak a szervezetük által véglegesített eszközökre. A preview URL-ek ideiglenesek; a tervezetet újra be kell szerezni a frissítéshez. A véglegesített objektumokra soha nem adható ki feltöltési URL.
Emberi felülvizsgálat és kézbesítés
A felülvizsgáló értesítést kap a műszerfalon, és megnyithatja a bejegyzést a Postings-ból vagy az áttekintési URL-jéből. A szerkesztés egy újabb megmásíthatatlan verziót hoz létre. A jóváhagyás a megjelenített verziót és a tartalom hash-jét használja, újból ellenőrzi a tagságot, a csatornákat és az eszközöket, és atomikusan hoz létre egy tartós kampányt. Ha a javasolt idő eltel, a felülvizsgáló köteles egy explicit új időpontot menteni vagy a jóváhagyáskor a közzétételt kiválasztani.
A sorba rendezett újrapróbálások újrahasznosítják a kampányt és annak platform-bizonylatait. Jóváhagyott kampányokat nem lehet helyben szerkeszteni. A dashboardon keresztüli törlés megőrzi a jóváhagyási történetet és a médiát; a törlés nem szakíthatja meg a tényleges kiszállítást. Tervezet vagy kampány lekérdezésével megkülönböztethető a jóváhagyás a tényleges platform-kiszállítástól.