Preskoči na glavni sadržaj

Scoutello API

Scoutello API je API za komunikaciju poslužitelj–poslužitelj koji omogućuje dvosmjernu sinkronizaciju kontakata, zadataka, protokola, prilika, projekata, ključnih etapa i događaja organizacije. Također omogućuje pristup povijesti odlazne pošte samo za čitanje, dohvaćanje članova kojima se mogu dodijeliti stavke te otkrivanje oznaka prema entitetu. Inkrementalne GET/rute za popis i idempotentna grupna ažuriranja osnovni su mehanizmi sinkronizacije u ovoj verziji. Brisanje i web-dojavnice nisu podržani.

Osnovni URL API-ja je:

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

Prikazan je i u odjeljku Postavke organizacije → Developer/API. OpenAPI dokument dostupan je na adresi:

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

Izrada i zaštita ključa​

Za modularne organizacije, uz potrebne opsege ključa mora biti aktivan i CRM modul. Valjani ključ ne može aktivirati modul koji nedostaje. Zahtjevi vraćaju HTTP 403 s kodom pogreške module_not_active ako CRM pristup nije dostupan. Osoba s administracijskim ovlastima organizacije može pregledati ili aktivirati CRM u odjeljku Pretplata; pokušaj ponoviti nakon aktivacije pristupa.

Osoba s administracijskim ovlastima organizacije može izraditi integraciju i API ključ u odjeljku Postavke organizacije → Developer/API. Cijeli se ključ prikazuje samo jednom. Kopirajte ga u upravitelj tajni prije zatvaranja dijaloškog okvira; Scoutello ga više ne može prikazati u cijelosti.

  • Za svaki vanjski sustav i okruženje upotrebljavati zasebnu integraciju i ključ.
  • Dodijeliti samo opsege koji su tom sustavu potrebni.
  • Ključ nikada ne pohranjivati u kôd preglednika, URL, sustav za upravljanje izvornim kôdom, zapisnike, poruke podršci ni pohranu na strani klijenta.
  • Ključeve rotirati prema rasporedu. Pri rotaciji aktivne integracije zamjenski ključ počinje raditi odmah, a prethodni ostaje valjan najviše 15 minuta kako bi vanjski sustav mogao prijeći bez prekida rada. I dalje vrijedi raniji rok isteka, pa prethodni ključ može prestati raditi i ranije.
  • Ako je ključ možda otkriven, pauzirati integraciju prije rotacije. Pauziranje privremeno odbija sve ključeve integracije. Rotacija dok je integracija pauzirana ne omogućuje preklapanje: prethodni ključ ostaje onemogućen, a zamjenski ključ ostaje onemogućen dok se integracija ponovno ne pokrene.
  • Pri prekidu veze s vanjskim sustavom trajno opozvati cijelu integraciju. Opoziv onemogućuje svaki njezin ključ i ne može se poništiti.

Ključ slati u svakom autentificiranom zahtjevu:

Authorization: Bearer YOUR_API_KEY

Preferira se autentifikacija nositeljem. Klijenti koji ne mogu postaviti Authorization mogu umjesto toga upotrijebiti x-api-key. Ne slati oba zaglavlja; zahtjevi s različitim vrijednostima u oba zaglavlja odbijaju se.

API je namijenjen pozadinskim klijentima i ne omogućuje pristup iz preglednika između različitih izvora.

Upotrijebiti GET /whoami nakon konfiguriranja ključa za provjeru integracije, organizacije, opsega i ograničenja ključa bez dohvaćanja osobnih podataka korisnika.

Opsezi​

OpsegOmogućuje
contacts.readPopisivanje i dohvaćanje kontakata. Kontakti organizacijskog računa i članova s pravima pristupa izuzeti su.
contacts.writeProvjeru i primjenu ažuriranja kontakata.
tasks.readPopisivanje i dohvaćanje nejavnih zadataka.
tasks.writeProvjeru i primjenu ažuriranja zadataka.
protocols.readPopisivanje i dohvaćanje nejavnih protokola.
protocols.writeProvjeru i primjenu ažuriranja protokola.
opportunities.readPopisivanje i dohvaćanje prilika.
opportunities.writeProvjeru i primjenu ažuriranja prilika.
projects.readPopisivanje i dohvaćanje projekata.
projects.writeProvjeru i primjenu ažuriranja projekata i sudionika.
milestones.readPopisivanje i dohvaćanje projektnih prekretnica.
milestones.writeProvjeru i primjenu ažuriranja prekretnica.
members.readPopisivanje prihvaćenih članova samo s korisničkim ID-om korisnika, korisničkim ID-om i prikaznim imenom člana.
events.readPopisivanje i dohvaćanje događaja i osnovnih rasporeda.
events.writeProvjeru i primjenu ažuriranja događaja.
mails.readČitanje povijesti poslane i neuspjele odlazne pošte u vlasništvu organizacije.
mail-drafts.readČitanje samostalnih nacrta e-poruka ove integracije za odobrenje i statusa isporuke.
mail-drafts.writePripremu ili izmjenu nacrta e-poruka za ljudsko odobrenje; nikad ne odobrava niti šalje e-poruke.
tags.readOtkrivanje odabirnih oznaka za podržane vrste entiteta.

Privatni zadaci i protokoli nikad se ne vraćaju putem ovog API-ja. Ako opseg nedostaje, vraća se pogreška autorizacije; to se ne tretira kao prazan rezultat.

CRM kontakt koji nije član može se pročitati i referencirati čak i kada je povezan s prijavom na Scoutello. Odgovor sadrži samo CRM polja organizacije, nikad identitet korisnika ni polja pristupa. Kontakti s ulogom, dopuštenjima, pozivom, prihvaćanjem ili statusom organizacijskog računa ostaju skriveni. Uređivanje kontakta povezanog s prijavom i dalje je zabranjeno (protected_contact), uključujući CRM polja koja inače nisu promijenjena. Za referenciranje postojećeg čitljivog kontakta iz zadatka/protokola, contacts.write može uspostaviti njegovu vanjsku poveznicu samo pomoću externalId, scoutelloId i neobaveznog externalUpdatedAt. Kasnija ažuriranja koja se odnose samo na metapodatke poveznice koriste externalId i neobavezni externalUpdatedAt; nakon povezivanja izostaviti početni scoutelloId. To nikad ne mijenja kontakt ni njegovog korisnika. Dodjela prihvaćenog člana koristi zasebnu projekciju members.read.

Novi ključevi koriste prefiks sctl_api_ i počinju samo s ovlasti contacts.write. Svaki dodatni opseg mora izričito odobriti osoba s pravima administracije organizacije pri stvaranju ili rotaciji ključa. Postojeće vjerodajnice zadržavaju trenutačne opsege i ostaju valjane.

Kontakti povezani s projektom i nacrti e-pošte​

Upsert kontakata prihvaća neobavezne parove projectScoutelloId / projectExternalId i companyScoutelloId / companyExternalId (odaberite jedan iz svakog para). Kontakt, odnos s tvrtkom i sudjelovanje u projektu spremaju se atomski za svaku stavku. Dodavanje sudjelovanja zahtijeva projects.write; izostavljene reference čuvaju druge odnose i sudjelovanja. Čitanje detalja kontakta uključuje projectParticipations kada je odobren projects.read. Agenti prodajnih projekata moraju izričito navesti referencu projekta i pri ponovnom korištenju kontakta.

Samostalni nacrti koriste postojeći sustav ljudskog odobravanja bez pokretanja tijeka rada:

MetodaPutanjaSvrha
GET/mail-draftsStraničeni nacrti u vlasništvu integracije; neobavezni filtri projectScoutelloId i status.
GET/mail-drafts/{scoutelloId}Trenutačna verzija, poveznica za pregled, sažetak sadržaja, status odobravanja/slanja i eventualni ID e-pošte.
GET/mail-drafts/external/{externalId}Traženje stabilnog vanjskog ID-a integracije.
POST/mail-drafts/batch-upsertProvjera ili primjena pripreme nacrta.

Priprema nacrta zahtijeva mail-drafts.write, contacts.read i projects.write. Referencirani kontakt postaje sudionik projekta. Osoba koja odobrava mora biti prihvaćeni član organizacije s ovlasti uređivanja e-pošte. Odabir pošiljatelja koristi postojeće dopuštene organizacijske ili osobne postavke tog člana; proizvoljne adrese From nisu prihvaćene.

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

Provjerite svaki rezultat validacije prije ponavljanja s mode: "apply". Pročitajte dobiveni ID radi vrijednosti reviewUrl, draftVersion, contentHash, status, dispatchStatus i mailScoutelloId. expectedVersion: 0 koristite samo za stvaranje, a vraćenu trenutačnu verziju za izmjene. Kontekst i osoba koja odobrava nepromjenjivi su; pregledani ili poslani nacrti odbijaju izmijenjeni sadržaj. Identična ponavljanja vraćaju izvorni nacrt.

Nacrti se prikazuju na karticama e-pošte projekta i kontakta te u obavijestima za odobravanje na nadzornoj ploči. Priprema putem API-ja ne šalje e-poštu, uključujući obavijesti; postojeće ponašanje obavijesti tijeka rada ostaje nepromijenjeno. Zadužena osoba može urediti primatelje, predmet, tekst i podržane privitke, spremiti verziju i odabrati Odobri i pošalji. Integracije ne mogu odobravati ni slati. Neuspjele ili nejasne isporuke nikada ne treba ponavljati bez provjere. Pri pretvaranju nacrta temeljenih na protokolima sačuvajte protokole i dodajte uzajamne reference na njihove zamjene.

MCP pristup​

Isti Scoutello API ključ i opsezi mogu se koristiti s MCP krajnjom točkom za streamable HTTP:

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

Konfigurirajte MCP klijent za slanje Authorization: Bearer YOUR_API_KEY. Stari URL /api/mcp ostaje alias za kompatibilnost putanje, ali novi klijenti trebaju koristiti verzioniranu krajnju točku. Ranije vjerodajnice sctl_mcp_ nisu prihvaćene; zamijenite ih integracijskim ključem Scoutello API-ja.

MCP alati izravno odgovaraju REST ugovoru i koriste iste sheme u izvršavanju, provjere organizacije, životni ciklus integracije, ograničenja učestalosti i metode usluge. Na primjer, contacts_list, contacts_get, contacts_get_by_external_id i contacts_batch_upsert odgovaraju četirima rutama kontakata. Isto vrijedi za zadatke, protokole, prilike, projekte, prekretnice i događaje. Za e-poštu postoje mails_list i mails_get, za članove members_list, a za oznake tags_list.

Poslužitelj objavljuje samo alate koje dopuštaju opsezi trenutačnog ključa. Ključ s contacts.read može otkriti alate za čitanje kontakata, ali ne contacts_batch_upsert; ključ s contacts.write dobiva alat za skupni upsert, ali ne alate za čitanje. whoami je uvijek dostupan. Alati za pisanje imaju iste neposredne učinke kao REST ekvivalenti. Koristite mode: "validate" za provjeru skupa bez primjene.

MCP je također namijenjen komunikaciji između poslužitelja i ne omogućuje pristup preglednika između različitih izvora. JSON-RPC prijenos zahtijeva poseban URL, pa MCP ne može dijeliti URL pojedinog REST resursa, iako su autentifikacija i ponašanje podataka jednaki.

Potpune upute za konfiguraciju klijenta, provjeru, mapiranje alata i rješavanje problema nalaze se u vodiču za MCP integraciju.

Čitanje zapisa​

Kontakti, zadaci, protokoli, prilike, projekti, prekretnice i događaji koriste iste rute za čitanje:

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

Za ostale resurse sinkronizacije zamijenite contacts s tasks, protocols, opportunities, projects, milestones ili events. externalId pojavljuje se u DTO-u za čitanje kada je zapis povezan ovom integracijom.

Odgovor s popisom ima ovaj omotač:

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

limit mora biti između 1 i 100. Rezultati su poredani prema vremenu kada se njihova javna API reprezentacija učinkovito promijenila, a zatim prema Scoutello ID-u. To vrijeme može biti kasnije od vraćenog entiteta updatedAt kada su se promijenili metapodaci integracijske veze. Kursori su neprozirni: spremati ih i slati nepromijenjene te ne izvoditi značenje iz njihova sadržaja.

Prvi odgovor određuje snapshotAt za to kretanje kroz rezultate. Slijediti nextCursor dok hasMore ne bude false, prije pokretanja drugog inkrementalnog čitanja. Time se sprječava da promjene zapisa tijekom paginacije učine trenutačno kretanje kroz rezultate nestabilnim.

Za inkrementalnu sinkronizaciju obraditi svaku stranicu kursora, a zatim trajno pohraniti snapshotAt tog kretanja kroz rezultate kao krajnju vremensku oznaku. Proslijediti je kao vrijednost updatedSince u formatu ISO 8601 pri sljedećem kretanju kroz rezultate. Donja granica je uključiva, pa ponovni pokušaj dovršenog snimka može vratiti zapise na granici, ali ih ne može preskočiti.

Odgovor za pojedinačni zapis ima ovaj omotač:

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

Odgovori za pojedinačne kontakte uključuju i polje relations. Svaka relacija zadržava svoj Scoutello ID relacije, vrijeme stvaranja, vrstu, bilješke te reference na kontakte connectedFrom i connectedTo. Reference na kontakte sadrže Scoutello ID i vanjski ID ove integracije, ako postoji. Kontakti isključeni pravilima privatnosti za pristup organizaciji API-ja ne izlažu se kroz relacije. Odgovor s popisom kontakata ostaje sažet i ne uključuje relacije; za detalje odnosa upotrijebiti jednu od ruta za pojedinačni kontakt.

Radni filtri i opseg kursora​

Popisi kontakata prihvaćaju search, type (person, company, supplier, other), status i tagIds. Pretraživanje uklanja razmake na početku i kraju, ne razlikuje velika i mala slova te je ograničeno na 200 znakova / 10 tokena odvojenih razmacima. Svaki token mora se pojaviti u barem jednom od polja firstName, lastName ili companyName, uključujući stare nazive tvrtki pohranjene u lastName. Znakovi poput % i _ podudaraju se doslovno. Oznake upotrebljavaju podudaranje bilo koje od navedenih s 1–50 ID-ova. Svi navedeni filtri kombiniraju se operatorom AND. REST kodira ID-ove oznaka kao ponovljene parametre, a MCP isporučuje polje:

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

Kursori kontakata vezani su uz organizaciju, integraciju i svaki filtar. Filtre zadržati na svakoj stranici; promjena filtra odbija kursor. Redoslijed i duplikati oznaka te redoslijed tokena, velika i mala slova i razmaci u pretraživanju ne mijenjaju učinkoviti filtar.

Rute radnih popisa prihvaćaju sljedeće dodatne filtre; druge kombinacije resursa/polja odbacuju se:

ResursFiltri
ZadaciprojectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter
ProtokoliprojectScoutelloId, milestoneScoutelloId, status (draft ili final)
PrilikeprojectScoutelloId, stage, ownerScoutelloUserId
Projektistatus, assignedContactScoutelloId
PrekretniceprojectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter

dueBefore isključuje graničnu vrijednost; dueAfter uključuje je. Uspoređuju rok zadatka ili datum završetka prekretnice; zapisi bez tog datuma ne podudaraju se. Zadajte datume i vremena u ISO formatu, s navedenom vremenskom zonom. Svi se filtri primjenjuju prije paginacije. Nastavite kursor s potpuno istim filtrima, uključujući updatedSince, te istom organizacijom/integracijom. Veličina stranice može se promijeniti. Stari kursori bez opsega nakon ovog izdanja moraju se ponovno pokrenuti od spremljene gornje vremenske granice.

Projekti, prekretnice, dodjele i bilješke​

GET /members (MCP members_list) upotrebljava standardnu paginaciju i zahtijeva members.read. Vraća scoutelloId (ID člana Customer), scoutelloUserId (ID User) i displayName. Prikazuju se samo prihvaćeni članovi organizacije s dodijeljenom ulogom; pretraživanje ne otkriva adrese e-pošte ni dozvole.

Zadaci prihvaćaju assignedScoutelloUserIds; prilike upotrebljavaju ownerScoutelloUserId. Projekti i prekretnice upotrebljavaju assignedContacts: [{"scoutelloId":"member-customer-id"}]. Dodjele zahtijevaju prihvaćene članove organizacije vjerodajnice. Izostavljene dodjele ostaju nepromijenjene; [] uklanja ih. Uvozi projekata, prekretnica, zadataka i protokola odvijaju se bez obavijesti: ne šalju obavijesti o dodjelama ni druge komunikacije.

Događaj assignedContacts podržava čitljive CRM kontakte i prihvaćene članove navedene prema ID-u člana Customer. Prihvaćeni članovi ostaju nedostupni kao uobičajene reference CRM kontakata ili odredišta vanjskih poveznica; za odgovornost tima upotrijebite polje za dodjelu člana.

Stvorite prekretnice pomoću name i projectScoutelloId ili projectExternalId. Podržavaju description (Markdown), status (open, in_progress, completed, closed), nullable startDate/endDate, order (zadano je 0) i assignedContacts. Datumi završetka ne mogu prethoditi datumima početka. Svaka prekretnica ima stabilnu vanjsku poveznicu ograničenu na integraciju. Projekt prekretnice ne može se promijeniti putem API-ja. Stvaranje i ažuriranje lokaliziraju naziv/opis na jezik organizacije.

Zadaci i protokoli prihvaćaju reference na projekte, prekretnice i prilike kao <entity>ScoutelloId ili <entity>ExternalId, na primjer milestoneExternalId. Za svaki odnos navedite samo jedan oblik naziva, uključujući brisanje pomoću null. Svi odnosi moraju pripadati organizaciji vjerodajnice. Referenca samo na prekretnicu određuje projekt; konfliktni projekt ili izričito brisanje projekta uz zadržavanje njegove prekretnice odbija se. Povezana prilika s projektom mora odgovarati projektu rada. Izostavljeni odnosi zadržavaju trenutačne vrijednosti; izričita vrijednost null briše odnos kada je preostali kontekst valjan. Čitanja izlažu oba oblika ID-ja i dodjele zadataka.

Planiranje zadataka i tijekovi rada​

status zadatka nepromjenjivi je ključ statusa u efektivnom tijeku rada zadatka, a ne fiksna enumeracija. Dostupne tijekove rada organizacije i projekta pročitajte pomoću GET /task-workflows uz opseg tasks.read. Svaki status uključuje svoj ključ, oznaku, životni ciklus type (backlog, unstarted, started, completed ili cancelled), boju, redoslijed, zadanu oznaku i stanje arhiviranja. Unosi projekta pokazuju nasljeđuje li se tijek rada organizacije. Konfiguracijom tijeka rada i dalje se upravlja putem nadzorne ploče.

Zadaci prihvaćaju nullable priority (low, medium, high ili urgent) i estimatedEffortMinutes, kao i nullable startDate i dueDate. Čitanja zadataka uključuju denormalizirani statusType, referencu na nadređeni zadatak, sažete reference na podzadatke te reference blockedBy / blocks.

Stvorite ili ažurirajte podzadatak na jednoj razini pomoću parentTaskScoutelloId ili parentTaskExternalId; null pretvara ga u zadatak najviše razine. Ovisnosti koriste nizove referenci { "scoutelloId": "..." } ili { "externalId": "..." } u blockedBy i blocks. Izostavljena polja odnosa zadržavaju postojeće vrijednosti, dok prazan niz ovisnosti briše taj smjer. API odbija ugniježđene podzadatke, ovisnosti između nadređenih i podređenih stavki, ovisnosti između organizacija, duplikate, reference na samog sebe te izravne ili tranzitivne cikluse.

Filtri popisa zadataka prihvaćaju točan tijek rada status, životni ciklus statusType, priority, parentState (top_level, subtask ili parent) te blockedState (blocked, blocking ili unblocked).

Protokoli dodatno prihvaćaju status: "draft" | "final" (novi zapisi prema zadanim postavkama dobivaju final). Za novi je protokol potrebno type, date te kontakt ili valjani kontekst projekta/prekretnice. contactExternalId: null uklanja kontakt samo kada kontekst projekta/prekretnice ostane prisutan. Interne bilješke projekta stoga se mogu stvarati i čitati bez izmišljanja korisnika. Skica/završno opisuje stanje bilješke i nikada ne šalje komunikaciju. Privatni zadaci i protokoli ostaju nedostupni.

Sudionici projekta​

Projektni participants sadrži kumulativne upise ili ažuriranja identificirane referencom contact, na primjer:

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

Sudionici označavaju potencijalne ili postojeće korisnike povezane s projektom; odgovorne osobe koriste se dodjelama. Izostavljeni sudionici, prazan niz i izostavljena polja sudionika zadržavaju postojeće podatke. null uklanja role, notes ili groupScoutelloId. Duplikati razriješenih kontakata unutar jednog sadržaja se odbijaju. Grupe već moraju pripadati odabranom projektu; očitanja uključuju participantGroups (ID/naziv), kao i ID-jeve sudionika, kontakte, ulogu, bilješke i ID grupe. Uklanjanje sudionika ili stvaranje grupa trenutačno je dostupno na nadzornoj ploči.

Skupno stvaranje ili ažuriranje zapisa​

Zapišite do 100 zapisa pomoću skupne rute resursa:

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

Skupni zapisi zadataka najprije razrješavaju zapise zadataka, a zatim primjenjuju odnose nadređenih stavki i ovisnosti. Ova dvofazna obrada omogućuje da nadređeni zadatak, blokator ili blokirani zadatak referencira drugi zadatak stvoren u istoj skupini putem njegova vanjskog ID-ja, neovisno o redoslijedu zapisa.

Za polja i ograničenja validacije svakog resursa upotrijebite OpenAPI dokument. Svaki zapis mora imati stabilni externalId duljine između 1 i 200 znakova. Tretirajte ga kao neprozirni tehnički identifikator: nemojte upotrebljavati adresu e-pošte, ime, API tajnu ni druge osobne podatke. externalUpdatedAt nije obavezan, ali se snažno preporučuje kada izvorni sustav pruža pouzdanu vremensku oznaku izmjene.

Tijelo zahtjeva ograničeno je na 1 MiB. mode prema zadanim se postavkama postavlja na apply:

  • apply provjerava i zapisuje prihvaćene zapise.
  • validate provodi istu validaciju i uparivanje bez zapisivanja te vraća rezultate would_*.

Za uvoz kontakata, matchByEmail može se postaviti na true u zahtjevu. Prema zadanim se postavkama postavlja na false; vanjski ID sigurnija je granica identiteta.

Izostavljena polja zadržavaju trenutačnu vrijednost. Izričiti null briše polje koje može imati vrijednost null, a zadani prazni niz dodjela/oznaka briše taj odnos. Project participants aditivne su upsert operacije: prazan niz ostavlja popis nepromijenjenim. Upisi oznaka za kontakte, zadatke, prilike i događaje upotrebljavaju Scoutello ID-ove oznaka. Vanjski ID-ovi odnosa razrješavaju se samo putem poveznica koje pripadaju trenutačnoj integraciji, dok Scoutello korisnički ID-ovi koji se upotrebljavaju za vlasništvo ili odgovornost moraju identificirati prihvaćene članove trenutačne organizacije.

Za stvaranje prilike potreban je račun ili kontakt, a za izgubljene prilike potreban je razlog gubitka. Novčani iznosi izražavaju se u cijelim centima. Nazivi i opisi projekata i događaja čitaju se i zapisuju na jeziku konfiguriranom za organizaciju. Upisi događaja podržavaju određene datume te dnevno, tjedno ili mjesečno ponavljanje s iznimkama; razine vidljivosti objavljenih događaja i dalje podliježu Scoutello provjerama pravne spremnosti. API ne izlaže prodaju ulaznica za događaje, sudionike, medije, predloške, biltene, suradnje ni druge napredne kontrole upravljanja događajima.

Otkrivanje oznaka​

Upotrijebite krajnju točku za oznake prije navođenja tagIds:

GET /tags?entity=events&type=category

entity obavezan je i prihvaća contacts, tasks, opportunities ili events. Preslikava se na odgovarajuću pohranjenju relevantnost oznake. type nije obavezan i prihvaća category ili attribute. Odabrive kategorije mogu biti u vlasništvu organizacije ili globalne; odabrivi atributi dolaze iz Scoutellova odabranog globalnog skupa atributa. Rezultati uključuju scoutelloId, naziv lokaliziran na jeziku organizacije, type i relevancy. ID-ovi oznaka iz druge organizacije, s pogrešnom relevantnošću ili koji nisu odabrivi odbijaju zahvaćenu stavku grupnog zahtjeva.

Čitanje povijesti odlazne pošte​

Povijest e-pošte dostupna je samo za čitanje:

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

Vraća se samo e-pošta u vlasništvu organizacije sa statusom sent ili failed. Odgovori sadrže uobičajena pohranjena zaglavlja i tijelo poruke, BCC, status i vremenske oznake, reference na projekte/događaje/newslettere, ID-ove i vrste privitaka te zbirne statistike o isporuci, otvaranju, klikovima, odbijanju, pritužbama i odbijenim isporukama primateljima. Skice, e-pošta u redu čekanja ili zakazana e-pošta, redci za pojedinačne primatelje, prikazane snimke, neobrađene pogreške pružatelja i URL-ovi za preuzimanje privitaka nikada se ne izlažu. Kasnije ažuriranje isporuke primatelju pomiče efektivnu vremensku oznaku sinkronizacije e-pošte, pa se e-pošta ponovno pojavljuje u inkrementalnim čitanjima. Ne postoje rute za upis e-pošte.

Rezultat primjene može biti created, updated, linked, unchanged, stale_ignored ili rejected. Validacija koristi would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale ili rejected. Valjani skupni zahtjev vraća HTTP 200 čak i kada su pojedinačni zapisi odbijeni, stoga uvijek provjerite svaku stavku i sažetak odgovora. Zadržite odgovor requestId kada od podrške za Scoutello tražite istragu neuspjeha.

Vremenske oznake i sukobi​

Kada je prisutan externalUpdatedAt, Scoutello ga koristi za odbijanje zastarjelih promjena bez neuspjeha ostatka skupa. Rezultat stale_ignored konačan je za taj stariji sadržaj; dohvatite trenutačni zapis prije nego što odlučite poslati noviju verziju.

Vremenske oznake tretirajte kao vrijednosti u formatu UTC ISO 8601. Sačuvajte izvornu preciznost i nemojte vrijeme pokretanja posla sinkronizacije zamijeniti vremenom izmjene izvornog zapisa.

Idempotentnost​

Granica idempotentnosti jest integracija plus externalId. Scoutello uspoređuje kanonski sažetak sadržaja i neobaveznu vrijednost externalUpdatedAt, pa ponovni pokušaj istog zapisa ne stvara duplikate i može vratiti unchanged.

Uz externalUpdatedAt, ista vremenska oznaka i sadržaj znače unchanged, starija vremenska oznaka znači stale_ignored, a ista vremenska oznaka s drugačijim sadržajem predstavlja sukob verzija. Za poveznicu koja nikada nije prihvatila vremensku oznaku, isti sadržaj bez vremenske oznake i dalje ostaje unchanged, dok se promijenjeni sadržaj primjenjuje redoslijedom pristizanja. Nakon što poveznica prihvati vremensku oznaku, promijenjeni sadržaj bez externalUpdatedAt odbija se kao sukob verzija, tako da podaci bez verzioniranja ne mogu prebrisati stanje s verzijom. Zato se izričito preporučuju vremenske oznake izmjene izvora.

Revizijski trag​

Prihvaćene radnje API-ja za stvaranje, ažuriranje i sinkronizaciju samo poveznica prikazuju se u zapisima promjena za Scoutello s izvorom Public API i povezane su s odgovarajućom integracijom. Sažeci operativnih pokretanja zadržavaju ID-jeve zahtjeva i zbirne brojeve rezultata radi otklanjanja poteškoća; ne zadržavaju sadržaje zapisa ni tajne API-ja.

Pogreške i ponovni pokušaji​

Pogreške na razini zahtjeva koriste ovaj omot:

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

Ponovite zahtjev za HTTP odgovore 429 i privremene odgovore 5xx uz eksponencijalno čekanje i nasumično kašnjenje. Poštujte Retry-After ako je naveden. Mrežni kvarovi mogli su se dogoditi nakon što je Scoutello prihvatio zahtjev; ponovno slanje iste skupine sigurno je jer je svaki zapis idempotentan prema vanjskom ID-u i kanonskom sadržaju. Nemojte automatski ponavljati zahtjeve za provjeru autentičnosti, autorizaciju, validaciju, sukob verzija ili pojedinačne ishode rejected bez izmjene zahtjeva.

Preporučeni tijek dvosmjerne sinkronizacije​

  1. Tijekom postavljanja pozovite /whoami i provjerite očekivanu organizaciju i opsege.
  2. Pročitajte svaku stranicu promijenjenu od posljednje dovršene gornje granice i idempotentno primijenite te promjene u vanjskom sustavu.
  3. Pošaljite vanjske promjene na /batch-upsert koristeći stabilne vanjske ID-jeve i vremenske oznake izmjene izvornog sustava.
  4. Kontrolne točke spremite tek nakon obrade svih stranica i rezultata stavki.
  5. Sukobe rješavajte prema pravilima vlasništva izvornog sustava; nemojte oponašati brisanje slanjem praznih zapisa.

Scoutello u ovoj prvoj verziji namjerno ne nudi javnu rutu za brisanje. Pravilima brisanja ili arhiviranja upravljajte izvan API-ja dok se ne uvede dokumentirana operacija životnog ciklusa.

Društvene objave za ljudsku provjeru​

Društveni API priprema objave za imenovanu osobu koja ih pregledava. Ne može ih odobriti ni objaviti. REST i MCP koriste iste opsege i istu uslugu.

OpsegKrajnje točke u okviru /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

Nove opsege potrebno je izričito dodijeliti. Postojeće vjerodajnice ne dobivaju dodatni pristup. Upotrijebite members.read za pronalaženje korisničkih ID-jeva članova i odaberite osobu koja pregledava objave i ima dozvolu za objavljivanje (newsletter.edit). Skice ne zahtijevaju CRM kontakt ni 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"]
}]
}
}]
}

Za objavu nakon odobrenja koristite publishMode: "now" i scheduledAt: null . Svaka varijanta kanala sadrži puni tekst, postavke i poredane ID-ove medija. Otkrivanje kanala vraća podržane formate, ograničenja i postavke. Trenutačno su podržani LinkedIn profili/stranice, Facebook, Instagram i Threads. Instagram zahtijeva medije. Varijanta prihvaća do deset slika ili videozapisa.

Skupovi prihvaćaju do 100 jedinstvenih vanjskih ID-ova unutar postojećeg ograničenja zahtjeva od 1 MiB. mode: "validate" provjerava reference i verzije bez spremanja nacrta, prijenosa resursa, stvaranja obavijesti ili stavljanja posla u red. Rezultati primjene sadrže ID-ove, poveznice za pregled, verzije i rezultate po zapisu. Djelomični neuspjesi ne poništavaju uspješne povezane zapise. Neuspjela obavijest vraća upozorenje i spremljeni URL za pregled.

Prije izmjene nacrta na čekanju dohvatite draftVersion . Identična ponavljanja su idempotentna i čuvaju kasnije ljudske izmjene. Osoba koja pregledava ne može se zamijeniti unutar nacrta. Nakon odobrenja ili odbijanja koristite novi vanjski ID za novi prijedlog. Nacrte može čitati samo integracija koja ih poziva; povijest objava obuhvaća sve trajne kampanje izrađene u Scoutellu unutar organizacije, uključujući objave s nadzorne ploče, skripti i starije Scoutello objave. Povijest vanjskih kanala ne uvozi se.

Popisi koriste standardne parametre limit , cursor i updatedSince . Objave i nacrti prihvaćaju i channelId , status , after , before i search ; sačuvajte sve filtre na sljedećim stranicama kursora. Datumski filtri odnose se na vrijeme objave (ili stvaranja za nacrte koji čekaju neposrednu objavu). status nacrta filtrira status odobrenja; status objave odgovara statusu isporuke kampanje ili kanala. Čitanje vraća posljednji poznati status isporuke, neuspjehe po kanalu, javne poveznice i vremenske oznake usklađivanja. Inkrementalno čitanje nacrta odražava i promjene isporuke kampanje.

Prijenos medija​

  1. Pozovite POST /social-media/uploads s parametrima clientUploadId, filename, contentType, size u bajtovima i sha256 izvornog sadržaja u malim heksadecimalnim slovima. Podržane vrste su PNG, JPEG, WebP, MP4, WebM, QuickTime i M4V. Ograničenje veličine prijenosa iznosi 500 MiB.
  2. Pošaljite izvorne bajtove putem HTTP PUT na vraćeni upload.url uz njegova zaglavlja. URL-ovi za prijenos istječu nakon 15 minuta. Za ponovne pokušaje prijenosa iste datoteke ponovno upotrijebite clientUploadId; za istekle sesije ili druge datoteke potreban je novi ID.
  3. Pozovite POST /social-media/uploads/{assetId}/finalize s JSON tijelom {}. Završetak provjerava veličinu, vrstu, potpis i kontrolni zbroj, zamrzava privatnu kopiju i vraća ID sredstva za mediaIds. Ponovljeni završetak je siguran.

Vlasništvo nad prijenosom povezano je s organizacijom i integracijom. Nacrti mogu upućivati na dovršena sredstva iz svoje organizacije. URL-ovi za pregled privremeni su; ponovno dohvatite nacrt kako biste ih osvježili. URL-ovi za prijenos nikada se ne izdaju za dovršene objekte.

Ljudska provjera i isporuka​

Osoba koja provjerava primit će obavijest na nadzornoj ploči i moći će otvoriti objavu iz odjeljka Postings ili putem URL-a za provjeru. Uređivanje stvara drugu nepromjenjivu verziju. Odobrenje upotrebljava prikazanu verziju i kontrolni zbroj sadržaja, ponovno provjerava članstvo, kanale i sredstva te atomarno stvara jednu trajnu kampanju. Ako je predloženo vrijeme prošlo, potrebno je spremiti izričito novo vrijeme ili odabrati objavljivanje nakon odobrenja.

Ponovni pokušaji u redu čekanja ponovno upotrebljavaju kampanju i njezine potvrde platforme. Odobrene kampanje ne mogu se uređivati na mjestu. Otkazivanje putem nadzorne ploče čuva povijest odobrenja i medije; otkazivanje ne može prekinuti aktivnu distribuciju. Dohvatite nacrt ili kampanju kako biste razlikovali odobrenje od stvarne isporuke na platformi.