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ă.

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:

{
  "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 — 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.

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

curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10"

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

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:

{
  "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):

{
  "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:

{
  "success": false,
  "error": "Invalid cursor",
  "error_code": 400
}

Verifică întotdeauna success (sau starea HTTP) înainte de a citi datele. Consultă Erori și paginare 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:

{
  "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.

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.

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. Fiecare are propriul ghid: Agenți AI, Puncte de intrare și Difuzări.

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 — alege metoda de autentificare potrivită pentru integrarea ta.
• Erori și paginare — gestionează eșecurile și parcurge rezultatele pagină cu pagină.
• Acces API — generează-ți cheia și consultă exemple practice.