API-integraatio

Työnnä tietoja ohjelmallisesti AI SmartTalk -tietopohjaasi käyttämällä REST API:ta. Ihanteellinen mukautetuille integraatioille, automatisoiduille putkistoille ja kaikille tietolähteille, joita ei kateta natiiviliittimillämme.

---

Yleiskatsaus

API-integraatio mahdollistaa:

• Dokumenttien työntämisen suoraan tietopohjaasi
• Sisällön päivittämisen ohjelmallisesti
• Vanhojen tietojen poistamisen
• Mukautettujen tietoputkien rakentamisen
• Integroimisen mihin tahansa järjestelmään, joka voi tehdä HTTP-pyyntöjä

---

Esivaatimukset

Ennen kuin aloitat, varmista, että sinulla on:

• Aktiivinen AI SmartTalk -tili
• API-käyttöoikeus aktivoituna (tarkista suunnitelmasi)
• Perustiedot REST API:sta
• Työkalu HTTP-pyyntöjen tekemiseen (curl, Postman tai sovelluskoodisi)

---

API-todistusten hankkiminen

Vaihe 1: Pääsy API-asetuksiin

1. Kirjaudu AI SmartTalk -tilillesi
2. Siirry kohtaan Asetukset → Integraatiot
3. Etsi API ja napsauta Määritä

Vaihe 2: Generoi API-tunnus

1. Napsauta Generoi uusi tunnus
2. Kopioi Chat-mallin ID ja API-tunnus
3. Tallenna nämä turvallisesti—tunnus näytetään vain kerran!

⚠️ Turvallisuusvaroitus: Älä koskaan paljasta API-tunnustasi asiakaspuolen koodissa tai julkisissa repositorioissa.

---

API-päätepisteet

Perus-URL

https://api.aismarttalk.tech/v1

Todennus

Kaikissa pyyntöissä vaaditaan API-tunnuksesi otsikossa:

Authorization: Bearer YOUR_API_TOKEN

---

API-päätepisteet

Perus-URL

https://api.aismarttalk.tech/v1

Varmennus

Kaikki pyynnöt vaativat API-tunnuksesi otsikossa:

Authorization: Bearer YOUR_API_TOKEN

---

Tuo asiakirjat

Päätepiste

POST /documents/import

Pyyntöruumis

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Tuotedokumentaatio",
      "content": "Asiakirjasi koko sisältö menee tänne...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ]
}

Parametrit

Kenttä	Tyyppi	Pakollinen	Kuvaus
chatModelId	merkkijono	✅	Yksilöllinen chat-mallin tunnisteesi
documents	taulukko	✅	Asiakirjaobjektien taulukko
documents[].title	merkkijono	✅	Asiakirjan otsikko tunnistamista varten
documents[].content	merkkijono	✅	Koko tekstisisältö
documents[].url	merkkijono	❌	Lähde-URL (viitteenä)
documents[].metadata	objekti	❌	Mukautetut avain-arvo-parit

Vastaus

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

Esimerkki: 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": "Aloitusopas",
        "content": "Tervetuloa alustallemme. Tässä on, miten pääset alkuun...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Kysely asiakirjat

Esitä kysymyksiä tietopohjaasi ohjelmallisesti.

Päätepiste

POST /chat/query

Pyyntöruumis

{
  "chatModelId": "your-chat-model-id",
  "query": "Miten voin palauttaa salasanani?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Vastaus

{
  "success": true,
  "response": "Palauttaaksesi salasanasi, siirry kohtaan Asetukset > Tietoturva > Vaihda salasana...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Tietoturvaopas",
      "relevance": 0.95
    }
  ]
}

---

Hae asiakirjat

Hae asiakirjoja, jotka vastaavat kyselyä (ilman AI-vastausta).

Päätepiste

POST /documents/search

Pyyntöruumis

{
  "chatModelId": "your-chat-model-id",
  "query": "salasanan turvallisuus",
  "limit": 10
}

Vastaus

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Tietoturvan parhaat käytännöt",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

Koodiesimerkit

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

# Tuo asiakirja
result = import_document(
    title="FAQ: Toimitus",
    content="Tarjoamme ilmaisen toimituksen yli 50 dollarin tilauksille...",
    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();
}

// Tuo asiakirja
importDocument(
  'FAQ: Palautukset',
  'Voit palauttaa tuotteita 30 päivän kuluessa ostosta...',
  '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' => 'Tuotteen tekniset tiedot',
            'content' => 'Meidän widgetillämme on seuraavat tekniset tiedot...',
            '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));

---

Käyttötapaukset

Mukautettu CMS-integraatio

Synkronoi sisältöä omasta CMS:stä:

• Liity CMS:n julkaisutapahtumiin
• Siirrä uutta/päivitettyä sisältöä AI SmartTalkiin
• Poista poistettu sisältö

Datan putki

Tuo datavarastoista:

• Vie olennaiset tiedot JSON-muotoon
• Ryhmätuonti API:n kautta
• Aikatauluta säännölliset päivitykset

Verkkokaupan tuotteet

Synkronoi tuotedata mukautetuista järjestelmistä:

• Tuotekuvaukset
• Tekniset tiedot
• Hintatiedot

Sisäiset järjestelmät

Yhdistä sisäiset työkalut, joita ei tueta natively:

• Mukautetut wikit
• Perintödatabases
• Omistusoikeudelliset sovellukset

---

Rajoitukset

Päätepiste	Rajoitus
Asiakirjan tuonti	100 pyyntöä/minuutti
Kysely	60 pyyntöä/minuutti
Haku	60 pyyntöä/minuutti

Huom: Rajoitukset vaihtelevat suunnitelman mukaan. Ota yhteyttä tukeen saadaksesi korkeammat rajat.

---

Virheiden käsittely

Virhevastauksen muoto

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Annettu API-tunnus on virheellinen tai vanhentunut"
  }
}

Yleiset virhekoodit

Koodi	Kuvaus	Ratkaisu
INVALID_TOKEN	Huono tai vanhentunut tunnus	Luo API-tunnus uudelleen
INVALID_MODEL_ID	Tuntematon keskustelumallin ID	Tarkista keskustelumallin ID
RATE_LIMITED	Liian monta pyyntöä	Toteuta takaisinotto, yritä myöhemmin uudelleen
INVALID_REQUEST	Virheellinen pyyntörunko	Tarkista JSON-rakenne
DOCUMENT_TOO_LARGE	Sisältö ylittää rajan	Jaa pienempiin asiakirjoihin
QUOTA_EXCEEDED	Suunnitelman rajat saavutettu	Päivitä tai ota yhteyttä tukeen

---

Vianetsintä

Todennus epäonnistuu

Ongelma	Ratkaisu
401 Ei valtuutettu	Tarkista, että tunnus on oikea ja aktiivinen
Tunnus ei toimi	Luo tunnus uudelleen asetuksissa
Vanhentunut tunnus	Tunnukset eivät vanhene, mutta ne voidaan peruuttaa

Tuontiongelmat

Ongelma	Ratkaisu
Tyhjät vastaukset	Tarkista, että Content-Type on application/json
Asiakirja ei näy	Odota käsittelyä; tarkista Tietopankki-osio
Osittainen tuonti	Joissakin asiakirjoissa voi olla validointivirheitä

Suorituskykyongelmat

Ongelma	Ratkaisu
Hitaita tuonteja	Ryhmittele asiakirjat (max 100 per pyyntö)
Aikakatkaisut	Vähennä eräkokoa, yritä uudelleen takaisinotolla
Rajoitettu	Toteuta eksponentiaalinen takaisinotto

---

Parhaat käytännöt

1. Ryhmätuonti: Lähetä useita asiakirjoja per pyyntö (enintään 100)
2. Uniikit otsikot: Käytä kuvaavia, ainutlaatuisia otsikoita jokaiselle asiakirjalle
3. Rakenteellinen sisältö: Hyvin muotoiltu sisältö parantaa AI-vastauksia
4. Metatietojen merkitseminen: Käytä metatietoja luokitteluun ja suodattamiseen
5. Turvalliset tunnukset: Tallenna tunnukset ympäristömuuttujiin
6. Virheiden käsittely: Toteuta uudelleenyrityslogiikka eksponentiaalisella takaisinotolla
7. Käytön seuranta: Seuraa API-kutsuja suunnitelmasi rajoja vastaan

---

Liittyvä dokumentaatio

• Integraatioiden yleiskatsaus
• Koko API-dokumentaatio
• Tietopankin hallinta
• SmartFlow Webhookit — Vastaanota tapahtumia