Integrazjoni tal-API

Ippushja d-dejta b'mod programmatiċi lejn il-bażi ta' għarfien tiegħek ta' AI SmartTalk bl-użu tal-API REST tagħna. Ideali għal integrazjonijiet custom, pipelines awtomatiċi, u kwalunkwe sors tad-dejta li m'għandux kopertura mill-konnetturi nativi tagħna.

---

Għarfien Ġenerali

L-integrazzjoni tal-API tippermettilek li:

• Ippushja dokumenti direttament lejn il-bażi ta' għarfien tiegħek
• Aġġorna kontenut b'mod programmatiċi
• Ħassar entries li mhumiex aġġornati
• Bini ta' pipelines tad-dejta custom
• Integra ma' kwalunkwe sistema li tista' tagħmel talbiet HTTP

---

Rekwiżiti

Qabel ma tibda, żgura li għandek:

• Kont attiv ta' AI SmartTalk
• Aċċess għall-API attivat (iċċekkja l-pjan tiegħek)
• Għarfien bażiku ta' REST APIs
• Għodda biex tagħmel talbiet HTTP (curl, Postman, jew il-kodiċi tal-applikazzjoni tiegħek)

---

Kif Tikseb il-Kredenzjali tal-API Tiegħek

Pass 1: Aċċess għall-Settings tal-API

1. Log in fil-kont tiegħek ta' AI SmartTalk
2. Naviga lejn Settings → Integrations
3. Sib API u ikklikkja Configure

Pass 2: Ġenera Token tal-API

1. Ikklikkja Generate New Token
2. Ikkopja l-Chat Model ID tiegħek u API Token
3. Ħażna dawn b'mod sikur—il-token juri biss darba!

⚠️ Avż ta' Sigurtà: Qatt ma wera t-token tal-API tiegħek fil-kodiċi tal-klijent jew f'repożitorji pubbliċi.

---

Endpoints tal-API

Base URL

https://api.aismarttalk.tech/v1

Awtentikazzjoni

Kull talba teħtieġ it-token tal-API tiegħek fil-header:

Authorization: Bearer YOUR_API_TOKEN

---

API Endpoints

Base URL

https://api.aismarttalk.tech/v1

Authentication

L-għatx kollha jeħtieġu t-token tal-API tiegħek fil-header:

Authorization: Bearer YOUR_API_TOKEN

---

Importa Dokumenti

Endpoint

POST /documents/import

Request Body

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Dokumentazzjoni tal-Prodott",
      "content": "Il-kontenut sħiħ tad-dokument tiegħek imur hawn...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ]
}

Parameters

Field	Type	Required	Description
chatModelId	string	✅	L-identifikatur uniku tal-mudell tal-chat tiegħek
documents	array	✅	Array ta' oġġetti dokumenti
documents[].title	string	✅	Titolu tad-dokument għall-identifikazzjoni
documents[].content	string	✅	Kontenut sħiħ tat-tekst
documents[].url	string	❌	URL tal-fonte (għall-referenza)
documents[].metadata	object	❌	Pairs ta' chiavi u valuri personalizzati

Response

{
  "success": true,
  "imported": 1,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Dokumentazzjoni tal-Prodott",
      "status": "processing"
    }
  ]
}

Eżempju: 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": "Ghid għall-Bidu",
        "content": "Merħba fuq il-pjattaforma tagħna. Hawn kif tibda...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Query Dokumenti

Staqsi mistoqsijiet kontra l-bażi tal-għarfien tiegħek b'mod programmatiċi.

Endpoint

POST /chat/query

Request Body

{
  "chatModelId": "your-chat-model-id",
  "query": "Kif nista' nresetta l-password tiegħi?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Response

{
  "success": true,
  "response": "Biex tirrisettja l-password tiegħek, mur Settings > Security > Change Password...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Ghid tas-Sigurtà",
      "relevance": 0.95
    }
  ]
}

---

Iretrieval Dokumenti

Ħu dokumenti li jaqblu ma' mistoqsija (mingħajr risposta AI).

Endpoint

POST /documents/search

Request Body

{
  "chatModelId": "your-chat-model-id",
  "query": "sigurtà tal-password",
  "limit": 10
}

Response

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Aħjar Prattiċi tas-Sigurtà",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

---

Eżempji ta' Kodiċi

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()

# Importa dokument
result = import_document(
    title="FAQ: Shipping",
    content="Aħna noffru shipping b'xejn fuq ordnijiet ta' aktar minn $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();
}

// Importa dokument
importDocument(
  'FAQ: Returns',
  'Tista\' tirtira l-oġġetti fi żmien 30 jum minn x-xiri...',
  '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' => 'Speċifikazzjonijiet tal-Prodott',
            'content' => 'Il-widget tagħna għandu s-sigħat li ġejjin...',
            '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));

---

Każijiet ta' Użu

Integrazjoni ta' CMS Personalizzat

Sinċronizza kontenut minn CMS proprju:

• Ikkonnettja ma' avvenimenti ta' pubblikazzjoni tal-CMS
• Ippusha kontenut ġdid/miġġaħ lejn AI SmartTalk
• Neħħi kontenut imħassar

Pipeline tad-Data

Importa minn warehouses tad-data:

• Esporta data relevanti għal JSON
• Importazzjoni bil-batch permezz tal-API
• Skeda ta' aġġornamenti regolari

Prodotti E-commerce

Sinċronizza data tal-prodott minn sistemi personalizzati:

• Deskrizzjonijiet tal-prodott
• Speċifikazzjonijiet
• Informazzjoni dwar il-prezz

Sistemi Interni

Ikkonnettja għodod interni li mhumiex appoġġjati b'mod nativ:

• Wikis personalizzati
• Databases ta' ħinijiet preċedenti
• Applikazzjonijiet proprji

---

Limiti tal-Rati

Endpoint	Limitu tar-Rati
Importazzjoni ta' Dokument	100 requests/minute
Query	60 requests/minute
Search	60 requests/minute

Nota: Limiti tar-rati jvarjaw skont il-pjan. Ikkuntattja s-sapport għal limiti ogħla.

---

Ġestjoni tal-Istejjer

Format ta' Risposta ta' Żball

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Il-token tal-API mogħti huwa invalidu jew skadut"
  }
}

Kodiċi ta' Żball Komuni

Kodiċi	Deskrizzjoni	Soluzzjoni
INVALID_TOKEN	Token ħażin jew skadut	Regenera t-token tal-API
INVALID_MODEL_ID	ID ta' mudell ta' chat mhux magħruf	Iċċekkja l-ID tal-Mudell tal-Chat tiegħek
RATE_LIMITED	Żewġ requests eċċessivi	Implimenta backoff, ipprova aktar tard
INVALID_REQUEST	Korpi ta' request maħduma ħażin	Iċċekkja l-istruttura tal-JSON
DOCUMENT_TOO_LARGE	Il-kontenut jaqbeż il-limitu	Splitti f'dokumenti iżgħar
QUOTA_EXCEEDED	Il-limiti tal-pjan ġew raggiunti	Aġġorna jew ikkuntattja s-sapport

---

Soluzzjoni ta' Problemi

Falliment ta' Awtentikazzjoni

Problema	Soluzzjoni
401 Mhux Awtorizzat	Iċċekkja li t-token hu korrett u attiv
Token mhux jaħdem	Regenera t-token fil-issettjar
Token skadut	Tokens ma jiskadux, iżda jistgħu jiġu revokati

Problemi ta' Importazzjoni

Problema	Soluzzjoni
Risposta vojt	Iċċekkja li l-Content-Type hu application/json
Dokument ma jidhirx	Stenna għall-ipproċessar; iċċekkja s-sezzjoni tal-Knowledge
Importazzjoni parzjali	Xi dokumenti jistgħu jkollhom żbalji ta' validazzjoni

Problemi ta' Prestazzjoni

Problema	Soluzzjoni
Importazzjonijiet bil-mod	Batch ta' dokumenti (massimu ta' 100 għal kull request)
Timeout	Ikkurta d-daqs tal-batch, ipprova bil-backoff
Limitu tal-rata	Implimenta backoff esponenzjali

---

Aħjar Prattiċi

1. Importazzjonijiet batch: Ibgħat diversi dokumenti għal kull request (sa 100)
2. Titoli uniċi: Uża titoli deskrittivi, uniċi għal kull dokument
3. Kontenut strutturat: Kontenut ifformattjat tajjeb ittejjeb ir-risposti tal-AI
4. Tagging ta' metadata: Uża metadata għall-kategorija u filtrazzjoni
5. Tokens sikuri: Ħażen tokens fil-varjabbli tal-ambjent
6. Ġestixxi żbalji: Implimenta l-loġika ta' retry bil-backoff esponenzjali
7. Monitora l-użu: Segwi l-calls tal-API kontra l-limiti tal-pjan tiegħek

---

Dokumentazzjoni Relatata

• Integrations Overview
• Full API Documentation
• Knowledge Base Management
• SmartFlow Webhooks — Riċievi avvenimenti