Intégration API

Poussez des données de manière programmatique vers votre base de connaissances AI SmartTalk en utilisant notre API REST. Idéal pour des intégrations personnalisées, des pipelines automatisés et toute source de données non couverte par nos connecteurs natifs.

---

Aperçu

L'intégration API vous permet de :

• Pousser des documents directement vers votre base de connaissances
• Mettre à jour le contenu de manière programmatique
• Supprimer les entrées obsolètes
• Construire des pipelines de données personnalisés
• Intégrer avec tout système capable de faire des requêtes HTTP

---

Prérequis

Avant de commencer, assurez-vous d'avoir :

• Un compte AI SmartTalk actif
• L'accès API activé (vérifiez votre plan)
• Des connaissances de base sur les API REST
• Un outil pour faire des requêtes HTTP (curl, Postman, ou votre code d'application)

---

Obtenir vos Identifiants API

Étape 1 : Accéder aux Paramètres API

1. Connectez-vous à votre compte AI SmartTalk
2. Accédez à Paramètres → Intégrations
3. Trouvez API et cliquez sur Configurer

Étape 2 : Générer un Jeton API

1. Cliquez sur Générer un Nouveau Jeton
2. Copiez votre ID de Modèle de Chat et votre Jeton API
3. Conservez-les en sécurité—le jeton n'est affiché qu'une seule fois !

⚠️ Avertissement de Sécurité : Ne jamais exposer votre jeton API dans du code côté client ou dans des dépôts publics.

---

Points de Terminaison API

URL de Base

https://api.aismarttalk.tech/v1

Authentification

Toutes les requêtes nécessitent votre jeton API dans l'en-tête :

Authorization: Bearer YOUR_API_TOKEN

---

Points de terminaison de l'API

URL de base

https://api.aismarttalk.tech/v1

Authentification

Toutes les requêtes nécessitent votre jeton API dans l'en-tête :

Authorization: Bearer YOUR_API_TOKEN

---

Importer des documents

Point de terminaison

POST /documents/import

Corps de la requête

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Documentation du produit",
      "content": "Le contenu complet de votre document va ici...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ]
}

Paramètres

Champ	Type	Requis	Description
chatModelId	string	✅	Votre identifiant unique de modèle de chat
documents	array	✅	Tableau d'objets document
documents[].title	string	✅	Titre du document pour identification
documents[].content	string	✅	Contenu textuel complet
documents[].url	string	❌	URL source (pour référence)
documents[].metadata	object	❌	Paires clé-valeur personnalisées

Réponse

{
  "success": true,
  "imported": 1,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Documentation du produit",
      "status": "processing"
    }
  ]
}

Exemple : cURL

curl -X POST https://api.aismarttalk.tech/v1/documents/import \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatModelId": "your-chat-model-id",
    "documents": [
      {
        "title": "Guide de démarrage",
        "content": "Bienvenue sur notre plateforme. Voici comment commencer...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Interroger des documents

Posez des questions à votre base de connaissances de manière programmatique.

Point de terminaison

POST /chat/query

Corps de la requête

{
  "chatModelId": "your-chat-model-id",
  "query": "Comment réinitialiser mon mot de passe ?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Réponse

{
  "success": true,
  "response": "Pour réinitialiser votre mot de passe, allez dans Paramètres > Sécurité > Changer le mot de passe...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Guide de sécurité",
      "relevance": 0.95
    }
  ]
}

---

Récupérer des documents

Obtenez des documents correspondant à une requête (sans réponse AI).

Point de terminaison

POST /documents/search

Corps de la requête

{
  "chatModelId": "your-chat-model-id",
  "query": "sécurité des mots de passe",
  "limit": 10
}

Réponse

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Meilleures pratiques de sécurité",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

---

Exemples de Code

Python

import requests

API_TOKEN = "your-api-token"
CHAT_MODEL_ID = "your-chat-model-id"

def import_document(title: str, content: str, url: str = None):
    response = requests.post(
        "https://api.aismarttalk.tech/v1/documents/import",
        headers={
            "Authorization": f"Bearer {API_TOKEN}",
            "Content-Type": "application/json"
        },
        json={
            "chatModelId": CHAT_MODEL_ID,
            "documents": [{
                "title": title,
                "content": content,
                "url": url
            }]
        }
    )
    return response.json()

# Importer un document
result = import_document(
    title="FAQ : Expédition",
    content="Nous offrons la livraison gratuite sur les commandes de plus de 50 $...",
    url="https://shop.example.com/faq/shipping"
)
print(result)

JavaScript / Node.js

const API_TOKEN = 'your-api-token';
const CHAT_MODEL_ID = 'your-chat-model-id';

async function importDocument(title, content, url = null) {
  const response = await fetch('https://api.aismarttalk.tech/v1/documents/import', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      chatModelId: CHAT_MODEL_ID,
      documents: [{
        title,
        content,
        url
      }]
    })
  });
  return response.json();
}

// Importer un document
importDocument(
  'FAQ : Retours',
  'Vous pouvez retourner des articles dans les 30 jours suivant l\'achat...',
  'https://shop.example.com/faq/returns'
).then(console.log);

PHP

<?php
$apiToken = 'your-api-token';
$chatModelId = 'your-chat-model-id';

$data = [
    'chatModelId' => $chatModelId,
    'documents' => [
        [
            'title' => 'Spécifications du Produit',
            'content' => 'Notre widget a les spécifications suivantes...',
            'url' => 'https://example.com/products/widget'
        ]
    ]
];

$ch = curl_init('https://api.aismarttalk.tech/v1/documents/import');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiToken,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);

print_r(json_decode($response, true));

---

Cas d'Utilisation

Intégration CMS Personnalisée

Synchroniser le contenu d'un CMS propriétaire :

• S'accrocher aux événements de publication du CMS
• Pousser le contenu nouveau/mis à jour vers AI SmartTalk
• Supprimer le contenu supprimé

Pipeline de Données

Importer depuis des entrepôts de données :

• Exporter les données pertinentes au format JSON
• Importation par lots via l'API
• Planifier des mises à jour régulières

Produits E-commerce

Synchroniser les données des produits depuis des systèmes personnalisés :

• Descriptions des produits
• Spécifications
• Informations tarifaires

Systèmes Internes

Connecter des outils internes non pris en charge nativement :

• Wikis personnalisés
• Bases de données héritées
• Applications propriétaires

---

Limites de Taux

Point de terminaison	Limite de Taux
Importation de Document	100 requêtes/minute
Requête	60 requêtes/minute
Recherche	60 requêtes/minute

Remarque : Les limites de taux varient selon le plan. Contactez le support pour des limites plus élevées.

---

Gestion des Erreurs

Format de Réponse d'Erreur

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Le token API fourni est invalide ou a expiré"
  }
}

Codes d'Erreur Courants

Code	Description	Solution
INVALID_TOKEN	Token invalide ou expiré	Régénérez le token API
INVALID_MODEL_ID	ID de modèle de chat inconnu	Vérifiez votre ID de modèle de chat
RATE_LIMITED	Trop de requêtes	Implémentez un backoff, réessayez plus tard
INVALID_REQUEST	Corps de requête mal formé	Vérifiez la structure JSON
DOCUMENT_TOO_LARGE	Le contenu dépasse la limite	Divisez en documents plus petits
QUOTA_EXCEEDED	Limites du plan atteintes	Mettez à niveau ou contactez le support

---

Dépannage

Échecs d'Authentification

Problème	Solution
401 Non autorisé	Vérifiez que le token est correct et actif
Token ne fonctionne pas	Régénérez le token dans les paramètres
Token expiré	Les tokens n'expirent pas, mais peuvent être révoqués

Problèmes d'Importation

Problème	Solution
Réponse vide	Vérifiez que le Content-Type est application/json
Document n'apparaît pas	Attendez le traitement ; vérifiez la section Connaissance
Importation partielle	Certains documents peuvent avoir des erreurs de validation

Problèmes de Performance

Problème	Solution
Imports lents	Regroupez les documents (maximum 100 par requête)
Délais d'attente	Réduisez la taille du lot, réessayez avec un backoff
Limité par le taux	Implémentez un backoff exponentiel

---

Meilleures Pratiques

1. Imports par lots : Envoyez plusieurs documents par requête (jusqu'à 100)
2. Titres uniques : Utilisez des titres descriptifs et uniques pour chaque document
3. Contenu structuré : Un contenu bien formaté améliore les réponses de l'IA
4. Étiquetage des métadonnées : Utilisez des métadonnées pour la catégorisation et le filtrage
5. Tokens sécurisés : Stockez les tokens dans des variables d'environnement
6. Gérer les erreurs : Implémentez une logique de réessai avec un backoff exponentiel
7. Surveiller l'utilisation : Suivez les appels API par rapport aux limites de votre plan

---

Documentation Connexe

• Aperçu des Intégrations
• Documentation Complète de l'API
• Gestion de la Base de Connaissances
• Webhooks SmartFlow — Recevez des événements