API du support, événements et export en masse
Tout ce dont une intégration a besoin dans le module de service client : les points d'entrée pour les dossiers, les fils de discussion, le SLA, les files, le catalogue, les droits de support et les enquêtes ; des abonnements aux événements signés, avec réessai et rejeu ; un flux que l'on reprend par curseur ; l'export en masse des dossiers et des messages ; et l'import idempotent de l'historique des dossiers d'un autre outil de support. Chaque point d'entrée a une commande équivalente sur le serveur MCP.
Le support a toujours été accessible par l'API générique des enregistrements : un dossier est un enregistrement, donc en lister et en créer fonctionnait déjà. Ce qui ne fonctionnait pas, c'est tout ce qui vit à côté du dossier sans être un enregistrement. Le fil de messages, l'horloge du SLA, les files, le catalogue de services, le solde des droits de support et les enquêtes n'avaient aucun point d'entrée : une intégration pouvait ouvrir un dossier sans pouvoir y répondre.
Cet article couvre les points d'entrée du support, les mêmes commandes sur le serveur MCP, les abonnements aux événements avec réessai et rejeu, le flux d'événements que l'on reprend, et la façon d'importer l'historique des dossiers depuis un autre outil de support.
Par où commencer - Créez une clé d'API dans Paramètres, sous API et développeurs. La clé identifie votre compte et limite tout à celui-ci. - Chaque appel s'authentifie comme le reste de l'API : Authorization: Bearer suivi de votre clé. - Tout ce dont parle cet article vit sous /api/v1/service et est limité à l'objet ticket. Une clé restreinte à d'autres objets n'y accède pas. - Chaque point d'entrée a une commande équivalente sur le serveur MCP : un agent IA connecté à SellioCRM peut donc faire exactement les mêmes choses.
Les dossiers - GET /api/v1/service/tickets liste les dossiers sous forme de lignes plates, filtrées par statut, priorité, file, responsable ou texte libre. Utilisez updated_since avec un horodatage pour ne récupérer que ce qui a changé depuis votre dernière synchronisation, et limit et offset pour paginer. - GET /api/v1/service/tickets/{id} renvoie un dossier avec son horloge de SLA : la date d'échéance, l'indication de pause, la cible de première réponse et la cible de réponse suivante. Cette horloge est la raison d'être de ce point d'entrée ; le point d'entrée générique des enregistrements renvoie les champs, pas les délais. - POST /api/v1/service/tickets ouvre un dossier par le même chemin que la console : le numéro de ticket, les cibles de SLA, les règles de routage et les webhooks sortants ont donc bien lieu. - PATCH /api/v1/service/tickets/{id} change le statut, la priorité, la catégorie, la file et le responsable. Affecter est le même verbe que changer le statut : il n'y a donc pas de point d'entrée séparé pour cela. - GET et POST /api/v1/service/tickets/{id}/messages lisent et écrivent le fil. Le kind public répond au client et envoie l'e-mail ; le kind internal laisse une note que seuls les agents voient. - POST /api/v1/service/tickets/merge fusionne deux dossiers : le secondaire est absorbé par le principal et ses messages y sont déplacés.
Autour du dossier - GET /api/v1/service/queues liste les files avec la capacité par agent, les heures ouvrées et la priorité par défaut. Lisez-le avant de router : le nom de la file est ce que l'appel de création attend. - GET et POST /api/v1/service/catalog lisent la vitrine du catalogue de services et demandent un article. Une demande ouvre un vrai dossier avec la file et la priorité de l'article ; envoyez votre propre idempotencyKey pour qu'un réessai renvoie la demande existante au lieu d'ouvrir un deuxième dossier. - GET /api/v1/service/entitlements renvoie les droits de support par compte ou par contrat, avec le solde restant. - GET /api/v1/service/surveys renvoie les invitations aux enquêtes de satisfaction, avec leur état et la date de réponse. Les enquêtes anonymes ne renvoient jamais le répondant.
Les événements, en temps réel et par curseur Une intégration a besoin des deux moitiés du temps réel : être prévenue à l'instant où quelque chose se produit, et rattraper ce qu'elle a manqué pendant son indisponibilité. La première vient d'un abonnement, la seconde du flux.
- POST /api/v1/service/subscriptions enregistre une URL et les événements qui vous intéressent. events accepte des types exacts ou une famille avec un joker, par exemple ticket.* Un événement inconnu est refusé par son nom, car un abonnement qui ne se déclenche jamais est pire qu'une erreur. Le secret n'est renvoyé qu'une fois ; copiez-le.
- Chaque livraison arrive sous forme de POST avec trois en-têtes : x-sellio-event avec le nom de l'événement, x-sellio-delivery avec l'identifiant de la tentative, et x-sellio-signature sous la forme sha256 suivi du code calculé sur le corps exact avec votre secret. Recalculez-le de votre côté et comparez ; en cas de différence, ignorez l'appel.
- Une livraison en échec est réessayée avec des attentes croissantes : environ une minute, cinq, trente, deux heures puis six heures. Ensuite elle est marquée morte et reste dans le journal.
- GET /api/v1/service/deliveries est la réponse consultable à la question « cet événement est-il arrivé ». Chaque ligne porte le nombre de tentatives, le dernier code de statut, l'erreur et le prochain réessai programmé.
- POST /api/v1/service/deliveries/{id}/replay renvoie une livraison. Il rejoue le corps stocké, octet pour octet identique à celui qui est parti la première fois. Reconstruire la charge utile maintenant enverrait l'état d'aujourd'hui avec l'horodatage d'hier.
- GET /api/v1/service/events est le flux. Passez le curseur de la réponse précédente et vous n'obtenez que ce qui s'est produit après ce point. nextCursor est renvoyé même sur une page vide, et c'est lui que vous conservez. Traitez le curseur comme opaque : faire de l'arithmétique dessus est la façon dont une intégration casse en silence plus tard.
- GET /api/v1/service/event-types liste tous les événements que le produit sait envoyer, lequel des trois registres de webhooks peut s'y abonner, et si atteindre un abonnement du service client exige que le bus d'événements soit activé pour votre compte. Lisez-le avant de créer un abonnement.
Exporter les dossiers et les messages GET /api/v1/service/export prend l'entité tickets ou messages et le format json ou csv. L'export des messages est la raison d'être de ce point d'entrée : le fil n'est pas un enregistrement, donc aucune autre surface ne le livrait en masse. Filtrez par since, status, queue, ticketId ou kind, et paginez avec limit, jusqu'à 500, et offset. La réponse json porte hasMore pour vous dire qu'une page vous attend encore.
Importer l'historique d'un autre outil de support POST /api/v1/service/import accepte jusqu'à 500 lignes par appel. Chaque ligne exige externalKey, c'est-à-dire le numéro du dossier dans l'outil que vous quittez, et un sujet. Elle peut aussi porter body, l'e-mail du demandeur, son nom et son téléphone, la priorité, la catégorie, la file, le canal, le statut et createdAt.
- L'import est idempotent par externalKey. Importer deux fois le même fichier signale les lignes comme existantes au lieu de les dupliquer : vous pouvez donc relancer un lot en échec sans crainte.
- Le dossier naît avec la date et le statut de la source. Sans cela, quinze mille dossiers clos arriveraient comme nouveaux à la date du jour, inondant la file des personnes au travail et faussant chaque rapport par période.
- Envoyez dryRun true pour voir ce qui se passerait sans rien écrire.
- Une ligne qui échoue à la validation devient une entrée dans problems, avec sa position dans le lot, et le reste du lot est bien importé. Une date incorrecte sur trois lignes ne vous oblige pas à tout recommencer.