API AllAI: Guide pour Développeurs — Intégrez l'IA Partout

Si vous êtes développeur et souhaitez intégrer les fonctionnalités AllAI dans une application mobile, un CRM personnalisé, un tableau de bord interne ou tout autre système, notre API REST est votre outil. Ce guide couvre tout ce dont vous avez besoin : de l'authentification et des points de terminaison principaux aux webhooks, exemples de code et meilleures pratiques.

Aperçu de l'API REST

L'API AllAI suit les principes REST standards :

• URL de base : https://api.allai.ro/v2/
• Format : JSON pour les requêtes et les réponses
• Versionnage : La version actuelle est v2 (v1 reste active pour la compatibilité descendante)
• HTTPS obligatoire : Toutes les requêtes doivent être effectuées via HTTPS
• Encodage : UTF-8

La documentation interactive complète (Swagger/OpenAPI) est disponible à https://api.allai.ro/docs.

Authentification (Clés API)

Toutes les requêtes API nécessitent une authentification par clé API. Voici comment obtenir et utiliser la clé :

Obtenir une Clé API

1. Accédez au Tableau de bord AllAI > Paramètres > API
2. Cliquez sur « Générer une nouvelle clé API »
3. Nommez la clé (ex : « Application Mobile Production »)
4. Sélectionnez les autorisations (lecture, écriture, admin)
5. Copiez la clé générée — elle est affichée une seule fois

Utilisation dans les Requêtes

Envoyez la clé API dans l'en-tête Authorization :

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Jetons de Session (pour le Frontend)

Pour les intégrations côté client, générez un jeton de session depuis votre backend :

POST /v2/auth/session-token
{
    "chatbot_id": "cb_abc123",
    "visitor_id": "visitor_xyz",
    "expires_in": 3600
}

// Réponse :
{
    "session_token": "st_live_...",
    "expires_at": "2026-01-19T15:30:00Z"
}

Le jeton de session a des autorisations limitées (uniquement pour la conversation) et expire automatiquement.

Points de Terminaison Principaux

/conversations — Gestion des Conversations

// Lister les conversations
GET /v2/conversations?status=active&limit=50&offset=0

// Détails de la conversation
GET /v2/conversations/{conversation_id}

// Créer une nouvelle conversation
POST /v2/conversations
{
    "chatbot_id": "cb_abc123",
    "visitor": {
        "name": "Ion Popescu",
        "email": "ion@exemplu.ro"
    },
    "channel": "api",
    "metadata": {
        "source": "mobile_app",
        "page": "/produits/laptop-x"
    }
}

// Fermer la conversation
PATCH /v2/conversations/{conversation_id}
{
    "status": "closed",
    "resolution": "resolved_by_bot"
}

/messages — Envoi et Réception de Messages

// Envoyer un message dans la conversation
POST /v2/conversations/{conversation_id}/messages
{
    "content": "Bonjour, je souhaite des informations sur le produit X",
    "role": "visitor",
    "type": "text"
}

// Réponse (inclure la réponse de l'IA) :
{
    "visitor_message": {
        "id": "msg_001",
        "content": "Bonjour, je souhaite des informations sur le produit X",
        "timestamp": "2026-01-19T10:30:00Z"
    },
    "bot_response": {
        "id": "msg_002",
        "content": "Bonjour ! Le produit X est disponible...",
        "confidence": 0.94,
        "sources": ["kb_article_15", "kb_article_23"],
        "timestamp": "2026-01-19T10:30:01Z"
    }
}

// Lister les messages de la conversation
GET /v2/conversations/{conversation_id}/messages?limit=100

/contacts — Gestion des Contacts

// Lister les contacts
GET /v2/contacts?search=ion@exemplu.ro

// Créer un contact
POST /v2/contacts
{
    "name": "Ion Popescu",
    "email": "ion@exemplu.ro",
    "phone": "+40722123456",
    "tags": ["lead", "intéressé-produit-x"],
    "custom_fields": {
        "companie": "SRL Exemplu",
        "industrie": "retail"
    }
}

// Mettre à jour un contact
PUT /v2/contacts/{contact_id}

// Historique des conversations d'un contact
GET /v2/contacts/{contact_id}/conversations

/analytics — Données et Rapports

// Statistiques générales
GET /v2/analytics/overview?period=30d

// Réponse :
{
    "total_conversations": 1847,
    "resolution_rate": 0.82,
    "avg_response_time_ms": 680,
    "satisfaction_score": 4.3,
    "top_topics": [
        {"topic": "prix", "count": 312},
        {"topic": "livraison", "count": 287},
        {"topic": "retour", "count": 156}
    ],
    "conversations_by_channel": {
        "website": 1203,
        "whatsapp": 412,
        "messenger": 232
    }
}

// Conversations par jour
GET /v2/analytics/conversations?period=30d&granularity=day

// Rapport de satisfaction
GET /v2/analytics/satisfaction?period=30d

Webhooks : Notifications en Temps Réel

Les webhooks envoient des notifications HTTP POST à votre URL chaque fois qu'un événement se produit. Ils sont essentiels pour les intégrations réactives.

Configurer les Webhooks

POST /v2/webhooks
{
    "url": "https://api.votre-site.fr/allai-webhook",
    "events": [
        "conversation.started",
        "conversation.ended",
        "message.received",
        "lead.created",
        "handoff.requested"
    ],
    "secret": "webhook_secret_pour_verification"
}

Événements Disponibles

• conversation.started — Une nouvelle conversation a commencé
• conversation.ended — Une conversation a été fermée
• message.received — Un nouveau message du visiteur
• message.sent — Le chatbot a envoyé une réponse
• lead.created — Un nouveau lead a été identifié
• lead.qualified — Un lead a été qualifié automatiquement
• handoff.requested — Le chatbot demande le transfert à un agent humain
• satisfaction.rated — Le client a donné une note de satisfaction

Vérification de la Signature

Chaque webhook inclut un en-tête X-AllAI-Signature pour vérification :

// Vérification en Node.js
const crypto = require('crypto');
const signature = req.headers['x-allai-signature'];
const hash = crypto.createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

if (signature === hash) {
    // Webhook valide, traiter
} else {
    // Webhook invalide, rejeter
}

Exemples de Code

JavaScript (Node.js)

const axios = require('axios');

const allai = axios.create({
    baseURL: 'https://api.allai.ro/v2',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    }
});

// Envoyer un message et recevoir la réponse de l'IA
async function sendMessage(conversationId, message) {
    const response = await allai.post(
        `/conversations/${conversationId}/messages`,
        {
            content: message,
            role: 'visitor',
            type: 'text'
        }
    );
    return response.data.bot_response;
}

// Obtenir les analyses des 30 derniers jours
async function getAnalytics() {
    const response = await allai.get('/analytics/overview', {
        params: { period: '30d' }
    });
    return response.data;
}

Python

import requests

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.allai.ro/v2'
HEADERS = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

# Créer une nouvelle conversation
def create_conversation(chatbot_id, visitor_name, visitor_email):
    response = requests.post(
        f'{BASE_URL}/conversations',
        headers=HEADERS,
        json={
            'chatbot_id': chatbot_id,
            'visitor': {
                'name': visitor_name,
                'email': visitor_email
            },
            'channel': 'api'
        }
    )
    return response.json()

# Obtenir toutes les conversations actives
def get_active_conversations():
    response = requests.get(
        f'{BASE_URL}/conversations',
        headers=HEADERS,
        params={'status': 'active', 'limit': 50}
    )
    return response.json()

PHP

<?php
$apiKey = 'YOUR_API_KEY';
$baseUrl = 'https://api.allai.ro/v2';

// Fonction d'aide pour les requêtes API
function allaiRequest($method, $endpoint, $data = null) {
    global $apiKey, $baseUrl;

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $baseUrl . $endpoint);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ]);

    if ($method === 'POST') {
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    }

    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

// Lister les contacts
$contacts = allaiRequest('GET', '/contacts?limit=100');

// Créer un lead à partir du formulaire
$newLead = allaiRequest('POST', '/contacts', [
    'name' => 'Maria Popescu',
    'email' => 'maria@exemplu.ro',
    'tags' => ['lead', 'formulaire-contact']
]);
?>

Limites de Taux et Meilleures Pratiques

Limitations des Requêtes

• Plan Professionnel : 1.000 requêtes/minute
• Plan Entreprise : 5.000 requêtes/minute
• Plan Marque Blanche : 10.000 requêtes/minute

Les réponses incluent des en-têtes pour surveiller les limites :

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1706097600

Meilleures Pratiques

1. Implémentez un retry avec backoff exponentiel — En cas d'erreurs 429 (Trop de Requêtes) ou 5xx, attendez et réessayez avec des intervalles croissants.
2. Utilisez la pagination — Pour les grandes listes, utilisez limit et offset au lieu de demander tous les résultats en une seule fois.
3. Mettez en cache les données statiques — La configuration du chatbot, la liste des intégrations et d'autres données qui ne changent pas fréquemment.
4. Validez les webhooks — Vérifiez toujours la signature X-AllAI-Signature avant de traiter les données.
5. Gérez les erreurs — L'API renvoie des codes HTTP standard (400, 401, 403, 404, 429, 500) avec des messages descriptifs.
6. Utilisez des champs spécifiques — Le paramètre fields permet de sélectionner uniquement les champs nécessaires, réduisant ainsi le payload.

SDK Disponibles

Nous offrons des SDK officiels pour accélérer l'intégration :

• JavaScript/Node.js — npm install @allai/sdk
• Python — pip install allai-sdk
• PHP — composer require allai/sdk

Les SDK incluent :

• Wrappers pour tous les points de terminaison de l'API
• Gestion automatique des limites de taux et des retries
• Types TypeScript pour l'auto-complétion
• Vérification automatique de la signature des webhooks
• Logging intégré pour le débogage

Cas d'Utilisation Fréquents

Intégration dans une Application Mobile

Créez une expérience de chat native dans votre application mobile (iOS/Android). Votre backend communique avec l'API AllAI, et le frontend affiche la conversation dans une interface personnalisée.

Intégration dans un CRM Personnalisé

Votre entreprise a un CRM développé en interne. Les webhooks AllAI envoient les données des conversations directement dans votre CRM, sans dépendre d'intégrations prédéfinies.

Tableau de Bord Personnalisé

Construisez un tableau de bord interne qui combine des données d'AllAI avec d'autres sources (ventes, marketing, support). Le point de terminaison /analytics fournit les données nécessaires.

Automatisations Complexes

Créez des flux complexes : vérification des stocks dans l'ERP, calcul des prix dynamiques, génération d'offres PDF — tout déclenché par la conversation du chatbot via des webhooks.

Sandbox pour Tests

L'environnement sandbox permet de tester l'intégration sans affecter les données de production :

• URL de base Sandbox : https://sandbox.api.allai.ro/v2/
• Clé API Sandbox : Générée séparément depuis le Tableau de bord > Paramètres > API > Onglet Sandbox
• Données de test : Contacts et conversations fictives pré-populées
• Sans coûts : Les requêtes sandbox ne sont pas comptabilisées
• Limite de taux réduite : 100 requêtes/minute (suffisant pour les tests)

Support pour Développeurs

Si vous avez des questions ou rencontrez des problèmes avec l'API :

• Documentation interactive : https://api.allai.ro/docs
• Page de statut : https://status.allai.ro pour surveiller la disponibilité
• Email support technique : dev@allai.ro
• Communauté Discord : Rejoignez le canal #developers

Êtes-vous prêt à intégrer AllAI dans votre projet ? Générez une clé API depuis le tableau de bord et commencez avec le sandbox. Ou, si vous avez besoin d'assistance avec l'architecture de l'intégration, programmez une session technique avec notre équipe de développeurs.