Vai al contenuto

L'API per la prenotazione di appuntamenti aperta a tutti i Suoi strumenti

Token con ambiti, webhook firmati, applicazioni OAuth, Zapier e Make. Le Sue prenotazioni arrivano là dove lavora.

Un'API per la prenotazione di appuntamenti serve non appena le prenotazioni devono vivere altrove rispetto allo strumento di prenotazione: un gestionale di settore, un'area clienti, un data warehouse, uno strumento di automazione. Senza di essa restano solo l'esportazione manuale e il reinserimento dei dati.

Perché un'API per la prenotazione di appuntamenti completa

Artibox Calendar espone un'API REST pubblica sulle sue rotte /api/v1: tipi di appuntamento, disponibilità, prenotazioni, sondaggi, link monouso, invii di link, webhook. Segue le stesse regole dell'applicazione: gli stessi permessi, lo stesso isolamento tra organizzazioni, la stessa prenotazione con blocco esclusivo. Ciò che un token può fare, può farlo il suo membro; niente di più.

Per i team senza sviluppatori, i connettori Zapier e Make collegano i Suoi appuntamenti ai Suoi strumenti senza scrivere codice. E per HubSpot, Salesforce o Pipedrive, le integrazioni CRM sono già pronte.

Come funziona

  1. Crei un token personale

    Scelga i suoi ambiti (leggere le prenotazioni, scrivere i tipi…). Il token inizia con rdv_pat_.

  2. Chiami l'API

    Invii il token nell'intestazione x-api-key. Fuori dai suoi ambiti, la chiamata viene rifiutata.

  3. Si iscriva agli eventi

    Dichiari un indirizzo di webhook e gli eventi che Le interessano.

  4. Segua le consegne

    Il registro dei webhook mostra ogni invio; può testare e ripetere.

Un'API pensata per la produzione

Token con ambiti

Ogni token personale ha ambiti precisi: leggere l'utente, leggere o amministrare l'organizzazione, leggere o scrivere i tipi, leggere le disponibilità, leggere o scrivere le prenotazioni, scrivere i link, gestire i webhook. Una chiamata fuori ambito riceve una risposta 403. Un token non può mai creare un altro token.

Limiti chiari

Ogni token può effettuare 100 chiamate al minuto. Gli elenchi sono paginati per numero di pagina. Le creazioni accettano un'intestazione Idempotency-Key, conservata 24 ore: una chiamata ripetuta dopo un'interruzione di rete non crea duplicati. Gli appuntamenti creati tramite API hanno origine «api».

Lo stesso motore della pagina di prenotazione

Una prenotazione creata tramite API segue le stesse regole della Sua pagina di prenotazione online: preavviso, margini, massimo giornaliero, calendari collegati. Se la fascia è appena stata presa, la risposta è un rifiuto chiaro, mai una doppia prenotazione.

Webhook firmati

Gli eventi

La Sua applicazione viene avvisata quando un appuntamento viene creato, spostato, annullato o registrato con il suo esito, quando un ospite vota in un sondaggio o un sondaggio viene confermato, e quando un tipo cambia. Ogni invio è firmato (intestazione X-Signature): Lei verifica che provenga davvero da Artibox Calendar.

Consegne affidabili

Se il Suo server non risponde, la consegna viene ritentata, da un minuto a dodici ore. Dopo 20 errori consecutivi, l'iscrizione viene disattivata. Il registro conserva 30 giorni di consegne; un pulsante invia un evento di prova, un altro ripete una consegna. Per sicurezza, i webhook non possono puntare a un indirizzo della rete interna.

OAuth per i produttori di software

Sviluppa uno strumento usato da altre organizzazioni? Dichiari un'applicazione OAuth in Impostazioni › Integrazioni. I Suoi utenti vedono una schermata di consenso, poi la Sua applicazione riceve un codice monouso, valido 10 minuti, protetto da PKCE (S256). Il token di accesso dura 2 ore; il token di aggiornamento ruota a ogni utilizzo, e il suo riutilizzo interrompe tutto l'accesso. Ogni membro revoca un accesso da «Applicazioni collegate».

Senza codice: Zapier, Make e il widget

Zapier e Make

I connettori Zapier e Make si collegano come applicazioni OAuth: avvii uno scenario a ogni nuovo appuntamento, invii un link di prenotazione da un altro strumento, cerchi un appuntamento per e-mail.

Il kit di integrazione

Lo script widget.js aggiunge un pulsante o un link di prenotazione al Suo sito. La prenotazione si apre in una finestra a parte. I parametri di tracciamento (utm_*, gclid, fbclid, ref) vengono conservati sull'appuntamento, e un contesto firmato può precompilare la prenotazione dal Suo strumento.

Piani e sicurezza

L'API (token personali, applicazioni OAuth) e i connettori Zapier e Make fanno parte del piano Pro; i webhook del piano Team. I dettagli sono nella pagina prezzi. Viene conservata solo l'impronta dei token, mai il token in chiaro: veda sicurezza e GDPR.

Per iniziare, segua le guide API e token e webhook (in francese). Per scegliere tra i due strumenti di automazione, legga Zapier o Make. Definizioni (in francese): API, webhook.

Per chi

  • Team commerciali

    Collegare gli appuntamenti ai Suoi strumenti di vendita e di reportistica.

  • Agenzie (FR)

    Integrare la prenotazione di appuntamenti nei siti e negli strumenti dei Suoi clienti.

  • Recruiting (FR)

    Creare i colloqui dal Suo software di gestione dei candidati.

  • Formatori (FR)

    Inviare le iscrizioni alle sessioni al Suo gestionale della formazione.

Domande frequenti

Come ci si autentica sull'API per la prenotazione di appuntamenti?

Con un token personale (rdv_pat_…) o un token di accesso OAuth, inviato nell'intestazione x-api-key. Ogni token ha i suoi ambiti.

Quali sono i limiti di chiamate?

100 chiamate al minuto per token. Le creazioni accettano un'intestazione Idempotency-Key, conservata 24 ore.

Come verificare che un webhook provenga davvero da Artibox Calendar?

Ogni invio è firmato nell'intestazione X-Signature. Verifichi la firma prima di elaborare il contenuto.

Cosa succede se il mio server non è disponibile?

La consegna viene ritentata da un minuto a dodici ore. Dopo 20 errori, l'iscrizione viene disattivata; può ripetere le consegne dal registro, conservato 30 giorni.

In quale piano è inclusa l'API?

L'API, Zapier e Make dal piano Pro; i webhook dal piano Team. Veda i prezzi.

Colleghi i Suoi appuntamenti ai Suoi strumenti

Crei il Suo account gratuitamente, poi il Suo primo token API.

Crea il mio account