# Wprowadzenie do API REST API Your AI Connector umożliwia zbudowanie własnej integracji z Twoim kontem. Możesz tworzyć i wyszukiwać kontakty, zarządzać kampaniami, FAQ, zadaniami i spotkaniami, wysyłać wiadomości, rejestrować webhooki, odczytywać analitykę oraz łączyć kanały komunikacji — wszystko to, co oferuje pulpit nawigacyjny, sterowane za pomocą kodu. To jest strona główna dokumentacji API. Jeśli łączysz Your AI Connector z narzędziem, które posiada już wbudowaną integrację, być może w ogóle nie potrzebujesz API. API jest przeznaczone do niestandardowych integracji i automatyzacji na dużą skalę. ::: note **Uwaga:** Te strony są przeznaczone dla programistów. Jeśli nie jesteś programistą, udostępnij tę sekcję swojemu zespołowi technicznemu. ::: --- ## Podstawowy adres URL Każde żądanie jest kierowane pod ten sam podstawowy adres internetowy, a wszystkie ścieżki w tej dokumentacji są względem niego relatywne: ``` https://api.youraiconnector.com/v1 ``` Zatem punkt końcowy kampanii to `https://api.youraiconnector.com/v1/campaigns`, punkt końcowy kontaktów to `https://api.youraiconnector.com/v1/contacts` i tak dalej. Wszystkie żądania muszą korzystać z bezpiecznego połączenia (HTTPS). Zwykłe żądania HTTP są odrzucane. --- ## Uzyskiwanie klucza API Dostęp do API jest **płatną funkcją**. Jeśli Twój plan go nie obejmuje, każde żądanie zwróci `403` z następującą treścią: ```json { "success": false, "error_code": 403, "error": "This action requires the \"api_access\" feature, which is not enabled for this account." } ``` Gdy dostęp do API zostanie włączony w Twoim planie, wygeneruj klucz z poziomu panelu nawigacyjnego. Pełna instrukcja krok po kroku znajduje się w [Dostęp do API](../integrations/api-access.md) — w skrócie: przejdź do **Ustawienia → Integracje → Klucz API**, aby wygenerować lub wygenerować ponownie swój klucz. Klucz API stanowi osobną sekcję w ramach Integracji, oddzieloną od Webhooków, i pojawia się dopiero po włączeniu dostępu do API w Twoim planie. Traktuj ten klucz jak hasło: zapewnia on pełny dostęp do Twojego konta. --- ## Uwierzytelnianie Możesz wysłać swój klucz API na cztery sposoby. Wszystkie działają w każdym punkcie końcowym, który akceptuje uwierzytelnianie kluczem API. | Metoda | Jak | Najlepsze dla | |---|---|---| | Parametr zapytania | `?apiKey=YOUR_API_KEY` | Szybkie testy, adresy URL w przeglądarce, starsze konfiguracje | | Nagłówek | `X-API-Key: YOUR_API_KEY` | Integracje produkcyjne | | Nagłówek Bearer | `Authorization: Bearer YOUR_API_KEY` | Integracje produkcyjne | | Token ID Firebase | `Authorization: Bearer ` | Tylko sesje aplikacji własnych | W środowisku produkcyjnym preferuj jedną z form nagłówka, aby klucz nigdy nie trafił do logów serwera ani historii przeglądarki. Forma parametru zapytania zawsze działa i jest najprostsza w przypadku jednorazowego testu. Zobacz [Uwierzytelnianie](authentication.md), aby uzyskać pełne zestawienie każdej metody wraz z przykładami i wskazówkami, kiedy której użyć. --- ## Twoje pierwsze żądanie Oto kompletne, działające wywołanie, które wyświetla listę kampanii na Twoim koncie. Wykorzystuje ono Twój klucz API i zwraca najnowsze kampanie w pierwszej kolejności. **cURL** ```bash curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=10", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); console.log(data.campaigns); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/campaigns", params={"limit": 10}, headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() print(data["campaigns"]) ``` Poprawna odpowiedź wygląda następująco: ```json { "success": true, "campaigns": [ { "id": "NBCXrhqGPSFsd6MV7pRo", "name": "Inbound WhatsApp Leads", "type": "Incoming from Unknown Contacts", "status": "Live", "enabled": true, "archived": false, "created_at": 1700000000000, "ai_mode": true, "language": "en", "enabled_channels": ["whatsapp", "instagram"] } ], "next_cursor": null } ``` --- ## Odpowiedzi poprawne i błędy Każda odpowiedź w formacie JSON zawiera flagę `success`, dzięki czemu możesz podejmować decyzje bez konieczności analizowania kodów statusu. Poprawna odpowiedź to `success: true` oraz dane dla danego punktu końcowego (nazwa pola jest zmienna — `campaigns`, `contacts`, `data` itd.): ```json { "success": true, "campaigns": [] } ``` Nieudana odpowiedź to `success: false` z czytelnym dla człowieka komunikatem `error` oraz numerycznym kodem `error_code`, który odpowiada statusowi HTTP: ```json { "success": false, "error": "Invalid cursor", "error_code": 400 } ``` Zawsze sprawdzaj `success` (lub status HTTP) przed odczytaniem danych. Zobacz [Błędy i stronicowanie](errors-and-pagination.md), aby uzyskać pełną tabelę kodów statusu oraz informacje o tym, jak poruszać się po dużych zbiorach wyników. --- ## Limity zapytań Uwierzytelnione żądania są ograniczone do **300 żądań na minutę** na klucz API. Istnieje również szerszy limit **1200 żądań na minutę na konto**, obejmujący każde uwierzytelnione żądanie wykonane dla tego konta. Jeśli przekroczysz którykolwiek z limitów, otrzymasz odpowiedź `429`: ```json { "success": false, "error_code": 429, "error": "Rate limit exceeded. Please try again later." } ``` Wstrzymaj się i ponów próbę po krótkim czasie. Możesz również w dowolnym momencie sprawdzić swoje bieżące zużycie za pomocą `GET https://api.youraiconnector.com/v1/api-keys/usage`, co zwróci liczbę żądań wykorzystanych w bieżącym oknie oraz czas resetowania — jest to przydatne przy tworzeniu mechanizmów ograniczania liczby żądań po stronie klienta. Zobacz [Klucze API](api-keys.md). --- ## Przewodniki po zasobach Poniższe grupy zasobów mają własne przewodniki z dokładnymi ścieżkami, polami żądań i strukturami odpowiedzi. | Zasób | Co obejmuje | |---|---| | [Agenci AI](agents.md) | Tworzenie i konfigurowanie agentów AI: ustawienia, godziny aktywności, wiedza, reguły tagowania, narzędzia, multimedia i szkice | | [Punkty wejścia](entry-points.md) | Decydowanie, który agent AI odpowiada na nową konwersację: domyślne ustawienia kanałów, jeden agent na numer WhatsApp, słowa kluczowe, reguły komentarzy i obserwujących | | [Transmisje](broadcasts.md) | Tworzenie, wycenianie, uruchamianie, wstrzymywanie i duplikowanie jednorazowych wysyłek do listy kontaktów | | [Kampanie](campaigns.md) | Tworzenie, aktualizowanie, duplikowanie, włączanie, archiwizowanie i sprawdzanie kampanii oraz ich konfiguracji bota | | [Kontakty](contacts.md) | Tworzenie, wyszukiwanie, wyświetlanie, aktualizowanie, importowanie, tagowanie i usuwanie kontaktów | | [FAQ](faqs.md) | Zarządzanie wpisami pytań i odpowiedzi używanymi przez asystenta AI oraz łączenie ich z kampaniami | | [Baza wiedzy](knowledge-base.md) | Importowanie stron internetowych i dokumentów do wiedzy AI oraz grupowanie FAQ w zestawy | | [Zadania](tasks.md) | Tworzenie i zarządzanie zadaniami CRM, etapami tablicy i typami zadań | | [Wiadomości](messages.md) | Wysyłanie wiadomości wychodzących i odczytywanie historii konwersacji | | [Spotkania](appointments.md) | Rezerwowanie, zmienianie terminu, anulowanie i usuwanie spotkań | | [Kanały](channels.md) | Łączenie i rozłączanie kanałów komunikacji, kupowanie numerów oraz ustawianie, który agent AI odpowiada na nowe konwersacje w każdym kanale | | [Szablony](templates.md) | Tworzenie, przesyłanie i sprawdzanie statusu zatwierdzenia szablonów wiadomości WhatsApp | | [Analityka](analytics.md) | Odczytywanie dziennych statystyk zdarzeń wiadomości, zużycia kredytów i podsumowań kosztów AI | | [Webhooki](webhooks.md) | Rejestrowanie punktów końcowych w celu otrzymywania powiadomień o zdarzeniach w czasie rzeczywistym | | [Zespół](team.md) | Zarządzanie członkami zespołu, zaproszeniami, rolami, uprawnieniami i działami | | [Klucze API](api-keys.md) | Sprawdzanie, rotowanie i unieważnianie klucza API, sprawdzanie wykorzystania limitów oraz tworzenie dodatkowych kluczy z ograniczonym dostępem | ### Agenci, Punkty wejścia i Transmisje Agenci AI, punkty wejścia i transmisje znajdują się w opublikowanej specyfikacji OpenAPI, dzięki czemu możesz przeglądać ich dokładne pola i wykonywać na nich aktywne żądania w [eksploratorze API](reference.md). Każdy z nich posiada własny przewodnik: [Agenci AI](agents.md), [Punkty wejścia](entry-points.md) oraz [Transmisje](broadcasts.md). --- ## Czytanie tej dokumentacji w formacie Markdown Każda strona w tej dokumentacji posiada swój odpowiednik w czystym formacie Markdown: wystarczy wziąć adres strony i dodać na końcu `/index.md`. Ta strona jest więc również dostępna pod adresem `https://docs.youraiconnector.com/api/getting-started/index.md` i zwraca czysty tekst zamiast strony internetowej — jest to przydatne, gdy chcesz wkleić stronę do asystenta AI lub pobrać ją za pomocą skryptu. Aby przejrzeć cały zestaw, zacznij od `https://docs.youraiconnector.com/sitemap.xml`, gdzie znajduje się lista wszystkich publikowanych przez nas stron. Pamiętaj, że dokumentacja jest celowo ukryta przed wyszukiwarkami, więc bezpośrednie pobieranie tych adresów jest najlepszym sposobem na uzyskanie do niej dostępu z poziomu kodu. Nie istnieje jeszcze żaden punkt końcowy dokumentacji chroniony kluczem ani możliwość pobrania zbiorczego — odpowiedniki w formacie Markdown oraz mapa witryny stanowią cały interfejs i żaden z nich nie wymaga klucza API. --- ## Następne kroki - [Uwierzytelnianie](authentication.md) — wybierz odpowiednią metodę uwierzytelniania dla swojej integracji. - [Błędy i stronicowanie](errors-and-pagination.md) — obsługuj błędy i przeglądaj wyniki strona po stronie. - [Dostęp do API](../integrations/api-access.md) — wygeneruj swój klucz i zobacz przykłady działania.