# Introducere în API API-ul REST Your AI Connector vă permite să construiți propria integrare pe baza contului dumneavoastră. Puteți crea și căuta contacte, gestiona campanii, întrebări frecvente (FAQ), sarcini și programări, trimite mesaje, înregistra webhook-uri, citi analize și conecta canale de mesagerie — tot ceea ce face tabloul de bord, controlat prin cod. Aceasta este pagina centrală pentru documentația API. Dacă conectați Your AI Connector la un instrument care are deja o integrare încorporată, este posibil să nu aveți nevoie deloc de API. API-ul este destinat integrărilor personalizate și automatizării la scară largă. ::: note **Notă:** Aceste pagini sunt scrise pentru dezvoltatori. Dacă nu sunteți dezvoltator, distribuiți această secțiune echipei dumneavoastră tehnice. ::: --- ## URL de bază Fiecare cerere este trimisă la aceeași adresă web de bază, iar toate căile din aceste documente sunt relative la aceasta: ``` https://api.youraiconnector.com/v1 ``` Așadar, punctul final (endpoint) pentru campanii este `https://api.youraiconnector.com/v1/campaigns`, punctul final pentru contacte este `https://api.youraiconnector.com/v1/contacts` și așa mai departe. Toate cererile trebuie să utilizeze o conexiune securizată (HTTPS). Cererile HTTP simple sunt respinse. --- ## Obținerea unei chei API Accesul la API este o **funcționalitate plătită**. Dacă planul dumneavoastră nu o include, fiecare cerere va returna un `403` cu acest conținut: ```json { "success": false, "error_code": 403, "error": "This action requires the \"api_access\" feature, which is not enabled for this account." } ``` Odată ce accesul API este activat în planul tău, generează o cheie din tabloul de bord. Pașii detaliați se află în [Acces API](../integrations/api-access.md) — pe scurt: mergi la **Setări → Integrări → Cheie API** pentru a genera sau regenera cheia. Cheia API are propria secțiune în cadrul Integrărilor, separată de Webhook-uri, și apare doar după ce accesul API este activat în planul tău. Tratează cheia ca pe o parolă: aceasta oferă acces complet la contul tău. --- ## Autentificare Puteți trimite cheia API în patru moduri. Toate funcționează pe fiecare punct final care acceptă autentificarea prin cheie API. | Metodă | Cum | Ideal pentru | |---|---|---| | Parametru de interogare | `?apiKey=YOUR_API_KEY` | Teste rapide, URL-uri în browser, configurații vechi | | Antet (Header) | `X-API-Key: YOUR_API_KEY` | Integrări în producție | | Antet Bearer | `Authorization: Bearer YOUR_API_KEY` | Integrări în producție | | Token ID Firebase | `Authorization: Bearer ` | Doar pentru sesiuni de aplicații proprii | Pentru producție, preferați una dintre formele de antet, astfel încât cheia dumneavoastră să nu ajungă niciodată într-un jurnal de server sau în istoricul browserului. Forma cu parametru de interogare funcționează întotdeauna și este cea mai simplă pentru un test rapid. Consultați [Autentificare](authentication.md) pentru o detaliere completă a fiecărei metode, cu exemple și îndrumări despre când să utilizați fiecare variantă. --- ## Prima dumneavoastră cerere Iată un apel complet și funcțional care listează campaniile din contul tău. Acesta utilizează cheia ta API și returnează mai întâi cele mai recente campanii. **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"]) ``` Un răspuns reușit arată astfel: ```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 } ``` --- ## Răspunsuri de succes și de eroare Fiecare răspuns JSON conține un indicator `success`, astfel încât să poți ramifica logica fără a analiza codurile de stare. Un răspuns reușit este `success: true` plus datele pentru acel endpoint (numele câmpului variază — `campaigns`, `contacts`, `data` și așa mai departe): ```json { "success": true, "campaigns": [] } ``` Un răspuns eșuat este `success: false` cu un mesaj `error` ușor de citit pentru oameni și un `error_code` numeric care corespunde stării HTTP: ```json { "success": false, "error": "Invalid cursor", "error_code": 400 } ``` Verifică întotdeauna `success` (sau starea HTTP) înainte de a citi datele. Consultă [Erori și paginare](errors-and-pagination.md) pentru tabelul complet cu coduri de stare și pentru modul de paginare a seturilor mari de rezultate. --- ## Limite de rată Cererile autentificate sunt limitate la **300 de cereri pe minut** per cheie API. Există, de asemenea, o limită mai largă de **1.200 de cereri pe minut per cont**, care contorizează fiecare cerere autentificată efectuată pentru acel cont. Dacă depășiți oricare dintre limite, veți primi un răspuns `429`: ```json { "success": false, "error_code": 429, "error": "Rate limit exceeded. Please try again later." } ``` Redu frecvența și reîncearcă după o scurtă așteptare. De asemenea, poți verifica utilizarea curentă în orice moment cu `GET https://api.youraiconnector.com/v1/api-keys/usage`, care returnează câte cereri ai utilizat în fereastra curentă și când se resetează — util pentru construirea limitării de rată (throttling) pe partea de client. Consultă [Chei API](api-keys.md). --- ## Ghiduri de resurse Grupurile de resurse de mai jos au fiecare propriul ghid cu căile exacte, câmpurile de solicitare și formele de răspuns. | Resursă | Ce acoperă | |---|---| | [Agenți AI](agents.md) | Creați și configurați Agenți AI: setări, ore active, cunoștințe, reguli de etichetare, instrumente, conținut media și ciorne | | [Puncte de intrare](entry-points.md) | Decideți ce Agent AI răspunde la o conversație nouă: setări implicite pentru canale, un Agent per număr WhatsApp, cuvinte cheie, reguli pentru comentarii și urmăritori | | [Difuzări](broadcasts.md) | Creați, stabiliți prețul, lansați, întrerupeți și duplicați trimiteri unice către o listă de contacte | | [Campanii](campaigns.md) | Creați, actualizați, duplicați, activați, arhivați și inspectați campaniile și configurația botului aferent | | [Contacte](contacts.md) | Creați, căutați, listați, actualizați, importați, etichetați și ștergeți contacte | | [Întrebări frecvente](faqs.md) | Gestionați intrările de tip întrebare-răspuns pe care le utilizează asistentul dvs. AI și conectați-le la campanii | | [Baza de cunoștințe](knowledge-base.md) | Importați site-uri web și documente în baza de cunoștințe a AI-ului dvs. și grupați întrebările frecvente în categorii | | [Sarcini](tasks.md) | Creați și gestionați sarcini CRM, etape de panou și tipuri de sarcini | | [Mesaje](messages.md) | Trimiteți mesaje de ieșire și citiți istoricul conversațiilor | | [Programări](appointments.md) | Rezervați, reprogramați, anulați și ștergeți programări | | [Canale](channels.md) | Conectați și deconectați canale de mesagerie, cumpărați numere și setați ce Agent AI răspunde la conversațiile noi pe fiecare canal | | [Șabloane](templates.md) | Creați, trimiteți și verificați starea de aprobare a șabloanelor de mesaje WhatsApp | | [Analize](analytics.md) | Citiți statisticile zilnice ale evenimentelor de mesagerie, utilizarea creditelor și centralizatoarele de costuri AI | | [Webhook-uri](webhooks.md) | Înregistrați puncte finale pentru a primi notificări despre evenimente în timp real | | [Echipă](team.md) | Gestionați membrii echipei, invitațiile, rolurile, permisiunile și departamentele | | [Chei API](api-keys.md) | Inspectați, rotiți și revocați cheia API, verificați utilizarea limitei de rată și creați chei suplimentare cu acces limitat | ### Agenți, puncte de intrare și difuzări Agenții AI, Punctele de intrare și Difuzările sunt toate incluse în specificația OpenAPI publicată, astfel încât puteți naviga prin câmpurile lor exacte și puteți rula cereri live împotriva acestora în [exploratorul API](reference.md). Fiecare are propriul ghid: [Agenți AI](agents.md), [Puncte de intrare](entry-points.md) și [Difuzări](broadcasts.md). --- ## Citirea acestor documente ca Markdown Fiecare pagină din această documentație are o variantă Markdown simplă: luați adresa paginii și adăugați `/index.md` la final. Astfel, această pagină este disponibilă și la `https://docs.youraiconnector.com/api/getting-started/index.md` și este returnată ca text simplu, nu ca pagină web — util atunci când doriți să lipiți o pagină într-un asistent AI sau să o preluați într-un script. Pentru a parcurge întregul set, începeți de la `https://docs.youraiconnector.com/sitemap.xml`, care listează fiecare pagină pe care o publicăm. Rețineți că documentația este exclusă în mod deliberat din motoarele de căutare, deci accesarea directă a acestor adrese este modalitatea de a o accesa din cod. Nu există un punct final de documentație protejat prin cheie și nici descărcare în masă deocamdată — variantele Markdown și harta site-ului reprezintă întreaga interfață, și niciuna nu necesită o cheie API. --- ## Pașii următori - [Autentificare](authentication.md) — alege metoda de autentificare potrivită pentru integrarea ta. - [Erori și paginare](errors-and-pagination.md) — gestionează eșecurile și parcurge rezultatele pagină cu pagină. - [Acces API](../integrations/api-access.md) — generează-ți cheia și consultă exemple practice.