Appuntamenti #

L’API Appointments ti consente di prenotare appuntamenti per i tuoi contatti sui tuoi tipi di evento, quindi di recuperarli, elencarli, aggiornarli, annullarli o eliminarli. Risponde anche alla domanda che sorge per prima nella maggior parte dei flussi di prenotazione — quali orari sono effettivamente liberi — e copre il lato calendario: elencando i Google Calendar che hai collegato e importando gli eventi che vi sono già presenti. Quando una connessione a Google Calendar è attiva, l’evento del calendario corrispondente viene creato e mantenuto sincronizzato automaticamente in background. I ristoranti che utilizzano Zenchef, Formitable, OpenTable o TheFork per il proprio sistema di prenotazione possono anche essere verificati e collegati qui, in modo che l’Agente AI prenoti tavoli reali invece di appuntamenti interni — e le attività basate su appuntamenti che gestiscono la propria programmazione in Trafft possono connettersi allo stesso modo.

Tutti i percorsi in questa pagina sono relativi all’URL di base https://api.youraiconnector.com/v1. Ogni richiesta richiede la tua chiave API: consulta Autenticazione per l’elenco completo delle modalità di invio. Gli esempi seguenti utilizzano l’intestazione X-API-Key, con un esempio cURL che mostra anche il formato di query ?apiKey=.

Eventi vs. appuntamenti: Una tipologia di evento è la definizione di uno slot prenotabile (il tipo di riunione, la sua durata, le sue sale). Un appuntamento è una singola istanza prenotata di una tipologia di evento per uno specifico contatto. Prenoti un appuntamento facendo riferimento al contatto e alla tipologia di evento.

L’oggetto appuntamento #

Ogni endpoint che restituisce un appuntamento utilizza la stessa struttura:

Informazioni sulla sincronizzazione del calendario: Subito dopo aver prenotato o modificato un appuntamento, google_calendar_event_id potrebbe essere ancora null e calendar_synced potrebbe essere false perché la sincronizzazione viene eseguita in background poco dopo. Recupera nuovamente l’appuntamento poco dopo per visualizzare i campi del calendario popolati.

Trova gli slot disponibili #

GET /appointments/available-slots

Restituisce gli orari che sono effettivamente liberi per un tipo di evento tra due momenti. Questa è solitamente la prima chiamata in un flusso di prenotazione: mostra questi slot, lascia che la persona ne scelga uno, quindi invia l’orario scelto a Prenota un appuntamento.

La risposta tiene già conto degli orari di apertura e della durata dello slot del tipo di evento, delle sue sale, degli appuntamenti che hai già prenotato su di esso e di tutto ciò che è bloccato sui Google Calendar collegati — quindi uno slot restituito qui è uno slot che puoi prenotare.

I risultati vengono restituiti raggruppati per giorno — e, quando il tipo di evento utilizza le sale, un gruppo per sala per giorno:

Ogni voce in available_slots ha:

Gli orari sono locali rispetto al tipo di evento, non UTC. date, start_time e end_time sono valori di orologio locale nel fuso orario del tipo di evento (il suo override, o il fuso orario del tuo account quando non ne ha uno). Prenota un appuntamento si aspetta un istante UTC ISO 8601, quindi converti lo slot che hai scelto prima di inviarlo.

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"])

Risposta (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 }
      ]
    }
  ]
}

Un giorno senza disponibilità semplicemente non appare. event_id, start_time o end_time mancanti restituiscono 400; un tipo di evento che non è sul tuo account restituisce 404.

Prenota un appuntamento #

POST /appointments

Crea un appuntamento per uno dei tuoi contatti. Ci sono due modi per utilizzarlo:

• Su uno dei tuoi tipi di evento — invia event_id e la prenotazione funzionerà esattamente come ha sempre fatto: la disponibilità e la capacità vengono rispettate, l’ora di fine viene calcolata in base alla durata dello slot del tipo di evento e l’appuntamento si sincronizza con il tuo Google Calendar quando ne è collegato uno.
• Come prenotazione esterna — ometti event_id e invia invece un title. Questo registra una prenotazione effettuata altrove (il tuo CRM, un programma di lezioni, un altro strumento di prenotazione) in modo che appaia nella pagina Appuntamenti insieme al resto.

Una prenotazione per una tipologia di evento con stanze deve avvenire in un orario proposto da Trova slot disponibili: all’interno degli orari della stanza, al di fuori del periodo di preavviso, entro il limite temporale di prenotazione della tipologia di evento, sulla griglia degli slot, non nel passato e non bloccato su un calendario collegato. Qualsiasi altro orario viene rifiutato con un 400 e non viene creato nulla. Lo stesso vale per un room_name che non corrisponde a nessuna delle stanze della tipologia di evento (il messaggio elenca i nomi validi). I tempi di buffer impostati sulla tipologia di evento (Buffer prima e Buffer dopo nell’editor della tipologia di evento, buffer_before e buffer_after in minuti) vengono mantenuti liberi attorno a ogni prenotazione.

Una prenotazione su un tipo di evento è anche soggetta a controllo dei conflitti: se lo slot è già pieno, la richiesta fallisce con un 409 e non viene creato nulla. Una prenotazione esterna non ha un tipo di evento associato, quindi non viene effettuato alcun controllo rispetto alla tua disponibilità o capacità e nulla viene sincronizzato con un calendario.

Riprovare è sicuro. Se lo stesso contatto ha già una prenotazione confermata sullo stesso tipo di evento allo stesso orario di inizio (nella stessa stanza, quando ne specifichi una), ad esempio perché la tua prima richiesta è andata in timeout dopo essere stata elaborata, riceverai quella prenotazione con un 200 e "replayed": true invece di una seconda prenotazione o un 409.

Un external_reference funziona come chiave di idempotenza. È univoco nel tuo account: se un appuntamento contiene già il riferimento che invii, tale appuntamento viene restituito con un 200 e "replayed": true e non viene creato nulla di nuovo, anche se il tentativo di riprova indica un orario o un contatto diverso e indipendentemente dallo stato dell’appuntamento. Usalo per le prenotazioni a pagamento (invia il tuo ID pagamento o ordine) e invia un nuovo riferimento per una prenotazione effettivamente nuova.

Invia event_id e title insieme, o nessuno dei due, e la richiesta restituirà un 400 — così come l’invio di entrambi end_time e duration_minutes.

cURL (utilizzando il formato di query ?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"])

Risposta (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
  }
}

Registrazione di una prenotazione effettuata altrove #

Stesso endpoint, senza un tipo di evento: un title e un start_time sono sufficienti, e duration_minutes imposta la durata.

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"])

Risposta (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
  }
}

Le prenotazioni esterne sono appuntamenti ordinari a tutti gli effetti: appaiono nella pagina Appuntamenti e in Elenca appuntamenti, possono essere riprogrammate, annullate o eliminate nell’app o tramite questa API, l’email di notifica della prenotazione viene inviata come al solito e il trigger di automazione Appuntamento prenotato e il webhook si attivano per loro come per qualsiasi altra prenotazione effettuata tramite l’API. Le uniche differenze sono quelle sopra indicate: nessun controllo di disponibilità o capacità, nessuna sincronizzazione del calendario e event_id rimane null.

Ottieni un appuntamento #

GET /appointments/{appointmentId}

Restituisce un singolo appuntamento tramite il suo ID, incluso il suo stato di sincronizzazione del calendario.

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"])

Risposta (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
  }
}

Elenca appuntamenti #

GET /appointments

Elenca gli appuntamenti per il tuo account, dal più recente, con paginazione basata su cursore.

Alcune regole da tenere a mente:

• Senza filtri, ottieni ogni appuntamento sull’account, pagina per pagina.
• Per contatto — imposta contact_id per vedere gli appuntamenti confermati di un contatto. Puoi restringere il campo a un singolo giorno passando anche date.
• Per stato — imposta status (senza contact_id) per elencare solo gli appuntamenti Confirmed o solo Canceled nell’account.
• Il filtro date senza contact_id, o status=Canceled insieme a contact_id, restituisce un 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"])

Risposta (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
}

Per scorrere i risultati, passa il next_cursor da una risposta come cursor della richiesta successiva. Continua finché next_cursor non è null. Vedi Errori e Paginazione per il pattern di paginazione condiviso.

Aggiorna un appuntamento #

PUT /appointments/{appointmentId}

Ripianifica un appuntamento o modifica i suoi dettagli. Invia solo i campi che desideri modificare: almeno uno è obbligatorio. L’inizio e la fine combinati devono rimanere in ordine cronologico (end_time deve essere successivo a start_time). Le modifiche vengono sincronizzate automaticamente con l’evento del calendario collegato.

Lo spostamento di una prenotazione confermata su un tipo di evento (un nuovo start_time o room_name) è soggetto a controllo dei conflitti come una nuova prenotazione: uno slot già pieno risponde 409 e nulla cambia, e una room_name che non corrisponde a nessuna delle stanze del tipo di evento risponde 400. Invia solo start_time e la prenotazione manterrà la sua durata. I tuoi orari di apertura e il periodo di preavviso non vengono applicati qui, quindi puoi comunque spostare una prenotazione in qualsiasi orario libero.

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"])

Risposta (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
  }
}

Annulla un appuntamento #

POST /appointments/{appointmentId}/cancel

Annulla un appuntamento confermato, registrando facoltativamente un motivo. L’appuntamento rimane nel tuo account con lo stato Canceled e l’evento del calendario collegato viene rimosso automaticamente in background. L’annullamento di un appuntamento già annullato restituisce 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"])

Risposta (200 OK):

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

Invia nuovamente la conferma della prenotazione #

POST /appointments/{appointmentId}/resend-confirmation

Invia nuovamente al contatto la conferma della prenotazione, ad esempio quando afferma di non averla mai ricevuta o che è finita nello spam. Si compone di due parti, entrambe inviate a meno che non ne venga disattivata una: l’email di conferma (la stessa ricevuta dal contatto al momento della prenotazione) e, quando l’appuntamento è presente sul tuo Google Calendar, l’invito di Google Calendar. Entrambi vengono inviati all’indirizzo email del contatto.

Ogni parte restituisce il proprio esito: sent, not_requested, no_contact_email, turned_off_for_event_type (l’interruttore Invia email di appuntamento al contatto del tipo di evento è disattivato), not_on_google_calendar, imported (gli appuntamenti importati dal tuo calendario non ricevono alcuna email di conferma) o failed.

• 200 quando almeno una parte è stata inviata. recipient è l’indirizzo a cui è stata inviata.
• 409 per un appuntamento annullato, già concluso o una prenotazione effettuata tramite Zenchef, Formitable, OpenTable, TheFork o Trafft (quel sistema invia la propria conferma). code è appointment_canceled, appointment_in_past o managed_by_provider.
• 422 quando non è stato possibile inviare nulla, con il motivo in 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())

Risposta (200 OK):

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

Elimina un appuntamento #

DELETE /appointments/{appointmentId}

Elimina definitivamente un appuntamento e i suoi riferimenti. Se desideri solo annullare la prenotazione mantenendo il record, utilizza invece annulla.

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"])

Risposta (200 OK):

{
  "success": true
}

Elenca i tuoi Google Calendar collegati #

GET /appointments/google-calendars

Restituisce i Google Calendar disponibili su questo account, direttamente da Google — utile per mostrare al titolare dell’account un selettore da cui importare il calendario qui sotto, o semplicemente per confermare che la connessione è attiva.

Questo funziona solo una volta che l’account ha collegato Google Calendar (Impostazioni → Integrazioni) con almeno l’accesso in lettura. Se non lo ha fatto, o se l’accesso concesso non include più l’ambito di lettura del calendario, riceverai un 400 che ti invita a (ri)collegarlo.

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"])

Risposta (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"
    }
  ]
}

Ogni voce ha la forma CalendarListEntry di Google, quindi i nomi dei campi seguono lo camelCase di Google, non il solito snake_case di questa API: si tratta dei dati di Google trasmessi così come sono, non dei nostri. Una connessione mancante o revocata restituisce 400 con un errore che spiega che Google Calendar deve essere (ri)collegato.

Importa eventi da un Google Calendar #

POST /appointments/import-calendar-events

Estrae gli eventi già presenti nel/i Google Calendar collegato/i di una campagna o di un Agente AI e li trasforma in appuntamenti; è utile la prima volta che si collega un calendario che ha già delle prenotazioni. Questa operazione può richiedere del tempo (ogni evento viene analizzato per capire a chi è destinato), quindi non viene mai eseguita in linea: la richiesta accoda un processo in background e ti restituisce un job_id da interrogare.

Invia esattamente uno tra campaign_id / agent_id, mai entrambi e mai nessuno dei due: qualsiasi altra combinazione restituisce un 400. Qualunque tu scelga di inviare deve appartenere al tuo account, altrimenti riceverai 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"])

Risposta (202 Accepted):

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

campaign_id e agent_id rimandano quello che hai inviato; l’altro è sempre null.

Interroga il processo di importazione #

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

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

Risposta (200 OK):

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

GET su un jobId che non esiste (o appartiene a un account diverso) restituisce 404.

Integrazioni di prenotazione esterne (Zenchef / Formitable / OpenTable / TheFork / Trafft) #

Zenchef e Formitable sono sistemi di prenotazione per ristoranti tramite i quali il tuo Agente IA può prenotare tavoli reali; Trafft è una piattaforma di pianificazione per attività basate su appuntamenti, collegata una volta per account anziché per ristorante. Le due piattaforme per ristoranti dispongono ciascuna di un widget di prenotazione pubblico e non autenticato (https://api.youraiconnector.com/v1/zenchef-widget/... e https://api.youraiconnector.com/v1/formitable-widget/...) che viene visualizzato all’interno della chat per il cliente — tali percorsi del widget sono semplici pagine HTML destinate ad essere aperte in un browser, non endpoint API JSON, quindi non sono documentati qui. Di seguito sono riportati gli endpoint di gestione dell’account: verifica che un ID ristorante appartenga al titolare dell’account, quindi aggiunta, aggiornamento o rimozione dello stesso.

Zenchef #

La connessione di un ristorante Zenchef è una verifica in due passaggi, in modo che il titolare dell’account dimostri di gestire effettivamente il ristorante prima che venga collegato al bot: prima si verifica che l’ID esista (senza rivelare il nome), poi si chiede di digitare il nome del ristorante e si verifica che corrisponda.

Passaggio 1 — Verificare che un ID ristorante esista

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

Risposta (200 OK):

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

exists: false significa che nessun ristorante Zenchef possiede quell’ID: non c’è altro da fare. Limitato a 10 controlli ogni 5 minuti per account; il superamento di questo limite restituisce 429.

Passaggio 2 — Verificare il nome del ristorante

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

Risposta (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 significa che il nome non corrisponde: restaurantDetails viene omesso, chiedi al titolare dell’account di riprovare. Limitato a 3 tentativi ogni 5 minuti (più restrittivo del controllo di esistenza, poiché questo è il passaggio di prova effettivo). Un restaurant_id che non è più risolvibile su Zenchef restituisce 404.

Passaggio 3 — Salvare il ristorante

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

Risposta (201 Created):

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

Aggiornare un ristorante Zenchef salvato

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 }'

Risposta (200 OK): stessa struttura della risposta di salvataggio sopra.

Rimuovere un ristorante 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"

Risposta (200 OK): { "success": true, "data": { "restaurantId": "12345" } }

Un restaurantId non attualmente presente nell’account restituisce 404 in caso di aggiornamento o eliminazione.

Formitable #

Formitable non richiede la verifica del nome in due passaggi necessaria per Zenchef: i suoi ID ristorante sono già limitati per attività, quindi una sola chiamata di verifica è sufficiente. Dispone inoltre di una ricerca dei dettagli utilizzata per memorizzare nella cache l’URL del sito web del ristorante durante la configurazione.

Verificare un ID ristorante

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

Risposta (200 OK):

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

Un restaurant_id non riconosciuto da Formitable restituisce 404. Limitato a 10 tentativi ogni 5 minuti per account.

Ottenere i dettagli del ristorante

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

Recupera il profilo pubblico del ristorante da Formitable, incluso il suo sito web: utilizzato per memorizzare nella cache l’URL del sito web durante la configurazione del ristorante. language è un parametro di query opzionale, con valore predefinito "en".

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

Risposta (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"
  }
}

Salva il ristorante

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

Risposta (201 Created): { "success": true, "data": { "restaurantId": "the-blue-door" } }

Aggiorna un ristorante Formitable salvato

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 }'

Risposta (200 OK): stessa struttura della risposta di salvataggio sopra.

Rimuovi un ristorante 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"

Risposta (200 OK): { "success": true, "data": { "restaurantId": "the-blue-door" } }

Un restaurantId non attualmente presente nell’account restituisce 404 in caso di aggiornamento o eliminazione.

OpenTable #

I ristoranti OpenTable vengono raggiunti tramite le credenziali partner OpenTable della piattaforma, e OpenTable consente a tali credenziali di vedere solo i ristoranti che hanno collegato l’elenco della piattaforma all’interno del Marketplace delle integrazioni di OpenTable. Quindi, come per Formitable, è sufficiente una chiamata di verifica: un ID Ristorante raggiungibile (il “RID” numerico) dimostra sia che il ristorante esiste, sia che ha collegato l’integrazione. Fino a quando l’elenco partner OpenTable non viene abilitato sulla piattaforma, la chiamata di verifica risponde 503.

Verifica un ristorante 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" }'

Risposta (200 OK):

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

verified: false significa che nessun ristorante OpenTable ha quell’ID. Un 403 significa che il ristorante esiste ma non ha ancora collegato l’integrazione della piattaforma all’interno di OpenTable. Limitato a 10 tentativi ogni 5 minuti per account.

Aggiungi un ristorante 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" }'

Risposta (201 Created): { "success": true, "data": { "restaurantId": "1038007" } }

Aggiorna un ristorante OpenTable salvato

PUT /appointments/opentable-restaurants/{restaurantId}

Invia uno qualsiasi tra restaurant_name, is_active (metti in pausa con false) o website_url (una stringa vuota lo cancella); i campi omessi rimangono invariati.

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 }'

Risposta (200 OK): { "success": true, "data": { "restaurantId": "1038007" } }

Rimuovere un ristorante 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"

Risposta (200 OK): { "success": true, "data": { "restaurantId": "1038007" } }

Un restaurantId non attualmente presente nell’account restituisce 404 durante l’aggiornamento.

TheFork #

I ristoranti TheFork vengono raggiunti tramite le credenziali partner TheFork della piattaforma, e TheFork consente a tali credenziali di vedere solo i ristoranti che hanno il partner della piattaforma abilitato sul proprio account TheFork. Quindi, come per Formitable e OpenTable, una chiamata di verifica è sufficiente: un ID Ristorante raggiungibile dimostra sia che il ristorante esiste sia che il partner è abilitato su di esso. L’ID è l’UUID che TheFork assegna al ristorante in TheFork Manager, inviato come stringa. Finché TheFork non avrà approvato la piattaforma come partner e rilasciato le credenziali, la chiamata di verifica risponderà 503 — vedi TheFork per cosa significa oggi.

Verifica un ristorante 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" }'

Risposta (200 OK):

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

partySizes sono le dimensioni del gruppo che il ristorante accetta online nei prossimi 30 giorni. Un 404 o 403 significa che TheFork non ci ha fornito un ristorante con quell’ID — o l’ID è errato, o il partner della piattaforma non è ancora abilitato su quel ristorante; un 400 significa che l’ID non è un UUID. Limitato a 10 tentativi ogni 5 minuti per account.

Aggiungi un ristorante 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" }'

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

Aggiorna un ristorante TheFork salvato

PUT /appointments/thefork-restaurants/{restaurantId}

Invia uno qualsiasi tra restaurant_name, is_active (metti in pausa con false) o website_url (una stringa vuota lo cancella); i campi omessi rimangono invariati.

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 }'

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

Rimuovi un ristorante 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"

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

Un restaurantId non attualmente presente nell’account restituisce 404 in caso di aggiornamento o eliminazione.

Trafft #

Trafft viene collegato una volta per l’intero account, non per singola sede: un indirizzo aziendale più le credenziali API dal pannello di amministrazione di Trafft (Features & Integrations → API & Connectors, parte del piano Business di Trafft). La chiamata di connessione verifica tali credenziali su Trafft prima di memorizzare qualsiasi cosa, quindi un indirizzo errato, credenziali errate o un piano senza accesso API falliranno in questa fase anziché durante una conversazione con il cliente. Il client secret viene memorizzato crittografato e non viene mai restituito da alcun endpoint.

Tutte e tre le chiamate di scrittura (POST, PUT, DELETE) richiedono l’autorizzazione edit per le Integrazioni; lo stato GET richiede l’autorizzazione view per le Integrazioni.

Collega 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"
  }'

Risposta (200 OK):

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

I conteggi vengono restituiti da Trafft durante la verifica — sono il modo più rapido per confermare che le credenziali puntino all’account desiderato.

Ottieni lo stato della connessione

GET /appointments/trafft

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

Risposta (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 significa che non è ancora stato configurato nulla. Il client secret non è mai incluso in questa risposta.

Aggiorna la connessione

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 }'

Risposta (200 OK): lo stesso oggetto di connessione del GET qui sopra.

Disconnetti Trafft

DELETE /appointments/trafft

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

Risposta (200 OK): { "success": true }

La disconnessione rimuove solo le credenziali memorizzate. Gli appuntamenti già presenti in Trafft rimangono invariati.

Formato dell’errore su tutti gli endpoint Zenchef/Formitable/OpenTable/TheFork: a differenza del resto di questa pagina, gli errori qui riportano il loro stato due volte — una come stato HTTP e una come error_code nel corpo — ad esempio { "success": false, "error": "Restaurant not found", "error_code": 404 }. Gestiscilo allo stesso modo di qualsiasi altro errore: controlla success, leggi error per il messaggio.

Errori dell’API Appuntamenti #

Gli endpoint degli appuntamenti restituiscono il formato di errore standard:

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

I codici condivisi che ogni endpoint può restituire — 401, 403 (il tuo piano non include l’accesso all’API), 429 (limite di frequenza) e 500 — sono elencati con indicazioni sui tentativi in Errori e Paginazione.

Passaggi successivi #

• Contatti — crea e cerca i contatti per cui effettui le prenotazioni.
• Messaggi e conversazioni — invia a un contatto una conferma o un promemoria.
• Webhook — ricevi notifiche quando gli appuntamenti cambiano.