Scoutello API
API-ul Scoutello este un API server-to-server pentru sincronizarea bidirecțională a contactelor, sarcinilor, protocoalelor, oportunităților, proiectelor, etapelor și evenimentelor unei organizații. Acesta oferă, de asemenea, acces doar pentru citire la istoricul mesajelor trimise, căutarea membrilor cărora li se pot atribui elemente și identificarea etichetelor în funcție de entitate. În această versiune, rutele incrementale GET/list și operațiunile batch upsert idempotente sunt primitivele de sincronizare. API-ul nu oferă operațiuni de ștergere sau webhook-uri.
URL-ul de bază al API-ului este:
https://admin.scoutello.com/api/v1
Este afișat și în Setările organizației → Developer/API. Documentul OpenAPI este disponibil la:
https://admin.scoutello.com/api/v1/openapi.json
Crearea și protejarea unei chei
Pentru organizațiile modulare, modulul CRM trebuie să fie activ, pe lângă domeniile de acces necesare cheii. O cheie validă nu poate activa un modul lipsă. Solicitările returnează HTTP 403 cu codul de eroare module_not_active atunci când accesul CRM nu este disponibil. Persoanele cu drepturi de administrare a organizației pot verifica sau activa CRM în Abonament; reîncercați după activarea accesului.
Persoanele cu drepturi de administrare a organizației pot crea o integrare și o cheie API în Setările organizației → Developer/API. Cheia completă este afișată o singură dată. Copiați-o într-un manager de secrete înainte de închiderea dialogului; Scoutello nu poate afișa din nou cheia completă.
- Utilizați o integrare și o cheie separate pentru fiecare sistem extern și mediu.
- Acordați doar domeniile de acces de care are nevoie sistemul respectiv.
- Nu introduceți niciodată o cheie în codul din browser, într-un URL, în controlul versiunilor, în jurnale, în mesajele trimise serviciului de asistență sau în stocarea din partea clientului.
- Rotiți cheile conform unui program stabilit. Atunci când o integrare activă este rotită, cheia de înlocuire funcționează imediat, iar cheia anterioară rămâne valabilă cel mult 15 minute, pentru ca sistemul extern să poată face schimbarea fără întreruperi. Se aplică în continuare orice termen de expirare stabilit anterior, astfel încât cheia anterioară poate înceta să funcționeze mai devreme.
- Dacă este posibil ca o cheie să fi fost expusă, suspendați integrarea înainte de rotirea cheii. Suspendarea respinge temporar toate cheile integrării. Rotirea în timp ce integrarea este suspendată nu oferă nicio perioadă de suprapunere: cheia anterioară rămâne dezactivată, iar cheia de înlocuire rămâne dezactivată până la reluarea integrării.
- Revocați permanent întreaga integrare atunci când deconectați un sistem extern. Revocarea dezactivează toate cheile acesteia și nu poate fi anulată.
Trimiteți cheia la fiecare solicitare autentificată:
Authorization: Bearer YOUR_API_KEY
Autentificarea Bearer este preferată. Clienții care nu pot seta Authorization pot utiliza în schimb x-api-key. Nu trimiteți ambele antete; solicitările cu valori diferite în cele două antete sunt respinse.
API-ul este destinat clienților backend și nu permite accesul browserelor de pe alte origini.
Utilizați GET /whoami după configurarea unei chei pentru a verifica integrarea, organizația, domeniile de acces și limitele cheii fără a prelua date personale ale utilizatorilor.
Domenii de acces
| Domeniu | Permite |
|---|---|
contacts.read | Listarea și preluarea contactelor. Sunt excluse contactele conturilor organizației și contactele membrilor cu acces. |
contacts.write | Validarea și aplicarea operațiunilor de creare sau actualizare a contactelor. |
tasks.read | Listarea și preluarea sarcinilor care nu sunt private. |
tasks.write | Validarea și aplicarea operațiunilor de creare sau actualizare a sarcinilor. |
protocols.read | Listarea și preluarea protocoalelor care nu sunt private. |
protocols.write | Validarea și aplicarea operațiunilor de creare sau actualizare a protocoalelor. |
opportunities.read | Listarea și preluarea oportunităților. |
opportunities.write | Validarea și aplicarea operațiunilor de creare sau actualizare a oportunităților. |
projects.read | Listarea și preluarea proiectelor. |
projects.write | Validarea și aplicarea operațiunilor de creare sau actualizare a proiectelor și participanților. |
milestones.read | Listarea și preluarea etapelor importante ale proiectelor. |
milestones.write | Validarea și aplicarea operațiunilor de creare sau actualizare a etapelor importante. |
members.read | Listarea membrilor acceptați, cu Customer ID, User ID și numele afișat al membrului. |
events.read | Listarea și preluarea evenimentelor și a programărilor de bază. |
events.write | Validarea și aplicarea operațiunilor de creare sau actualizare a evenimentelor. |
mails.read | Citirea istoricului mesajelor de e-mail trimise și eșuate, deținute de organizație. |
mail-drafts.read | Citirea schițelor independente de aprobare a e-mailurilor și a stării livrării pentru această integrare. |
mail-drafts.write | Pregătirea sau modificarea schițelor de e-mail pentru aprobarea de către o persoană; aprobarea sau trimiterea nu este permisă. |
tags.read | Identificarea etichetelor selectabile pentru tipurile de entități acceptate. |
Sarcinile și protocoalele private nu sunt niciodată returnate de acest API. Lipsa unui domeniu returnează o eroare de autorizare; nu este tratată ca un rezultat gol.
Un contact CRM care nu este membru poate fi citit și menționat chiar și atunci când este asociat cu un cont Scoutello. Răspunsul conține doar câmpurile CRM ale organizației și nu include niciodată date de identificare sau câmpuri de acces ale utilizatorului. Contactele cu rol, permisiuni, invitație, acceptare sau statut de cont al organizației rămân ascunse. Editarea unui contact asociat cu un cont de utilizator rămâne interzisă (protected_contact), inclusiv atunci când câmpurile CRM nu se modifică. Pentru a menționa un contact existent și accesibil dintr-o sarcină sau dintr-un protocol, contacts.write poate stabili asocierea externă folosind doar externalId, scoutelloId și, opțional, externalUpdatedAt. Actualizările ulterioare limitate la metadatele asocierii folosesc externalId și, opțional, externalUpdatedAt; omiteți scoutelloId de inițializare după realizarea asocierii. Acest lucru nu modifică niciodată contactul sau utilizatorul asociat. Asocierea membrilor acceptați folosește proiecția separată members.read.
Cheile noi folosesc prefixul sctl_api_ și încep doar cu contacts.write. Orice alt domeniu necesită acordare explicită, iar o persoană cu drepturi de administrare a organizației trebuie să îl autorizeze la crearea sau reînnoirea unei chei. Credentialele existente își păstrează domeniile actuale și rămân valabile.
Contacte asociate proiectelor și ciorne de e-mail
Operațiunile de tip upsert pentru contacte acceptă perechi opționale projectScoutelloId / projectExternalId și companyScoutelloId / companyExternalId (alegeți câte una din fiecare pereche). Contactul, relația cu compania și apartenența la proiect sunt salvate atomic pentru fiecare element. Adăugarea apartenenței la un proiect necesită projects.write; referințele omise păstrează celelalte relații și apartenențe. Datele citite din detaliile contactului includ projectParticipations atunci când projects.read este acordat. Agenții proiectelor de vânzări trebuie să includă explicit referința proiectului, chiar și atunci când reutilizează un contact.
Ciornele independente folosesc sistemul existent de aprobare umană, fără o execuție de flux de lucru:
| Metodă | Cale | Scop |
|---|---|---|
| GET | /mail-drafts | Ciorne deținute de integrare, paginate; filtre opționale projectScoutelloId și status. |
| GET | /mail-drafts/{scoutelloId} | Versiunea curentă, linkul de examinare, hash-ul conținutului, starea aprobării/trimiterii și ID-ul final al mesajului. |
| GET | /mail-drafts/external/{externalId} | Căutarea unui ID extern stabil al integrării. |
| POST | /mail-drafts/batch-upsert | Validarea sau aplicarea pregătirii ciornei. |
Pregătirea ciornei necesită mail-drafts.write, contacts.read și projects.write. Contactul referit devine participant la proiect. Persoana care aprobă trebuie să fie un membru acceptat al organizației, cu permisiunea de a edita e-mailuri. Selectarea expeditorului folosește setările existente ale organizației sau ale expeditorului personal, permise pentru membrul respectiv; adresele From arbitrare nu sunt acceptate.
{
"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."
}
}]
}
Verificați fiecare rezultat al validării înainte de a repeta operațiunea cu mode: "apply". Citiți ID-ul rezultat pentru a obține reviewUrl, draftVersion, contentHash, status, dispatchStatus și mailScoutelloId. Folosiți expectedVersion: 0 numai pentru creare, iar pentru revizii utilizați versiunea curentă returnată. Contextul și persoana care aprobă sunt imuabile; ciornele examinate sau expediate resping conținutul modificat. Reîncercările identice returnează ciorna originală.
Ciornele apar în filele Email ale proiectului/contactului și în notificările tabloului de bord pentru aprobare. Pregătirea prin API nu trimite e-mailuri, inclusiv e-mailuri de notificare; comportamentul existent al e-mailurilor de notificare din fluxurile de lucru rămâne neschimbat. Persoana desemnată poate edita destinatarii, subiectul, corpul și atașamentele acceptate, poate salva versiunea, apoi poate selecta Aprobă și trimite. Integrările nu pot efectua aprobarea sau expedierea. Livrarea eșuată sau ambiguă nu este niciodată reîncercată automat. La convertirea ciornelor bazate pe protocoale, păstrați protocoalele și indicați încrucișat înlocuitorii acestora.
Acces MCP
Aceeași cheie API și aceleași domenii de acces Scoutello pot fi utilizate cu endpointul MCP HTTP cu streaming:
https://admin.scoutello.com/api/v1/mcp
Configurați clientul MCP pentru a trimite Authorization: Bearer YOUR_API_KEY. Adresa URL /api/mcp moștenită rămâne un alias de compatibilitate pentru cale, însă clienții noi ar trebui să utilizeze endpointul cu versiuni. Credentialele sctl_mcp_ anterioare nu sunt acceptate; înlocuiți-le cu o cheie de integrare API Scoutello.
Instrumentele MCP corespund direct contractului REST și utilizează aceleași scheme de rulare, verificări ale entității, ciclu de viață al integrării, limită de rată și metode de serviciu. De exemplu, contacts_list, contacts_get, contacts_get_by_external_id și contacts_batch_upsert reflectă cele patru rute pentru contacte. Același model se aplică pentru sarcini, protocoale, oportunități, proiecte, etape și evenimente; mailul expune mails_list și mails_get, membrii expun members_list, iar etichetele expun tags_list.
Serverul anunță doar instrumentele permise de domeniile de acces ale cheii curente. O cheie cu contacts.read poate descoperi instrumentele pentru citirea contactelor, dar nu și contacts_batch_upsert; o cheie cu contacts.write primește instrumentul pentru actualizare în lot, dar nu și instrumentele de citire. whoami este disponibil întotdeauna. Instrumentele de scriere au aceleași efecte imediate ca echivalentele REST, așadar utilizați mode: "validate" atunci când apelantul trebuie să inspecteze un lot fără să îl aplice.
MCP funcționează, de asemenea, între servere și nu activează accesul browserului între origini. Transportul său JSON-RPC necesită o adresă URL dedicată, astfel încât nu poate partaja adresa URL a unei resurse REST individuale, chiar dacă autentificarea și comportamentul datelor sunt comune.
Pentru instrucțiuni complete privind configurarea clientului, verificarea, corespondența instrumentelor și depanarea, consultați ghidul de integrare MCP.
Citirea înregistrărilor
Contactele, sarcinile, protocoalele, oportunitățile, proiectele, etapele și evenimentele utilizează aceleași rute de citire:
GET /contacts?limit=50&updatedSince=2026-09-01T00:00:00.000Z
GET /contacts/{scoutelloId}
GET /contacts/external/{externalId}
Înlocuiți contacts cu tasks, protocols, opportunities, projects, milestones sau events pentru celelalte resurse de sincronizare. externalId apare într-un DTO de citire atunci când înregistrarea a fost asociată de această integrare.
Un răspuns de tip listă are acest înveliș:
{
"data": [],
"page": {
"nextCursor": null,
"hasMore": false,
"snapshotAt": "2026-09-01T12:00:00.000Z"
},
"requestId": "request-id"
}
limit trebuie să fie între 1 și 100. Rezultatele sunt ordonate după momentul efectiv în care s-a modificat reprezentarea lor în API-ul public și apoi după ID-ul Scoutello. Acest moment efectiv poate fi ulterior valorii updatedAt a entității returnate atunci când s-au modificat metadatele legăturii de integrare. Cursorii sunt opaci: stocați-i și trimiteți-i neschimbați și nu deduceți semnificații din conținutul lor.
Primul răspuns stabilește snapshotAt pentru parcurgerea respectivă. Urmați nextCursor până când hasMore este false înainte de a începe o altă citire incrementală. Astfel, modificarea înregistrărilor în timpul paginării nu destabilizează parcurgerea curentă.
Pentru sincronizarea incrementală, parcurgeți fiecare pagină a cursorului, apoi salvați snapshotAt al parcurgerii ca marcaj temporal superior. Trimiteți-l ca valoare updatedSince ISO 8601 la următoarea parcurgere. Limita inferioară este inclusivă, astfel încât repetarea unui instantaneu finalizat poate returna înregistrări de la limită, dar nu le poate omite.
Un răspuns pentru o singură înregistrare are acest înveliș:
{
"data": {},
"requestId": "request-id"
}
Răspunsurile pentru un singur contact includ și un array relations. Fiecare relație își păstrează ID-ul relației Scoutello, momentul creării, tipul, notițele și referințele connectedFrom și connectedTo către contacte. Referințele către contacte conțin ID-ul Scoutello și ID-ul extern al acestei integrări, atunci când există. Contactele excluse de limita de confidențialitate privind accesul organizației a API-ului nu sunt expuse prin relații.
Răspunsul pentru lista de contacte rămâne compact și nu include relații; pentru detalii despre relații, utilizați una dintre rutele pentru un singur contact.
Filtre de lucru și domeniul cursorului
Listele de contacte acceptă search, type (person, company, supplier, other), status și tagIds. Căutarea elimină spațiile de la început și de la sfârșit, nu ține cont de litere mari și mici și este limitată la 200 de caractere / 10 tokenuri separate prin spații albe. Fiecare token trebuie să apară în cel puțin unul dintre firstName, lastName sau companyName, inclusiv în numele de companii istorice stocate în lastName. Caractere precum % și _ sunt potrivite literal. Etichetele folosesc potrivirea oricăruia dintre elemente, cu 1–50 de ID-uri. Toate filtrele furnizate se combină cu AND. REST codifică ID-urile etichetelor ca parametri repetați; MCP furnizează un array:
GET /contacts?search=Hamburg%20Hotel&type=company&status=prospect&tagIds=tag-one&tagIds=tag-two
Cursorii pentru contacte sunt asociați cu organizația, integrarea și fiecare filtru. Păstrați filtrele la fiecare pagină; modificarea unui filtru invalidează cursorul. Ordinea și duplicatele etichetelor, precum și ordinea, literele mari și mici și spațiile albe ale tokenurilor de căutare nu modifică filtrul efectiv.
Rutele listei de lucru acceptă următoarele filtre suplimentare; alte combinații de resurse/câmpuri sunt respinse:
| Resursă | Filtre |
|---|---|
| Tasks | projectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter |
| Protocols | projectScoutelloId, milestoneScoutelloId, status (draft sau final) |
| Opportunities | projectScoutelloId, stage, ownerScoutelloUserId |
| Projects | status, assignedContactScoutelloId |
| Milestones | projectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter |
dueBefore este exclusiv; dueAfter este inclusiv. Acestea compară data scadentă a sarcinii sau data de final a etapei; înregistrările fără data respectivă nu corespund. Furnizați date și ore ISO care includ fusul orar. Toate filtrele se aplică înainte de paginare. Continuați un cursor folosind exact aceleași filtre, inclusiv updatedSince, și aceeași organizație/integrare. Dimensiunea paginii se poate modifica. Cursorii vechi fără domeniu trebuie reluați de la marcajul temporal high-water salvat după această versiune.
Proiecte, etape, atribuiri și note
GET /members (MCP members_list) folosește paginarea standard și necesită members.read. Returnează scoutelloId (ID-ul membrului Customer), scoutelloUserId (ID-ul User) și displayName. Sunt afișați doar membrii acceptați ai organizației care au un rol; căutarea nu expune adrese de e-mail sau permisiuni.
Tasks acceptă assignedScoutelloUserIds; opportunities folosesc ownerScoutelloUserId. Projects și milestones folosesc assignedContacts: [{"scoutelloId":"member-customer-id"}]. Atribuirile necesită membri acceptați ai organizației asociate acreditării. Atribuirile omise rămân neschimbate; [] le elimină. Importurile de proiecte, etape, sarcini și protocoale sunt silențioase: nu trimit notificări sau comunicări privind atribuirea.
Evenimentul assignedContacts acceptă contacte CRM ușor de identificat și membri acceptați furnizați prin ID-ul de membru Customer. Membrii acceptați rămân indisponibili ca referințe obișnuite de contacte CRM sau ca ținte de linkuri externe; pentru responsabilitatea echipei, utilizați câmpul de atribuire a membrului.
Creați repere cu un name și fie projectScoutelloId, fie projectExternalId. Acestea acceptă description (Markdown), status (open, in_progress, completed, closed), startDate/endDate care acceptă valori nule, order (implicit 0) și assignedContacts. Datele de sfârșit nu pot fi anterioare datelor de început. Fiecare reper are un link extern stabil, asociat integrării. Proiectul reperului nu poate fi schimbat prin API. Operațiunile de creare și actualizare localizează numele și descrierea în limba organizației.
Sarcinile și protocoalele acceptă referințe la proiect, reper și oportunitate ca <entity>ScoutelloId sau <entity>ExternalId, de exemplu milestoneExternalId. Furnizați o singură formă pentru fiecare relație, inclusiv la ștergere folosind null. Toate relațiile trebuie să aparțină organizației asociate acreditării. O referință care conține doar reperul deduce proiectul; un proiect contradictoriu sau ștergerea explicită a unui proiect, păstrând în același timp reperul, este respins(ă). O oportunitate asociată unui proiect trebuie să corespundă proiectului activității. Relațiile omise păstrează valorile curente; null explicit șterge o relație atunci când contextul rămas este valid. Răspunsurile de citire expun ambele forme de ID și atribuirile sarcinilor.
Planificarea sarcinilor și fluxurile de lucru
status al unei sarcini este cheia imuabilă a unui statut din fluxul de lucru efectiv al sarcinii, nu o enumerare fixă. Citiți fluxurile de lucru disponibile la nivel de organizație și proiect cu GET /task-workflows, folosind domeniul tasks.read. Fiecare statut include cheia, eticheta, type al ciclului de viață (backlog, unstarted, started, completed sau cancelled), culoarea, ordinea, indicatorul de valoare implicită și starea de arhivare. Înregistrările proiectelor indică dacă fluxul de lucru al organizației este moștenit. Configurarea fluxurilor de lucru rămâne administrată din tabloul de bord.
Sarcinile acceptă priority care acceptă valori nule (low, medium, high sau urgent) și estimatedEffortMinutes, precum și startDate și dueDate care acceptă valori nule. Răspunsurile de citire ale sarcinilor includ statusType denormalizat, referința la sarcina-părinte, referințe compacte la subsarcini și referințe blockedBy / blocks.
Creați sau actualizați o subactivitate pe un singur nivel folosind parentTaskScoutelloId sau parentTaskExternalId; null o promovează la activitate de nivel superior. Dependențele folosesc tablouri de referințe { "scoutelloId": "..." } sau { "externalId": "..." } în blockedBy și blocks. Câmpurile de relație omise le păstrează pe cele existente, iar un tablou de dependențe gol elimină relațiile din direcția respectivă. API-ul respinge subactivitățile imbricate, dependențele părinte-copil, dependențele între organizații, duplicatele, referințele proprii și ciclurile directe sau tranzitive.
Filtrele listei de activități acceptă un flux de lucru exact status, un ciclu de viață statusType, priority, parentState (top_level, subtask sau parent) și blockedState (blocked, blocking sau unblocked).
Protocoalele acceptă, de asemenea, status: "draft" | "final" (înregistrările noi primesc implicit final). Un protocol nou necesită type, date și fie un contact, fie un context valid de proiect/etapă. contactExternalId: null elimină contactul numai atunci când rămâne contextul de proiect/etapă. Astfel, notele interne ale proiectului pot fi create și citite fără inventarea unui client. Schița/final descrie starea notei și nu trimite niciodată o comunicare. Activitățile și protocoalele private rămân inaccesibile.
Participanții proiectului
participants al proiectului conține operațiuni de tip upsert aditive, identificate printr-o referință contact, de exemplu:
{
"externalId": "gtm:hotels",
"participants": [{
"contact": {"scoutelloId": "prospect-contact-id"},
"role": "Potential pilot",
"notes": "Existing warm lead; qualify the next step.",
"groupScoutelloId": null
}]
}
Participanții descriu potențialii clienți/clienții asociați unui proiect; membrii responsabili sunt gestionați prin atribuiri. Participanții omişi, un tablou gol și câmpurile participanților omise păstrează datele existente. null elimină role, notes sau groupScoutelloId. Contactele rezolvate duplicate din aceeași încărcare sunt respinse. Grupurile trebuie să aparțină deja proiectului selectat; citirile includ participantGroups (ID/nume), precum și ID-urile participanților, contactele, rolul, notele și ID-ul grupului. Eliminarea participanților sau crearea grupurilor este disponibilă în prezent în tabloul de bord.
Operațiuni upsert în lot pentru înregistrări
Scrieți până la 100 de înregistrări folosind ruta de lot a resursei:
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"
}
]
}
Loturile de activități rezolvă înregistrările activităților înainte de aplicarea relațiilor de tip părinte și a dependențelor. Această procesare în două faze permite unei activități părinte, blocante sau blocate să facă referire la o altă activitate creată în același lot prin ID-ul său extern, indiferent de ordinea înregistrărilor.
Utilizați documentul OpenAPI pentru câmpurile și constrângerile de validare ale fiecărei resurse. Fiecare înregistrare trebuie să aibă un externalId stabil, cu lungimea între 1 și 200 de caractere. Tratați-l ca pe un identificator tehnic opac: nu utilizați o adresă de e-mail, un nume, un secret API sau alte date cu caracter personal. externalUpdatedAt este opțional, dar recomandat cu fermitate atunci când sistemul sursă furnizează un marcaj temporal fiabil al modificării.
Corpul solicitării este limitat la 1 MiB. mode are implicit valoarea apply:
applyvalidează și scrie înregistrările acceptate.validateefectuează aceeași validare și asociere fără a scrie date, returnând rezultatewould_*.
Pentru importurile de contacte, matchByEmail poate fi setat la true în solicitare. Valoarea implicită este false; identificatorul extern reprezintă limita de identitate mai sigură.
Câmpurile omise păstrează valoarea curentă. Un null explicit golește un câmp care acceptă valoarea nulă, iar un tablou gol de atribuiri/etichete furnizat golește relația respectivă. Project participants sunt upserturi aditive: un tablou gol nu modifică lista de persoane. Scrierile de etichete pentru contacte, sarcini, oportunități și evenimente utilizează ID-urile etichetelor Scoutello. Identificatorii externi ai relațiilor sunt rezolvați numai prin legăturile care aparțin integrării curente, iar ID-urile de utilizator Scoutello utilizate pentru proprietate sau responsabilitate trebuie să identifice membri acceptați ai organizației curente.
Crearea oportunităților necesită un cont sau un contact, iar oportunitățile pierdute necesită un motiv al pierderii. Sumele monetare utilizează cenți întregi. Numele și descrierile proiectelor și evenimentelor sunt citite și scrise în limba configurată a organizației. Scrierile evenimentelor acceptă date explicite și recurență zilnică, săptămânală sau lunară, cu excluderi; nivelurile de vizibilitate publicate rămân supuse controalelor Scoutello privind pregătirea juridică. API-ul nu expune funcții de vânzare a biletelor la evenimente, participanți, materiale media, șabloane, buletine informative, colaborări sau alte controale avansate de gestionare a evenimentelor.
Descoperirea etichetelor
Utilizați endpointul pentru etichete înainte de a furniza tagIds:
GET /tags?entity=events&type=category
entity este obligatoriu și acceptă contacts, tasks, opportunities sau events. Acesta se mapează la relevanța etichetei stocate corespunzătoare. type este opțional și acceptă category sau attribute. Categoriile selectabile pot aparține organizației sau pot fi globale; atributele selectabile provin din setul global de atribute gestionat de Scoutello. Rezultatele includ scoutelloId, numele localizat în limba organizației, type și relevancy. ID-urile etichetelor care aparțin altei organizații, au relevanța greșită sau nu sunt selectabile resping elementul de lot afectat.
Citirea istoricului mesajelor trimise
Istoricul e-mailurilor este disponibil doar pentru citire:
GET /mails?updatedSince=2026-09-01T00:00:00.000Z
GET /mails/{scoutelloId}
Sunt returnate doar e-mailurile deținute de organizație, aflate în starea sent sau failed. Răspunsurile conțin antetele stocate uzuale și corpul mesajului, destinatarii BCC, starea și marcajele temporale, referințe la proiecte/evenimente/newslettere, ID-urile și tipurile atașamentelor, precum și statistici agregate privind livrarea, deschiderea, accesarea, returnarea, reclamațiile și respingerea mesajelor de către destinatari. Ciornele, e-mailurile puse în coadă sau programate, rândurile pentru fiecare destinatar, instantaneele randate, erorile brute ale furnizorului și URL-urile de descărcare a atașamentelor nu sunt niciodată expuse. O actualizare ulterioară privind livrarea către un destinatar actualizează marcajul temporal efectiv de sincronizare al e-mailului, astfel încât acesta să apară din nou în citirile incrementale. Nu există rute pentru scrierea e-mailurilor.
Un rezultat al aplicării poate fi created, updated, linked, unchanged, stale_ignored sau rejected. Validarea utilizează would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale sau rejected. O solicitare de lot validă returnează HTTP 200 chiar și atunci când anumite înregistrări sunt respinse, prin urmare trebuie verificat fiecare element și rezumatul răspunsului. Păstrați răspunsul requestId atunci când solicitați echipei de asistență Scoutello investigarea unei erori.
Marcaje temporale și conflicte
Când este prezent externalUpdatedAt, Scoutello îl utilizează pentru a respinge modificările depășite fără a eșua pentru restul lotului. Un rezultat stale_ignored este definitiv pentru payloadul mai vechi; preluați înregistrarea curentă înainte de a decide dacă să trimiteți o versiune mai nouă.
Tratați marcajele temporale ca valori UTC ISO 8601. Păstrați precizia originală și nu înlocuiți momentul în care a avut loc o operațiune de sincronizare cu momentul modificării înregistrării sursă.
Idempotență
Limita de idempotență este integrarea împreună cu externalId. Scoutello compară un hash canonic al payloadului și valoarea opțională externalUpdatedAt, astfel încât reîncercarea aceleiași înregistrări nu creează duplicate și poate returna unchanged.
Cu externalUpdatedAt, aceeași marcă temporală și același payload reprezintă unchanged, o marcă temporală mai veche reprezintă stale_ignored, iar aceeași marcă temporală împreună cu un payload diferit reprezintă un conflict de versiune. Pentru un link care nu a acceptat niciodată o marcă temporală, același payload fără marcă temporală rămâne unchanged, în timp ce un payload modificat este aplicat în ordinea sosirii. După ce un link a acceptat o marcă temporală, un payload modificat care omite externalUpdatedAt este respins ca fiind un conflict de versiune, astfel încât datele fără versiune nu pot suprascrie starea cu versiune. Din acest motiv, marcajele temporale ale modificărilor din sursă sunt recomandate cu fermitate.
Jurnal de audit
Acțiunile acceptate de API pentru creare, actualizare și sincronizare exclusivă a legăturilor apar în jurnalele de modificări Scoutello cu Public API ca sursă și sunt asociate integrării responsabile. Rezumatele operaționale ale rulărilor păstrează ID-urile solicitărilor și numărul agregat de rezultate pentru depanare; acestea nu păstrează datele înregistrărilor sau secretele API.
Erori și reîncercări
Erorile la nivel de solicitare folosesc acest format:
{
"error": {
"code": "error_code",
"message": "Safe error message",
"requestId": "request-id",
"details": {}
}
}
Reîncercați răspunsurile HTTP 429 și răspunsurile 5xx tranzitorii folosind backoff exponențial și jitter. Respectați Retry-After atunci când este prezent. Este posibil ca erorile de rețea să fi apărut după ce Scoutello a acceptat o solicitare; retrimiterea aceluiași lot este sigură, deoarece fiecare înregistrare este idempotentă pe baza ID-ului extern și a datelor canonice. Nu reîncercați automat erorile de autentificare, autorizare, validare, conflict de versiune sau rezultatele individuale rejected fără modificarea solicitării.
Bucla recomandată pentru sincronizarea bidirecțională
- Apelați
/whoamiîn timpul configurării și verificați organizația și permisiunile așteptate. - Citiți fiecare pagină modificată de la ultimul marker high-water finalizat și aplicați idempotent modificările în sistemul extern.
- Trimiteți modificările externe către
/batch-upsert, folosind ID-uri externe stabile și marcaje temporale ale modificării din sursă. - Salvați punctele de verificare numai după procesarea tuturor paginilor și rezultatelor elementelor.
- Rezolvați conflictele conform regulilor de proprietate ale sistemului sursă; nu imitați ștergerile trimițând înregistrări goale.
Scoutello nu oferă în mod deliberat o rută publică de ștergere în această primă versiune. Gestionați politicile de ștergere sau arhivare în afara API-ului până la introducerea unei operațiuni de ciclu de viață documentate.
Postări sociale pentru verificare umană
API-ul social pregătește postări pentru o persoană desemnată să le verifice. Nu le poate aproba sau publica. REST și MCP folosesc aceleași permisiuni și același serviciu.
| Permisiune | Endpointuri sub /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 |
Noile permisiuni trebuie acordate explicit. Credentialele existente nu dobândesc acces suplimentar. Folosiți members.read pentru a descoperi ID-urile utilizatorilor membri și selectați o persoană care are permisiune de publicare (newsletter.edit). Schițele nu necesită un contact CRM sau un proiect.
{
"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"]
}]
}
}]
}
Folosiți publishMode: "now" și scheduledAt: null pentru publicare după aprobare.
Fiecare variantă de canal include textul complet, setările și ID-urile media în
ordine. Descoperirea canalelor returnează formatele, limitele și setările acceptate.
Sunt acceptate profilurile/paginile LinkedIn, Facebook, Instagram și Threads.
Instagram necesită conținut media. O variantă acceptă până la zece imagini sau videoclipuri.
Loturile acceptă până la 100 de ID-uri externe unice în limita existentă a
cererii de 1 MiB. mode: "validate" verifică referințele și versiunile fără a
salva schițe, a încărca resurse, a crea notificări sau a pune lucrări în coadă.
Rezultatele aplicării includ ID-uri, linkuri de revizuire, versiuni și rezultate
pentru fiecare înregistrare. Eșecurile parțiale nu anulează înregistrările
reușite. Eșecul notificării returnează un avertisment și URL-ul de revizuire salvat.
Citiți versiunea curentă draftVersion înainte de modificarea unei schițe în așteptare. Repetările
identice sunt idempotente și păstrează modificările umane ulterioare. Persoana care revizuiește nu
poate fi schimbată în aceeași schiță. După aprobare sau respingere, folosiți un ID extern nou
pentru o propunere nouă. Schițele pot fi citite doar de integrarea apelantă. Istoricul publicării
include toate campaniile persistente create în Scoutello din organizație, inclusiv postările din
panoul de control, scripturi și postările Scoutello mai vechi. Istoricul canalelor externe nu este importat.
Listele folosesc parametrii standard limit , cursor și updatedSince . Postările și
schițele acceptă și channelId , status , after , before și search ; păstrați toate
filtrele pe paginile următoare ale cursorului. Filtrele de dată se aplică momentului publicării,
sau creării pentru schițele în așteptare cu publicare imediată. status al schiței filtrează
starea aprobării; status al postării corespunde stării de livrare a campaniei sau canalului.
Citirea oferă ultima stare de livrare cunoscută, eșecurile pe canal, linkurile publice și marcajele
temporale de reconciliere. Citirea incrementală a schițelor reflectă și schimbările livrării campaniei.
Încărcarea conținutului media
- Apelați
POST /social-media/uploadscuclientUploadId,filename,contentType,sizeîn bytes și cusha256hexazecimal cu litere mici al bytes-ilor originali. Tipurile acceptate sunt PNG, JPEG, WebP, MP4, WebM, QuickTime și M4V. Limita de încărcare este de 500 MiB. - Trimiteți bytes-ii originali prin HTTP
PUTcătreupload.urlreturnat, folosind antetele acestuia. URL-urile de încărcare expiră după 15 minute. ReutilizațiclientUploadIdpentru reîncercările aceluiași fișier; sesiunile expirate sau fișierele diferite necesită un ID nou. - Apelați
POST /social-media/uploads/{assetId}/finalizecu un corp JSON de{}. Finalizarea verifică dimensiunea, tipul, semnătura și suma de control, blochează o copie privată și returnează ID-ul activului pentrumediaIds. Finalizarea repetată nu produce efecte nedorite.
Dreptul de proprietate asupra încărcării este asociat organizației și integrării. Ciornele pot face referire la active finalizate din organizația respectivă. URL-urile de previzualizare sunt temporare; preluați din nou ciorna pentru a le reîmprospăta. URL-urile de încărcare nu sunt emise niciodată pentru obiecte finalizate.
Verificarea umană și livrarea
Persoana care efectuează verificarea primește o notificare în tabloul de bord și poate deschide postarea din Postings sau folosind URL-ul de verificare. Editarea creează o altă versiune imuabilă. Aprobarea folosește versiunea afișată și hash-ul conținutului, verifică din nou apartenența, canalele și activele și creează atomic o singură campanie persistentă. Dacă momentul propus a trecut, persoana care efectuează verificarea trebuie să salveze o oră nouă explicită sau să selecteze publicarea la aprobare.
Reîncercările din coadă reutilizează campania și confirmările platformei asociate. Campaniile aprobate nu pot fi editate pe loc. Anularea din tabloul de bord păstrează istoricul aprobării și materialele media; anularea nu poate întrerupe o trimitere activă. Interogați ciorna sau campania pentru a face diferența dintre aprobare și livrarea efectivă pe platformă.