# Programări

API-ul de Programări vă permite să rezervați programări pentru contactele dvs. în funcție de tipurile de evenimente, apoi să le preluați, să le listați, să le actualizați, să le anulați sau să le ștergeți. De asemenea, răspunde la întrebarea care apare prima în majoritatea fluxurilor de rezervare — ce intervale orare sunt libere — și acoperă partea de calendar: listarea calendarelor Google pe care le-ați conectat și importarea evenimentelor care există deja în acestea. Când o conexiune la Google Calendar este activă, evenimentul corespondent din calendar este creat și sincronizat automat în fundal. Restaurantele care utilizează Zenchef sau Formitable pentru propriul sistem de rezervări pot fi, de asemenea, verificate și conectate aici, astfel încât Agentul AI să rezerve mese reale în loc de programări interne.

Toate căile de pe această pagină sunt relative la URL-ul de bază `https://api.youraiconnector.com/v1`. Fiecare cerere necesită cheia dvs. API — consultați [Autentificare](authentication.md) pentru lista completă a modalităților de trimitere a acesteia. Exemplele de mai jos utilizează antetul `X-API-Key`, un exemplu cURL arătând și forma de interogare `?apiKey=`.

> **Evenimente vs. programări:** Un *tip de eveniment* este o definiție a unui interval rezervabil (tipul de întâlnire, durata sa, sălile sale). O *programare* este o instanță rezervată a unui tip de eveniment pentru un anumit contact. Rezervați o programare făcând referire la contact și la tipul de eveniment.

---

## Obiectul programare

Fiecare endpoint care returnează o programare utilizează aceeași structură:

| Câmp | Descriere |
|---|---|
| `id` | ID unic al programării. |
| `contact_id` | ID-ul contactului cu care este făcută programarea. |
| `event_id` | ID-ul tipului de eveniment pentru care a fost făcută programarea. |
| `status` | `Confirmed` sau `Canceled`. |
| `start_time` | Începutul programării, ISO 8601 în UTC. |
| `end_time` | Sfârșitul programării, ISO 8601 în UTC. |
| `created_at` | Când a fost creată programarea. |
| `last_modified_at` | Când a fost modificată ultima dată programarea. |
| `room_name` | Sala sau resursa în care este rezervată programarea, atunci când tipul de eveniment utilizează săli. |
| `description` | Descrierea liberă a programării. |
| `summary` | Rezumat scurt sau titlu. |
| `cancelation_reason` | Motivul furnizat la anularea programării, dacă există. |
| `google_calendar_event_id` | ID-ul evenimentului Google Calendar asociat. Setat odată ce sincronizarea calendarului este finalizată; `null` când niciun calendar nu este conectat sau în timp ce sincronizarea este încă în curs. |
| `calendar_synced` | `true` odată ce programarea este legată de un eveniment din calendar. |
| `imported` | `true` când programarea a fost importată dintr-un calendar extern în loc să fie rezervată direct. |
| `is_recurring` | `true` când programarea face parte dintr-o serie recurentă. |
| `recurrence_frequency` | Cât de des se repetă programarea, în cazul recurenței. |
| `recurring_event_id` | ID-ul seriei recurente din care face parte această programare. |
| `recurring_interval` | Intervalul dintre repetiții, în cazul recurenței. |
| `recurring_sequence` | Poziția acestei programări în cadrul seriei sale recurente. |
| `end_after_x_occurrences` | Numărul de apariții după care se încheie seria recurentă. |
| `booking_provider` | Sistemul sursă din care provine rezervarea, atunci când este rezervată printr-un furnizor de rezervări conectat. |

> **Despre sincronizarea calendarului:** Imediat după ce rezervați sau modificați o programare, `google_calendar_event_id` poate fi încă `null` și `calendar_synced` poate fi `false` deoarece sincronizarea rulează în fundal puțin mai târziu. Preluarea programării din nou la scurt timp după aceea va afișa câmpurile de calendar completate.

---

## Găsiți intervale disponibile

`GET /appointments/available-slots`

Returnează momentele care sunt cu adevărat libere pentru un tip de eveniment între două puncte în timp. Acesta este, de obicei, **primul** apel într-un flux de rezervare: afișați aceste intervale, lăsați persoana să aleagă unul, apoi postați ora aleasă către [Rezervați o programare](#book-an-appointment).

Răspunsul ia deja în considerare programul de funcționare și durata intervalului specifice tipului de eveniment, sălile acestuia, programările pe care le-ați făcut deja și tot ceea ce este blocat în calendarele Google conectate — astfel încât un interval returnat aici este unul pe care îl puteți rezerva.

| Parametru interogare | Obligatoriu | Descriere |
|---|---|---|
| `event_id` | Da | Tipul de eveniment de verificat. Trebuie să aparțină contului dvs. |
| `start_time` | Da | Începutul ferestrei pentru care doriți intervale, dată-oră ISO 8601. |
| `end_time` | Da | Sfârșitul ferestrei, dată-oră ISO 8601. Întreaga zi de sfârșit este inclusă. |

Rezultatele sunt returnate grupate pe zi — și, atunci când tipul de eveniment utilizează săli, un grup per sală per zi:

| Câmp | Descriere |
|---|---|
| `date` | Ziua pe care o acoperă grupul, scrisă `DD/MM/YYYY`. |
| `day` | Numele zilei săptămânii cu litere mici, de exemplu `monday`. |
| `room_name` | Sala sau resursa căreia îi aparține acest grup, atunci când tipul de eveniment utilizează săli. |
| `available_slots` | Blocurile rezervabile din acea zi, începând cu cel mai devreme. |

Fiecare intrare din `available_slots` are:

| Câmp | Descriere |
|---|---|
| `start_time` | Începutul blocului ca `HH:mm`. |
| `end_time` | Sfârșitul blocului ca `HH:mm`. |
| `available` | `true` — este returnat doar timpul liber. |
| `spots_left` | Câte rezervări mai încap în acest bloc. Prezent doar pentru tipurile de evenimente care acceptă mai mult de o rezervare per interval. |

> **Orele sunt locale pentru tipul de eveniment, nu UTC.** `date`, `start_time` și `end_time` sunt valori de ceas de perete în fusul orar propriu al tipului de eveniment (suprascrierea acestuia sau fusul orar al contului dvs. când nu are unul). [Rezervați o programare](#book-an-appointment) așteaptă un moment UTC ISO 8601, deci convertiți intervalul ales înainte de a-l posta.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/appointments/available-slots?event_id=event_xyz789&start_time=2026-06-15T00:00:00.000Z&end_time=2026-06-19T00:00:00.000Z" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({
  event_id: "event_xyz789",
  start_time: "2026-06-15T00:00:00.000Z",
  end_time: "2026-06-19T00:00:00.000Z",
});
const res = await fetch(
  `https://api.youraiconnector.com/v1/appointments/available-slots?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.data);
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/appointments/available-slots",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={
        "event_id": "event_xyz789",
        "start_time": "2026-06-15T00:00:00.000Z",
        "end_time": "2026-06-19T00:00:00.000Z",
    },
)
print(res.json()["data"])
```

**Răspuns** (`200 OK`):

```json
{
  "success": true,
  "data": [
    {
      "date": "15/06/2026",
      "day": "monday",
      "room_name": "Room A",
      "available_slots": [
        { "start_time": "10:00", "end_time": "10:30", "available": true },
        { "start_time": "10:30", "end_time": "11:00", "available": true }
      ]
    },
    {
      "date": "16/06/2026",
      "day": "tuesday",
      "room_name": "Room A",
      "available_slots": [
        { "start_time": "09:00", "end_time": "09:30", "available": true, "spots_left": 2 }
      ]
    }
  ]
}
```

O zi în care nu există nimic liber pur și simplu nu apare. Lipsa `event_id`, `start_time` sau `end_time` returnează `400`; un tip de eveniment care nu se află în contul dvs. returnează `404`.

---

## Rezervarea unei programări

`POST /appointments`

Rezervă o nouă programare pentru un contact pe unul dintre tipurile dvs. de evenimente. Ora de sfârșit este calculată automat din durata intervalului tipului de eveniment.

Rezervarea este verificată pentru conflicte: dacă intervalul solicitat se suprapune cu o programare confirmată existentă pe același tip de eveniment, cererea eșuează cu un `409` și nu se creează nimic.

| Câmp | Obligatoriu | Descriere |
|---|---|---|
| `contact_id` | Da | ID-ul contactului pentru care se face rezervarea. Trebuie să aparțină contului dvs. |
| `event_id` | Da | ID-ul tipului de eveniment pe care se face rezervarea. Trebuie să aparțină contului dvs. |
| `start_time` | Da | Începutul dorit ca dată-oră ISO 8601. |
| `room_name` | Nu | Numele sălii sau resursei, atunci când tipul de eveniment utilizează săli. |

**cURL** (folosind forma de interogare `?apiKey=`)

```bash
curl -X POST "https://api.youraiconnector.com/v1/appointments?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "start_time": "2026-06-15T10:00:00.000Z",
    "room_name": "Room A"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/appointments", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contact_id: "contact_abc123",
    event_id: "event_xyz789",
    start_time: "2026-06-15T10:00:00.000Z",
    room_name: "Room A",
  }),
});
const data = await res.json();
console.log(data.appointment_id);
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "contact_id": "contact_abc123",
        "event_id": "event_xyz789",
        "start_time": "2026-06-15T10:00:00.000Z",
        "room_name": "Room A",
    },
)
print(res.json()["appointment_id"])
```

**Răspuns** (`201 Created`):

```json
{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678",
  "appointment": {
    "id": "aBcD1234eFgH5678",
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "status": "Confirmed",
    "start_time": "2026-06-15T10:00:00.000Z",
    "end_time": "2026-06-15T10:30:00.000Z",
    "created_at": "2026-06-10T09:00:00.000Z",
    "last_modified_at": "2026-06-10T09:00:00.000Z",
    "room_name": "Room A",
    "google_calendar_event_id": null,
    "calendar_synced": false
  }
}
```

---

## Obțineți o programare

`GET /appointments/{appointmentId}`

Returnează o singură programare după ID-ul acesteia, incluzând starea de sincronizare a calendarului.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.appointment);
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["appointment"])
```

**Răspuns** (`200 OK`):

```json
{
  "success": true,
  "appointment": {
    "id": "aBcD1234eFgH5678",
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "status": "Confirmed",
    "start_time": "2026-06-15T10:00:00.000Z",
    "end_time": "2026-06-15T10:30:00.000Z",
    "room_name": "Room A",
    "google_calendar_event_id": "abc123googleevent",
    "calendar_synced": true
  }
}
```

---

## Listează programările

`GET /appointments`

Listează programările pentru contul dvs., începând cu cele mai recente, folosind paginarea bazată pe cursor.

| Parametru de interogare | Obligatoriu | Descriere |
|---|---|---|
| `contact_id` | Nu | Returnează doar programările pentru acest contact. Listele filtrate după contact includ **doar programările confirmate** |
| `date` | Nu | Returnează doar programările din această zi calendaristică (`YYYY-MM-DD`). **Necesită `contact_id`.** |
| `status` | Nu | Filtrați după `Confirmed` sau `Canceled`. Disponibil doar **fără** `contact_id`. |
| `limit` | Nu | Dimensiunea paginii, un număr întreg între 1 și 100. Valoarea implicită este `50`. |
| `cursor` | Nu | Valoarea `next_cursor` dintr-un răspuns anterior. |

Câteva reguli de reținut:

- **Fără filtre**, obțineți fiecare programare din cont, pagină cu pagină.
- **După contact** — setați `contact_id` pentru a vedea programările confirmate ale unui contact. Puteți restrânge acest lucru la o singură zi transmițând și `date`.
- **După stare** — setați `status` (fără `contact_id`) pentru a lista doar programările `Confirmed` sau doar pe cele `Canceled` din întregul cont.
- Filtrul `date` fără `contact_id`, sau `status=Canceled` împreună cu `contact_id`, returnează o `400`.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/appointments?contact_id=contact_abc123&date=2026-06-15" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({
  contact_id: "contact_abc123",
  date: "2026-06-15",
});
const res = await fetch(
  `https://api.youraiconnector.com/v1/appointments?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.appointments, data.next_cursor);
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/appointments",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"contact_id": "contact_abc123", "date": "2026-06-15"},
)
data = res.json()
print(data["appointments"], data["next_cursor"])
```

**Răspuns** (`200 OK`):

```json
{
  "success": true,
  "appointments": [
    {
      "id": "aBcD1234eFgH5678",
      "contact_id": "contact_abc123",
      "event_id": "event_xyz789",
      "status": "Confirmed",
      "start_time": "2026-06-15T10:00:00.000Z",
      "end_time": "2026-06-15T10:30:00.000Z",
      "calendar_synced": true
    }
  ],
  "next_cursor": null
}
```

Pentru a naviga prin rezultate, transmiteți `next_cursor` dintr-un răspuns ca `cursor` al următoarei cereri. Continuați până când `next_cursor` este `null`. Consultați [Erori și paginare](errors-and-pagination.md) pentru modelul de paginare partajat.

---

## Actualizați o programare

`PUT /appointments/{appointmentId}`

Reprogramați o întâlnire sau modificați detaliile acesteia. Trimiteți doar câmpurile pe care doriți să le modificați — este necesar cel puțin unul. Combinația de început și sfârșit trebuie să rămână în ordine cronologică (`end_time` trebuie să fie după `start_time`). Modificările sunt sincronizate automat cu evenimentul din calendarul asociat.

| Câmp | Descriere |
|---|---|
| `start_time` | Dată-oră de început nouă, format ISO 8601. |
| `end_time` | Dată-oră de sfârșit nouă, format ISO 8601. Trebuie să fie ulterioară orei de început. |
| `room_name` | Nume nou pentru cameră sau resursă. |
| `description` | Descriere nouă sau `null` pentru a o șterge. |
| `summary` | Rezumat nou sau `null` pentru a-l șterge. |

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": "2026-06-16T10:00:00.000Z",
    "end_time": "2026-06-16T10:30:00.000Z"
  }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      start_time: "2026-06-16T10:00:00.000Z",
      end_time: "2026-06-16T10:30:00.000Z",
    }),
  }
);
const data = await res.json();
console.log(data.appointment);
```

**Python**

```python
import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "start_time": "2026-06-16T10:00:00.000Z",
        "end_time": "2026-06-16T10:30:00.000Z",
    },
)
print(res.json()["appointment"])
```

**Răspuns** (`200 OK`):

```json
{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678",
  "appointment": {
    "id": "aBcD1234eFgH5678",
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "status": "Confirmed",
    "start_time": "2026-06-16T10:00:00.000Z",
    "end_time": "2026-06-16T10:30:00.000Z",
    "calendar_synced": true
  }
}
```

---

## Anularea unei programări

`POST /appointments/{appointmentId}/cancel`

Anulează o programare confirmată, înregistrând opțional un motiv. Programarea rămâne în contul tău cu starea `Canceled`, iar evenimentul din calendarul asociat este eliminat automat în fundal. Anularea unei programări deja anulate returnează un `400`.

| Câmp | Obligatoriu | Descriere |
|---|---|---|
| `cancellation_reason` | Nu | Motivul anulării, stocat în programare. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/cancel" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cancellation_reason": "Client asked to reschedule next month"
  }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/cancel",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      cancellation_reason: "Client asked to reschedule next month",
    }),
  }
);
const data = await res.json();
console.log(data.success);
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/cancel",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"cancellation_reason": "Client asked to reschedule next month"},
)
print(res.json()["success"])
```

**Răspuns** (`200 OK`):

```json
{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678"
}
```

---

## Ștergerea unei programări

`DELETE /appointments/{appointmentId}`

Șterge definitiv o programare și referințele acesteia. Dacă dorești doar să anulezi rezervarea păstrând în același timp înregistrarea, folosește [anulare](#cancel-an-appointment) în schimb.

**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.success);
```

**Python**

```python
import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["success"])
```

**Răspuns** (`200 OK`):

```json
{
  "success": true
}
```

---

## Listați calendarele Google conectate

`GET /appointments/google-calendars`

Returnează calendarele Google disponibile în acest cont, direct de la Google — util pentru a arăta deținătorului contului un selector din care calendar să importe mai jos, sau pur și simplu pentru a confirma că conexiunea este activă.

Acest lucru funcționează doar după ce contul a conectat Google Calendar (Setări → Integrări) cu cel puțin acces de citire. Dacă nu a făcut-o, sau dacă accesul acordat nu mai include permisiunea de citire a calendarului, vei primi un `400` care îți solicită să îl (re)conectezi.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/appointments/google-calendars" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/appointments/google-calendars", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.data);
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/appointments/google-calendars",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["data"])
```

**Răspuns** (`200 OK`):

```json
{
  "success": true,
  "data": [
    {
      "id": "primary",
      "summary": "jane@example.com",
      "timeZone": "America/New_York",
      "accessRole": "owner",
      "primary": true
    },
    {
      "id": "abcdefg1234567890@group.calendar.google.com",
      "summary": "Bookings",
      "timeZone": "America/New_York",
      "accessRole": "writer"
    }
  ]
}
```

Fiecare intrare are forma [`CalendarListEntry`](https://developers.google.com/calendar/api/v3/reference/calendarList) proprie Google, deci numele câmpurilor urmează `camelCase` de la Google, nu `snake_case` obișnuit al acestui API — acestea sunt datele Google transmise ca atare, nu ale noastre. O conexiune lipsă sau revocată returnează `400` cu o eroare care explică faptul că Google Calendar trebuie (re)conectat.

---

## Importă evenimente dintr-un Google Calendar

`POST /appointments/import-calendar-events`

Extrage evenimentele deja existente în Google Calendarul/Calendarele conectate ale unei campanii sau ale unui Agent AI și le transformă în programări — util prima dată când conectezi un calendar care are deja rezervări. Acest proces poate dura (fiecare eveniment trece prin extracție pentru a determina cui îi aparține), așa că nu rulează niciodată inline: cererea pune în coadă un job de fundal și îți returnează un `job_id` pentru interogare (polling).

| Câmp | Obligatoriu | Descriere |
|---|---|---|
| `campaign_id` | Unul dintre cele două | Campania din al cărei calendar/calendare conectate se face importul. |
| `agent_id` | Unul dintre cele două | Agentul AI din al cărui calendar/calendare conectate se face importul. |
| `identifier` | Da | `"EMAIL"` sau `"PHONE_NUMBER"` — ce informație de contact să fie extrasă din fiecare eveniment din calendar pentru a potrivi sau crea contactul căruia îi aparține. |

Trimite exact unul dintre `campaign_id` / `agent_id`, niciodată pe ambele și niciodată pe niciunul — orice altă combinație returnează un `400`. Oricare dintre ele trimiți, trebuie să aparțină contului tău, altfel vei primi un `404`.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/appointments/import-calendar-events?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "identifier": "EMAIL"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/appointments/import-calendar-events", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_id: "agent_abc123",
    identifier: "EMAIL",
  }),
});
const data = await res.json();
console.log(data.job_id);
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments/import-calendar-events",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"agent_id": "agent_abc123", "identifier": "EMAIL"},
)
print(res.json()["job_id"])
```

**Răspuns** (`202 Accepted`):

```json
{
  "success": true,
  "job_id": "jK9mQ2xR7pL4wN1t",
  "status": "queued",
  "campaign_id": null,
  "agent_id": "agent_abc123"
}
```

`campaign_id` și `agent_id` reflectă exact ceea ce ai trimis; celălalt este întotdeauna `null`.

### Interoghează jobul de import

`GET /appointments/import-calendar-events/{jobId}`

```bash
curl "https://api.youraiconnector.com/v1/appointments/import-calendar-events/jK9mQ2xR7pL4wN1t" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Răspuns** (`200 OK`):

```json
{
  "success": true,
  "job_id": "jK9mQ2xR7pL4wN1t",
  "status": "completed",
  "message": "Imported 12 events as appointments.",
  "error": null
}
```

| `status` | Semnificație |
|---|---|
| `queued` | Încă nu a fost preluat. Continuă interogarea. |
| `processing` | Importul este în curs de desfășurare. Continuă interogarea. |
| `completed` | Finalizat — `message` conține un scurt rezumat ușor de citit. |
| `failed` | Ceva nu a mers bine — `error` conține motivul. |

`GET` pe un `jobId` care nu există (sau aparține unui alt cont) returnează `404`.

---

## Integrări pentru rezervări la restaurante (Zenchef / Formitable)

Zenchef și Formitable sunt sisteme de rezervări pentru restaurante prin care Agentul tău AI poate rezerva mese reale. Fiecare are un **widget de rezervare public, neautentificat** (`https://api.youraiconnector.com/v1/zenchef-widget/...` și `https://api.youraiconnector.com/v1/formitable-widget/...`) care se afișează în chat pentru client — acele rute de widget sunt pagini HTML simple menite să fie deschise într-un browser, nu endpoint-uri API JSON, deci nu sunt documentate aici. Ceea ce urmează sunt endpoint-urile de gestionare a contului: verificarea faptului că un ID de restaurant aparține deținătorului contului, apoi adăugarea, actualizarea sau eliminarea acestuia.

### Zenchef

Conectarea unui restaurant Zenchef este un proces de verificare în doi pași, astfel încât titularul contului să demonstreze că administrează efectiv restaurantul înainte ca acesta să fie conectat la bot: mai întâi se verifică dacă ID-ul există (fără a dezvălui numele), apoi i se cere acestuia să introducă singur numele restaurantului pentru a verifica dacă acesta corespunde.

**Pasul 1 — Verificarea existenței unui ID de restaurant**

`POST /appointments/zenchef-restaurants/check`

| Câmp | Obligatoriu | Descriere |
|---|---|---|
| `restaurant_id` | Da | ID-ul restaurantului Zenchef care trebuie verificat. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants/check?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "12345" }'
```

**Răspuns** (`200 OK`):

```json
{
  "success": true,
  "data": { "exists": true, "requiresNameVerification": true }
}
```

`exists: false` înseamnă că niciun restaurant Zenchef nu are acel ID — nu mai este nimic de făcut. Limitat la 10 verificări la fiecare 5 minute per cont; depășirea acestei limite returnează `429`.

**Pasul 2 — Verificarea numelui restaurantului**

`POST /appointments/zenchef-restaurants/verify-name`

| Câmp | Obligatoriu | Descriere |
|---|---|---|
| `restaurant_id` | Da | ID-ul restaurantului Zenchef de la pasul 1. |
| `user_input_name` | Da | Numele introdus de titularul contului — comparat cu numele real al restaurantului din Zenchef (fără a ține cont de majuscule/spații). |

```bash
curl -X POST "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants/verify-name?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "12345", "user_input_name": "The Blue Door Bistro" }'
```

**Răspuns** (`200 OK`):

```json
{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "id": "12345",
      "name": "The Blue Door Bistro",
      "address": "1 Rue de Rivoli, Paris",
      "status": "active"
    }
  }
}
```

`verified: false` înseamnă că numele nu a corespuns — `restaurantDetails` este omis, cereți titularului contului să încerce din nou. Limitat la 3 încercări la fiecare 5 minute (mai strict decât verificarea existenței, deoarece acesta este pasul de verificare propriu-zisă). Un `restaurant_id` care nu mai este valid în Zenchef returnează `404`.

**Pasul 3 — Salvarea restaurantului**

`POST /appointments/zenchef-restaurants`

| Câmp | Obligatoriu | Descriere |
|---|---|---|
| `restaurant_id` | Da | 1–64 caractere, litere/cifre/underscore/cratimă. |
| `restaurant_name` | Da | Numele verificat al restaurantului de la pasul 2. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "12345", "restaurant_name": "The Blue Door Bistro" }'
```

**Răspuns** (`201 Created`):

```json
{ "success": true, "data": { "restaurantId": "12345" } }
```

**Actualizarea unui restaurant Zenchef salvat**

`PUT /appointments/zenchef-restaurants/{restaurantId}`

| Câmp | Obligatoriu | Descriere |
|---|---|---|
| `restaurant_name` | Nu | Numele de afișare nou. |
| `is_active` | Nu | Setați `false` pentru a împiedica botul să efectueze rezervări la acest restaurant fără a-l elimina. |

```bash
curl -X PUT "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants/12345" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'
```

**Răspuns** (`200 OK`): aceeași formă ca răspunsul de salvare de mai sus.

**Eliminarea unui restaurant Zenchef**

`DELETE /appointments/zenchef-restaurants/{restaurantId}`

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants/12345" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Răspuns** (`200 OK`): `{ "success": true, "data": { "restaurantId": "12345" } }`

Un `restaurantId` care nu se află în prezent în cont returnează `404` la actualizare sau ștergere.

### Formitable

Formitable nu are nevoie de verificarea numelui în doi pași ca Zenchef — ID-urile sale de restaurant sunt deja delimitate per afacere, deci un singur apel de verificare este suficient. De asemenea, are o funcție de căutare a detaliilor utilizată pentru a stoca în cache URL-ul site-ului web al restaurantului în timpul configurării.

**Verificarea unui ID de restaurant**

`POST /appointments/formitable-restaurants/verify`

| Câmp | Obligatoriu | Descriere |
|---|---|---|
| `restaurant_id` | Da | ID-ul restaurantului Formitable. |
| `language` | Nu | Etichetă de limbă pentru cererea de sondare. Valoarea implicită este `"nl"`. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/appointments/formitable-restaurants/verify?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "the-blue-door", "language": "en" }'
```

**Răspuns** (`200 OK`):

```json
{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "restaurantId": "the-blue-door",
      "productCount": 4,
      "sampleProductTitle": "Dinner for two",
      "language": "en"
    }
  }
}
```

Un `restaurant_id` pe care Formitable nu îl recunoaște returnează `404`. Limitat la 10 încercări la fiecare 5 minute per cont.

**Obținerea detaliilor restaurantului**

`GET /appointments/formitable-restaurants/{restaurantId}/details?language=en`

Preluarea profilului public al restaurantului de pe Formitable, inclusiv site-ul web — utilizat pentru a stoca în cache URL-ul site-ului web în timpul configurării restaurantului. `language` este un parametru de interogare opțional, cu valoarea implicită `"en"`.

```bash
curl "https://api.youraiconnector.com/v1/appointments/formitable-restaurants/the-blue-door/details?language=en" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Răspuns** (`200 OK`):

```json
{
  "success": true,
  "data": {
    "uid": "the-blue-door",
    "name": "The Blue Door Bistro",
    "website": "https://thebluedoorbistro.com",
    "email": "info@thebluedoorbistro.com",
    "telephone": "+31201234567",
    "streetAddress": "Prinsengracht 1",
    "zipcode": "1015 AB",
    "city": "Amsterdam",
    "country": "Netherlands",
    "countryCode": "NL",
    "currency": "EUR"
  }
}
```

**Salvează restaurantul**

`POST /appointments/formitable-restaurants`

| Câmp | Obligatoriu | Descriere |
|---|---|---|
| `restaurant_id` | Da | 1–64 caractere, litere/cifre/underscore/cratimă. |
| `restaurant_name` | Da | Nume afișat. |
| `language` | Da | Etichetă de limbă ISO, de ex. `"en"` sau `"en-GB"`. |
| `website_url` | Nu | Site-ul web al restaurantului, din căutarea detaliilor de mai sus. Trebuie să fie `http(s)://`. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/appointments/formitable-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "restaurant_id": "the-blue-door",
    "restaurant_name": "The Blue Door Bistro",
    "language": "en",
    "website_url": "https://thebluedoorbistro.com"
  }'
```

**Răspuns** (`201 Created`): `{ "success": true, "data": { "restaurantId": "the-blue-door" } }`

**Actualizează un restaurant Formitable salvat**

`PUT /appointments/formitable-restaurants/{restaurantId}`

| Câmp | Obligatoriu | Descriere |
|---|---|---|
| `restaurant_name` | Nu | Nume afișat nou. |
| `language` | Nu | Etichetă de limbă ISO nouă. |
| `is_active` | Nu | Setează `false` pentru a opri botul din a efectua rezervări la acest restaurant fără a-l elimina. |
| `website_url` | Nu | URL site web nou. |

```bash
curl -X PUT "https://api.youraiconnector.com/v1/appointments/formitable-restaurants/the-blue-door" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'
```

**Răspuns** (`200 OK`): aceeași formă ca răspunsul de salvare de mai sus.

**Elimină un restaurant Formitable**

`DELETE /appointments/formitable-restaurants/{restaurantId}`

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/appointments/formitable-restaurants/the-blue-door" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Răspuns** (`200 OK`): `{ "success": true, "data": { "restaurantId": "the-blue-door" } }`

Un `restaurantId` care nu se află în prezent în cont returnează `404` la actualizare sau ștergere.

> **Formatul erorilor pentru toate endpoint-urile Zenchef/Formitable:** spre deosebire de restul acestei pagini, erorile de aici conțin statusul de două ori — o dată ca status HTTP și o dată ca `error_code` în corp — de exemplu `{ "success": false, "error": "Restaurant not found", "error_code": 404 }`. Gestionează-le la fel ca pe orice altă eroare: verifică `success`, citește `error` pentru mesaj.

---

## Erori API pentru programări

Endpoint-urile pentru programări returnează plicul standard de eroare:

```json
{
  "success": false,
  "error": "Appointment not found"
}
```

| Status | Când apare pe un endpoint de programări |
|---|---|
| `400` | Un câmp obligatoriu lipsește sau este invalid — de exemplu, un `start_time` incorect, un `end_time` care nu este după `start_time`, o combinație de filtre invalidă, lipsa câmpurilor de actualizat sau o programare deja anulată. |
| `404` | Programarea, contactul sau tipul de eveniment nu a fost găsit. |
| `409` | Intervalul orar solicitat este deja ocupat (conflict de rezervare). |

Codurile partajate pe care orice endpoint le poate returna — `401`, `403` (planul dvs. nu include acces API), `429` (limită de rată) și `500` — sunt listate cu îndrumări pentru reîncercare în [Erori și Paginare](errors-and-pagination.md).

---

## Pașii următori

- [Contacte](contacts.md) — creează și caută contactele pentru care faci rezervări.
- [Mesaje și conversații](messages.md) — trimite unui contact o confirmare sau un memento.
- [Webhook-uri](webhooks.md) — primește notificări când programările se modifică.