Dacă ești dezvoltator și vrei să integrezi funcționalitățile AllAI într-o aplicație mobilă, un CRM custom, un dashboard intern sau orice alt sistem, API-ul nostru REST este instrumentul tău. Acest ghid acoperă tot ce ai nevoie: de la autentificare și endpoints principale la webhooks, exemple de cod și best practices.

REST API Overview

API-ul AllAI urmează principiile REST standard:

  • Base URL: https://api.allai.ro/v2/
  • Format: JSON pentru request și response
  • Versionare: Versiunea curentă este v2 (v1 rămâne activă pentru backward compatibility)
  • HTTPS obligatoriu: Toate request-urile trebuie făcute prin HTTPS
  • Encoding: UTF-8

Documentația interactivă completă (Swagger/OpenAPI) este disponibilă la https://api.allai.ro/docs.

Autentificare (API Keys)

Toate request-urile API necesită autentificare prin API key. Iată cum să obții și să folosești cheia:

Obținere API Key

  1. Accesează Dashboard AllAI > Setări > API
  2. Click pe „Generare API Key Nouă"
  3. Denumește cheia (ex: „App Mobilă Producție")
  4. Selectează permisiunile (read, write, admin)
  5. Copiază cheia generată — este afișată o singură dată

Utilizare în Request-uri

Trimite API key-ul în header-ul Authorization:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
⚠️ Securitate

Nu expune niciodată API key-ul în cod client-side (JavaScript frontend, aplicații mobile decompilabile). Folosește-l doar pe server-side. Pentru integrări frontend, utilizează token-urile de sesiune (vezi secțiunea Session Tokens mai jos).

Session Tokens (pentru Frontend)

Pentru integrări client-side, generează un session token din backend-ul tău:

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

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

Session token-ul are permisiuni limitate (doar conversație) și expiră automat.

Endpoints Principale

/conversations — Gestionare Conversații

// Listare conversații
GET /v2/conversations?status=active&limit=50&offset=0

// Detalii conversație
GET /v2/conversations/{conversation_id}

// Creare conversație nouă
POST /v2/conversations
{
    "chatbot_id": "cb_abc123",
    "visitor": {
        "name": "Ion Popescu",
        "email": "ion@exemplu.ro"
    },
    "channel": "api",
    "metadata": {
        "source": "mobile_app",
        "page": "/produse/laptop-x"
    }
}

// Închidere conversație
PATCH /v2/conversations/{conversation_id}
{
    "status": "closed",
    "resolution": "resolved_by_bot"
}

/messages — Trimitere și Primire Mesaje

// Trimitere mesaj în conversație
POST /v2/conversations/{conversation_id}/messages
{
    "content": "Bună ziua, doresc informații despre produsul X",
    "role": "visitor",
    "type": "text"
}

// Response (include răspunsul AI):
{
    "visitor_message": {
        "id": "msg_001",
        "content": "Bună ziua, doresc informații despre produsul X",
        "timestamp": "2026-01-19T10:30:00Z"
    },
    "bot_response": {
        "id": "msg_002",
        "content": "Bună ziua! Produsul X este disponibil...",
        "confidence": 0.94,
        "sources": ["kb_article_15", "kb_article_23"],
        "timestamp": "2026-01-19T10:30:01Z"
    }
}

// Listare mesaje din conversație
GET /v2/conversations/{conversation_id}/messages?limit=100

/contacts — Managementul Contactelor

// Listare contacte
GET /v2/contacts?search=ion@exemplu.ro

// Creare contact
POST /v2/contacts
{
    "name": "Ion Popescu",
    "email": "ion@exemplu.ro",
    "phone": "+40722123456",
    "tags": ["lead", "interesat-produs-x"],
    "custom_fields": {
        "companie": "SRL Exemplu",
        "industrie": "retail"
    }
}

// Actualizare contact
PUT /v2/contacts/{contact_id}

// Istoricul conversațiilor unui contact
GET /v2/contacts/{contact_id}/conversations

/analytics — Date și Rapoarte

// Statistici generale
GET /v2/analytics/overview?period=30d

// Response:
{
    "total_conversations": 1847,
    "resolution_rate": 0.82,
    "avg_response_time_ms": 680,
    "satisfaction_score": 4.3,
    "top_topics": [
        {"topic": "prețuri", "count": 312},
        {"topic": "livrare", "count": 287},
        {"topic": "retur", "count": 156}
    ],
    "conversations_by_channel": {
        "website": 1203,
        "whatsapp": 412,
        "messenger": 232
    }
}

// Conversații pe zi
GET /v2/analytics/conversations?period=30d&granularity=day

// Raport satisfacție
GET /v2/analytics/satisfaction?period=30d

Webhooks: Notificări în Real-Time

Webhook-urile trimit notificări HTTP POST către URL-ul tău de fiecare dată când un eveniment are loc. Sunt esențiale pentru integrări reactive.

Configurare Webhooks

POST /v2/webhooks
{
    "url": "https://api.situl-tau.ro/allai-webhook",
    "events": [
        "conversation.started",
        "conversation.ended",
        "message.received",
        "lead.created",
        "handoff.requested"
    ],
    "secret": "webhook_secret_pentru_verificare"
}

Evenimente Disponibile

  • conversation.started — O conversație nouă a început
  • conversation.ended — O conversație s-a închis
  • message.received — Un mesaj nou de la vizitator
  • message.sent — Chatbot-ul a trimis un răspuns
  • lead.created — Un nou lead a fost identificat
  • lead.qualified — Un lead a fost calificat automat
  • handoff.requested — Chatbot-ul solicită transferul către un agent uman
  • satisfaction.rated — Clientul a dat o notă de satisfacție

Verificare Semnătură

Fiecare webhook include un header X-AllAI-Signature pentru verificare:

// Verificare în 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 valid, procesează
} else {
    // Webhook invalid, respinge
}
💡 Consejo Pro

Configurează webhook-urile să returneze status 200 rapid (sub 5 secunde) și procesează datele asincron. Dacă endpoint-ul tău nu răspunde în 30 de secunde, AllAI va face retry de 3 ori cu backoff exponențial.

Exemple de Cod

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'
    }
});

// Trimite un mesaj și primește răspunsul AI
async function sendMessage(conversationId, message) {
    const response = await allai.post(
        `/conversations/${conversationId}/messages`,
        {
            content: message,
            role: 'visitor',
            type: 'text'
        }
    );
    return response.data.bot_response;
}

// Obține analytics-ul ultimelor 30 de zile
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'
}

# Creare conversație nouă
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()

# Obține toate conversațiile active
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';

// Funcție helper pentru request-uri 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);
}

// Listare contacte
$contacts = allaiRequest('GET', '/contacts?limit=100');

// Creare lead din formular
$newLead = allaiRequest('POST', '/contacts', [
    'name' => 'Maria Popescu',
    'email' => 'maria@exemplu.ro',
    'tags' => ['lead', 'formular-contact']
]);
?>

Rate Limits și Best Practices

Limitări de Request-uri

  • Plan Professional: 1.000 request-uri/minut
  • Plan Enterprise: 5.000 request-uri/minut
  • Plan White-Label: 10.000 request-uri/minut

Răspunsurile includ header-e pentru monitorizarea limitelor:

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

Best Practices

  1. Implementează retry cu backoff exponențial — La erori 429 (Too Many Requests) sau 5xx, așteaptă și încearcă din nou cu intervale crescătoare.
  2. Folosește paginare — Pentru listări mari, folosește limit și offset în loc să ceri toate rezultatele odată.
  3. Cache-uiește datele statice — Configurația chatbot-ului, lista de integrări și alte date care nu se schimbă frecvent.
  4. Validează webhook-urile — Verifică întotdeauna semnătura X-AllAI-Signature înainte de a procesa datele.
  5. Gestionează erorile — API-ul returnează coduri HTTP standard (400, 401, 403, 404, 429, 500) cu mesaje descriptive.
  6. Folosește câmpuri specifice — Parametrul fields permite selectarea doar a câmpurilor necesare, reducând payload-ul.
⚠️ Important

Nu stoca API key-uri în repository-uri Git publice. Folosește variabile de environment (.env) sau un secrets manager. Dacă un API key este compromis, revocă-l imediat din Dashboard și generează altul.

SDK-uri Disponibile

Oferim SDK-uri oficiale pentru a accelera integrarea:

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

SDK-urile includ:

  • Wrapper-e pentru toate endpoint-urile API
  • Gestionare automată a rate limit-urilor și retry-urilor
  • Tipuri TypeScript pentru autocompletare
  • Verificare automată a semnăturii webhook-urilor
  • Logging integrat pentru debugging

Use Cases Frecvente

Integrare în Aplicație Mobilă

Creezi o experiență de chat nativă în aplicația ta mobilă (iOS/Android). Backend-ul tău comunică cu API-ul AllAI, iar frontend-ul afișează conversația într-o interfață custom.

Integrare în CRM Custom

Compania ta are un CRM dezvoltat intern. Webhook-urile AllAI trimit datele conversațiilor direct în CRM-ul tău, fără a depinde de integrări predefinite.

Dashboard Personalizat

Construiești un dashboard intern care combină date din AllAI cu alte surse (vânzări, marketing, suport). Endpoint-ul /analytics furnizează datele necesare.

Automatizări Complexe

Creezi fluxuri complexe: verificare stoc în ERP, calculare preț dinamic, generare ofertă PDF — totul declanșat din conversația chatbot-ului prin webhook-uri.

Sandbox pentru Testare

Mediul sandbox permite testarea integrării fără a afecta datele de producție:

  • Base URL Sandbox: https://sandbox.api.allai.ro/v2/
  • API Key Sandbox: Generează separat din Dashboard > Setări > API > Tab Sandbox
  • Date de test: Contacte și conversații fictive pre-populare
  • Fără costuri: Request-urile sandbox nu se contorizează
  • Rate limit redus: 100 request-uri/minut (suficient pentru testare)
💡 Consejo Pro

Dezvoltă și testează întotdeauna în sandbox înainte de a trece în producție. Folosește variabile de environment pentru a comuta ușor între sandbox.api.allai.ro și api.allai.ro.

Suport pentru Dezvoltatori

Dacă ai întrebări sau întâmpini probleme cu API-ul:

  • Documentație interactivă: https://api.allai.ro/docs
  • Status page: https://status.allai.ro pentru monitorizarea disponibilității
  • Email suport tehnic: dev@allai.ro
  • Comunitate Discord: Alătură-te canalului #developers

Ești pregătit să integrezi AllAI în proiectul tău? Generează un API key din dashboard și începe cu sandbox-ul. Sau, dacă ai nevoie de asistență cu arhitectura integrării, programează o sesiune tehnică cu echipa noastră de dezvoltatori.