Agenda

Calendari e appuntamenti.

9 endpoint Versione v1 · revisione 2026-07-20

Gli endpoint sono relativi a https://api.officina.it e richiedono l'header Authorization: Bearer con la chiave API e X-API-Version: 2026-07-20. L'header della revisione è obbligatorio: differenza fra v1 e revisione.

GET /v1/calendar-entries
Permesso richiesto calendar.read

Elenca gli appuntamenti

Gli appuntamenti in agenda. Filtra per intervallo con from / to, per calendario con calendar_id e per collaboratore con user_id. Ogni voce include cliente, veicolo e calendario già risolti, senza chiamate aggiuntive.
Risposte
200
Gli appuntamenti nell'intervallo richiesto.
401
Chiave API mancante, non valida, revocata o scaduta.
402
Il piano non include l'accesso API, oppure non è attivo un abbonamento.
403
La chiave non ha il permesso richiesto per questa operazione.
415
Il Content-Type deve essere application/json e Accept deve accettare JSON.
422
Un campo della richiesta manca o non è valido: «param» indica quale.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl https://api.officina.it/v1/calendar-entries \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "calendar_entry",
      "id": "c72e9a41-8b35-4d07-9e62-1f4a8c3d5b90",
      "title": "Tagliando Fiat Panda",
      "description": "Cliente lascia l'auto alle 8:30.",
      "start_time": "2026-08-12T08:30:00Z",
      "end_time": "2026-08-12T10:00:00Z",
      "color": "#2563eb",
      "calendar_id": "a18f3c65-2d90-4b47-8e13-6c9b2f5a7d04",
      "user_id": "4e7b1d29-5a63-40c8-9f15-2b8d6e3a1c74",
      "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
      "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
      "worksheet_id": "a5d21e64-8f37-4b90-ae12-3c7d6b048f95",
      "quote_id": null,
      "checkin_id": null,
      "work_category_id": "3a8e5c21-9d76-4f03-b418-2c6a9e7d5b40",
      "work_category_name": "Tagliando",
      "email_reminder": false,
      "auto_reminder_enabled": false,
      "auto_reminder_channel": null,
      "auto_reminder_sent_at": null,
      "customer": {
        "object": "customer",
        "id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
        "full_name": "Mario Rossi"
      },
      "vehicle": {
        "object": "vehicle",
        "id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
        "model": "Panda",
        "license": "AB123CD"
      },
      "calendar": {
        "object": "calendar",
        "id": "a18f3c65-2d90-4b47-8e13-6c9b2f5a7d04",
        "name": "Officina 1"
      },
      "user": {
        "object": "user",
        "id": "4e7b1d29-5a63-40c8-9f15-2b8d6e3a1c74",
        "name": "Luca Bianchi"
      },
      "deleted_at": null,
      "created_at": "2026-08-01T09:00:00Z",
      "updated_at": "2026-08-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "url": "/v1/calendar-entries"
}
POST /v1/calendar-entries
Permesso richiesto calendar.write

Crea un appuntamento

Fissa un appuntamento. Servono start_time e end_time in RFC 3339; collega il lavoro con customer_id, vehicle_id, worksheet_id o quote_id. I promemoria automatici via SMS o WhatsApp non sono disponibili via API: inviano messaggi ai tuoi clienti e consumano crediti, quindi una richiesta con auto_reminder_enabled: true e un canale a pagamento viene rifiutata con 403. Il canale email resta ammesso perché usa il tuo mittente e non costa crediti.
Risposte
201
L'appuntamento creato.
400
Corpo della richiesta non leggibile o JSON non valido.
401
Chiave API mancante, non valida, revocata o scaduta.
402
Il piano non include l'accesso API, oppure non è attivo un abbonamento.
403
La chiave non ha il permesso richiesto per questa operazione.
415
Il Content-Type deve essere application/json e Accept deve accettare JSON.
422
Un campo della richiesta manca o non è valido: «param» indica quale.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl -X POST https://api.officina.it/v1/calendar-entries \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Tagliando Fiat Panda",
  "description": "Cambio olio + filtri.",
  "start_time": "2026-06-12T08:00:00Z",
  "end_time": "2026-06-12T10:00:00Z",
  "color": "#2563eb",
  "customer_id": "11111111-1111-1111-1111-111111111111",
  "vehicle_id": "22222222-2222-2222-2222-222222222222",
  "email_reminder": true
}'
Risposta
{
  "object": "calendar_entry",
  "id": "c72e9a41-8b35-4d07-9e62-1f4a8c3d5b90",
  "title": "Tagliando Fiat Panda",
  "description": "Cliente lascia l'auto alle 8:30.",
  "start_time": "2026-08-12T08:30:00Z",
  "end_time": "2026-08-12T10:00:00Z",
  "color": "#2563eb",
  "calendar_id": "a18f3c65-2d90-4b47-8e13-6c9b2f5a7d04",
  "user_id": "4e7b1d29-5a63-40c8-9f15-2b8d6e3a1c74",
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
  "worksheet_id": "a5d21e64-8f37-4b90-ae12-3c7d6b048f95",
  "quote_id": null,
  "checkin_id": null,
  "work_category_id": "3a8e5c21-9d76-4f03-b418-2c6a9e7d5b40",
  "work_category_name": "Tagliando",
  "email_reminder": false,
  "auto_reminder_enabled": false,
  "auto_reminder_channel": null,
  "auto_reminder_sent_at": null,
  "customer": {
    "object": "customer",
    "id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
    "full_name": "Mario Rossi"
  },
  "vehicle": {
    "object": "vehicle",
    "id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
    "model": "Panda",
    "license": "AB123CD"
  },
  "calendar": {
    "object": "calendar",
    "id": "a18f3c65-2d90-4b47-8e13-6c9b2f5a7d04",
    "name": "Officina 1"
  },
  "user": {
    "object": "user",
    "id": "4e7b1d29-5a63-40c8-9f15-2b8d6e3a1c74",
    "name": "Luca Bianchi"
  },
  "deleted_at": null,
  "created_at": "2026-08-01T09:00:00Z",
  "updated_at": "2026-08-01T09:00:00Z"
}
GET /v1/calendar-entries/{id}
Permesso richiesto calendar.read

Recupera un appuntamento

Restituisce il singolo appuntamento con cliente, veicolo, calendario e collaboratore già risolti.
Risposte
200
L'appuntamento richiesto.
401
Chiave API mancante, non valida, revocata o scaduta.
402
Il piano non include l'accesso API, oppure non è attivo un abbonamento.
403
La chiave non ha il permesso richiesto per questa operazione.
404
La risorsa non esiste, è stata eliminata o non appartiene alla tua officina.
415
Il Content-Type deve essere application/json e Accept deve accettare JSON.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl https://api.officina.it/v1/calendar-entries/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "calendar_entry",
  "id": "c72e9a41-8b35-4d07-9e62-1f4a8c3d5b90",
  "title": "Tagliando Fiat Panda",
  "description": "Cliente lascia l'auto alle 8:30.",
  "start_time": "2026-08-12T08:30:00Z",
  "end_time": "2026-08-12T10:00:00Z",
  "color": "#2563eb",
  "calendar_id": "a18f3c65-2d90-4b47-8e13-6c9b2f5a7d04",
  "user_id": "4e7b1d29-5a63-40c8-9f15-2b8d6e3a1c74",
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
  "worksheet_id": "a5d21e64-8f37-4b90-ae12-3c7d6b048f95",
  "quote_id": null,
  "checkin_id": null,
  "work_category_id": "3a8e5c21-9d76-4f03-b418-2c6a9e7d5b40",
  "work_category_name": "Tagliando",
  "email_reminder": false,
  "auto_reminder_enabled": false,
  "auto_reminder_channel": null,
  "auto_reminder_sent_at": null,
  "customer": {
    "object": "customer",
    "id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
    "full_name": "Mario Rossi"
  },
  "vehicle": {
    "object": "vehicle",
    "id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
    "model": "Panda",
    "license": "AB123CD"
  },
  "calendar": {
    "object": "calendar",
    "id": "a18f3c65-2d90-4b47-8e13-6c9b2f5a7d04",
    "name": "Officina 1"
  },
  "user": {
    "object": "user",
    "id": "4e7b1d29-5a63-40c8-9f15-2b8d6e3a1c74",
    "name": "Luca Bianchi"
  },
  "deleted_at": null,
  "created_at": "2026-08-01T09:00:00Z",
  "updated_at": "2026-08-01T09:00:00Z"
}
PATCH /v1/calendar-entries/{id}
Permesso richiesto calendar.write

Aggiorna un appuntamento

Aggiorna solo i campi presenti nel corpo: gli altri restano invariati. Valgono gli stessi limiti sui promemoria a pagamento della creazione. In più, un appuntamento che ha già un promemoria automatico attivo non è modificabile via API: la modifica potrebbe far partire un nuovo messaggio al cliente, quindi la richiesta risponde 403 e va fatta dall'app.
Risposte
200
L'appuntamento aggiornato.
400
Corpo della richiesta non leggibile o JSON non valido.
401
Chiave API mancante, non valida, revocata o scaduta.
402
Il piano non include l'accesso API, oppure non è attivo un abbonamento.
403
La chiave non ha il permesso richiesto per questa operazione.
404
La risorsa non esiste, è stata eliminata o non appartiene alla tua officina.
415
Il Content-Type deve essere application/json e Accept deve accettare JSON.
422
Un campo della richiesta manca o non è valido: «param» indica quale.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl -X PATCH https://api.officina.it/v1/calendar-entries/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Tagliando Fiat Panda — riprogrammato",
  "start_time": "2026-06-13T09:00:00Z",
  "end_time": "2026-06-13T11:00:00Z",
  "description": null
}'
Risposta
{
  "object": "calendar_entry",
  "id": "c72e9a41-8b35-4d07-9e62-1f4a8c3d5b90",
  "title": "Tagliando Fiat Panda",
  "description": "Cliente lascia l'auto alle 8:30.",
  "start_time": "2026-08-12T08:30:00Z",
  "end_time": "2026-08-12T10:00:00Z",
  "color": "#2563eb",
  "calendar_id": "a18f3c65-2d90-4b47-8e13-6c9b2f5a7d04",
  "user_id": "4e7b1d29-5a63-40c8-9f15-2b8d6e3a1c74",
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
  "worksheet_id": "a5d21e64-8f37-4b90-ae12-3c7d6b048f95",
  "quote_id": null,
  "checkin_id": null,
  "work_category_id": "3a8e5c21-9d76-4f03-b418-2c6a9e7d5b40",
  "work_category_name": "Tagliando",
  "email_reminder": false,
  "auto_reminder_enabled": false,
  "auto_reminder_channel": null,
  "auto_reminder_sent_at": null,
  "customer": {
    "object": "customer",
    "id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
    "full_name": "Mario Rossi"
  },
  "vehicle": {
    "object": "vehicle",
    "id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
    "model": "Panda",
    "license": "AB123CD"
  },
  "calendar": {
    "object": "calendar",
    "id": "a18f3c65-2d90-4b47-8e13-6c9b2f5a7d04",
    "name": "Officina 1"
  },
  "user": {
    "object": "user",
    "id": "4e7b1d29-5a63-40c8-9f15-2b8d6e3a1c74",
    "name": "Luca Bianchi"
  },
  "deleted_at": null,
  "created_at": "2026-08-01T09:00:00Z",
  "updated_at": "2026-08-01T09:00:00Z"
}
DELETE /v1/calendar-entries/{id}
Permesso richiesto calendar.write

Elimina un appuntamento

Eliminazione logica dell'appuntamento.
Risposte
200
L'appuntamento eliminato.
401
Chiave API mancante, non valida, revocata o scaduta.
402
Il piano non include l'accesso API, oppure non è attivo un abbonamento.
403
La chiave non ha il permesso richiesto per questa operazione.
404
La risorsa non esiste, è stata eliminata o non appartiene alla tua officina.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl -X DELETE https://api.officina.it/v1/calendar-entries/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "calendar_entry",
  "id": "c72e9a41-8b35-4d07-9e62-1f4a8c3d5b90",
  "title": "Tagliando Fiat Panda",
  "description": "Cliente lascia l'auto alle 8:30.",
  "start_time": "2026-08-12T08:30:00Z",
  "end_time": "2026-08-12T10:00:00Z",
  "color": "#2563eb",
  "calendar_id": "a18f3c65-2d90-4b47-8e13-6c9b2f5a7d04",
  "user_id": "4e7b1d29-5a63-40c8-9f15-2b8d6e3a1c74",
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
  "worksheet_id": "a5d21e64-8f37-4b90-ae12-3c7d6b048f95",
  "quote_id": null,
  "checkin_id": null,
  "work_category_id": "3a8e5c21-9d76-4f03-b418-2c6a9e7d5b40",
  "work_category_name": "Tagliando",
  "email_reminder": false,
  "auto_reminder_enabled": false,
  "auto_reminder_channel": null,
  "auto_reminder_sent_at": null,
  "customer": {
    "object": "customer",
    "id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
    "full_name": "Mario Rossi"
  },
  "vehicle": {
    "object": "vehicle",
    "id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
    "model": "Panda",
    "license": "AB123CD"
  },
  "calendar": {
    "object": "calendar",
    "id": "a18f3c65-2d90-4b47-8e13-6c9b2f5a7d04",
    "name": "Officina 1"
  },
  "user": {
    "object": "user",
    "id": "4e7b1d29-5a63-40c8-9f15-2b8d6e3a1c74",
    "name": "Luca Bianchi"
  },
  "deleted_at": null,
  "created_at": "2026-08-01T09:00:00Z",
  "updated_at": "2026-08-01T09:00:00Z",
  "deleted_at": "2026-08-05T11:04:00Z"
}
GET /v1/calendars
Permesso richiesto calendar.read

Elenca i calendari

I calendari configurati dall'officina, da usare per valorizzare calendar_id. L'elenco è breve e non paginato.
Risposte
200
I calendari configurati.
401
Chiave API mancante, non valida, revocata o scaduta.
402
Il piano non include l'accesso API, oppure non è attivo un abbonamento.
403
La chiave non ha il permesso richiesto per questa operazione.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl https://api.officina.it/v1/calendars \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "calendar",
      "id": "a18f3c65-2d90-4b47-8e13-6c9b2f5a7d04",
      "name": "Officina 1",
      "default_color": "#2563eb"
    },
    {
      "object": "calendar",
      "id": "6d2b9f14-7c58-4a03-b91e-3f5a8d2c6e47",
      "name": "Carrozzeria",
      "default_color": "#16a34a"
    }
  ],
  "has_more": false,
  "url": "/v1/calendars"
}
POST /v1/calendars
Permesso richiesto calendar.write

Crea un calendario

Crea un calendario. default_color è il colore esadecimale usato in agenda per le voci che non ne specificano uno.
Risposte
201
Il calendario creato.
401
Chiave API mancante, non valida, revocata o scaduta.
402
Il piano non include l'accesso API, oppure non è attivo un abbonamento.
403
La chiave non ha il permesso richiesto per questa operazione.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl -X POST https://api.officina.it/v1/calendars \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Officina 1",
  "default_color": "#2563eb"
}'
Risposta
{
  "object": "calendar",
  "id": "a18f3c65-2d90-4b47-8e13-6c9b2f5a7d04",
  "name": "Officina 1",
  "default_color": "#2563eb"
}
PATCH /v1/calendars/{id}
Permesso richiesto calendar.write

Aggiorna un calendario

Aggiorna nome e colore predefinito del calendario.
Risposte
200
Il calendario aggiornato.
401
Chiave API mancante, non valida, revocata o scaduta.
402
Il piano non include l'accesso API, oppure non è attivo un abbonamento.
403
La chiave non ha il permesso richiesto per questa operazione.
404
La risorsa non esiste, è stata eliminata o non appartiene alla tua officina.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl -X PATCH https://api.officina.it/v1/calendars/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Officina 1",
  "default_color": "#2563eb"
}'
Risposta
{
  "object": "calendar",
  "id": "a18f3c65-2d90-4b47-8e13-6c9b2f5a7d04",
  "name": "Officina 1",
  "default_color": "#2563eb"
}
DELETE /v1/calendars/{id}
Permesso richiesto calendar.write

Elimina un calendario

Elimina il calendario. Gli appuntamenti che vi appartenevano vengono riassegnati a un altro calendario.
Risposte
200
Il calendario eliminato.
401
Chiave API mancante, non valida, revocata o scaduta.
402
Il piano non include l'accesso API, oppure non è attivo un abbonamento.
403
La chiave non ha il permesso richiesto per questa operazione.
404
La risorsa non esiste, è stata eliminata o non appartiene alla tua officina.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl -X DELETE https://api.officina.it/v1/calendars/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "calendar",
  "id": "a18f3c65-2d90-4b47-8e13-6c9b2f5a7d04"
}