API-integraatio

Siirrä tietoja ohjelmallisesti AI SmartTalk -tietopohjaasi käyttämällä REST API:a. Ihanteellinen mukautettuihin integraatioihin, automatisoituihin putkistoihin ja mihin tahansa tietolähteeseen, jota ei kateta natiiviliittimillämme.

---

Yleiskatsaus

API-integraatio mahdollistaa:

• Asiakirjojen siirtämisen suoraan tietopohjaasi
• Sisällön päivittämisen ohjelmallisesti
• Vanhojen tietueiden 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-tunnistetietojen 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: Luo API-tunnus

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

⚠️ Turvavaroitus: Älä koskaan paljasta API-tunnustasi asiakaspään koodissa tai julkisissa repositorioissa.

---

API-päätepisteet

Perus-URL

https://api.aismarttalk.tech/v1

Todennus

Kaikki pyynnöt vaativat API-tunnuksesi otsikossa:

Authorization: Bearer YOUR_API_TOKEN

---

API-päätteet

Perus-URL

https://api.aismarttalk.tech/v1

Varmennus

Kaikki pyynnöt vaativat API-tunnuksesi otsikossa:

Authorization: Bearer YOUR_API_TOKEN

---

Tuo asiakirjat

Päätteen

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 (viittaukseksi)
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äätteen

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äätteen

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 tilauksiin...",
    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' => 'Tuotetiedot',
            'content' => 'Meidän widgetillä on seuraavat 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 julkaisu-tapahtumiin
• Siirrä uutta/päivitettyä sisältöä AI SmartTalkiin
• Poista poistettu sisältö

Datan putki

Tuo tietovarastoista:

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

Verkkokaupan tuotteet

Synkronoi tuotedata mukautetuista järjestelmistä:

• Tuotekuvaukset
• Tiedot
• Hintatiedot

Sisäiset järjestelmät

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

• 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 korkeampien rajoitusten saamiseksi.

---

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 takaisinvetomekanismi, yritä myöhemmin uudelleen
INVALID_REQUEST	Virheellinen pyyntö	Tarkista JSON-rakenne
DOCUMENT_TOO_LARGE	Sisältö ylittää rajan	Jaa pienempiin asiakirjoihin
QUOTA_EXCEEDED	Suunnitelman rajoitukset saavutettu	Päivitä tai ota yhteyttä tukeen

---

Vianetsintä

Todennus epäonnistuu

Ongelma	Ratkaisu
401 Valtuutus epäonnistui	Tarkista, että tunnus on oikea ja aktiivinen
Tunnus ei toimi	Luo tunnus uudelleen asetuksista
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 Tietämyksen osio
Osittainen tuonti	Joissakin asiakirjoissa voi olla validoimattomia virheitä

Suorituskykyongelmat

Ongelma	Ratkaisu
Hitaita tuontia	Käsittele asiakirjat erissä (max 100 per pyyntö)
Aikakatkaisut	Vähennä eräkokoa, yritä uudelleen takaisinvetomekanismilla
Rajoitettu käyttö	Toteuta eksponentiaalinen takaisinvetomekanismi

---

Parhaat käytännöt

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

---

Liittyvä dokumentaatio

• Integraatioiden yleiskatsaus
• Koko API-dokumentaatio
• Tietämyksen hallinta
• SmartFlow Webhookit — Vastaanota tapahtumia