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 Google Calendar este activă, evenimentul corespondent din calendar este creat și menținut sincronizat automat în fundal. Restaurantele care utilizează Zenchef, Formitable, OpenTable sau TheFork 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 — iar companiile care își gestionează programul în Trafft se pot conecta în același mod.

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

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.

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.

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

Fiecare intrare din available_slots are:

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 așteaptă un moment UTC ISO 8601, deci convertiți intervalul ales înainte de a-l posta.

cURL

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

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

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

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

Creează o programare pentru unul dintre contactele tale. Există două moduri de a o utiliza:

• Pe unul dintre tipurile tale de evenimente — trimite event_id, iar rezervarea funcționează exact ca întotdeauna: disponibilitatea și capacitatea sunt respectate, ora de sfârșit este calculată din durata intervalului tipului de eveniment, iar programarea se sincronizează cu Google Calendar atunci când acesta este conectat.
• Ca rezervare externă — omite event_id și trimite un title în schimb. Aceasta înregistrează o rezervare care a fost făcută în altă parte (propriul tău CRM, un program de cursuri, un alt instrument de rezervare), astfel încât să apară pe pagina Programări alături de celelalte.

O rezervare pentru un tip de eveniment cu săli trebuie să fie pentru un interval orar pe care Găsește intervale disponibile l-ar oferi: în cadrul orelor de funcționare ale sălii, în afara perioadei de preaviz, în limita intervalului de timp în care poate fi rezervat tipul de eveniment, pe grila de intervale, să nu fie în trecut și să nu fie blocat într-un calendar conectat. Orice altă oră este refuzată cu un 400 și nu se creează nimic. La fel și un room_name care nu corespunde niciuneia dintre sălile tipului de eveniment (mesajul listează numele valide). Timpii de buffer setați pentru tipul de eveniment (Buffer înainte și Buffer după în editorul tipului de eveniment, buffer_before și buffer_after în minute) sunt păstrați liberi în jurul fiecărei rezervări.

O rezervare pentru un tip de eveniment este, de asemenea, verificată pentru conflicte: dacă intervalul este deja ocupat, cererea eșuează cu o eroare 409 și nu se creează nimic. O rezervare externă nu are un tip de eveniment asociat, deci nu se verifică nimic în raport cu disponibilitatea sau capacitatea ta și nimic nu este sincronizat cu un calendar.

Reîncercarea este sigură. Dacă același contact are deja o rezervare confirmată pentru același tip de eveniment la aceeași oră de început (în aceeași sală, când specifici una), de exemplu pentru că prima ta cerere a expirat după ce a fost procesată, vei primi înapoi acea rezervare cu un 200 și "replayed": true în loc de o a doua rezervare sau o eroare 409.

Un external_reference funcționează ca o cheie de idempotență. Este unic în contul tău: dacă o programare are deja referința pe care o trimiți, acea programare este returnată cu un 200 și "replayed": true și nu se creează nimic nou, chiar dacă reîncercarea specifică o oră sau un contact diferit și indiferent de starea programării respective. Folosește-l pentru rezervări plătite (trimite ID-ul plății sau al comenzii tale) și trimite o referință nouă pentru o rezervare cu adevărat nouă.

Trimite event_id și title împreună, sau niciunul dintre cele două, iar cererea returnează un 400 — la fel ca trimiterea ambelor end_time și duration_minutes.

cURL (folosind forma de interogare ?apiKey=)

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

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

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

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

Înregistrarea unei rezervări făcute în altă parte #

Același endpoint, fără un tip de eveniment: un title și un start_time sunt suficiente, iar duration_minutes stabilește cât timp durează.

cURL

curl -X POST "https://api.youraiconnector.com/v1/appointments" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "contact_abc123",
    "title": "Beginner guitar class",
    "start_time": "2026-06-15T10:00:00.000Z",
    "duration_minutes": 90,
    "external_reference": "class-slot-4812"
  }'

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",
    title: "Beginner guitar class",
    start_time: "2026-06-15T10:00:00.000Z",
    duration_minutes: 90,
  }),
});
const data = await res.json();
console.log(data.appointment_id);

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",
        "title": "Beginner guitar class",
        "start_time": "2026-06-15T10:00:00.000Z",
        "duration_minutes": 90,
    },
)
print(res.json()["appointment_id"])

Răspuns (201 Created):

{
  "success": true,
  "appointment_id": "eFgH5678aBcD1234",
  "appointment": {
    "id": "eFgH5678aBcD1234",
    "contact_id": "contact_abc123",
    "event_id": null,
    "status": "Confirmed",
    "start_time": "2026-06-15T10:00:00.000Z",
    "end_time": "2026-06-15T11:30:00.000Z",
    "created_at": "2026-06-10T09:00:00.000Z",
    "last_modified_at": "2026-06-10T09:00:00.000Z",
    "summary": "Beginner guitar class",
    "google_calendar_event_id": null,
    "calendar_synced": false
  }
}

Rezervările externe sunt programări obișnuite de acolo înainte: apar pe pagina Programări și în Listare programări, pot fi reprogramate, anulate sau șterse în aplicație sau prin acest API, e-mailul de notificare a rezervării este trimis ca de obicei, iar declanșatorul de automatizare Programare rezervată și webhook-ul se activează pentru ele ca pentru orice altă rezervare făcută prin API. Singurele diferențe sunt cele de mai sus — nicio verificare a disponibilității sau capacității, nicio sincronizare cu calendarul, iar event_id rămâne null.

Obțineți o programare #

GET /appointments/{appointmentId}

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

cURL

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

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

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

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

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

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

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

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

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

Mutarea unei rezervări confirmate pentru un tip de eveniment (un start_time sau room_name nou) este verificată pentru conflicte la fel ca o rezervare nouă: un interval care este deja ocupat răspunde cu 409 și nimic nu se schimbă, iar o room_name care nu corespunde niciuneia dintre sălile tipului de eveniment răspunde cu 400. Trimite doar start_time și rezervarea își păstrează durata. Propriile tale ore de deschidere și perioada de preaviz nu se aplică aici, deci poți muta în continuare o rezervare la orice oră liberă.

cURL

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

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

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

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

cURL

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

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

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

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

Retrimiteți confirmarea rezervării #

POST /appointments/{appointmentId}/resend-confirmation

Retrimite contactului confirmarea rezervării, de exemplu atunci când acesta spune că nu a primit-o sau că a ajuns în folderul spam. Două părți, ambele trimise dacă nu dezactivați una dintre ele: e-mailul de confirmare (același e-mail pe care l-a primit contactul la efectuarea rezervării) și, atunci când programarea se află în Google Calendar, invitația Google Calendar. Ambele sunt trimise la adresa de e-mail a contactului.

Fiecare parte revine cu propriul rezultat: sent, not_requested, no_contact_email, turned_off_for_event_type (comutatorul Trimite e-mailul de programare către contact al tipului de eveniment este oprit), not_on_google_calendar, imported (programările importate din calendarul dvs. nu primesc e-mail de confirmare) sau failed.

• 200 atunci când a fost trimisă cel puțin o parte. recipient este adresa la care a fost trimisă.
• 409 pentru o programare anulată, una care a trecut deja sau o rezervare efectuată prin Zenchef, Formitable, OpenTable, TheFork sau Trafft (acel sistem își trimite propria confirmare). code este appointment_canceled, appointment_in_past sau managed_by_provider.
• 422 atunci când nu a putut fi trimis nimic, cu motivul în error.

cURL

curl -X POST "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/resend-confirmation" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/resend-confirmation",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ calendar_invite: false }),
  }
);
const data = await res.json();
console.log(data.email, data.recipient);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/resend-confirmation",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={},
)
print(res.json())

Răspuns (200 OK):

{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678",
  "email": "sent",
  "calendar_invite": "sent",
  "recipient": "jane@example.com"
}

Ș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 în schimb.

cURL

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Răspuns (200 OK):

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

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

Integrări externe de rezervare (Zenchef / Formitable / OpenTable / TheFork / Trafft) #

Zenchef și Formitable sunt sisteme de rezervări pentru restaurante prin care Agentul dvs. AI poate rezerva mese reale; Trafft este o platformă de programări pentru afaceri, conectată o singură dată per cont, nu per restaurant. Cele două platforme pentru restaurante au fiecare 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 ale widget-ului 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 titularului 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

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

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

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

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

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

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

Actualizarea unui restaurant Zenchef salvat

PUT /appointments/zenchef-restaurants/{restaurantId}

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}

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

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

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

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

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

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}

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}

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.

OpenTable #

Restaurantele OpenTable sunt accesate prin intermediul acreditărilor de partener OpenTable ale platformei, iar OpenTable permite acestor acreditări să vadă doar restaurantele care au conectat listarea platformei în cadrul Marketplace-ului de Integrări OpenTable. Așadar, la fel ca în cazul Formitable, un singur apel de verificare este suficient: un ID de restaurant accesibil (numărul “RID”) dovedește atât faptul că restaurantul există, cât și că a conectat integrarea. Până când listarea de partener OpenTable este activată pe platformă, apelul de verificare va răspunde 503.

Verificarea unui restaurant OpenTable

POST /appointments/opentable-restaurants/verify

curl -X POST "https://api.youraiconnector.com/v1/appointments/opentable-restaurants/verify?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "1038007" }'

Răspuns (200 OK):

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "restaurantId": "1038007",
      "diningAreaCount": 2,
      "diningAreaNames": ["Main Room", "Garden"],
      "tableTypes": ["default", "outdoor", "bar"]
    }
  }
}

verified: false înseamnă că niciun restaurant OpenTable nu are acel ID. Un 403 înseamnă că restaurantul există, dar nu a conectat încă integrarea platformei în OpenTable. Limitat la 10 încercări la fiecare 5 minute per cont.

Adăugarea unui restaurant OpenTable

POST /appointments/opentable-restaurants

curl -X POST "https://api.youraiconnector.com/v1/appointments/opentable-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "1038007", "restaurant_name": "The Blue Door", "website_url": "https://thebluedoor.example" }'

Răspuns (201 Created): { "success": true, "data": { "restaurantId": "1038007" } }

Actualizarea unui restaurant OpenTable salvat

PUT /appointments/opentable-restaurants/{restaurantId}

Trimiteți oricare dintre restaurant_name, is_active (întrerupeți cu false) sau website_url (un șir gol îl șterge); câmpurile omise rămân neschimbate.

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

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

Eliminarea unui restaurant OpenTable

DELETE /appointments/opentable-restaurants/{restaurantId}

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/opentable-restaurants/1038007" \
  -H "X-API-Key: YOUR_API_KEY"

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

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

TheFork #

Restaurantele TheFork sunt accesate prin intermediul acreditărilor de partener TheFork ale platformei, iar TheFork permite acestor acreditări să vadă doar restaurantele care au activat partenerul platformei în contul lor TheFork. Așadar, la fel ca în cazul Formitable și OpenTable, un singur apel de verificare este suficient: un ID de restaurant accesibil dovedește atât faptul că restaurantul există, cât și faptul că partenerul este activat pentru acesta. ID-ul este UUID-ul pe care TheFork îl atribuie restaurantului în TheFork Manager, trimis ca șir de caractere. Până când TheFork aprobă platforma ca partener și emite acreditările, apelul de verificare răspunde cu 503 — consultați TheFork pentru a vedea ce înseamnă acest lucru în prezent.

Verificarea unui restaurant TheFork

POST /appointments/thefork-restaurants/verify

curl -X POST "https://api.youraiconnector.com/v1/appointments/thefork-restaurants/verify?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" }'

Răspuns (200 OK):

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60",
      "partySizes": [1, 2, 3, 4, 5, 6, 7, 8]
    }
  }
}

partySizes reprezintă dimensiunile grupului pe care restaurantul le acceptă online în următoarele 30 de zile. Un 404 sau 403 înseamnă că TheFork nu ne-a oferit un restaurant cu acel ID — fie ID-ul este greșit, fie partenerul platformei nu este încă activat pentru acel restaurant; un 400 înseamnă că ID-ul nu este un UUID. Limitat la 10 încercări la fiecare 5 minute per cont.

Adăugarea unui restaurant TheFork

POST /appointments/thefork-restaurants

curl -X POST "https://api.youraiconnector.com/v1/appointments/thefork-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60", "restaurant_name": "The Blue Door", "website_url": "https://thebluedoor.example" }'

Răspuns (201 Created): { "success": true, "data": { "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" } }

Actualizarea unui restaurant TheFork salvat

PUT /appointments/thefork-restaurants/{restaurantId}

Trimiteți oricare dintre restaurant_name, is_active (întrerupeți cu false) sau website_url (un șir gol îl șterge); câmpurile omise rămân neschimbate.

curl -X PUT "https://api.youraiconnector.com/v1/appointments/thefork-restaurants/9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Răspuns (200 OK): { "success": true, "data": { "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" } }

Elimină un restaurant TheFork

DELETE /appointments/thefork-restaurants/{restaurantId}

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/thefork-restaurants/9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns (200 OK): { "success": true, "data": { "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" } }

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

Trafft #

Trafft este conectat o singură dată pentru întregul cont, nu per locație: o adresă de companie plus credențialele API din panoul de administrare Trafft (Features & Integrations → API & Connectors, parte din planul Business al Trafft). Apelul de conectare verifică acele credențiale în Trafft înainte de a stoca orice, astfel încât o adresă greșită, credențiale incorecte sau un plan fără acces API vor eșua aici, nu în timpul unei conversații cu un client. Secretul clientului (client secret) este stocat criptat și nu este returnat niciodată de niciun endpoint.

Toate cele trei apeluri de scriere (POST, PUT, DELETE) necesită permisiunea edit pentru Integrări; starea GET necesită permisiunea view pentru Integrări.

Conectare Trafft

POST /appointments/trafft/connect

curl -X POST "https://api.youraiconnector.com/v1/appointments/trafft/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subdomain": "acme",
    "client_id": "YOUR_TRAFFT_CLIENT_ID",
    "client_secret": "YOUR_TRAFFT_CLIENT_SECRET",
    "company_name": "Acme Salon"
  }'

Răspuns (200 OK):

{
  "success": true,
  "data": {
    "subdomain": "acme",
    "service_count": 12,
    "employee_count": 4,
    "location_count": 2
  }
}

Numărătorile vin înapoi de la Trafft în timpul verificării — acestea sunt cea mai rapidă metodă de a confirma că acele credențiale indică spre contul dorit.

Obținerea stării conexiunii

GET /appointments/trafft

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

Răspuns (200 OK):

{
  "success": true,
  "data": {
    "connected": true,
    "subdomain": "acme",
    "hostname": "acme.admin.trafft.com",
    "client_id": "YOUR_TRAFFT_CLIENT_ID",
    "company_name": "Acme Salon",
    "is_active": true,
    "service_count": 12,
    "employee_count": 4,
    "location_count": 2
  }
}

connected: false înseamnă că nu este nimic configurat încă. Secretul clientului nu este inclus niciodată în acest răspuns.

Actualizarea conexiunii

PUT /appointments/trafft

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

Răspuns (200 OK): același obiect de conexiune ca GET de mai sus.

Deconectare Trafft

DELETE /appointments/trafft

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

Răspuns (200 OK): { "success": true }

Deconectarea elimină doar credențialele stocate. Programările deja existente în Trafft rămân intacte.

Formatul erorii pentru toate endpoint-urile Zenchef/Formitable/OpenTable/TheFork: 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ă-l 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:

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

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.

Pașii următori #

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