# Acces API

Un API (Application Programming Interface) reprezintă o modalitate prin care diferite sisteme software pot comunica între ele. API-ul <span data-t="appName">Your AI Connector</span> 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ă.

::: note
**Notă:** Această pagină are un caracter mai tehnic. Dacă sunteți proprietarul unei afaceri și nu un dezvoltator, poate doriți să partajați această pagină cu echipa dumneavoastră tehnică sau cu un dezvoltator freelancer.
:::


---

## Generarea cheii API

::: note
**Notă:** Accesul la API este o funcționalitate plătită, disponibilă în planurile eligibile. Dacă planul dumneavoastră nu o include, cererile API vor fi respinse cu un răspuns `403`. Verificați planul dumneavoastră sau contactați asistența dacă nu sunteți sigur dacă accesul la API este activat.
:::


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.


::: note
**Notă:** Unele conturi afișează „Your key can't be displayed” în loc de controlul Show/Copy — acest lucru se întâmplă pentru cheile create înainte ca aplicația să le poată afișa din nou. Cheia funcționează în continuare normal; aveți nevoie de **Regenerate** (sub cardul cheii, în aceeași secțiune) doar dacă trebuie neapărat să vedeți din nou textul clar. Regenerarea invalidează imediat cheia veche și întrerupe orice integrare care o utilizează până când introduceți noua cheie — actualizați integrările imediat după aceea.
:::


::: warning
**Important:** Cheia dumneavoastră API este ca o parolă — oferă acces complet la contul dumneavoastră. Nu o partajați public și nu o postați nicăieri unde alții o pot vedea. Dacă bănuiți că cheia dumneavoastră a fost compromisă, regenerați-o imediat.
:::


> **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](../api/getting-started.md) și [Referința API](../api/reference.md).

---

## Operațiuni API comune

### Crearea unui contact

**Cerere:**

```http
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:**

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

::: note
**Notă:** dacă un contact cu același număr de telefon există deja, API-ul **nu** creează și nu returnează acel contact — returnează `{ "success": false, "error_code": 409 }`. Căutați mai întâi contactul existent cu `GET https://api.youraiconnector.com/v1/contacts?phoneNumber=...`.
:::


---

### Adăugare contact într-o listă

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

```http
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](../get-started/custom-contact-fields.md#bulk-loading-custom-fields). Detalii complete în [API-ul de contacte](../api/contacts.md).

---

### Trimitere mesaj (Canal personalizat)

```http
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"
  }
}
```

| Câmp | Obligatoriu | Descriere |
|---|---|---|
| `customData.fromId` | Da | ID-ul contactului pe platforma dumneavoastră |
| `customData.customChannel` | Da | Numele canalului dumneavoastră personalizat |
| `customData.body` | Da | Textul mesajului de trimis |
| `customData.campaignId` | Nu | Direcționați mesajul către o campanie specifică |
| `customData.firstName` | Nu | Prenumele contactului (folosit la crearea unui contact nou) |
| `customData.lastName` | Nu | Numele de familie al contactului |
| `customData.email` | Nu | Adresa de e-mail a contactului |

::: note
**Notă:** acest endpoint este pentru mesageria prin canal personalizat. Pentru WhatsApp, SMS, Instagram și Messenger, mesajele sunt trimise prin Broadcast-uri, Campanii și Agenți AI.
:::


---

### 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 <span data-t="appName">Your AI Connector</span>. Consultați [Canale personalizate](../messaging-channels/custom-channels.md) pentru detalii complete.

```http
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"
}
```

| Câmp | Obligatoriu | Descriere |
|---|---|---|
| `customData.messageSid` | Da | Un ID unic pentru acest mesaj (previne duplicatele). Poți folosi și `customData.id`. |
| `customData.fromId` | Da | ID-ul expeditorului în sistemul tău extern. |
| `customData.toId` | Da | Identificatorul afacerii tale. |
| `customData.body` | Da | Textul mesajului. |
| `customData.channel` | Nu | O etichetă pentru sursă (de exemplu, `"email"`, `"livechat"`, `"custom"`). |
| `customData.status` | Nu | Starea mesajului. Valoarea implicită este `"received"`. |
| `messageType` | Nu | `"text"` pentru mesaje text, `"reaction"` pentru reacții emoji. |

---

## Prezentare generală a operațiunilor disponibile

| Acțiune | Metodă | Adresă | Descriere |
|---|---|---|---|
| Creare contact | `POST` | `/contacts` | Adaugă un contact nou în contul tău |
| Obținere detalii contact | `GET` | `/contacts?phoneNumber=X` sau `/contacts?email=X` | Caută un contact după numărul de telefon sau e-mail |
| Actualizare contact | `PUT` | `/contacts/{contactId}` | Actualizează orice câmp al unui contact existent |
| Adăugare contact în listă | `POST` | `/contacts/lists` | Adaugă un contact existent într-o listă specifică |
| Trimitere mesaj | `POST` | `/send_custom_channel_message` | Trimite un mesaj printr-un canal personalizat |
| Primire mesaj | `POST` | `/incoming_custom_channel_message` | Acceptă un mesaj de la un sistem extern |

---

## 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](../get-started/importing-contacts.md) or email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto: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

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

| Status Code | Meaning |
|---|---|
| `200` | Success |
| `201` | Resource created |
| `400` | Bad request — check your parameters |
| `401` | Unauthorized — invalid or missing API key |
| `403` | Forbidden — your plan doesn't include API access, or you lack permission |
| `404` | Resource not found |
| `429` | Rate limit exceeded |
| `500` | Server error — email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com) if this persists |

---

## Pașii următori

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