Vai al contenuto principale

Scoutello API

L’API di Scoutello è un’API server-to-server per sincronizzare in entrambe le direzioni i contatti, le attività, i protocolli, le opportunità, i progetti, le milestone e gli eventi di un’organizzazione. Espone inoltre la cronologia di sola lettura delle email in uscita, la ricerca dei membri assegnabili e l’individuazione dei tag in base all’entità. In questa versione, le route incrementali GET/list e gli upsert batch idempotenti sono i meccanismi fondamentali per la sincronizzazione. Non espone operazioni di eliminazione né webhook.

L’URL di base dell’API è:

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

È disponibile anche in Impostazioni dell’organizzazione → Sviluppatore/API. Il documento OpenAPI è disponibile all’indirizzo:

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

Creare e proteggere una chiave​

Per le organizzazioni modulari, oltre agli ambiti richiesti dalla chiave deve essere attivo anche il modulo CRM. Una chiave valida non può attivare un modulo mancante. Le richieste restituiscono HTTP 403 con il codice di errore module_not_active quando l’accesso al CRM non è disponibile. Una persona con diritti di amministrazione dell’organizzazione può verificare o attivare il CRM in Abbonamento; riprovare dopo l’attivazione dell’accesso.

Una persona con diritti di amministrazione dell’organizzazione può creare un’integrazione e una chiave API in Impostazioni dell’organizzazione → Sviluppatore/API. La chiave completa viene mostrata una sola volta. Copiarla in un gestore di segreti prima di chiudere la finestra di dialogo; Scoutello non può mostrare nuovamente la chiave completa.

  • Usare un’integrazione e una chiave separate per ogni sistema esterno e ambiente.
  • Concedere solo gli ambiti necessari al sistema.
  • Non inserire mai una chiave nel codice del browser, in un URL, nel controllo del codice sorgente, nei log, nei messaggi all’assistenza o nello spazio di archiviazione lato client.
  • Ruotare le chiavi secondo una pianificazione. Quando un’integrazione attiva viene ruotata, la chiave sostitutiva funziona immediatamente e la chiave precedente rimane valida per non più di 15 minuti, così il sistema esterno può effettuare il passaggio senza interruzioni. Un’eventuale scadenza precedente continua ad applicarsi, quindi la chiave precedente potrebbe smettere di funzionare prima.
  • Se una chiave potrebbe essere stata esposta, mettere in pausa l’integrazione prima di ruotarla. La messa in pausa rifiuta temporaneamente tutte le chiavi dell’integrazione. Una rotazione durante la pausa non prevede sovrapposizione: la chiave precedente resta disabilitata e quella sostitutiva rimane disabilitata finché l’integrazione non viene ripresa.
  • Revocare definitivamente l’intera integrazione quando si scollega un sistema esterno. La revoca disabilita tutte le relative chiavi e non può essere annullata.

Inviare la chiave in ogni richiesta autenticata:

Authorization: Bearer YOUR_API_KEY

È preferibile l’autenticazione Bearer. I client che non possono impostare Authorization possono usare x-api-key. Non inviare entrambe le intestazioni; le richieste con valori diversi nelle due intestazioni vengono rifiutate.

L’API è destinata ai client backend e non abilita l’accesso browser cross-origin.

Usare GET /whoami dopo aver configurato una chiave per verificare l’integrazione, l’organizzazione, gli ambiti e i limiti della chiave senza recuperare dati personali delle persone.

Ambiti​

AmbitoConsente
contacts.readElencare e recuperare i contatti. I contatti dell'account dell'organizzazione e i contatti dei membri con accesso sono esclusi.
contacts.writeConvalidare e applicare gli upsert dei contatti.
tasks.readElencare e recuperare le attività non private.
tasks.writeConvalidare e applicare gli upsert delle attività.
protocols.readElencare e recuperare i protocolli non privati.
protocols.writeConvalidare e applicare gli upsert dei protocolli.
opportunities.readElencare e recuperare le opportunità.
opportunities.writeConvalidare e applicare gli upsert delle opportunità.
projects.readElencare e recuperare i progetti.
projects.writeConvalidare e applicare gli upsert di progetti e partecipanti.
milestones.readElencare e recuperare le milestone dei progetti.
milestones.writeConvalidare e applicare gli upsert delle milestone.
members.readElencare i membri accettati mostrando esclusivamente l'ID cliente del membro, l'ID utente e il nome visualizzato.
events.readElencare e recuperare gli eventi e i calendari principali.
events.writeConvalidare e applicare gli upsert degli eventi.
mails.readLeggere la cronologia della posta in uscita inviata e non recapitata di proprietà dell'organizzazione.
mail-drafts.readLeggere le bozze autonome di approvazione delle email e lo stato di consegna di questa integrazione.
mail-drafts.writePreparare o modificare bozze di email per l'approvazione da parte di persone; non approvare né inviare mai.
tags.readIndividuare i tag selezionabili per i tipi di entità supportati.

Le attività e i protocolli privati non vengono mai restituiti da questa API. Se manca un ambito, viene restituito un errore di autorizzazione; non viene trattato come un risultato vuoto.

Un contatto CRM non membro può essere letto e referenziato anche quando è collegato a un accesso Scoutello. La risposta contiene esclusivamente i campi CRM dell'organizzazione, mai l'identità dell'utente o i campi relativi all'accesso. I contatti con un ruolo, autorizzazioni, invito, accettazione o stato di account dell'organizzazione restano nascosti. La modifica di un contatto collegato a un accesso resta vietata (protected_contact), inclusi i campi CRM altrimenti invariati. Per fare riferimento a un contatto leggibile esistente da un'attività/protocollo, contacts.write può stabilire il collegamento esterno utilizzando solo externalId, scoutelloId e externalUpdatedAt opzionale. Gli aggiornamenti successivi dei soli metadati del collegamento utilizzano externalId e externalUpdatedAt opzionale; omettere scoutelloId di inizializzazione una volta stabilito il collegamento. Questo non modifica mai il contatto né il relativo utente. L'assegnazione di membri accettati utilizza la proiezione separata members.read.

Le nuove chiavi usano il prefisso sctl_api_ e iniziano solo con contacts.write. Ogni altro ambito richiede un consenso esplicito che una persona con diritti di amministrazione dell’organizzazione deve concedere durante la creazione o la rotazione di una chiave. Le credenziali esistenti mantengono gli ambiti attuali e restano valide.

Contatti associati ai progetti e bozze email​

Gli upsert dei contatti accettano le coppie facoltative projectScoutelloId / projectExternalId e companyScoutelloId / companyExternalId (sceglierne una per coppia). Il contatto, la relazione con l’azienda e l’appartenenza al progetto vengono salvati atomicamente per ogni elemento. L’aggiunta dell’appartenenza a un progetto richiede projects.write; i riferimenti omessi preservano le altre relazioni e appartenenze. Le risposte di lettura dei dettagli del contatto includono projectParticipations quando projects.read è concesso. Gli agenti dei progetti di vendita devono includere esplicitamente il riferimento al progetto, anche quando riutilizzano un contatto.

Le bozze indipendenti usano il sistema esistente di approvazione umana, senza esecuzione di un workflow:

MetodoPercorsoScopo
GET/mail-draftsBozze di proprietà dell’integrazione con paginazione; filtri facoltativi projectScoutelloId e status.
GET/mail-drafts/{scoutelloId}Versione attuale, link per la revisione, hash del contenuto, stato di approvazione/invio e ID email definitivo.
GET/mail-drafts/external/{externalId}Ricerca di un ID esterno stabile dell’integrazione.
POST/mail-drafts/batch-upsertConvalida o applicazione della preparazione della bozza.

La preparazione della bozza richiede mail-drafts.write, contacts.read e projects.write. Il contatto indicato diventa partecipante al progetto. La persona approvatrice deve essere una persona membro dell’organizzazione accettata, con autorizzazione a modificare le email. La selezione del mittente utilizza le impostazioni esistenti del mittente dell’organizzazione o personali consentite per tale membro; non vengono accettati indirizzi From arbitrari.

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

Esaminare ogni risultato della convalida prima di ripetere l’operazione con mode: "apply". Leggere l’ID risultante per ottenere reviewUrl, draftVersion, contentHash, status, dispatchStatus e mailScoutelloId. Utilizzare expectedVersion: 0 solo per la creazione e la versione restituita attualmente per le revisioni. Il contesto e la persona approvatrice sono immutabili; le bozze revisionate o inviate rifiutano contenuti modificati. I tentativi identici restituiscono la bozza originale.

Le bozze compaiono nelle schede Email del progetto/contatto e nelle notifiche di approvazione della dashboard. La preparazione tramite API non invia email, comprese le email di notifica; il comportamento esistente delle email di notifica del flusso di lavoro rimane invariato. La persona assegnata può modificare destinatari, oggetto, corpo e allegati supportati, salvare la versione, quindi Approvare e inviare. Le integrazioni non possono eseguire l’approvazione o l’invio. La consegna fallita o ambigua non viene mai ritentata alla cieca. Quando si convertono bozze basate su protocolli, preservare i protocolli e inserire riferimenti incrociati alle relative sostituzioni.

Accesso MCP​

La stessa chiave API e gli stessi ambiti di Scoutello possono essere utilizzati con l’endpoint MCP HTTP trasmissibile:

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

Configurare il client MCP affinché invii Authorization: Bearer YOUR_API_KEY. L’URL /api/mcp legacy rimane un alias di compatibilità del percorso, ma i nuovi client devono utilizzare l’endpoint con versione. Le credenziali sctl_mcp_ precedenti non sono accettate; sostituirle con una chiave di integrazione API di Scoutello.

Gli strumenti MCP corrispondono direttamente al contratto REST e utilizzano gli stessi schemi di runtime, controlli del tenant, ciclo di vita dell’integrazione, limiti di frequenza e metodi di servizio. Ad esempio, contacts_list, contacts_get, contacts_get_by_external_id e contacts_batch_upsert rispecchiano le quattro route dei contatti. Lo stesso schema si applica a attività, protocolli, opportunità, progetti, milestone ed eventi; mail espone mails_list e mails_get, i membri espongono members_list, mentre i tag espongono tags_list.

Il server pubblicizza solo gli strumenti consentiti dagli ambiti della chiave corrente. Una chiave con contacts.read può rilevare gli strumenti di lettura dei contatti, ma non contacts_batch_upsert; una chiave con contacts.write ottiene lo strumento di aggiornamento batch, ma non gli strumenti di lettura. whoami è sempre disponibile. Gli strumenti di scrittura producono gli stessi effetti immediati dei relativi equivalenti REST; utilizzare quindi mode: "validate" quando occorre ispezionare un batch senza applicarlo.

MCP è inoltre server-to-server e non abilita l’accesso browser cross-origin. Il relativo trasporto JSON-RPC richiede un URL dedicato, quindi non può condividere l’URL di una singola risorsa REST, anche se autenticazione e comportamento dei dati sono condivisi.

Per la configurazione completa del client, la verifica, la mappatura degli strumenti e le istruzioni per la risoluzione dei problemi, consultare la guida all’integrazione MCP.

Lettura dei record​

Contatti, attività, protocolli, opportunità, progetti, milestone ed eventi utilizzano le stesse route di lettura:

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

Sostituire contacts con tasks, protocols, opportunities, projects, milestones o events per le altre risorse di sincronizzazione. externalId compare in un DTO di lettura quando il record è stato collegato da questa integrazione.

Una risposta di elenco ha questo involucro:

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

limit deve essere compreso tra 1 e 100. I risultati sono ordinati in base all'ora effettiva in cui è cambiata la loro rappresentazione nell'API pubblica e poi in base all'ID Scoutello. Questa ora effettiva può essere successiva a quella dell'entità restituita updatedAt quando cambiano i metadati del collegamento all'integrazione. I cursori sono opachi: conservarli e inviarli senza modificarli e non dedurne il significato dal contenuto.

La prima risposta fissa snapshotAt per quella scansione. Seguire nextCursor finché hasMore non è false prima di avviare un'altra lettura incrementale. In questo modo si impedisce che i record modificati durante la paginazione rendano instabile la scansione corrente.

Per la sincronizzazione incrementale, elaborare ogni pagina del cursore e quindi salvare snapshotAt di quella scansione come timestamp di riferimento massimo. Passarlo come valore updatedSince ISO 8601 nella scansione successiva. Il limite inferiore è inclusivo, quindi ripetere uno snapshot completato può restituire i record al limite, ma non può saltarli.

Una risposta per singolo record ha questo involucro:

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

Le risposte per singolo contatto includono anche un array relations. Ogni relazione conserva l'ID della relazione Scoutello, l'ora di creazione, il tipo, le note e i riferimenti ai contatti connectedFrom e connectedTo. I riferimenti ai contatti contengono l'ID Scoutello e l'ID esterno di questa integrazione, quando disponibile. I contatti esclusi dal limite di privacy relativo all'accesso dell'organizzazione all'API non vengono esposti tramite le relazioni. La risposta dell'elenco dei contatti rimane compatta e non include le relazioni; usare una delle route per singolo contatto quando sono necessari i dettagli della relazione.

Filtri di lavoro e ambito del cursore​

Gli elenchi dei contatti accettano search, type (person, company, supplier, other), status e tagIds. La ricerca rimuove gli spazi superflui, non distingue tra maiuscole e minuscole ed è limitata a 200 caratteri / 10 token separati da spazi bianchi. Ogni token deve comparire in almeno uno tra firstName, lastName o companyName, inclusi i nomi aziendali precedenti memorizzati in lastName. Caratteri come % e _ vengono confrontati letteralmente. I tag usano la corrispondenza any-of con 1–50 ID. Tutti i filtri forniti vengono combinati con AND. REST codifica gli ID dei tag come parametri ripetuti; MCP fornisce un array:

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

I cursori dei contatti sono associati all'organizzazione, all'integrazione e a ogni filtro. Mantenere i filtri in ogni pagina; la modifica di un filtro invalida il cursore. L'ordine e i duplicati dei tag, così come l'ordine, le maiuscole/minuscole e gli spazi bianchi dei token di ricerca, non modificano il filtro effettivo.

Le route dell’elenco di lavoro accettano i seguenti filtri aggiuntivi; le altre combinazioni di risorse e campi vengono rifiutate:

RisorsaFiltri
AttivitàprojectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter
ProtocolliprojectScoutelloId, milestoneScoutelloId, status (draft o final)
OpportunitàprojectScoutelloId, stage, ownerScoutelloUserId
Progettistatus, assignedContactScoutelloId
MilestoneprojectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter

dueBefore è esclusivo; dueAfter è inclusivo. I filtri confrontano la data di scadenza dell’attività o la data di fine della milestone; i record privi di tale data non corrispondono. Fornire valori data-ora ISO con fuso orario. Tutti i filtri vengono applicati prima della paginazione. Continuare un cursore con esattamente gli stessi filtri, incluso updatedSince, e con la stessa organizzazione/integrazione. La dimensione della pagina può cambiare. Dopo questa release, i vecchi cursori senza ambito devono ripartire dal timestamp di riferimento salvato.

Progetti, milestone, assegnazioni e note​

GET /members (MCP members_list) utilizza la paginazione standard e richiede members.read. Restituisce scoutelloId (ID del membro Customer), scoutelloUserId (ID User) e displayName. Vengono visualizzati solo i membri accettati dell’organizzazione che hanno un ruolo; la ricerca non espone indirizzi email o autorizzazioni.

Le attività accettano assignedScoutelloUserIds; le opportunità utilizzano ownerScoutelloUserId. I progetti e le milestone utilizzano assignedContacts: [{"scoutelloId":"member-customer-id"}]. Le assegnazioni richiedono membri accettati dell’organizzazione associata alla credenziale. Le assegnazioni omesse restano invariate; [] le rimuove. Le importazioni di progetti, milestone, attività e protocolli sono silenziose: non inviano notifiche di assegnazione né comunicazioni.

L’evento assignedContacts supporta i contatti CRM leggibili e i membri accettati forniti tramite l’ID membro Customer. I membri accettati restano non disponibili come normali riferimenti a contatti CRM o destinazioni di collegamenti esterni; per assegnare responsabilità al team, utilizzare il campo di assegnazione del membro.

Crea milestone con un name e projectScoutelloId oppure projectExternalId. Supportano description (Markdown), status (open, in_progress, completed, closed), startDate/endDate nullable, order (con valore predefinito 0) e assignedContacts. Le date non possono terminare prima dell'inizio. Ogni milestone ha un link esterno stabile associato all'integrazione. Il progetto non può essere modificato tramite l'API. Le operazioni di creazione e aggiornamento localizzano il nome e la descrizione nella lingua dell'organizzazione.

Le attività e i protocolli accettano riferimenti a progetti, milestone e opportunità come <entity>ScoutelloId o <entity>ExternalId, ad esempio milestoneExternalId. Fornire una sola forma per relazione, anche quando la si cancella con null. Tutte le relazioni devono appartenere all'organizzazione della credenziale. Un riferimento con la sola milestone determina il progetto; un progetto in conflitto o la cancellazione esplicita di un progetto mantenendo la relativa milestone vengono rifiutati. Un'opportunità collegata a un progetto deve corrispondere al progetto dell'attività. Le relazioni omesse mantengono i valori correnti; null esplicito cancella una relazione quando il contesto rimanente è valido. Le letture espongono entrambe le forme degli ID e le assegnazioni delle attività.

Pianificazione delle attività e flussi di lavoro​

Task status è la chiave immutabile di uno stato nel flusso di lavoro effettivo dell'attività, non un'enumerazione fissa. Leggere i flussi di lavoro disponibili dell'organizzazione e del progetto con GET /task-workflows usando l'ambito tasks.read. Ogni stato include la relativa chiave, etichetta, type del ciclo di vita (backlog, unstarted, started, completed o cancelled), colore, ordine, indicatore predefinito e stato di archiviazione. Le voci del progetto indicano se il flusso di lavoro dell'organizzazione è ereditato. La configurazione del flusso di lavoro resta amministrata dalla dashboard.

Le attività accettano priority nullable (low, medium, high o urgent) e estimatedEffortMinutes, oltre a startDate e dueDate nullable. Le letture delle attività includono statusType denormalizzato, il riferimento al padre, riferimenti compatti alle sottoattività e riferimenti blockedBy / blocks.

Creare o aggiornare una sottoattività di un solo livello con parentTaskScoutelloId o parentTaskExternalId; null la promuove ad attività di primo livello. Le dipendenze usano array di riferimenti { "scoutelloId": "..." } o { "externalId": "..." } in blockedBy e blocks. Omettere i campi delle relazioni li conserva, mentre un array di dipendenze vuoto cancella quella direzione. L'API rifiuta sottoattività annidate, dipendenze tra elemento padre e figlio, dipendenze tra organizzazioni diverse, duplicati, riferimenti a sé stessi e cicli diretti o transitivi.

I filtri dell'elenco delle attività accettano un workflow esatto status, un ciclo di vita statusType, priority, parentState (top_level, subtask o parent) e blockedState (blocked, blocking o unblocked).

I protocolli accettano inoltre status: "draft" | "final" (i nuovi record hanno final come valore predefinito). Un nuovo protocollo richiede type, date e un contatto oppure un contesto valido di progetto/traguardo. contactExternalId: null cancella il contatto solo quando rimane il contesto di progetto/traguardo. È quindi possibile creare e leggere note interne di progetto senza inventare un cliente. Draft/final descrive lo stato della nota e non invia mai una comunicazione. Le attività e i protocolli privati restano inaccessibili.

Partecipanti al progetto​

Project participants contiene upsert incrementali identificati da un riferimento contact, ad esempio:

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

I partecipanti descrivono prospect/clienti associati a un progetto; per le persone responsabili si usano le assegnazioni. Omettere i partecipanti, usare un array vuoto o omettere i campi dei partecipanti conserva i dati esistenti. null cancella role, notes o groupScoutelloId. I contatti risolti duplicati nello stesso payload vengono rifiutati. I gruppi devono appartenere già al progetto selezionato; le letture includono participantGroups (ID/nome), gli ID dei partecipanti, i contatti, il ruolo, le note e l'ID del gruppo. La rimozione dei partecipanti e la creazione di gruppi sono attualmente disponibili nella dashboard.

Upsert batch dei record​

Scrivere fino a 100 record con la route batch della risorsa:

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

I batch di attività risolvono i relativi record prima di applicare le relazioni padre e le dipendenze. Questa elaborazione in due fasi consente a un'attività padre, bloccante o bloccata di fare riferimento, tramite l'ID esterno, a un'altra attività creata nello stesso batch, indipendentemente dall'ordine dei record.

Utilizzare il documento OpenAPI per i campi e i vincoli di convalida di ogni risorsa. Ogni record deve avere un externalId stabile, lungo da 1 a 200 caratteri. Trattarlo come un identificatore tecnico opaco: non utilizzare un indirizzo email, un nome, un segreto API o altri dati personali. externalUpdatedAt è facoltativo, ma fortemente consigliato quando il sistema di origine fornisce un timestamp di modifica affidabile.

Il corpo della richiesta è limitato a 1 MiB. mode ha come valore predefinito apply:

  • apply convalida e scrive i record accettati.
  • validate esegue la stessa convalida e lo stesso abbinamento senza scrivere, restituendo gli esiti would_*.

Per le importazioni di contatti, matchByEmail può essere impostato su true nella richiesta. Il valore predefinito è false; l'ID esterno rappresenta il confine di identità più sicuro.

I campi omessi conservano il valore corrente. Un null esplicito cancella un campo nullable, mentre un array di assegnazioni/tag vuoto fornito cancella la relazione. I participants dei progetti sono upsert incrementali: un array vuoto lascia invariato l'elenco. Le scritture dei tag di contatti, attività, opportunità ed eventi utilizzano gli ID dei tag di Scoutello. Gli ID esterni delle relazioni vengono risolti solo tramite collegamenti appartenenti all'integrazione corrente, mentre gli ID utente Scoutello utilizzati per la proprietà o la responsabilità devono identificare membri accettati dell'organizzazione corrente.

La creazione di opportunità richiede un account o un contatto; per le opportunità perse è obbligatorio un motivo della perdita. Gli importi monetari utilizzano centesimi interi. I nomi e le descrizioni di progetti ed eventi vengono letti e scritti nella lingua configurata dell'organizzazione. Le scritture degli eventi supportano date esplicite e ricorrenze giornaliere, settimanali o mensili con esclusioni; i livelli di visibilità pubblicati restano soggetti ai controlli di conformità legale di Scoutello. L'API non espone la gestione dei biglietti degli eventi, dei partecipanti, dei contenuti multimediali, dei modelli, delle newsletter, delle collaborazioni o di altri controlli avanzati per la gestione degli eventi.

Individuare i tag​

Utilizzare l'endpoint dei tag prima di fornire tagIds:

GET /tags?entity=events&type=category

entity è obbligatorio e accetta contacts, tasks, opportunities o events. Viene mappato sulla rilevanza del tag memorizzata corrispondente. type è facoltativo e accetta category o attribute. Le categorie selezionabili possono appartenere all'organizzazione o essere globali; gli attributi selezionabili provengono dall'insieme globale di attributi curato da Scoutello. I risultati includono scoutelloId, il nome localizzato nella lingua dell'organizzazione, type e relevancy. Gli ID dei tag appartenenti a un'altra organizzazione, con rilevanza errata o non selezionabili rifiutano l'elemento interessato del batch.

Leggere la cronologia della posta in uscita​

La cronologia delle e-mail è di sola lettura:

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

Vengono restituite solo le e-mail di proprietà dell'organizzazione con stato sent o failed. Le risposte contengono le intestazioni e il corpo comuni archiviati, i destinatari in Ccn, lo stato e i timestamp, i riferimenti a progetti/eventi/newsletter, gli ID e i tipi degli allegati, oltre alle statistiche aggregate relative alla consegna, all'apertura, ai clic, ai mancati recapiti, ai reclami e ai rifiuti dei destinatari. Le e-mail in bozza, in coda o programmate, le righe per destinatario, le anteprime renderizzate, gli errori grezzi del provider e gli URL per il download degli allegati non vengono mai esposti. Un aggiornamento successivo sulla consegna a un destinatario aggiorna il timestamp effettivo di sincronizzazione dell'e-mail, che viene quindi nuovamente restituita nelle letture incrementali. Non sono disponibili endpoint per la scrittura delle e-mail.

Un risultato di applicazione può essere created, updated, linked, unchanged, stale_ignored o rejected. La convalida utilizza would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale o rejected. Una richiesta batch valida restituisce HTTP 200 anche quando singoli record vengono rifiutati; è quindi necessario controllare sempre ogni elemento e il riepilogo della risposta. Conservare la risposta requestId quando si chiede al supporto Scoutello di analizzare un errore.

Timestamp e conflitti​

Quando è presente externalUpdatedAt, Scoutello lo utilizza per rifiutare le modifiche obsolete senza interrompere il resto del batch. Un risultato stale_ignored è definitivo per quel payload meno recente; recuperare il record corrente prima di decidere se inviare una versione più aggiornata.

Trattare i timestamp come valori UTC in formato ISO 8601. Mantenerne la precisione originale e non sostituire l'ora di esecuzione di un job di sincronizzazione con l'ora di modifica del record di origine.

Idempotenza​

Il limite di idempotenza è costituito dall'integrazione e da externalId. Scoutello confronta un hash canonico del payload e il valore facoltativo externalUpdatedAt; pertanto, riprovare con lo stesso record non crea duplicati e può restituire unchanged.

Con externalUpdatedAt, lo stesso timestamp e payload risultano unchanged, un timestamp meno recente risulta stale_ignored e lo stesso timestamp con un payload diverso costituisce un conflitto di versione. Per un link che non ha mai accettato un timestamp, lo stesso payload privo di timestamp rimane unchanged, mentre un payload modificato viene applicato nell'ordine di arrivo. Dopo che un link ha accettato un timestamp, un payload modificato che omette externalUpdatedAt viene rifiutato come conflitto di versione, impedendo così ai dati senza versione di sovrascrivere lo stato con versione. Per questo motivo, è fortemente consigliato utilizzare i timestamp di modifica dell'origine.

Registro di audit​

Le azioni di sincronizzazione accettate dall’API, incluse creazioni, aggiornamenti e azioni limitate ai soli collegamenti, vengono visualizzate nei changelog di Scoutello con Public API come origine e sono associate all’integrazione responsabile. I riepiloghi delle esecuzioni operative conservano gli ID delle richieste e i conteggi aggregati dei risultati per la risoluzione dei problemi; non conservano i payload dei record né i segreti API.

Errori e nuovi tentativi​

Gli errori a livello di richiesta utilizzano questo envelope:

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

Riprovare le risposte HTTP 429 e le risposte 5xx temporanee utilizzando un backoff esponenziale con jitter. Rispettare Retry-After quando presente. I problemi di rete possono verificarsi dopo che Scoutello ha accettato una richiesta; inviare nuovamente lo stesso batch è sicuro, perché ogni record è idempotente in base all’ID esterno e al payload canonico. Non riprovare automaticamente gli esiti di autenticazione, autorizzazione, convalida, conflitto di versione o singoli esiti rejected senza modificare la richiesta.

Ciclo di sincronizzazione bidirezionale consigliato​

  1. Chiamare /whoami durante la configurazione e verificare l’organizzazione e gli ambiti previsti.
  2. Leggere ogni pagina modificata dall’ultimo punto di controllo completato e applicare tali modifiche al sistema esterno in modo idempotente.
  3. Inviare le modifiche esterne a /batch-upsert, utilizzando ID esterni stabili e i timestamp delle modifiche della fonte.
  4. Salvare i checkpoint solo dopo aver gestito tutte le pagine e i risultati degli elementi.
  5. Risolvere i conflitti secondo le regole di gestione della proprietà del sistema di origine; non simulare le eliminazioni inviando record vuoti.

In questa prima versione Scoutello non offre deliberatamente alcun endpoint pubblico per l’eliminazione. Gestire le policy di eliminazione o archiviazione al di fuori dell’API finché non viene introdotta un’operazione del ciclo di vita documentata.

Post social per la revisione da parte di persone​

L’API social prepara i post per una persona revisora indicata per nome. Non può approvarli né pubblicarli. REST e MCP utilizzano gli stessi ambiti e lo stesso servizio.

AmbitoEndpoint in /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

I nuovi ambiti devono essere concessi esplicitamente. Le credenziali esistenti non acquisiscono alcun accesso aggiuntivo. Utilizzare members.read per individuare gli ID utente dei membri e selezionare una persona revisora con autorizzazione alla pubblicazione (newsletter.edit). Le bozze non richiedono un contatto CRM né un progetto.

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

Usare publishMode: "now" e scheduledAt: null per pubblicare dopo l'approvazione. Ogni variante di canale contiene il testo completo, le impostazioni e gli ID dei media ordinati. La ricerca dei canali restituisce i formati supportati, i limiti e le impostazioni. I canali attualmente supportati sono profili e pagine LinkedIn, Facebook, Instagram e Threads. Instagram richiede contenuti multimediali. Una variante accetta fino a dieci immagini o video.

I batch accettano fino a 100 ID esterni univoci entro il limite esistente di 1 MiB per richiesta. mode: "validate" verifica riferimenti e versioni senza salvare bozze, caricare risorse, creare notifiche o accodare attività. I risultati dell'applicazione includono ID, link di revisione, versioni ed esiti per ogni record. Gli errori parziali non annullano i record correlati completati correttamente. Un errore di notifica restituisce un avviso con l'URL di revisione salvato.

Recuperare l'attuale draftVersion prima di modificare una bozza in sospeso. I tentativi identici sono idempotenti e preservano le modifiche umane successive. Le persone incaricate della revisione non possono essere modificate direttamente. Dopo l'approvazione o il rifiuto, usare un nuovo ID esterno per un'altra proposta. La lettura delle bozze è limitata all'integrazione chiamante; la cronologia delle pubblicazioni include tutte le campagne create e persistite da Scoutello nell'organizzazione, comprese le pubblicazioni create dal dashboard, dallo script e dalle versioni precedenti di Scoutello. Non importa la cronologia esterna dei canali.

Gli elenchi usano i parametri standard limit, cursor e updatedSince. I post e le bozze accettano anche channelId, status, after, before e search; mantenere tutti i filtri nelle pagine successive del cursore. I filtri per data si applicano all'orario di pubblicazione (all'orario di creazione per le bozze immediate in sospeso). Il filtro status delle bozze filtra lo stato di approvazione; status dei post corrisponde allo stato di consegna della campagna o del canale. Le letture espongono l'ultimo stato di consegna noto, gli errori per canale, i link pubblici e i timestamp di riconciliazione. Le letture incrementali delle bozze riflettono anche le modifiche alla consegna delle campagne.

Caricare contenuti multimediali​

  1. Chiama POST /social-media/uploads con clientUploadId, filename, contentType, size in byte e sha256 esadecimale minuscolo dei byte originali. I tipi supportati sono PNG, JPEG, WebP, MP4, WebM, QuickTime e M4V. Il limite di caricamento è di 500 MiB.
  2. Invia i byte originali con HTTP PUT all'upload.url restituito, utilizzando le relative intestazioni. Gli URL di caricamento scadono dopo 15 minuti. Riutilizza clientUploadId per i tentativi successivi dello stesso file; per le sessioni scadute o per file diversi è necessario un nuovo ID.
  3. Chiama POST /social-media/uploads/{assetId}/finalize con un corpo JSON di {}. Il completamento verifica dimensioni, tipo, firma e checksum, congela una copia privata e restituisce l'ID dell'asset per mediaIds. Ripetere il completamento è sicuro.

La proprietà dei caricamenti è associata all'organizzazione e all'integrazione. Le bozze possono fare riferimento ad asset completati della propria organizzazione. Gli URL di anteprima sono temporanei; recuperare nuovamente la bozza per aggiornarli. Gli URL di caricamento non vengono mai emessi per oggetti completati.

Revisione manuale e pubblicazione​

La persona incaricata della revisione riceve una notifica nella dashboard e può aprire il post da Postings o dal relativo URL di revisione. La modifica crea un'altra versione immutabile. L'approvazione utilizza la versione visualizzata e l'hash del contenuto, verifica nuovamente appartenenza, canali e asset e crea atomicamente una singola campagna permanente. Se l'orario proposto è già trascorso, è necessario salvare un nuovo orario esplicito oppure selezionare la pubblicazione al momento dell'approvazione.

I tentativi della coda riutilizzano la campagna e le relative ricevute della piattaforma. Le campagne approvate non possono essere modificate direttamente. L'annullamento tramite la dashboard conserva la relativa cronologia di approvazione e i contenuti multimediali; l'annullamento non può interrompere una pubblicazione già in corso. Eseguire il polling della bozza o della campagna per distinguere l'approvazione dall'effettiva pubblicazione sulla piattaforma.