Configurare e utilizzare l'API REST

 

Configurare e utilizzare l'API REST

Interrogare gli appuntamenti liberi e prenotare appuntamenti, direttamente dalla Sua applicazione.

L'API lavora con JSON e viene richiamata tramite l'indirizzo https://example.com/api. La procedura di prenotazione è composta da sei chiamate che si basano l'una sull'altra: calendario, motivo appuntamento, giorno, ora, campi del modulo e infine la prenotazione. Tutte le chiamate avvengono dal Suo server, non dal browser dei Suoi clienti.

Passo 1: attivare l'API e generare il token

Alla consegna l'API è disattivata. La attivi nell'area di amministrazione.

  1. Faccia clic nella navigazione su Configurazione.
  2. Faccia clic nella sottonavigazione su Impostazioni generali.
  3. Faccia clic nell'elenco su Interfaccia.
  4. Attivi API attivare. La modifica viene salvata subito.
  5. Faccia clic su Genera nuovo token per creare il token di accesso dell'interfaccia.
  6. Copi subito il token mostrato e lo conservi in un luogo sicuro, non viene mostrato una seconda volta.

Schermate

Faccia clic nella navigazione su Configurazione

1 Faccia clic nella navigazione su Configurazione

Faccia clic nella sottonavigazione su Impostazioni generali

2 Faccia clic nella sottonavigazione su Impostazioni generali

Faccia clic nell'elenco su Interfaccia

3 Faccia clic nell'elenco su Interfaccia

Attivi API attivare. La modifica viene salvata subito

4 Attivi API attivare. La modifica viene salvata subito

Faccia clic su Genera nuovo token per creare il token di accesso dell'interfaccia

5 Faccia clic su Genera nuovo token per creare il token di accesso dell'interfaccia

Copi subito il token mostrato e lo conservi in un luogo sicuro, non viene mostrato una seconda volta

6 Copi subito il token mostrato e lo conservi in un luogo sicuro, non viene mostrato una seconda volta

Il token inizia con apm_, seguito da 64 caratteri, e viene mostrato una sola volta. Nel sistema viene salvato esclusivamente un hash, il token stesso non è più leggibile in seguito. C'è esattamente un token per installazione: se genera un nuovo token, quello precedente perde subito validità.

Il token va inviato a ogni chiamata nell'intestazione della richiesta:

Authorization: Bearer apm_suo-token

Passo 2: verificare la connessione e interrogare i calendari

Con la prima chiamata verifica la connessione e ottiene i numeri dei Suoi calendari appuntamenti.

curl -H "Authorization: Bearer apm_suo-token" \
  https://example.com/api/schedules

Risposta:

{
    "data": [
        { "id": 1, "name": "Sede principale" },
        { "id": 2, "name": "Filiale" }
    ]
}

L'id del calendario desiderato si usa in tutte le altre chiamate come parametro schedule.

Passo 3: interrogare i motivi appuntamento

curl -H "Authorization: Bearer apm_suo-token" \
  "https://example.com/api/reasons?schedule=1"

Risposta:

{
    "data": [
        {
            "id": 1,
            "name": "Colloquio di consulenza",
            "description": "Consulenza standard",
            "duration": 1800
        },
        {
            "id": 2,
            "name": "Appuntamento di controllo",
            "description": "",
            "duration": 900
        }
    ]
}

duration è la durata in secondi (1800 secondi corrispondono a 30 minuti). L'id si usa poi come parametro reason. Se per un calendario non sono configurati motivi appuntamento, data è vuoto.

Passo 4: interrogare i giorni con appuntamenti liberi

curl -H "Authorization: Bearer apm_suo-token" \
  "https://example.com/api/days?schedule=1&reason=1"

Risposta:

{
    "data": ["2026-05-23", "2026-05-24", "2026-05-26"]
}

Vengono restituiti solo i giorni in cui è libero almeno un orario appuntamento. Fin dove arriva l'elenco nel futuro lo determinano le impostazioni del Suo calendario appuntamenti.

Passo 5: interrogare gli orari liberi di un giorno

curl -H "Authorization: Bearer apm_suo-token" \
  "https://example.com/api/slots?schedule=1&reason=1&day=2026-05-23"

Risposta:

{
    "data": [
        "2026-05-23 09:00:00",
        "2026-05-23 09:30:00",
        "2026-05-23 10:00:00"
    ]
}

Gli orari sono orari locali della Sua installazione, il formato è sempre AAAA-MM-GG HH:MM:SS.

Passo 6: interrogare i campi del modulo della prenotazione

Quali campi servono per una prenotazione lo stabilisce Lei stesso nel pianificatore appuntamenti. Interroghi quindi sempre i campi invece di inserirli in modo fisso nel Suo programma. Lo spazio nel parametro slot deve essere codificato come %20.

curl -H "Authorization: Bearer apm_suo-token" \
  "https://example.com/api/forms?schedule=1&reason=1&slot=2026-05-23%2009:00:00"

Risposta:

{
    "data": {
        "first_name": {
            "form_type": "textbox",
            "input_type": "text",
            "label": "Nome",
            "required": true,
            "value": ""
        },
        "last_name": {
            "form_type": "textbox",
            "input_type": "text",
            "label": "Cognome",
            "required": true,
            "value": ""
        },
        "email": {
            "form_type": "textbox",
            "input_type": "email",
            "label": "Indirizzo e-mail",
            "required": false,
            "value": ""
        }
    }
}

Tutti i campi con "required": true devono essere compilati al momento della prenotazione. Il campo password non viene mai restituito dall'API.

Passo 7: prenotare l'appuntamento

La prenotazione è l'unica chiamata con il metodo POST. L'intestazione deve contenere Content-Type: application/json. In submission inserisce i valori relativi ai nomi dei campi del passo 6.

curl -X POST https://example.com/api/bookings \
  -H "Authorization: Bearer apm_suo-token" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": 1,
    "reason": 1,
    "slot": "2026-05-23 09:00:00",
    "submission": {
        "first_name": "Hans",
        "last_name": "Pitt",
        "email": "hans.pitt@example.com"
    }
  }'

Risposta in caso di successo (stato 201):

{
    "booking_id": 142,
    "booking_details_id": "a3f8c2d1e5b6",
    "user_id": 87,
    "slot": "2026-05-23T09:00:00Z"
}

L'appuntamento è così registrato nel pianificatore appuntamenti. Le e-mail di notifica vengono inviate come per ogni altra prenotazione.

Messaggi di errore

Anche gli errori vengono restituiti come JSON, per esempio {"error":"Unauthorized"}.

Note

Torna alla panoramica: Modulo "API (interfaccia)".

Su