Aller au contenu principal

API Scoutello

L’API Scoutello est une API serveur à serveur permettant de synchroniser dans les deux sens les contacts, tâches, protocoles, opportunités, projets, jalons et événements d’une organisation. Elle donne également accès à l’historique des e-mails sortants en lecture seule, à la recherche des membres assignables et à la découverte de tags tenant compte des entités. Les routes GET/list incrémentielles et les mises à jour groupées idempotentes constituent les mécanismes de synchronisation de cette version. L’API n’expose aucune opération de suppression ni aucun webhook.

L’URL de base de l’API est la suivante :

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

Elle est également affichée dans Paramètres de l’organisation → Développeur/API. Le document OpenAPI est disponible à l’adresse suivante :

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

Créer et protéger une clé​

Pour les organisations modulaires, le module CRM doit être actif en plus des autorisations requises pour la clé. Une clé valide ne peut pas activer un module manquant. Les requêtes renvoient le statut HTTP 403 avec le code d’erreur module_not_active lorsque l’accès au CRM est indisponible. Une personne disposant de droits d’administration de l’organisation peut vérifier ou activer le CRM dans Abonnement ; réessayer une fois l’accès activé.

Une personne disposant de droits d’administration de l’organisation peut créer une intégration et une clé API dans Paramètres de l’organisation → Développeur/API. La clé complète n’est affichée qu’une seule fois. La copier dans un gestionnaire de secrets avant de fermer la boîte de dialogue ; Scoutello ne peut pas afficher à nouveau la clé complète.

  • Utiliser une intégration et une clé distinctes pour chaque système externe et chaque environnement.
  • Accorder uniquement les autorisations nécessaires au système concerné.
  • Ne jamais placer une clé dans du code exécuté dans le navigateur, une URL, un système de contrôle de version, des journaux, des messages adressés au support ou un stockage côté client.
  • Faire tourner les clés selon un calendrier défini. Lorsqu’une intégration active fait l’objet d’une rotation, la clé de remplacement fonctionne immédiatement et l’ancienne clé reste valide pendant 15 minutes au maximum afin de permettre au système externe de basculer sans interruption. Une échéance antérieure continue de s’appliquer ; l’ancienne clé peut donc cesser de fonctionner plus tôt.
  • Si une clé a pu être exposée, mettre l’intégration en pause avant de la faire tourner. La mise en pause rejette temporairement toutes les clés de l’intégration. Une rotation effectuée pendant la pause ne crée aucune période de chevauchement : l’ancienne clé reste désactivée et la clé de remplacement demeure désactivée jusqu’à la reprise de l’intégration.
  • Révoquer définitivement l’intégration entière lors de la déconnexion d’un système externe. La révocation désactive toutes ses clés et ne peut pas être annulée.

Envoyer la clé avec chaque requête authentifiée :

Authorization: Bearer YOUR_API_KEY

L’authentification Bearer est recommandée. Les clients qui ne peuvent pas définir Authorization peuvent utiliser x-api-key à la place. Ne pas envoyer les deux en-têtes ; les requêtes contenant des valeurs différentes dans les deux en-têtes sont rejetées.

L’API est destinée aux clients backend et n’autorise pas l’accès cross-origin depuis un navigateur.

Utiliser GET /whoami après avoir configuré une clé afin de vérifier l’intégration, l’organisation, les autorisations et les limites de la clé sans récupérer de données personnelles sur les membres.

Autorisations​

PortéeAutorisations
contacts.readRépertorier et récupérer les contacts. Les contacts associés au compte de l’organisation et ceux des membres disposant d’un accès sont exclus.
contacts.writeValider et appliquer les créations ou mises à jour de contacts.
tasks.readRépertorier et récupérer les tâches non privées.
tasks.writeValider et appliquer les créations ou mises à jour de tâches.
protocols.readRépertorier et récupérer les protocoles non privés.
protocols.writeValider et appliquer les créations ou mises à jour de protocoles.
opportunities.readRépertorier et récupérer les opportunités.
opportunities.writeValider et appliquer les créations ou mises à jour d’opportunités.
projects.readRépertorier et récupérer les projets.
projects.writeValider et appliquer les créations ou mises à jour de projets et de participants.
milestones.readRépertorier et récupérer les jalons de projet.
milestones.writeValider et appliquer les créations ou mises à jour de jalons.
members.readRépertorier les membres acceptés avec uniquement leur identifiant client, leur identifiant utilisateur et leur nom d’affichage.
events.readRépertorier et récupérer les événements et les calendriers principaux.
events.writeValider et appliquer les créations ou mises à jour d’événements.
mails.readLire l’historique des e-mails sortants envoyés et en échec appartenant à l’organisation.
mail-drafts.readLire les brouillons autonomes de demandes d’approbation d’e-mails de cette intégration et leur état de distribution.
mail-drafts.writePréparer ou modifier des brouillons d’e-mails pour approbation humaine ; ne jamais approuver ni envoyer.
tags.readRechercher les tags sélectionnables pour les types d’entités pris en charge.

Les tâches et protocoles privés ne sont jamais renvoyés par cette API. Une portée manquante renvoie une erreur d’autorisation ; elle n’est pas traitée comme un résultat vide.

Un contact CRM non membre peut être lu et référencé même s’il est associé à un identifiant de connexion Scoutello. La réponse contient uniquement les champs CRM de l’organisation, jamais les informations d’identité ou d’accès de l’utilisateur. Les contacts associés à un rôle, à des autorisations, à une invitation, à une acceptation ou à un compte d’organisation restent masqués. La modification d’un contact associé à un identifiant de connexion reste interdite (protected_contact), y compris lorsque les champs CRM concernés ne sont autrement pas modifiés. Pour référencer un contact existant et lisible depuis une tâche ou un protocole, contacts.write peut établir son lien externe avec uniquement externalId, scoutelloId et, facultativement, externalUpdatedAt. Les mises à jour ultérieures limitées aux métadonnées du lien utilisent externalId et, facultativement, externalUpdatedAt ; omettre scoutelloId d’initialisation une fois le lien établi. Cela ne modifie jamais le contact ni son utilisateur. L’affectation d’un membre accepté utilise la projection distincte members.read.

Les nouvelles clés utilisent le préfixe sctl_api_ et commencent uniquement par contacts.write. Toute autre portée nécessite une autorisation explicite qu’une personne disposant de droits d’administration de l’organisation doit accorder lors de la création ou de la rotation d’une clé. Les identifiants existants conservent leurs portées actuelles et restent valides.

Contacts associés à un projet et brouillons d’e-mails​

Les opérations d’insertion ou de mise à jour des contacts acceptent facultativement les paires projectScoutelloId / projectExternalId et companyScoutelloId / companyExternalId (en choisir une par paire). Le contact, la relation avec l’entreprise et l’appartenance au projet sont enregistrés de manière atomique pour chaque élément. L’ajout d’une appartenance à un projet nécessite projects.write ; les références omises préservent les autres relations et appartenances. Les lectures détaillées des contacts incluent projectParticipations lorsque projects.read est accordé. Les agents des projets commerciaux doivent inclure explicitement la référence du projet, même lors de la réutilisation d’un contact.

Les brouillons autonomes utilisent le système d’approbation humaine existant, sans exécution de workflow :

MéthodeCheminFonction
GET/mail-draftsBrouillons appartenant à l’intégration, paginés ; filtres facultatifs projectScoutelloId et status.
GET/mail-drafts/{scoutelloId}Version actuelle, lien de révision, hachage du contenu, statut d’approbation/d’envoi et identifiant définitif de l’e-mail.
GET/mail-drafts/external/{externalId}Rechercher un identifiant externe stable de l’intégration.
POST/mail-drafts/batch-upsertValider ou appliquer la préparation du brouillon.

La préparation d’un brouillon nécessite mail-drafts.write, contacts.read et projects.write. Le contact référencé devient membre du projet. La personne chargée de l’approbation doit être membre accepté de l’organisation et disposer de l’autorisation de modifier les e-mails. La sélection de l’expéditeur utilise les paramètres d’expéditeur d’organisation ou personnels déjà autorisés pour cette personne ; les adresses d’expédition arbitraires ne sont pas acceptées.

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

Examiner chaque résultat de validation avant de réessayer avec mode: "apply". Lire l’identifiant renvoyé pour obtenir reviewUrl, draftVersion, contentHash, status, dispatchStatus et mailScoutelloId. Utiliser expectedVersion: 0 uniquement pour la création et la version actuellement renvoyée pour les révisions. Le contexte et la personne chargée de l’approbation sont immuables ; les brouillons révisés ou envoyés refusent tout contenu modifié. Les nouvelles tentatives identiques renvoient le brouillon d’origine.

Les brouillons apparaissent dans les onglets E-mails des projets et des contacts, ainsi que dans les notifications d’approbation du tableau de bord. La préparation via l’API n’envoie aucun e-mail, y compris les e-mails de notification ; le comportement existant des e-mails de notification des workflows reste inchangé. La personne responsable peut modifier les destinataires, l’objet, le corps et les pièces jointes prises en charge, enregistrer la version, puis cliquer sur Approuver et envoyer. Les intégrations ne peuvent ni effectuer l’approbation ni lancer l’envoi. Les échecs ou les livraisons ambiguës ne font jamais l’objet d’une nouvelle tentative automatique. Lors de la conversion de brouillons fondés sur des protocoles, conserver les protocoles et référencer leurs remplacements.

Accès MCP​

La même clé API Scoutello et les mêmes portées peuvent être utilisées avec le point de terminaison MCP HTTP diffusé en continu :

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

Configurer le client MCP pour envoyer Authorization: Bearer YOUR_API_KEY. L’URL /api/mcp, désormais obsolète, reste un alias de compatibilité de chemin, mais les nouveaux clients doivent utiliser le point de terminaison versionné. Les identifiants sctl_mcp_ précédents ne sont pas acceptés ; les remplacer par une clé d’intégration API Scoutello.

Les outils MCP correspondent directement au contrat REST et utilisent les mêmes schémas d’exécution, contrôles de locataire, cycle de vie de l’intégration, limites de débit et méthodes de service. Par exemple, contacts_list, contacts_get, contacts_get_by_external_id et contacts_batch_upsert correspondent aux quatre routes de contacts. Le même modèle s’applique aux tâches, protocoles, opportunités, projets, jalons et événements ; la messagerie expose mails_list et mails_get, les membres exposent members_list, tandis que les tags exposent tags_list.

Le serveur n’annonce que les outils autorisés par les portées de la clé active. Une clé disposant de contacts.read peut découvrir les outils de lecture des contacts, mais pas contacts_batch_upsert ; une clé disposant de contacts.write obtient l’outil de mise à jour par lots, mais pas les outils de lecture. whoami est toujours disponible. Les outils d’écriture produisent les mêmes effets immédiats que leurs équivalents REST ; utiliser donc mode: "validate" lorsqu’un appelant doit inspecter un lot sans l’appliquer.

MCP fonctionne également de serveur à serveur et n’active pas l’accès interorigine depuis un navigateur. Son transport JSON-RPC nécessite une URL dédiée ; il ne peut donc pas partager l’URL d’une ressource REST individuelle, même si l’authentification et le comportement des données sont communs.

Pour obtenir la configuration complète du client, les instructions de vérification, la correspondance des outils et les procédures de résolution des problèmes, consulter le guide d’intégration MCP.

Lire des enregistrements​

Les contacts, tâches, protocoles, opportunités, projets, jalons et événements utilisent les mêmes routes de lecture :

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

Remplacer contacts par tasks, protocols, opportunities, projects, milestones ou events pour les autres ressources de synchronisation. externalId apparaît dans un DTO de lecture lorsque l’enregistrement a été associé par cette intégration.

Une réponse de liste possède cette enveloppe :

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

limit doit être compris entre 1 et 100. Les résultats sont classés selon l’heure effective à laquelle leur représentation dans l’API publique a changé, puis selon l’identifiant Scoutello. Cette heure effective peut être ultérieure à updatedAt de l’entité renvoyée lorsque les métadonnées du lien d’intégration ont changé. Les curseurs sont opaques : les stocker et les envoyer sans modification, sans déduire leur signification de leur contenu.

La première réponse fixe snapshotAt pour ce parcours. Suivre nextCursor jusqu’à ce que hasMore soit false avant de commencer une autre lecture incrémentielle. Cela évite que les enregistrements modifiés pendant la pagination déstabilisent le parcours en cours.

Pour la synchronisation incrémentielle, parcourir toutes les pages du curseur, puis enregistrer snapshotAt de ce parcours comme horodatage de référence. Le transmettre comme valeur updatedSince au format ISO 8601 lors du parcours suivant. La borne inférieure est inclusive : la nouvelle tentative d’un instantané terminé peut donc renvoyer les enregistrements situés à la limite, mais ne peut pas les ignorer.

Une réponse concernant un seul enregistrement possède cette enveloppe :

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

Les réponses concernant un seul contact incluent également un tableau relations. Chaque relation conserve son identifiant de relation Scoutello, sa date de création, son type, ses notes, ainsi que les références de contact connectedFrom et connectedTo. Les références de contact contiennent l’identifiant Scoutello et l’identifiant externe de cette intégration, lorsqu’il existe. Les contacts exclus par la limite de confidentialité liée à l’accès de l’organisation de l’API ne sont pas exposés dans les relations. La réponse de liste des contacts reste compacte et n’inclut pas les relations ; utiliser l’une ou l’autre route concernant un seul contact pour obtenir les détails des relations.

Filtres de travail et portée des curseurs​

Les listes de contacts acceptent search, type (person, company, supplier, other), status et tagIds. La recherche est débarrassée des espaces superflus, insensible à la casse et limitée à 200 caractères / 10 jetons séparés par des espaces. Chaque jeton doit apparaître dans au moins l’un des champs firstName, lastName ou companyName, y compris dans les anciens noms d’entreprise stockés dans lastName. Les caractères tels que % et _ sont comparés littéralement. Les tags utilisent une correspondance any-of avec 1 à 50 identifiants. Tous les filtres fournis sont combinés avec AND. REST encode les identifiants de tags comme des paramètres répétés ; MCP fournit un tableau :

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

Les curseurs de contacts sont liés à l’organisation, à l’intégration et à chaque filtre. Conserver les filtres sur chaque page ; toute modification d’un filtre invalide le curseur. L’ordre et les doublons des tags, ainsi que l’ordre, la casse et les espaces des jetons de recherche, ne modifient pas le filtre effectif.

Les routes de liste de travaux acceptent les filtres supplémentaires suivants ; les autres combinaisons de ressources et de champs sont rejetées :

RessourceFiltres
TâchesprojectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter
ProtocolesprojectScoutelloId, milestoneScoutelloId, status (draft ou final)
OpportunitésprojectScoutelloId, stage, ownerScoutelloUserId
Projetsstatus, assignedContactScoutelloId
JalonsprojectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter

dueBefore est exclusif ; dueAfter est inclusif. Ils comparent la date d’échéance de la tâche ou la date de fin du jalon ; les enregistrements dépourvus de cette date ne correspondent pas. Fournir des date-heures ISO avec fuseau horaire. Tous les filtres sont appliqués avant la pagination. Continuer un curseur avec exactement les mêmes filtres, y compris updatedSince, et la même organisation/intégration. La taille de page peut changer. Après cette mise à jour, les anciens curseurs sans portée doivent redémarrer à partir de l’horodatage de référence enregistré.

Projets, jalons, affectations et notes​

GET /members (MCP members_list) utilise la pagination standard et nécessite members.read. Il renvoie scoutelloId (ID du membre Customer), scoutelloUserId (ID User) et displayName. Seuls les membres acceptés de l’organisation disposant d’un rôle apparaissent ; la recherche n’expose ni les adresses e-mail ni les autorisations.

Les tâches acceptent assignedScoutelloUserIds ; les opportunités utilisent ownerScoutelloUserId. Les projets et les jalons utilisent assignedContacts: [{"scoutelloId":"member-customer-id"}]. Les affectations nécessitent des membres acceptés de l’organisation associée aux identifiants. Les affectations omises restent inchangées ; [] les efface. Les importations de projets, de jalons, de tâches et de protocoles sont silencieuses : elles n’envoient aucune notification d’affectation ni communication.

L’événement assignedContacts prend en charge les contacts CRM lisibles et les membres acceptés fournis via l’ID de membre Customer. Les membres acceptés restent indisponibles en tant que références de contacts CRM ordinaires ou cibles de liens externes ; utiliser le champ d’affectation de membre pour attribuer les responsabilités au sein de l’équipe.

Créer des jalons avec un name et soit projectScoutelloId, soit projectExternalId. Ils prennent en charge description (Markdown), status (open, in_progress, completed, closed), startDate/endDate nullable, order (valeur par défaut : 0) et assignedContacts. Les dates de fin ne peuvent pas être antérieures aux dates de début. Chaque jalon possède un lien externe stable, associé à l’intégration. Son projet ne peut pas être modifié via l’API. La création et la mise à jour localisent le nom et la description dans la langue de l’organisation.

Les tâches et les protocoles acceptent des références à des projets, des jalons et des opportunités sous la forme de <entity>ScoutelloId ou <entity>ExternalId, par exemple milestoneExternalId. Fournir une seule notation par relation, y compris lors de la suppression avec null. Toutes les relations doivent appartenir à l’organisation associée aux identifiants d’accès. Une référence à un jalon בלבד déduit le projet ; un projet contradictoire ou la suppression explicite d’un projet tout en conservant son jalon est rejeté. Une opportunité associée à un projet doit correspondre au projet de l’élément de travail. Les relations omises conservent leurs valeurs actuelles ; null explicite supprime une relation lorsque le contexte restant est valide. Les lectures exposent les deux notations d’identifiant ainsi que les affectations de tâches.

Planification des tâches et workflows​

Task status est la clé immuable d’un statut dans le workflow effectif de la tâche, et non une valeur fixe d’une énumération. Lire les workflows disponibles de l’organisation et des projets avec GET /task-workflows en utilisant la portée tasks.read. Chaque statut comprend sa clé, son libellé, son cycle de vie type (backlog, unstarted, started, completed ou cancelled), sa couleur, son ordre, son indicateur de valeur par défaut et son état d’archivage. Les entrées de projet indiquent si le workflow de l’organisation est hérité. La configuration des workflows reste administrée depuis le tableau de bord.

Les tâches acceptent priority nullable (low, medium, high ou urgent) et estimatedEffortMinutes, ainsi que startDate et dueDate nullable. Les lectures de tâches incluent statusType dénormalisé, la référence au parent, les références compactes aux sous-tâches et les références blockedBy / blocks.

Créez ou mettez à jour une sous-tâche d’un seul niveau avec parentTaskScoutelloId ou parentTaskExternalId ; null la convertit en tâche de niveau supérieur. Les dépendances utilisent des tableaux de références { "scoutelloId": "..." } ou { "externalId": "..." } dans blockedBy et blocks. Les champs de relation omis les préservent, tandis qu’un tableau de dépendances vide efface cette direction. L’API rejette les sous-tâches imbriquées, les dépendances parent-enfant, les dépendances entre organisations, les doublons, les références à soi-même ainsi que les cycles directs ou transitifs.

Les filtres de liste des tâches acceptent un workflow exact status, un cycle de vie statusType, priority, parentState (top_level, subtask ou parent) et blockedState (blocked, blocking ou unblocked).

Les protocoles acceptent également status: "draft" | "final" (les nouveaux enregistrements utilisent par défaut final). Un nouveau protocole nécessite type, date et soit un contact, soit un contexte de projet/jalon valide. contactExternalId: null efface son contact uniquement lorsqu’un contexte de projet/jalon est conservé. Des notes internes de projet peuvent donc être créées et consultées sans inventer de client. Brouillon/final décrit l’état de la note et n’envoie jamais de communication. Les tâches et protocoles privés restent inaccessibles.

Participants au projet​

Le projet participants contient des mises à jour additives identifiées par une référence contact, par exemple :

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

Les participants représentent les prospects/clients associés à un projet ; les membres responsables utilisent les affectations. Les participants omis, un tableau vide et les champs de participant omis préservent les données existantes. null efface role, notes ou groupScoutelloId. Les contacts résolus en double dans une même requête sont rejetés. Les groupes doivent déjà appartenir au projet sélectionné ; les lectures incluent participantGroups (ID/nom), ainsi que les identifiants des participants, les contacts, le rôle, les notes et l’identifiant du groupe. La suppression de participants ou la création de groupes est actuellement disponible dans le tableau de bord.

Mise à jour groupée des enregistrements​

Écrivez jusqu’à 100 enregistrements avec la route groupée de la ressource :

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

Les traitements groupés de tâches résolvent les enregistrements de tâches avant d’appliquer les relations parent et de dépendance. Ce traitement en deux phases permet à une tâche parent, bloquante ou bloquée de référencer, par son identifiant externe, une autre tâche créée dans le même traitement groupé, quel que soit l’ordre des enregistrements.

Utilisez le document OpenAPI pour connaître les champs et les contraintes de validation de chaque ressource. Chaque enregistrement doit comporter un externalId stable de 1 à 200 caractères. Traitez-le comme un identifiant technique opaque : n’utilisez ni adresse e-mail, ni nom, ni secret d’API, ni aucune autre donnée personnelle. externalUpdatedAt est facultatif, mais fortement recommandé lorsque le système source fournit un horodatage de modification fiable.

Le corps de la requête est limité à 1 Mio. mode prend par défaut la valeur apply :

  • apply valide et enregistre les enregistrements acceptés.
  • validate effectue la même validation et la même mise en correspondance sans enregistrer les données, puis renvoie les résultats would_*.

Pour les importations de contacts, matchByEmail peut être défini sur true dans la requête. La valeur par défaut est false ; l’identifiant externe constitue la limite d’identité la plus sûre.

Les champs omis conservent leur valeur actuelle. Un null explicite efface un champ pouvant être nul, et un tableau vide d’affectations ou d’étiquettes fourni efface la relation correspondante. Les participants de projet sont des mises à jour ou créations additives : un tableau vide ne modifie pas la liste. Les écritures d’étiquettes de contacts, de tâches, d’opportunités et d’événements utilisent les identifiants d’étiquettes Scoutello. Les identifiants externes des relations sont résolus uniquement via les liens appartenant à l’intégration actuelle, tandis que les identifiants d’utilisateurs Scoutello utilisés pour la propriété ou la responsabilité doivent correspondre à des membres acceptés de l’organisation actuelle.

La création d’une opportunité nécessite un compte ou un contact, et les opportunités perdues nécessitent un motif de perte. Les montants monétaires sont exprimés en centimes entiers. Les noms et descriptions des projets et des événements sont lus et écrits dans la langue configurée de l’organisation. Les écritures d’événements prennent en charge les dates explicites ainsi que les récurrences quotidiennes, hebdomadaires ou mensuelles avec exclusions ; les niveaux de visibilité publiés restent soumis aux contrôles de conformité juridique de Scoutello. L’API n’expose pas la billetterie des événements, les participant·es, les médias, les modèles, les newsletters, les collaborations ni les autres fonctions avancées de gestion des événements.

Découvrir les étiquettes​

Utilisez le point de terminaison des étiquettes avant de fournir tagIds :

GET /tags?entity=events&type=category

entity est obligatoire et accepte contacts, tasks, opportunities ou events. Il correspond au niveau de pertinence de l’étiquette enregistrée. type est facultatif et accepte category ou attribute. Les catégories sélectionnables peuvent appartenir à l’organisation ou être globales ; les attributs sélectionnables proviennent de l’ensemble mondial d’attributs sélectionnés par Scoutello. Les résultats incluent scoutelloId, le nom localisé dans la langue de l’organisation, type et relevancy. Les identifiants d’étiquettes provenant d’une autre organisation, associés à une pertinence incorrecte ou non sélectionnables entraînent le rejet de l’élément de lot concerné.

Lire l’historique des e-mails sortants​

L’historique des e-mails est en lecture seule :

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

Seuls les e-mails appartenant à l’organisation et ayant le statut sent ou failed sont renvoyés. Les réponses contiennent les en-têtes et le corps courants enregistrés, les destinataires en CCI, le statut et les horodatages, les références aux projets, événements et newsletters, les identifiants et types de pièces jointes, ainsi que les statistiques agrégées de livraison, d’ouverture, de clic, de rebond, de plainte et de rejet des destinataires. Les brouillons, les e-mails en file d’attente ou planifiés, les lignes par destinataire, les aperçus rendus, les erreurs brutes du fournisseur et les URL de téléchargement des pièces jointes ne sont jamais exposés. Une mise à jour ultérieure de la livraison à un destinataire actualise l’horodatage de synchronisation effectif de l’e-mail, qui réapparaît alors dans les lectures incrémentielles. Aucune route d’écriture d’e-mails n’est disponible.

Un résultat d’application peut être created, updated, linked, unchanged, stale_ignored ou rejected. La validation utilise would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale ou rejected. Une requête de lot valide renvoie HTTP 200 même lorsque certains enregistrements sont rejetés individuellement : toujours examiner chaque élément ainsi que le résumé de la réponse. Conserver la réponse requestId lors d’une demande d’analyse d’un échec auprès de l’assistance Scoutello.

Horodatages et conflits​

Lorsque externalUpdatedAt est présent, Scoutello l’utilise pour rejeter les modifications obsolètes sans faire échouer le reste du lot. Un résultat stale_ignored est définitif pour cette ancienne charge utile ; récupérer l’enregistrement actuel avant de décider d’envoyer une version plus récente.

Traiter les horodatages comme des valeurs UTC au format ISO 8601. Préserver leur précision d’origine et ne pas remplacer l’heure de modification de l’enregistrement source par l’heure d’exécution d’une tâche de synchronisation.

Idempotence​

La limite d’idempotence se situe au niveau de l’intégration et de externalId. Scoutello compare le hachage canonique de la charge utile et la valeur facultative externalUpdatedAt ; ainsi, la nouvelle tentative d’envoi du même enregistrement ne crée pas de doublon et peut renvoyer unchanged.

Avec externalUpdatedAt, le même horodatage et la même charge utile donnent unchanged, un horodatage plus ancien donne stale_ignored, et le même horodatage associé à une charge utile différente constitue un conflit de version. Pour un lien n’ayant jamais accepté d’horodatage, une charge utile sans horodatage identique reste unchanged, tandis qu’une charge utile modifiée est appliquée dans l’ordre d’arrivée. Après qu’un lien a accepté un horodatage, une charge utile modifiée qui omet externalUpdatedAt est rejetée comme conflit de version afin que des données non versionnées ne puissent pas écraser un état versionné. C’est pourquoi les horodatages de modification de la source sont vivement recommandés.

Piste d’audit​

Les créations, mises à jour et actions de synchronisation limitées aux liens acceptées via l’API apparaissent dans les journaux des modifications de Scoutello avec Public API comme source et sont associées à l’intégration responsable. Les résumés d’exécution opérationnelle conservent les identifiants de requête et les nombres agrégés de résultats pour faciliter le dépannage ; ils ne conservent ni les données des enregistrements ni les secrets d’API.

Erreurs et nouvelles tentatives​

Les erreurs au niveau des requêtes utilisent cette enveloppe :

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

Effectuer de nouvelles tentatives pour les réponses HTTP 429 et les réponses 5xx temporaires avec un intervalle exponentiel et une temporisation aléatoire. Respecter Retry-After lorsqu’il est présent. Des défaillances réseau peuvent survenir après l’acceptation d’une requête par Scoutello ; il est possible de renvoyer le même lot sans risque, car chaque enregistrement est idempotent grâce à son identifiant externe et à sa charge utile canonique. Ne pas relancer automatiquement les erreurs d’authentification, d’autorisation, de validation, de conflit de version ou les résultats individuels rejected sans modifier la requête.

Boucle de synchronisation bidirectionnelle recommandée​

  1. Appeler /whoami lors de la configuration et vérifier l’organisation et les portées attendues.
  2. Lire chaque page modifiée depuis le dernier point de progression maximal validé et appliquer ces modifications au système externe de manière idempotente.
  3. Envoyer les modifications externes à /batch-upsert, en utilisant des identifiants externes stables et les horodatages de modification de la source.
  4. Enregistrer les points de contrôle uniquement après le traitement de toutes les pages et de tous les résultats des éléments.
  5. Résoudre les conflits conformément aux règles de propriété du système source ; ne pas simuler les suppressions en envoyant des enregistrements vides.

Dans cette première version, Scoutello ne fournit volontairement aucune route publique de suppression. Gérer les règles de suppression ou d’archivage en dehors de l’API jusqu’à l’introduction d’une opération de cycle de vie documentée.

Publications sociales pour validation humaine​

L’API sociale prépare des publications destinées à une personne chargée de leur validation. Elle ne peut ni les approuver ni les publier. REST et MCP utilisent les mêmes portées et le même service.

PortéePoints de terminaison sous /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

Les nouvelles portées doivent être accordées explicitement. Les identifiants existants n’obtiennent aucun accès supplémentaire. Utiliser members.read pour découvrir les identifiants utilisateur des membres, puis sélectionner une personne chargée de la validation disposant de l’autorisation de publication (newsletter.edit). Les brouillons ne nécessitent ni contact CRM ni projet.

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

Utiliser publishMode: "now" et scheduledAt: null pour publier après approbation. Chaque variante de canal contient son texte complet, ses paramètres et les identifiants de médias dans l’ordre. La découverte des canaux renvoie les formats pris en charge, les limites et les paramètres. Les canaux actuellement pris en charge sont les profils et pages LinkedIn, Facebook, Instagram et Threads. Instagram nécessite des médias. Une variante accepte jusqu’à dix images ou vidéos.

Les lots acceptent jusqu’à 100 identifiants externes uniques dans la limite actuelle de 1 MiB par requête. mode: "validate" vérifie les références et les versions sans enregistrer de brouillons, téléverser des ressources, créer des notifications ni mettre du travail en file d’attente. Les résultats de l’application incluent les identifiants, les liens de révision, les versions et le résultat pour chaque enregistrement. Les échecs partiels n’annulent pas les enregistrements associés traités avec succès. Un échec de notification renvoie un avertissement accompagné de l’URL de révision enregistrée.

Récupérer le draftVersion actuel avant de modifier un brouillon en attente. Les nouvelles tentatives identiques sont idempotentes et préservent les modifications ultérieures effectuées par les équipes de révision. Les personnes chargées de la révision ne peuvent pas être modifiées directement. Après une approbation ou un refus, utiliser un nouvel identifiant externe pour une autre proposition. La lecture des brouillons est limitée à l’intégration appelante ; l’historique des publications couvre toutes les campagnes créées et conservées par Scoutello dans l’organisation, y compris les publications créées depuis le tableau de bord, le script et les anciennes versions de Scoutello. L’historique externe des canaux n’est pas importé.

Les listes utilisent les paramètres standard limit, cursor et updatedSince. Les publications et les brouillons acceptent également channelId, status, after, before et search ; conserver tous les filtres sur les pages suivantes parcourues avec le curseur. Les filtres de date s’appliquent à l’heure de publication (à l’heure de création pour les brouillons en attente immédiats). Le filtre status des brouillons porte sur le statut d’approbation ; le filtre status des publications correspond au statut de diffusion d’une campagne ou d’un canal. Les lectures exposent le dernier état de diffusion connu, les échecs par canal, les liens publics et les horodatages de rapprochement. Les lectures incrémentielles des brouillons reflètent également les changements de diffusion des campagnes.

Téléverser des médias​

  1. Appelez POST /social-media/uploads avec clientUploadId, filename,
    contentType, size en octets, ainsi que sha256
    hexadécimal en minuscules des octets d’origine. Les types pris en charge sont PNG, JPEG, WebP, MP4, WebM, QuickTime et
    M4V. La taille maximale d’envoi est de 500 MiB.
  2. Envoyez les octets d’origine avec HTTP PUT vers upload.url retourné, en utilisant
    ses en-têtes. Les URL d’envoi expirent après 15 minutes. Réutilisez clientUploadId pour
    les nouvelles tentatives concernant le même fichier ; les sessions expirées ou les fichiers différents nécessitent un nouvel identifiant.
  3. Appelez POST /social-media/uploads/{assetId}/finalize avec un corps JSON {}.
    La finalisation vérifie la taille, le type, la signature et la somme de contrôle, fige une copie privée
    et renvoie l’identifiant de l’asset pour mediaIds. Les finalisations répétées sont sans risque.

La propriété des envois est liée à l’organisation et à l’intégration. Les brouillons peuvent référencer
des assets finalisés appartenant à leur organisation. Les URL d’aperçu sont temporaires ; récupérer à nouveau le
brouillon permet de les actualiser. Les URL d’envoi ne sont jamais générées pour les objets finalisés.

Vérification humaine et diffusion​

La personne chargée de la vérification reçoit une notification dans le tableau de bord et peut ouvrir la publication depuis Postings
ou via son URL de vérification. Toute modification crée une autre version immuable. L’approbation utilise la
version affichée et le hachage du contenu, revérifie l’appartenance, les canaux et les assets, puis crée
atomiquement une campagne durable. Si l’heure proposée est dépassée, une nouvelle heure explicite doit être enregistrée
ou la publication lors de l’approbation doit être sélectionnée.

Les nouvelles tentatives de la file réutilisent la campagne et ses reçus de plateforme. Les campagnes approuvées
ne peuvent pas être modifiées sur place. L’annulation depuis le tableau de bord conserve leur
historique d’approbation et leurs médias ; l’annulation ne peut pas interrompre une diffusion active.
Interroger le brouillon ou la campagne permet de distinguer l’approbation de la diffusion effective sur la plateforme.