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.

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 #

The API enforces rate limits to ensure platform stability. Exceeding your limit returns 429 Too Many Requests — back off and retry after the time indicated in the response headers. For high-volume use cases (bulk imports), use the built-in import feature or email hi@youraiconnector.com for guidance.

Cele mai bune practici #

• Stochează-ți cheia API în siguranță — folosește 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 întotdeauna codul țării în numerele de telefon (+1 pentru SUA, +44 pentru Regatul Unit, +31 pentru Țările de Jos).
• Gestionează erorile corect — verifică codurile de stare și citește orice mesaj de eroare returnat.
• Gestionează duplicatele — un număr de telefon duplicat returnează { "success": false, "error_code": 409 } în loc de un contact nou. Caută mai întâi contactul dacă trebuie să lucrezi cu el.
• Testează cu un set de date mic î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ă.