Acces API #

Un API (Application Programming Interface) reprezintă o modalitate prin care diferite sisteme software pot comunica între ele. API-ul Your AI Connector vă permite (dumneavoastră sau dezvoltatorului dumneavoastră) să creați automat contacte, să trimiteți mesaje, să gestionați liste și să primiți mesaje primite de la canale personalizate — totul fără a utiliza tabloul de bord.

De ce să utilizați API-ul? Dacă doriți să conectați aplicația la un instrument care nu are o integrare nativă sau dacă trebuie să automatizați sarcini repetitive la scară largă, API-ul este soluția potrivită.

Generarea cheii API #

1. În bara laterală din stânga, faceți clic pe Settings (pictograma roată).
2. În bara laterală Settings, sub grupul Integrations, faceți clic pe API Key.

3. Dacă nu aveți încă o cheie, faceți clic pe Generate API key.
4. Dacă aveți deja una, aceasta este afișată mascată sub Your key. Dacă cheia dvs. permite acest lucru, faceți clic pe Show pentru a o dezvălui, apoi pe Copy pentru a o copia — veți vedea un mesaj de confirmare.
5. Păstrați cheia într-un loc sigur — veți avea nevoie de ea pentru fiecare solicitare API.

Membrii echipei: cheia API aparține proprietarului contului, așadar, dacă sunteți conectat ca membru invitat al echipei (inclusiv ca Administrator), secțiunea va afișa o notă în loc de cheie. Conectați-vă ca proprietar al contului pentru a o vizualiza, copia sau regenera — acest lucru este valabil și pentru cheile cu domeniu de aplicare limitat.

Unde o puteți găsi: API Key este o secțiune proprie sub Settings → Integrations, separată de Webhooks. Dacă un ghid sau un coleg vă spune să căutați cheia sub “Webhooks”, căutați în secțiunea de alături.

Chei cu domeniu de aplicare (scoped keys): chei suplimentare pentru o sarcină specifică #

Cheia principală poate face totul, așa că nu este cheia potrivită pentru a fi oferită unui raport, unui tablou de bord pentru clienți sau unei configurații separate de sandbox și dezvoltare. Pentru aceasta, creați chei cu domeniu de aplicare în cardul Chei cu domeniu de aplicare, în aceeași secțiune Cheie API de sub Cheia dvs.:

1. Faceți clic pe Cheie nouă.
2. Oferiți-i un Nume pe care îl veți recunoaște mai târziu, de exemplu „Sandbox” sau „Tablou de bord client Acme”.
3. Sub Ce poate vedea, bifați doar zonele de care are nevoie.
4. Sub Ce poate face, lăsați bifat Doar citire (Read only) decât dacă instrumentul trebuie să facă modificări. O cheie care poate face modificări poate trimite mesaje și edita configurația dvs.
5. Opțional, setați Cereri pe minut (propria limită, astfel încât să nu încetinească niciodată celelalte integrări ale dvs.) și o dată de Expiră la.
6. Faceți clic pe Creează cheia și copiați-o imediat. Cheile cu domeniu de aplicare sunt afișate o singură dată; dacă pierdeți una, revocați-o și creați alta.

Puteți crea câte aveți nevoie. Fiecare cheie din listă arată când a fost utilizată ultima dată, iar Revocare cheie o oprește imediat din funcționare. Crearea sau revocarea unei chei cu domeniu de aplicare nu afectează niciodată cheia principală. Opțiunile complete, inclusiv cheile limitate la anumite sub-conturi, se află pe pagina cheilor API din referința API.

URL de bază #

Toate cererile API utilizează următoarea adresă web de bază:

https://api.youraiconnector.com/v1/

Autentificare #

Fiecare cerere trebuie să includă cheia dumneavoastră API pentru ca platforma să știe că sunteți dumneavoastră. Cea mai simplă metodă este să o adăugați la sfârșitul adresei web:

https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY

De asemenea, puteți trimite cheia ca antet de cerere în loc de URL (recomandat pentru producție, astfel încât cheia să nu ajungă în jurnalele serverului):

X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

Toate cererile trebuie să utilizeze o conexiune securizată (HTTPS). Cererile nesecurizate (HTTP) sunt respinse.

Cauți ghidurile complete pentru dezvoltatori? Această pagină este o introducere rapidă care acoperă cele mai comune operațiuni. Pentru ghiduri complete, pas cu pas — fiecare resursă, cu exemple în cURL, JavaScript și Python — consultă Introducere în API și Referința API.

Operațiuni API comune #

Crearea unui contact #

Cerere:

POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}

Câmpuri obligatorii: un phoneNumber (cu codul țării) este întotdeauna necesar pentru a crea un contact. O adresă de e-mail singură nu este suficientă — o cerere fără un număr de telefon valid este respinsă. E-mailul este opțional.

Răspuns:

{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}

Salvați data.contactId — veți avea nevoie de el pentru apelul “Add a Contact to a List”.

Adăugare contact într-o listă #

POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}

Găsește ID-ul unei liste în aplicație la Contacte → Liste, din meniul rândului listei (Copiază ID-ul listei).

Actualizarea unui contact #

PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}

Doar câmpurile pe care le incluzi sunt modificate. Acesta este, de asemenea, modul de a încărca în masă valori ale câmpurilor personalizate după un import — consultă Câmpuri personalizate, profil de lead și note. Detalii complete în API-ul de contacte.

Trimitere mesaj (Canal personalizat) #

POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}

Primire mesaje primite (Canal personalizat) #

Acceptați mesaje din sisteme externe ca un canal personalizat. Acesta este modul în care integrări precum GoHighLevel trimit mesaje către Your AI Connector. Consultați Canale personalizate pentru detalii complete.

POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}

Prezentare generală a operațiunilor disponibile #

Limitarea ratei de apelare #

API-ul impune limite de rată pentru a asigura stabilitatea platformei. Depășirea limitei returnează 429 Too Many Requests — reduceți frecvența cererilor și reîncercați după timpul indicat în antetele răspunsului. Pentru cazuri de utilizare cu volum mare (importuri în masă), utilizați funcția de import integrată sau trimiteți un e-mail la hi@youraiconnector.com pentru îndrumare.

Cele mai bune practici #

• Stocați-vă cheia API în siguranță — utilizați un manager de parole sau o configurație pe partea de server, niciodată cod pe partea de client pe care un vizitator al browserului l-ar putea citi.
• Includeți întotdeauna prefixul țării în numerele de telefon (+1 pentru SUA, +44 pentru Regatul Unit, +31 pentru Țările de Jos).
• Gestionați erorile cu grație — verificați codurile de stare și citiți orice mesaje de eroare returnate.
• Gestionați duplicatele — un număr de telefon duplicat returnează { "success": false, "error_code": 409 } în loc de un contact nou, cu ID-ul contactului existent în contactId.
• Testați cu un set mic de date înainte de a rula operațiuni în masă.

Răspunsuri la erori #

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}

Pașii următori #

• Webhooks — primește notificări în timp real din aplicație (o secțiune separată de cheia ta API).
• Conectare asistenți AI (MCP) — folosește aceeași cheie API pentru a lăsa Claude să îți gestioneze contul.
• Formulare pentru lead-uri Facebook — folosește API-ul cu platforme de automatizare pentru a captura lead-uri.
• Integrare GoHighLevel — un exemplu complet de integrare API bidirecțională.