API pour les intégrateurs

JSON sur HTTPS, encodé en UTF-8. Les erreurs des points d'accès documentés ci-dessous suivent la même enveloppe JSON ; un chemin inexistant ou une méthode non prise en charge répond 404 ou 405 sans cette enveloppe. URL de base :

https://tiqo.fr/api/v1

Les identifiants (clé API et secret HMAC) sont créés dans l'application Tiqo et affichés une seule fois. Les exemples ci-dessous les lisent dans les variables TIQO_API_KEY et TIQO_HMAC_SECRET : ne les écrivez jamais en clair dans un script partagé.

La signature est le HMAC-SHA256, en hexadécimal minuscule, calculé avec le secret HMAC de l'espace sur les octets suivants :

<X-Tiqo-Timestamp>.<Idempotency-Key>.<raw body>

• le corps est signé exactement tel qu'envoyé : signez la chaîne JSON que vous transmettez, sans la re-sérialiser ;
• pour un GET, la clé d'idempotence et le corps sont vides : l'entrée est <timestamp>.. ;
• l'horodatage doit être à moins de 300 secondes de l'horloge du serveur ; la signature couvre la clé d'idempotence, donc une requête capturée ne peut pas être rejouée avec une autre clé, et une clé déjà reçue est refusée (409). Sur /analyze seulement, une clé dont l'analyse a échoué est libérée pour permettre une nouvelle tentative ; sur les autres POST, la clé reste consommée même quand la requête échoue : chaque nouvelle tentative utilise une nouvelle clé.

Vecteur de référence

printf '%s' '1793385000.evt-1.{"a":1}' | openssl dgst -sha256 -hmac 'test-secret'
# 7a8306e38b71005597b83dbc4c7e1facccd25781bd92a60874d1f72b40126be4

Exemples

API_URL="https://tiqo.fr/api/v1"
BODY='{"glpi_ticket_id":1042,"title":"Impossible de me connecter au Wi-Fi","categories":[]}'
TIMESTAMP=$(date +%s)
IDEMPOTENCY_KEY=$(uuidgen | tr 'A-Z' 'a-z')
SIGNATURE=$(printf '%s.%s.%s' "$TIMESTAMP" "$IDEMPOTENCY_KEY" "$BODY" \
  | openssl dgst -sha256 -hmac "$TIQO_HMAC_SECRET" -hex | sed 's/^.*= //')

curl -sS -X POST "$API_URL/analyze" \
  -H "Authorization: Bearer $TIQO_API_KEY" \
  -H "X-Tiqo-Timestamp: $TIMESTAMP" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "X-Tiqo-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  --data-binary "$BODY"

import { createHmac, randomUUID } from 'node:crypto'

const API_URL = 'https://tiqo.fr/api/v1'
const body = JSON.stringify({ glpi_ticket_id: 1042, title: 'Impossible de me connecter au Wi-Fi', categories: [] })
const timestamp = String(Math.floor(Date.now() / 1000))
const idempotencyKey = randomUUID()
const signature = createHmac('sha256', process.env.TIQO_HMAC_SECRET)
  .update(`${timestamp}.${idempotencyKey}.${body}`)
  .digest('hex')

const response = await fetch(`${API_URL}/analyze`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TIQO_API_KEY}`,
    'X-Tiqo-Timestamp': timestamp,
    'Idempotency-Key': idempotencyKey,
    'X-Tiqo-Signature': signature,
    'Content-Type': 'application/json',
  },
  body, // exactly the bytes that were signed
})

$body = json_encode(
    ['glpi_ticket_id' => 1042, 'title' => 'Impossible de me connecter au Wi-Fi', 'categories' => []],
    JSON_UNESCAPED_UNICODE
);
$timestamp      = (string) time();
$idempotencyKey = bin2hex(random_bytes(16));
$signature      = hash_hmac('sha256', $timestamp . '.' . $idempotencyKey . '.' . $body, getenv('TIQO_HMAC_SECRET'));
// Send $body unchanged with Authorization, X-Tiqo-Timestamp, Idempotency-Key and X-Tiqo-Signature.

TIMESTAMP=$(date +%s)
SIGNATURE=$(printf '%s..' "$TIMESTAMP" | openssl dgst -sha256 -hmac "$TIQO_HMAC_SECRET" -hex | sed 's/^.*= //')

curl -sS "https://tiqo.fr/api/v1/usage" \
  -H "Authorization: Bearer $TIQO_API_KEY" \
  -H "X-Tiqo-Timestamp: $TIMESTAMP" \
  -H "X-Tiqo-Signature: $SIGNATURE"

Analyse un ticket et renvoie résumé, type, catégorie et urgence (ces trois derniers avec un niveau de confiance entre 0 et 1), brouillon de réponse, mots-clés, doublons et articles de la base de connaissances utilisés. Les catégories ne sont choisies que dans categories ; en cas de doute, category.id vaut null avec une confiance de 0. L'urgence va de 1 à 5.

{
  "glpi_ticket_id": 1042,
  "glpi_entity_id": 0,
  "title": "Impossible de me connecter au Wi-Fi depuis ce matin",
  "content": "Depuis ce matin, mon portable (DELL-7420, 192.168.10.57) ne se connecte plus au Wi-Fi CORP-STAFF. Joignable au <phone_1> ou sur <email_1>.",
  "content_format": "text",
  "requester_type": "user",
  "glpi_created_at": "2026-10-30 08:41:12",
  "current": { "type": 1, "category_id": null, "urgency": 3, "status": "open" },
  "plugin_options": { "kb_sync": true, "send_solutions": true },
  "categories": [
    { "id": 1, "name": "Réseau", "completename": "Réseau" },
    { "id": 2, "name": "Wi-Fi", "completename": "Réseau > Wi-Fi" },
    { "id": 4, "name": "Poste de travail", "completename": "Poste de travail" }
  ],
  "language": "fr"
}

{
  "analysis_id": "6f1c2a9e-8f0b-4c55-9d1e-2b7c3a4d5e6f",
  "summary": "Le portable DELL-7420 du demandeur ne se connecte plus au Wi-Fi CORP-STAFF depuis ce matin, le mot de passe est refusé. Les collègues du même étage ne sont pas touchés.",
  "type": { "value": "incident", "confidence": 0.93 },
  "category": { "id": 2, "name": "Wi-Fi", "confidence": 0.88 },
  "urgency": { "value": 3, "confidence": 0.71 },
  "draft_reply": "Bonjour,\n\nMerci pour votre message. Pouvez-vous nous indiquer ...",
  "tags": ["wifi", "authentification", "portable"],
  "duplicates": [
    { "glpi_ticket_id": 1039, "score": 0.91, "title": "Plus de Wi-Fi CORP-STAFF, écrire à [adresse e-mail]" }
  ],
  "similar_solved": [
    { "glpi_ticket_id": 987, "excerpt": "Certificat RADIUS expiré sur le poste : réinstallé depuis le portail, puis oubli et reconnexion au réseau CORP-STAFF.", "score": 0.892 }
  ],
  "knowledge": [
    { "glpi_kb_id": 12, "title": "Wi-Fi CORP-STAFF : renouveler le certificat du poste", "score": 0.884, "audience": "internal" },
    { "glpi_kb_id": 5, "title": "Se connecter au Wi-Fi CORP-STAFF", "score": 0.871, "audience": "faq" }
  ],
  "usage": { "tickets_this_month": 42, "tickets_total": 42, "limit": 100, "remaining": 58 },
  "model": "mistral-medium-latest",
  "latency_ms": 1840
}

Valeurs données à titre d'exemple. usage.limit est la limite de l'offre (essai : tickets au total, Starter : tickets par mois, Pro : null) ; usage.remaining est calculé sur le bon compteur.

Avec l'offre Pro et pendant l'essai, et sinon ces tableaux sont vides :

• duplicates liste au plus 5 tickets de l'espace déjà analysés et créés dans GLPI ces 7 derniers jours (à défaut de glpi_created_at, analysés pour la première fois dans cette période) dont la similarité atteint 0,91, hors tickets résolus, clos ou supprimés, d'après current.status ou POST /tickets/events. Une nouvelle analyse ne prolonge pas cette période. Leur titre arrive avec des mentions neutres à la place des données personnelles ([adresse e-mail]…). Ils ne sont pas filtrés par entité : comme le plugin, vérifiez que l'utilisateur a le droit de voir un ticket avant de l'afficher ;
• similar_solved liste au plus 3 solutions mémorisées proches, de la même entité que le ticket (glpi_entity_id), avec un extrait de 300 caractères au plus, quand la mémoire des tickets résolus est activée dans l'espace et que plugin_options.send_solutions ne vaut pas false ;
• le résumé et le brouillon s'appuient sur au plus 5 passages de FAQ publiques (is_faq), les plus proches parmi les articles visibles dans l'entité du ticket, et le brouillon cite l'article utilisé, quand la synchronisation est activée dans l'espace et que plugin_options.kb_sync ne vaut pas false. Seules les FAQ sont fournies au modèle : un article interne n'est jamais envoyé au modèle pour rédiger les suggestions, il est seulement retrouvé par similarité (son texte est indexé à la synchronisation) et signalé aux techniciens dans knowledge. Le contexte retrouvé est transmis au modèle comme une simple donnée de référence, jamais comme une instruction ;
• knowledge liste les articles retrouvés, FAQ et articles internes, du plus proche au moins proche : un seul élément par article (au plus 5), avec son numéro GLPI glpi_kb_id, son titre title tel qu'il a été synchronisé (mentions neutres à la place des données personnelles), le score de son passage le plus proche (au moins 0,86, arrondi à 3 décimales) et audience : faq (FAQ publique, dont les passages les plus proches peuvent être fournis au modèle) ou internal (article réservé aux techniciens, jamais fourni au modèle). Cette liste ne dépend pas du modèle : elle comprend chaque FAQ dont un passage lui a été fourni, et le résumé ne parle de la base de connaissances que s'il s'appuie sur un article. Elle est vide quand la base de connaissances n'a pas servi. Comme le plugin, vérifiez que l'utilisateur a le droit de voir un article avant de l'afficher.

Ce que le technicien a fait d'une analyse, pour le taux d'acceptation. Ne demande pas l'offre Pro. Les champs sont fusionnés dans une seule ligne par analyse : un champ absent ou null garde la valeur enregistrée, et au moins un des trois champs doit être renseigné (sinon 400 invalid_request). La réponse renvoie l'état fusionné. Le plugin GLPI met ces retours en file d'attente et les envoie avec son action automatique tiqoAnalyze : le tableau de bord peut les afficher avec quelques minutes de décalage.

{
  "analysis_id": "6f1c2a9e-8f0b-4c55-9d1e-2b7c3a4d5e6f",
  "category_accepted": true
}

{
  "analysis_id": "6f1c2a9e-8f0b-4c55-9d1e-2b7c3a4d5e6f",
  "category_accepted": true,
  "urgency_accepted": null,
  "reply_used": "edited"
}

Synchronise les articles de la base de connaissances (offre Pro et essai, option « Synchronisation de la base de connaissances » activée dans l'espace ; sinon 402 plan_feature_unavailable ou 403 feature_disabled). Une requête qui ne fait que supprimer (items vide) est toujours acceptée, quels que soient l'offre et les réglages. Envoyez du texte brut et les données personnelles déjà remplacées par des mentions neutres ([adresse e-mail], [numéro de téléphone], [IBAN]), jamais par des jetons <email_1> ; l'API applique de nouveau ce remplacement à la réception. Chaque article est découpé en passages d'environ 1 200 caractères qui se recouvrent, 100 au plus par article, et chaque passage est conservé avec son embedding.

• Une seule synchronisation à la fois par espace : un second appel simultané reçoit 429 rate_limited (details.reason = kb_sync_in_progress, Retry-After : 30 s).
• Par requête : 50 articles, 600 passages (sinon 400 invalid_request, too_many_chunks) et 1 Mio au plus (sinon 413 payload_too_large).
• Par espace, vérifié avant tout calcul (sinon 402 retrieval_limit_reached) : pendant l'essai 300 articles, 3 000 passages et 3 000 000 jetons d'embedding par mois ; avec l'offre Pro 5 000 articles, 50 000 passages et 30 000 000 jetons par mois. Le volume mensuel est partagé avec /solutions.
• Ordre de traitement : les suppressions (deleted_ids, articles sans texte ou sans entité) sont appliquées avant toute vérification, même quand le reste de la requête est refusé ; les entités et le statut FAQ des articles déjà indexés sont mis à jour avant les limites, si bien qu'un changement de visibilité n'est jamais refusé. Quand seule la limite d'articles est atteinte, les articles déjà indexés de la requête sont recalculés, les nouveaux sont acceptés dans l'ordre de la requête tant qu'ils tiennent dans la limite, et seuls ceux qui la dépassent sont refusés (402 retrieval_limit_reached, details.refused_ids) : comme le plugin GLPI, envoyez les articles déjà synchronisés dans des lots séparés des nouveaux. La limite de passages et le volume mensuel refusent en revanche toute la requête, y compris les modifications d'articles déjà indexés, jusqu'à la suppression d'articles, le mois suivant ou un changement d'offre.
• Chaque requête dispose de 50 s côté serveur : au-delà, aucun nouveau groupe d'articles n'est commencé, les articles déjà traités restent enregistrés et la réponse est 503 ai_unavailable (details.reason = deadline). Renvoyez le même lot avec une nouvelle clé : les articles terminés reviennent dans unchanged.
• Désactiver l'option dans l'application, ou passer à l'offre Starter, supprime la base synchronisée.

{
  "items": [
    {
      "glpi_kb_id": 12,
      "title": "Se connecter au Wi-Fi CORP-STAFF",
      "content": "Le réseau CORP-STAFF demande le certificat de l'organisation. En cas d'échec, écrire à [adresse e-mail] ...",
      "updated_at": "2026-10-28 16:05:00",
      "entity_ids": [0, 3, 4],
      "is_faq": true
    }
  ],
  "deleted_ids": [7]
}

{ "upserted": 1, "unchanged": 0, "deleted": 1, "chunks": 2, "kb_articles": 37, "truncated": 0, "truncated_ids": [], "kb_index_version": "3:mistral-embed" }

upserted : articles recalculés ; unchanged : titre et texte identiques, rien n'est recalculé (entités et statut FAQ mis à jour le cas échéant) ; deleted : articles supprimés ; chunks : passages écrits par cet appel ; kb_articles : articles synchronisés dans l'espace après l'appel ; truncated : nombre d'articles de la requête indexés en partie seulement (au-delà de 60 000 caractères ou de 100 passages) ; truncated_ids : leurs identifiants, pour signaler chacun de ces articles ; kb_index_version : version de l'indexation côté serveur, découpage et modèle d'embeddings (par exemple 3:mistral-embed ; quand elle change, renvoyez tous les articles). Chaque appel réussi, même vide, met à jour la « Dernière synchronisation » du tableau de bord.

Mémorise la solution d'un ticket résolu ou clos (offre Pro et essai, option « Mémoire des tickets résolus » activée, désactivée par défaut ; sinon 402 plan_feature_unavailable ou 403 feature_disabled). Le ticket doit déjà être connu de Tiqo, c'est-à-dire analysé au moins une fois ; sinon 404 not_found (details.resource = ticket), à ne pas réessayer. Texte brut, avec les mêmes mentions neutres que pour la base de connaissances. Les solutions proches d'un nouveau ticket de la même entité reviennent dans similar_solved. Le plugin GLPI envoie ainsi la solution des tickets qu'il a analysés, quelques minutes après la résolution, avec son action automatique ; si l'analyse du ticket est encore en cours de reprise (après une erreur), la solution attend qu'elle aboutisse.

• Par espace, au plus 1 000 solutions mémorisées pendant l'essai et 50 000 avec l'offre Pro (sinon 402 retrieval_limit_reached, details.reason = solutions) ; remplacer la solution d'un ticket déjà mémorisé ne compte pas. Les embeddings entrent dans le volume mensuel partagé avec /kb/sync.
• Une solution est supprimée quand le ticket est supprimé définitivement (purged sur /tickets/events, qui la retire aussi des solutions similaires enregistrées avec les autres analyses), quand l'option est désactivée dans l'application ou au passage à l'offre Starter ; ces deux derniers cas vident aussi les solutions similaires enregistrées avec les analyses de l'espace.

{
  "glpi_ticket_id": 987,
  "glpi_entity_id": 3,
  "title": "Wi-Fi CORP-STAFF refusé sur un portable",
  "solution_text": "Certificat RADIUS expiré sur le poste : réinstallé depuis le portail, puis oubli et reconnexion au réseau CORP-STAFF."
}

{ "glpi_ticket_id": 987, "stored": true }

Signale le cycle de vie des tickets analysés, sans aucun texte : un ticket résolu ou clos n'est plus proposé comme doublon, un ticket rouvert le redevient, et un ticket supprimé définitivement est effacé de Tiqo avec ses analyses, ses retours et sa solution ; son numéro, son titre et l'extrait de sa solution sont aussi retirés des doublons et des solutions similaires enregistrés avec les autres analyses de l'espace. Accepté pour toutes les offres et quels que soient les réglages (une suppression doit toujours aboutir). Clé d'idempotence facultative ; une clé déjà reçue dans les 24 dernières heures répond 409 duplicate_idempotency_key, même si la première requête a échoué : utilisez une nouvelle clé à chaque tentative.

Le plugin GLPI met ces événements en file d'attente et les envoie par lots de 100 au plus avec son action automatique tiqoAnalyze. Une erreur de configuration ou d'authentification (401, 402, 403, 404, horloge décalée, plugin non configuré, serveur injoignable) met la file en pause, sans compter de tentative, jusqu'à ce qu'elle soit corrigée. Un événement purged n'est jamais abandonné sur une erreur passagère : il reste en file jusqu'à 30 jours après la suppression du ticket, durée au-delà de laquelle tout événement expire. Les autres événements sont abandonnés après 10 tentatives (délai dépassé, 429, 5xx). Seule une erreur 400 ou 413 fait abandonner un lot, après un dernier envoi de ses événements purged seuls.

{
  "events": [
    { "glpi_ticket_id": 1039, "event": "solved" },
    { "glpi_ticket_id": 1020, "event": "reopened" },
    { "glpi_ticket_id": 987, "event": "purged" }
  ]
}

{ "updated": 2, "deleted": 1 }

updated : tickets dont le statut a changé ; deleted : tickets supprimés.

Renvoie l'espace, l'offre, le quota, les réglages utiles au client (dont solved_memory et kb_sync, choisis dans l'application) et les fonctions de l'offre (features). C'est l'appel du bouton « Tester la connexion » du plugin. Signé comme un GET, sans clé d'idempotence.

{
  "workspace": { "id": "0b6c1d2e-3f40-4a5b-8c6d-7e8f9a0b1c2d", "name": "Mairie de Villeneuve — DSI", "slug": "mairie-de-villeneuve-dsi" },
  "plan": "trial",
  "trial_ends_at": "2026-11-14T09:00:00.000Z",
  "usage": { "tickets_this_month": 42, "tickets_total": 42, "limit": 100, "remaining": 58 },
  "settings": {
    "language": "fr",
    "auto_apply_category": false,
    "auto_apply_urgency": false,
    "confidence_threshold": 0.8,
    "pseudonymize": true,
    "solved_memory": true,
    "kb_sync": true
  },
  "features": { "kb_grounding": true, "solved_memory": true, "duplicates": true }
}

Sans authentification. Répond 200 quand le service et la base de données fonctionnent, 503 sinon ("status": "degraded"). Utilisable par une sonde de supervision ; voir aussi la page d'état du service.

{ "status": "ok", "version": "0.1.0", "time": "2026-10-31T09:00:00.000Z", "checks": { "database": "ok" } }

Les erreurs de l’API ont toutes la même forme (sauf 404 et 405 sur un chemin ou une méthode inconnus) :

{
  "error": {
    "code": "invalid_signature",
    "message": "Missing or invalid X-Tiqo-Signature or X-Tiqo-Timestamp header.",
    "details": { "reason": "stale_timestamp" }
  }
}

• 60 requêtes par minute et par espace (429 avec Retry-After).
• 5 analyses par ticket et par jour ; les ré-analyses ne consomment pas de ticket supplémentaire.
• Au plus 3 fois la limite de tickets, tolérance de 10 % comprise, en analyses par période, ré-analyses comprises (soit 990 par mois en Starter et 330 sur toute la durée de l'essai, pas de plafond en Pro) : au-delà, 402 plan_limit_reached.
• Corps de 4 Mio au plus, 1 Mio pour /kb/sync (413).
• Une synchronisation de la base de connaissances à la fois par espace (429 kb_sync_in_progress, réessayez après Retry-After avec une nouvelle clé d'idempotence).
• Après une erreur 5xx ou un dépassement de délai, réessayez au plus 3 fois avec un délai croissant et une nouvelle clé d'idempotence : une requête interrompue a pu aboutir côté serveur. Chaque nouvelle tentative, quelle que soit l'erreur, utilise une nouvelle clé : sur /feedback, /kb/sync, /solutions et /tickets/events, un 409 signifie seulement que la clé a déjà été reçue, pas que la requête a abouti.
• Ne réessayez jamais une erreur 400, 401, 402, 403, 404 ou 409 sans changer la requête ou le réglage concerné, et toujours avec une nouvelle clé d'idempotence.