Riferimento REST-API

Tutte le chiamate con parametri, codici di stato e schemi.

Questa pagina descrive l'interfaccia in modo completo. Se configura l'API per la prima volta, è meglio iniziare dalla guida passo dopo passo.

L'indirizzo di base è /api sulla Sua installazione, negli esempi quindi https://example.com/api. Tutte le chiamate avvengono dal Suo server, non dal browser dei Suoi clienti: non vengono inviate intestazioni CORS e il token non deve essere inserito in un sito web o in una app.

In questa pagina

Autenticazione

Ogni chiamata richiede un token. Lo genera nell'area di amministrazione in Configurazione → API. Il token inizia con apm_, seguito da 64 caratteri, e viene visualizzato una sola volta. Esiste esattamente un token per installazione: un nuovo token invalida immediatamente quello precedente.

Authorization: Bearer apm_suo-token

Senza un token valido ogni chiamata risponde con 401 {"error":"Unauthorized"}. Se l'API non è attivata nell'area di amministrazione, risponde con 503 API disabled.

GET/schedules

Restituisce tutti i calendari appuntamenti dell'installazione. I valori id restituiti si utilizzano in tutte le chiamate successive come parametro schedule.

Codici di stato

StatoSignificato
200 Elenco dei calendari appuntamenti
401 Token mancante o non valido
429 Limite di richieste raggiunto
503 L'API non è attivata oppure l'installazione non è ancora conclusa

Risposta 200

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

Chiamata con curl

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

GET/reasons

Restituisce i motivi appuntamento (prestazioni) di un calendario appuntamenti. Se per il calendario non sono configurati motivi appuntamento, data è un array vuoto. duration è la durata in secondi.

Parametri query

NomeTipoObbligatorioDescrizioneEsempio
schedule integer ≥ 1 obbligatorio Numero del calendario appuntamenti da GET /schedules 1

Codici di stato

StatoSignificato
200 Elenco dei motivi appuntamento (può essere vuoto)
401 Token mancante o non valido
404 Calendario appuntamenti non trovato
429 Limite di richieste raggiunto
503 L'API non è attivata oppure l'installazione non è ancora conclusa

Risposta 200

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

Chiamata con curl

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

GET/days

Restituisce i giorni nei quali per questo calendario appuntamenti e questo motivo appuntamento è libero almeno un orario. Il formato è AAAA-MM-GG. Quanto lontano nel futuro arrivi l'elenco dipende dalle impostazioni del calendario appuntamenti.

Parametri query

NomeTipoObbligatorioDescrizioneEsempio
schedule integer ≥ 1 obbligatorio Numero del calendario appuntamenti 1
reason integer ≥ 1 obbligatorio Numero del motivo appuntamento da GET /reasons 1

Codici di stato

StatoSignificato
200 Elenco dei giorni con appuntamenti liberi
401 Token mancante o non valido
404 Calendario appuntamenti o motivo appuntamento non trovato
429 Limite di richieste raggiunto
503 L'API non è attivata oppure l'installazione non è ancora conclusa

Risposta 200

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

Chiamata con curl

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

GET/slots

Restituisce gli orari liberi di un giorno. Gli orari sono espressi nell'ora locale dell'installazione, il formato è AAAA-MM-GG HH:MM:SS. Se in quel giorno non è più libero nulla, data è un array vuoto.

Parametri query

NomeTipoObbligatorioDescrizioneEsempio
schedule integer ≥ 1 obbligatorio Numero del calendario appuntamenti 1
reason integer ≥ 1 obbligatorio Numero del motivo appuntamento 1
day string obbligatorio Giorno nel formato AAAA-MM-GG da GET /days 2026-05-23

Codici di stato

StatoSignificato
200 Elenco degli orari liberi (può essere vuoto)
401 Token mancante o non valido
404 Calendario appuntamenti, motivo appuntamento o giorno non trovato
429 Limite di richieste raggiunto
503 L'API non è attivata oppure l'installazione non è ancora conclusa

Risposta 200

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

Chiamata con curl

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

GET/forms

Restituisce i campi del modulo che devono essere compilati per la prenotazione di questo orario. I nomi dei campi si utilizzano come chiavi nell'oggetto submission di POST /bookings. Interroghi sempre i campi, invece di inserirli in modo fisso nel Suo programma. Per l'appellativo title (form_type select), value contiene le opzioni disponibili; nella prenotazione invii il value dell'opzione scelta. Il campo password non viene mai restituito.

Parametri query

NomeTipoObbligatorioDescrizioneEsempio
schedule integer ≥ 1 obbligatorio Numero del calendario appuntamenti 1
reason integer ≥ 1 obbligatorio Numero del motivo appuntamento 1
slot string obbligatorio Orario nel formato AAAA-MM-GG HH:MM:SS. Lo spazio deve essere codificato come %20. 2026-05-23%2009:00:00

Codici di stato

StatoSignificato
200 Campi del modulo, indicizzati per nome del campo
401 Token mancante o non valido
404 Calendario appuntamenti, motivo appuntamento o orario non trovato
429 Limite di richieste raggiunto
503 L'API non è attivata oppure l'installazione non è ancora conclusa

Risposta 200

{
    "data": {
        "title": {
            "form_type": "select",
            "input_type": "text",
            "label": "Appellativo",
            "required": false,
            "value": [
                { "label": "Sig.", "value": "title_mr", "selected": false },
                { "label": "Sig.ra", "value": "title_mrs", "selected": false },
                { "label": "Diverso", "value": "title_diverse", "selected": false }
            ]
        },
        "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": ""
        },
        "phone": {
            "form_type": "textbox",
            "input_type": "tel",
            "label": "Telefono",
            "required": false,
            "value": ""
        }
    }
}

Chiamata con curl

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

POST/bookings

Crea un appuntamento. Interroghi prima i campi del modulo tramite GET /forms e invii i relativi valori nell'oggetto submission. L'API accetta sempre il campo phone, anche se il modulo di prenotazione non contiene un campo telefono. L'intestazione deve contenere Content-Type: application/json.

Campi nel request body

NomeTipoObbligatorioDescrizioneEsempio
schedule integer ≥ 1 obbligatorio Numero del calendario appuntamenti 1
reason integer ≥ 1 obbligatorio Numero del motivo appuntamento 1
slot string obbligatorio Orario nel formato AAAA-MM-GG HH:MM:SS, esattamente 19 caratteri 2026-05-23 09:00:00
submission object obbligatorio Valori per i nomi dei campi da GET /forms
submission.phone string, max. 32 caratteri opzionale Numero di telefono di chi chiama, per esempio il numero trasmesso a un assistente telefonico, preferibilmente nel formato E.164. Sono ammessi cifre, spazi e + - ( ) / . da 3 a 20 cifre. Se il numero è nascosto, ometta il campo o invii un testo vuoto. +491701234567
submission.title string opzionale Appellativo: title_mr, title_mrs, title_diverse o un testo vuoto. Obbligatorio solo se GET /forms contrassegna il campo come required. title_mr

Request Body

{
    "schedule": 1,
    "reason": 1,
    "slot": "2026-05-23 09:00:00",
    "submission": {
        "title": "title_mr",
        "first_name": "Hans",
        "last_name": "Pitt",
        "email": "hans.pitt@example.com",
        "phone": "+491701234567"
    }
}

Codici di stato

StatoSignificato
201 L'appuntamento è stato creato
400 Richiesta non valida, campo obbligatorio mancante, numero di telefono non valido, appellativo non valido o JSON non valido
401 Token mancante o non valido
404 Calendario appuntamenti, motivo appuntamento o orario non trovato
415 Content-Type: application/json mancante
429 Limite di richieste raggiunto
500 Non è stato possibile salvare il record del cliente o l'appuntamento
503 L'API non è attivata oppure l'installazione non è ancora conclusa

Risposta 201

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

Risposta 400 in caso di campo obbligatorio mancante

{
    "error": "Field is required",
    "field": "email"
}

Chiamata con curl

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

Schemi

Le strutture di dati che compaiono nelle risposte.

Schedule

{
    "id": integer,
    "name": string
}

Reason

{
    "id": integer,
    "name": string,
    "description": string,
    "duration": integer   // secondi
}

FormField

{
    "form_type": string,
    "input_type": string,
    "label": string,
    "required": boolean,
    "value": any   // per select: elenco delle opzioni
}

BookingRequest

{
    "schedule": integer,
    "reason": integer,
    "slot": "AAAA-MM-GG HH:MM:SS",
    "submission": {
        "<nomecampo>": <valore>,
        "phone": string,   // opzionale, max. 32 caratteri
        "title": string    // opzionale: title_mr, title_mrs, title_diverse
    }
}

BookingResponse

{
    "booking_id": integer,
    "booking_details_id": string,
    "user_id": integer,
    "slot": "2026-05-23T09:00:00Z"   // UTC, ISO 8601
}

Error / BookingError

{
    "error": string,
    "field": string   // opzionale
}

Risposte di errore comuni

Queste risposte possono presentarsi in tutte le chiamate.

StatoSignificatoSpiegazione
401 Unauthorized Il token manca, è errato oppure è stato sostituito da uno nuovo. Alcuni server rimuovono l'intestazione Authorization; in caso di dubbio chieda al Suo provider.
404 Not Found Il calendario appuntamenti, il motivo appuntamento, il giorno o l'orario richiesto non è (più) disponibile. Anche un parametro mancante o formattato in modo errato genera 404, non 400.
429 Too Many Requests Il limite di 300 richieste al minuto per token è stato raggiunto. L'intestazione Retry-After indica il tempo di attesa in secondi.
503 Service Unavailable L'API non è attivata nell'area di amministrazione (API disabled) oppure l'installazione non è ancora conclusa (Not configured). Entrambi i casi riguardano tutte le chiamate.

Gli errori vengono sempre restituiti come JSON e hanno sempre la stessa forma:

{ "error": "Descrizione dell'errore" }

Nella prenotazione un errore di validazione indica inoltre il campo interessato:

{ "error": "Field is required", "field": "email" }

Se il numero di telefono o l'appellativo non è valido, field contiene rispettivamente il valore phone o title.

L'elenco completo dei testi di errore per ogni chiamata lo trova nella guida.

Descrizione leggibile dalla macchina

Tutte le chiamate sono descritte anche come file OpenAPI secondo la versione 3.1. In questo modo può generare librerie client oppure caricare l'interfaccia in strumenti come Postman, Insomnia o Swagger UI.

Visualizza openapi.json

Nel file, sotto servers, è indicato l'indirizzo /api. Si tratta volutamente di un'indicazione relativa, affinché il file sia valido su ogni installazione. Nel Suo strumento inserisca quindi l'indirizzo della Sua agenda appuntamenti, ad esempio https://example.com/api. Lo stesso file si trova anche nella Sua installazione in /api/openapi.json.

Torni alla guida oppure alla panoramica: modulo "API (interfaccia)".

Su