# Utilizzare le API delle pratiche per inviare messaggi

## Interazione programmatica con le pratiche

La piattaforma espone endpoint API ReST che consentono di interagire in modo completamente programmatico con le pratiche inviate dai cittadini. In particolare, sono disponibili due risorse principali sotto il percorso `/api/applications`:

***

### Endpoint disponibili

#### Transizione di stato

<mark style="color:green;">`POST`</mark> `https://servizi.comune.bugliano.pi.it/lang/api/applications/{id}/transition/{action}`

Consente di modificare lo stato di una pratica: approvare, rigettare, richiedere integrazioni e qualsiasi altra transizione prevista dal flusso configurato per il servizio.

#### Invio messaggi

<mark style="color:green;">`POST`</mark> `https://servizi.comune.bugliano.pi.it/lang/api/applications/{id}/messages`

Consente di inviare messaggi al cittadino contestualizzati alla singola pratica. I messaggi saranno visibili al cittadino nella propria area personale, all'interno del dettaglio della pratica stessa.

***

### Combinare API e Webhook per l'automazione

Il flusso di una pratica può attraversare diversi stati (per una panoramica completa si veda il capitolo [Integrazioni con il flusso delle pratiche](https://docs.opencityitalia.it/sviluppatori-e-partner-tecnologici/integrazioni/integrazioni-con-il-flusso-delle-pratiche)) e le API permettono di intervenire in ciascuna fase. Tuttavia, come descritto nel capitolo [Webhooks](https://docs.opencityitalia.it/sviluppatori-e-partner-tecnologici/integrazioni/integrazioni-con-il-flusso-delle-pratiche/webhooks), le sole API non sono sufficienti per realizzare un'integrazione completa: è necessario che il sistema esterno venga **notificato** quando avviene un cambiamento.

Combinando **Webhook** e **API** è possibile costruire flussi completamente automatizzati:

1. **Configurazione del webhook** — Dalla piattaforma si configura uno o più webhook che puntano a un endpoint pubblico della vostra infrastruttura. I webhook si attivano sui cambi di stato delle pratiche.
2. **Ricezione dell'evento** — Quando una pratica cambia stato, il vostro endpoint riceve una notifica con il payload dell'evento.
3. **Risposta automatica via API** — In base alla logica applicativa, il vostro sistema può richiamare le API di transizione o di messaggistica per gestire la pratica e comunicare direttamente con il cittadino.

> **Esempio pratico:** è possibile inviare messaggi massivi a tutte le pratiche in un determinato stato (ad esempio tutte quelle approvate) iterando sull'elenco delle pratiche ottenuto via API e richiamando l'endpoint `/messages` per ciascuna.