Skip to content

Przewodnik po API naszej aplikacji

1. Wprowadzenie

Nasze API umożliwia programistyczne korzystanie z funkcji naszej aplikacji AI, w tym tworzenie wątków konwersacji, wysyłanie zapytań do różnych modeli oraz zarządzanie załącznikami i ustawieniami. Komunikacja odbywa się za pomocą standardowych zapytań HTTP, a dane są przesyłane w formacie JSON.

Unikalny endpoint API

Ważne: Każdy klient posiada swój indywidualny endpoint API. Twój unikalny URL bazowy API jest konieczny do wszystkich wywołań API i powinien być używany jako zmienna w twoich aplikacjach:

const CHATBOT_WIDGET_API_URL = 'https://twój-unikalny-endpoint.laurenscoster.com/api';

Ten URL otrzymasz po rejestracji jako klient naszej platformy i jest on powiązany z twoim kontem. Przykładowy endpoint może wyglądać następująco:

https://demo-backend.laurenscoster.com/api

We wszystkich przykładach w tej dokumentacji używamy zmiennej CHATBOT_WIDGET_API_URL dla oznaczenia twojego unikalnego bazowego URL API.

Format odpowiedzi

Wszystkie odpowiedzi są zwracane w formacie JSON z odpowiednim kodem statusu HTTP.

2. Autentykacja

Do komunikacji z API wymagane jest uwierzytelnienie za pomocą tokenu z konta usługowego (Service Account).

Tokeny Service Account

Tokeny Service Account zapewniają bezpieczny i kontrolowany dostęp do API. Każdy token ma określony zestaw uprawnień i może być w dowolnym momencie unieważniony.

Format nagłówka autoryzacji:

Authorization: Token YOUR_API_TOKEN

Gdzie YOUR_API_TOKEN to unikalny token dostępu generowany w panelu konta usługowego.

Zarządzanie tokenami

Możesz zarządzać swoimi tokenami API w panelu administratora:

  1. Tworzenie tokenów - określ nazwę, uprawnienia i opcjonalny termin ważności
  2. Unieważnianie tokenów - natychmiastowe wycofanie dostępu
  3. Rotacja tokenów - wymiana istniejącego tokenu na nowy bez przerwy w dostępie
  4. Monitorowanie użycia - śledzenie aktywności dla każdego tokenu

Uprawnienia tokenów

Tokeny mogą mieć różne poziomy dostępu:

Uprawnienie Opis
read Tylko odczyt danych
write Odczyt i tworzenie zasobów
admin Pełen dostęp, w tym możliwość usuwania zasobów
files Zarządzanie plikami

Zalecamy stosowanie zasady minimalnych uprawnień - przydzielanie tokenowi tylko tych uprawnień, które są niezbędne do wykonania konkretnych zadań.

3.Struktura zapytań

Podstawowa struktura URL

${CHATBOT_WIDGET_API_URL}/{zasób}/{identyfikator}/{akcja}

Metody HTTP

API obsługuje standardowe metody HTTP:

  • GET - pobieranie zasobów
  • POST - tworzenie zasobów
  • PUT - pełna aktualizacja zasobów
  • PATCH - częściowa aktualizacja zasobów
  • DELETE - usuwanie zasobów

Parametry zapytania

Parametry mogą być przekazywane na trzy sposoby:

  1. Jako parametry ścieżki: /api/chatbot/threads/{thread_id}
  2. Jako parametry zapytania: /api/chatbot/threads?limit=10&offset=0
  3. Jako dane JSON w ciele zapytania

4. Dostępne endpointy

Zarządzanie wątkami

Endpoint Metoda Opis
/api/chatbot/threads/ GET Pobierz listę wątków
/api/chatbot/threads/ POST Utwórz nowy wątek
/api/chatbot/threads/{id}/ GET Pobierz szczegóły wątku
/api/chatbot/threads/{id}/ PUT Zaktualizuj wątek
/api/chatbot/threads/{id}/ DELETE Usuń wątek

Wiadomości

Endpoint Metoda Opis
/api/chatbot/{chatbot_id}/threads/{thread_id}/messages/ GET Pobierz wiadomości wątku
/api/chatbot/{chatbot_id}/threads/{thread_id}/response/ POST Wyślij wiadomość i otrzymaj odpowiedź

Pliki i załączniki

Proces przesyłania plików składa się z trzech etapów:

Endpoint Metoda Opis
/api/files/upload-url/ POST Generuj podpisany URL do przesłania pliku
/api/files/update/ POST Zaktualizuj status pliku po przesłaniu
/api/files/{id}/ GET Pobierz informacje o pliku
/api/files/{id}/ DELETE Usuń plik
/api/chatbot/threads/{thread_id}/files/ GET Pobierz pliki załączone do wątku

Modele

Endpoint Metoda Opis
/api/models/ GET Pobierz dostępne modele
/api/models/{id}/ GET Pobierz szczegóły modelu

Service Accounts

Endpoint Metoda Opis
/api/service-accounts/ GET Pobierz listę kont usługowych
/api/service-accounts/ POST Utwórz nowe konto usługowe
/api/service-accounts/{id}/tokens/ GET Pobierz tokeny konta usługowego
/api/service-accounts/{id}/tokens/ POST Wygeneruj nowy token
/api/service-accounts/{id}/tokens/{token_id}/ DELETE Unieważnij token

5. Przykłady użycia

Inicjalizacja klienta API

// Konfiguracja klienta API
const CHATBOT_WIDGET_API_URL = 'https://twój-unikalny-endpoint.laurenscoster.com/api';
const CHATBOT_ID = '44da2c7d-9449-4df7-bd8a-2eaedca53535';
const ACCESS_TOKEN = 'f350a16a71c0eab685c5c502fd8eb1402e7e361c8960290ae5462d71e4076551';

// Funkcja pomocnicza do wykonywania żądań
async function apiRequest(endpoint, method = 'GET', data = null) {
  const url = `${CHATBOT_WIDGET_API_URL}${endpoint}`;
  const options = {
    method,
    headers: {
      'Authorization': `Token ${ACCESS_TOKEN}`,
      'Content-Type': 'application/json'
    }
  };

  if (data) {
    options.body = JSON.stringify(data);
  }

  const response = await fetch(url, options);

  if (!response.ok) {
    throw new Error(`API error: ${response.status} - ${await response.text()}`);
  }

  return response.json();
}

1. Utworzenie nowego wątku

Zapytanie:

curl -X POST "${CHATBOT_WIDGET_API_URL}/chatbot/threads/" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Mój nowy wątek",
    "chatbot": "44da2c7d-9449-4df7-bd8a-2eaedca53535"
  }'

Odpowiedź:

{
  "uuid": "7f9a8d7c-6b5e-4f3d-2c1b-0a9b8c7d6e5f",
  "title": "Mój nowy wątek",
  "created_at": "2023-07-15T10:30:45Z",
  "updated_at": "2023-07-15T10:30:45Z",
  "chatbot": "44da2c7d-9449-4df7-bd8a-2eaedca53535"
}

2. Wysłanie wiadomości i uzyskanie odpowiedzi

Zapytanie:

curl -X POST "${CHATBOT_WIDGET_API_URL}/chatbot/44da2c7d-9449-4df7-bd8a-2eaedca53535/threads/7f9a8d7c-6b5e-4f3d-2c1b-0a9b8c7d6e5f/response/" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-flash",
    "text": "Jaka jest stolica Polski?"
  }'

Odpowiedź:

{
  "id": "msg_123456789",
  "thread_id": "7f9a8d7c-6b5e-4f3d-2c1b-0a9b8c7d6e5f",
  "created_at": "2023-07-15T10:32:15Z",
  "role": "assistant",
  "text": "Stolica Polski to Warszawa. Jest to największe miasto w Polsce, a także centrum polityczne, gospodarcze i kulturalne kraju.",
  "model": "gemini-flash",
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 25,
    "total_tokens": 37
  }
}

3. Przesyłanie pliku (pełny proces)

Krok 1: Generowanie podpisanego URL-a do przesłania pliku

Zapytanie:

curl -X POST "${CHATBOT_WIDGET_API_URL}/files/upload-url/" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "dokument.pdf",
    "content_type": "application/pdf",
    "thread_id": "7f9a8d7c-6b5e-4f3d-2c1b-0a9b8c7d6e5f",
    "description": "Ważny dokument z danymi"
  }'

Odpowiedź:

{
  "file_id": "file_pending_987654321",
  "upload_url": "https://storage-service.example.com/uploads/temp_987654321?signature=abc123...",
  "expires_at": "2023-07-15T11:00:00Z"
}

Krok 2: Przesłanie pliku pod wskazany URL

Zapytanie:

curl -X PUT "https://storage-service.example.com/uploads/temp_987654321?signature=abc123..." \
  -H "Content-Type: application/pdf" \
  --data-binary "@dokument.pdf"

Odpowiedź: Zwykle kod statusu HTTP 200 OK lub 204 No Content bez treści.

Krok 3: Zaktualizowanie statusu pliku

Zapytanie:

curl -X POST "${CHATBOT_WIDGET_API_URL}/files/update/" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "file_pending_987654321",
    "status": "completed"
  }'

Odpowiedź:

{
  "id": "file_987654321",
  "filename": "dokument.pdf",
  "size": 1254789,
  "mime_type": "application/pdf",
  "description": "Ważny dokument z danymi",
  "created_at": "2023-07-15T10:40:22Z",
  "updated_at": "2023-07-15T10:42:15Z",
  "thread_id": "7f9a8d7c-6b5e-4f3d-2c1b-0a9b8c7d6e5f",
  "status": "completed",
  "url": "${CHATBOT_WIDGET_API_URL}/files/dokument_987654321.pdf"
}

4. Tworzenie nowego tokenu API

Zapytanie:

curl -X POST "${CHATBOT_WIDGET_API_URL}/service-accounts/5eb2f645-7a2d-4c34-9a1b-2c3d4e5f6a7b/tokens/" \
  -H "Authorization: Token ADMIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Token dla systemu CRM",
    "permissions": ["read", "write"],
    "expires_at": "2024-12-31T23:59:59Z"
  }'

Odpowiedź:

{
  "id": "token_1a2b3c4d5e",
  "service_account_id": "5eb2f645-7a2d-4c34-9a1b-2c3d4e5f6a7b",
  "name": "Token dla systemu CRM",
  "token": "f350a16a71c0eab685c5c502fd8eb1402e7e361c8960290ae5462d71e4076551",
  "permissions": ["read", "write"],
  "created_at": "2023-07-15T11:20:45Z",
  "expires_at": "2024-12-31T23:59:59Z",
  "last_used_at": null
}

6. Obsługa błędów

API zwraca odpowiednie kody statusu HTTP oraz strukturę JSON z opisem błędu:

{
  "error": {
    "code": "authentication_required",
    "message": "Brak autoryzacji do wykonania tej operacji",
    "details": "Token wygasł lub jest nieprawidłowy"
  }
}

Typowe kody błędów

Kod statusu Opis
400 Nieprawidłowe zapytanie - sprawdź parametry
401 Brak autoryzacji - sprawdź token
403 Dostęp zabroniony - brak uprawnień
404 Zasób nie znaleziony
429 Przekroczono limit zapytań
500 Błąd serwera - skontaktuj się z supportem

7. Limity zapytań

Aby zapewnić stabilność i dostępność API, stosujemy następujące limity:

Plan Zapytań na minutę Zapytań dziennie Jednoczesnych połączeń
Podstawowy 60 10,000 5
Biznes 300 50,000 20
Enterprise 1,000 Bez limitu 100

Po przekroczeniu limitów otrzymasz kod błędu 429. W odpowiedzi znajdziesz również nagłówki: - X-RateLimit-Limit: limit zapytań - X-RateLimit-Remaining: pozostała liczba zapytań - X-RateLimit-Reset: czas do zresetowania limitu (w sekundach)

8. Najlepsze praktyki

  1. Używaj identyfikacji aplikacji - Zawsze dołączaj nagłówek User-Agent z nazwą swojej aplikacji.
  2. Implementuj buforowanie - Wykorzystuj nagłówki ETag i If-None-Match do ograniczenia transferu danych.
  3. Obsługuj ograniczenia szybkości - Implementuj mechanizm ponownych prób z wykładniczym wycofaniem.
  4. Przechowuj tokeny bezpiecznie - Nie umieszczaj tokenów w publicznie dostępnym kodzie.
  5. Monitoruj zużycie - Regularnie sprawdzaj metryki zużycia API w panelu administracyjnym.
  6. Regularnie rotuj tokeny - Zmieniaj tokeny przynajmniej raz na 90 dni dla lepszego bezpieczeństwa.
  7. Używaj dedykowanych tokenów - Twórz osobne tokeny dla różnych systemów i zastosowań.
  8. Zapamiętuj swój endpoint API - Przechowuj unikalny URL endpoint API w zmiennej konfiguracyjnej aplikacji.

9. FAQ

Jak uzyskać token API?

Token API można wygenerować w panelu administratora w sekcji "Konta usługowe" > "Tokeny API". Upewnij się, że nadajesz tokenowi odpowiednie uprawnienia. Tokeny są powiązane z konkretnym kontem usługowym (Service Account).

Gdzie znajdę mój unikalny endpoint API?

Twój unikalny endpoint API jest dostępny w panelu administratora w sekcji "Ustawienia API" > "Endpoint URL". Ten endpoint jest przypisany specjalnie do twojego konta i powinien być używany jako bazowy URL we wszystkich wywołaniach API.

Czy mogę używać API w aplikacji frontendowej?

Nie zalecamy używania tokenów API bezpośrednio w aplikacjach frontendowych ze względów bezpieczeństwa. Zamiast tego, zaimplementuj własny backend jako warstwę pośrednią, która będzie komunikować się z naszym API.

Co zrobić, gdy otrzymuję błąd 429?

Błąd 429 oznacza przekroczenie limitu zapytań. Należy zaimplementować mechanizm wycofania i ponownych prób lub rozważyć przejście na wyższy plan.

Jak mogę testować API przed użyciem produkcyjnym?

Udostępniamy środowisko testowe dla twojego endpointu API z sufiksem -sandbox. Na przykład, jeśli twój produkcyjny endpoint to https://acme-corp.laurenscoster.com/api, to środowisko testowe będzie dostępne pod adresem https://acme-corp-sandbox.laurenscoster.com/api. Możesz używać tego środowiska do testowania bez wpływu na dane produkcyjne.

Co się stanie, gdy mój token wygaśnie?

Jeśli token ma ustawioną datę wygaśnięcia i termin ten upłynie, wszystkie żądania API wykorzystujące ten token będą otrzymywać błąd 401. Aby uniknąć przerw w działaniu, monitoruj daty wygaśnięcia tokenów i generuj nowe z wyprzedzeniem.

W przypadku dalszych pytań lub problemów, skontaktuj się z naszym zespołem wsparcia technicznego pod adresem api-support@nasza-aplikacja.com lub odwiedź naszą dokumentację online: https://docs.laurenscoster.com/api