Riferimento

 

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_ihr-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": "Hauptstandort" },
        { "id": 2, "name": "Filiale" }
    ]
}

Chiamata con curl

curl -H "Authorization: Bearer apm_ihr-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": "Beratungsgespräch",
            "description": "Standardberatung",
            "duration": 1800
        },
        {
            "id": 2,
            "name": "Folgetermin",
            "description": "",
            "duration": 900
        }
    ]
}

Chiamata con curl

curl -H "Authorization: Bearer apm_ihr-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_ihr-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_ihr-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. 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": {
        "first_name": {
            "form_type": "textbox",
            "input_type": "text",
            "label": "Vorname",
            "required": true,
            "value": ""
        },
        "last_name": {
            "form_type": "textbox",
            "input_type": "text",
            "label": "Nachname",
            "required": true,
            "value": ""
        },
        "email": {
            "form_type": "textbox",
            "input_type": "email",
            "label": "E-Mail-Adresse",
            "required": false,
            "value": ""
        },
        "phone": {
            "form_type": "textbox",
            "input_type": "tel",
            "label": "Telefonnummer",
            "required": false,
            "value": ""
        }
    }
}

Chiamata con curl

curl -H "Authorization: Bearer apm_ihr-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'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

Request Body

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

Codici di stato

StatoSignificato
201 L'appuntamento è stato creato
400 Richiesta non valida, campo obbligatorio mancante 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_ihr-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
}

BookingRequest

{
    "schedule": integer,
    "reason": integer,
    "slot": "AAAA-MM-GG HH:MM:SS",
    "submission": {
        "<nomecampo>": <valore>
    }
}

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

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