Scadenzario API REST: script, n8n e Make sulle tue scadenze

La base

Cos'è l'API di Scadenzario

Un'interfaccia HTTP JSON su https://www.scadenzario.app/api/v1 per gestire le scadenze personali: leggerle, crearle, modificarle, completarle, segnarle come pagate ed eliminarle. È pensata per programmi, non per browser: non imposta CORS, quindi il token non deve stare in una pagina web.

Pagata e completata restano distinte.

Pagare non completa e completare non paga. Pagare una rata di una ricorrente non chiude la serie; completare o spostare una ricorrente si fa solo dall'app.

Autenticazione

Una sola chiave per API e MCP

1
Apri Impostazioni in Scadenzario.
2
Apri Analizza con AI.
3
Scegli Chiave di accesso API e MCP.
4
Tocca Genera e copiala subito: viene mostrata una volta sola.

Ogni richiesta porta l'header Authorization: Bearer <chiave>. Mai la chiave nell'URL: finirebbe nei log.

Verifica la chiavecurl -H "Authorization: Bearer $SCADENZARIO_TOKEN" https://www.scadenzario.app/api/v1/me

Riferimento

Endpoint

Tutti gli esempi usano $SCADENZARIO_TOKEN come variabile d'ambiente con la chiave.

Leggere le scadenze

curl -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  "https://www.scadenzario.app/api/v1/deadlines?status=active&limit=50"

Filtri: status=active|completed|all, from, to, q, label_id (ripetibile, OR), paid, recurring, overdue. Risposta paginata: {data, next_cursor, truncated}.

curl -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  "https://www.scadenzario.app/api/v1/deadlines/abc123"

Creare una scadenza

curl -X POST -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bollo-2026" \
  -d '{ "title": "Bollo auto", "due_at": "2026-11-15", "amount": 120.50, "transaction_type": "expense" }' \
  https://www.scadenzario.app/api/v1/deadlines

Risposta 201 con header Location. Ripetere la stessa richiesta con la stessa Idempotency-Key restituisce la scadenza originale, senza duplicati.

curl -X POST -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "deadlines": [ {"title": "Bollo", "due_at": "2026-11-15"}, {"title": "Assicurazione", "due_at": "2026-12-01"} ] }' \
  https://www.scadenzario.app/api/v1/deadlines/batch

Fino a 20 scadenze per chiamata; la risposta elenca created e failed.

Modificare una scadenza

curl -X PATCH -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Bollo auto 2026", "amount": 125.00 }' \
  https://www.scadenzario.app/api/v1/deadlines/abc123

Sulle ricorrenti solo i metadati (titolo, note, importo, pagamento, etichette): la data si sposta dall'app.

Completare e riaprire

curl -X POST -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  https://www.scadenzario.app/api/v1/deadlines/abc123/complete

curl -X POST -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  https://www.scadenzario.app/api/v1/deadlines/abc123/reopen

Solo scadenze singole, mai ricorrenti. Riaprire ricontrolla la quota del piano.

Pagare senza completare

curl -X POST -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "paid_at": "2026-10-10T10:00:00Z", "amount": 120.50 }' \
  https://www.scadenzario.app/api/v1/deadlines/abc123/pay

curl -X POST -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  https://www.scadenzario.app/api/v1/deadlines/abc123/unpay

Vale anche sulle ricorrenti: pagare una rata non chiude la serie. Le scadenze pagate smettono di inviare promemoria email.

Eliminare una scadenza

curl -X DELETE -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  https://www.scadenzario.app/api/v1/deadlines/abc123

Risposta 204. Scrive il tombstone di sincronizzazione: sparisce da tutti i dispositivi. Su una ricorrente termina la serie.

Etichette e riepilogo

curl -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  https://www.scadenzario.app/api/v1/labels

curl -X POST -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Auto" }' \
  https://www.scadenzario.app/api/v1/labels

curl -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  https://www.scadenzario.app/api/v1/summary

/summary risponde con scadenze scadute, prossimi 7 e 30 giorni e totale non pagato: la domanda "quanto devo pagare questo mese?".

Liste lunghe

Paginazione con cursore

GET /deadlines restituisce al massimo limit elementi (default 50, max 200). Se next_cursor non è nullo, ci sono altre pagine: ripeti la stessa richiesta aggiungendo&cursor=.... Se truncated è vero, la scansione ha toccato il suo tetto interno: continua con next_cursor per non perdere elementi.

curl -H "Authorization: Bearer $SCADENZARIO_TOKEN" \
  "https://www.scadenzario.app/api/v1/deadlines?limit=200&cursor=eyJkdWVBdE1pbGxpcyI6MTc5MjAwMDAwMDAwMCwiaWQiOiJhYmMifQ"

Diagnostica

Errori

Corpo sempre {error: {code, message}}. Dettagli completi in openapi.json.

401 unauthenticated

Chiave mancante o non valida. Include WWW-Authenticate: Bearer.

400 invalid_input

JSON malformato, campo non valido, cursore illeggibile.

404 not_found

ID sconosciuto o già eliminato.

409 unsupported_for_recurring

Operazione vietata sulle ricorrenti: falla dall'app.

409 sync_limit_reached

Quota del piano esaurita, con details: {count, limit}.

429 rate_limited

Troppe richieste, con header Retry-After.

Quote

Limiti

60 richieste al minuto per account, poi 429;
corpo max 256 KB;
quota cloud del piano: 20 scadenze attive nel Free, 5.000 con PRO — applicata dentro ogni scrittura;
solo scadenze personali, niente team in v1;
gli allegati restano nell'app: l'API segnala solo se esistono.

Automazioni

Usarla da n8n e Make

n8n — nodo HTTP Request

1
Aggiungi un nodo HTTP Request, metodo POST, URL https://www.scadenzario.app/api/v1/deadlines.
2
In Authentication scegli Generic Credential Type → HttpHeaderAuth: nome Authorization, valore Bearer <chiave>.
3
Corpo JSON con title e due_at. Aggiungi l'header Idempotency-Key con un ID stabile se il flusso può rieseguire.

Make — modulo HTTP

1
Aggiungi il modulo HTTP → Make a request, metodo POST, URL https://www.scadenzario.app/api/v1/deadlines.
2
Negli Headers aggiungi Authorization: Bearer <chiave> e Content-Type: application/json.
3
Corpo con title e due_at in formato ISO.

Ricetta

Crea una scadenza da un nuovo record di un foglio

Esempio tipico: un Foglio Google raccoglie fatture da pagare. In n8n il triggerGoogle Sheets Trigger → Row Added alimenta un nodo HTTP Request versoPOST /deadlines con corpo costruito dalle colonne:

{
  "title": "Fattura {{ $json.Fornitore - {$json.Numero} }}",
  "due_at": "{{ $json.Scadenza }}",
  "amount": "{{ $json.Importo }}",
  "transaction_type": "expense",
  "client_request_id": "foglio-fatture-{{ $json.ID }}"
}

client_request_id stabile sull'ID riga rende il flusso rieseguibile senza duplicati. Per sincronizzazioni permanenti bidirezionali servirà l'upsert con ID esterno (dopo la v1).

FAQ

Domande frequenti

Serve PRO per usare l’API?

No. Vale la stessa regola dell’MCP: l’API è disponibile su ogni piano entro la quota cloud (20 scadenze attive nel Free, 5.000 con PRO). PRO resta conveniente per la quota, i team e le funzioni future.

API o MCP, cosa scelgo?

MCP se il lavoro lo fa un assistente AI (Claude, Codex, Cursor). API se il lavoro lo fa un programma: script, n8n, Make, gestionali. Stesso token, stesse operazioni, stessa quota.

Posso leggere o modificare le scadenze dei team?

No: la v1 copre solo le scadenze personali. Le scadenze condivise nei team restano fuori finché un cliente Business non le usa via API.

Perché non posso completare una ricorrente?

Completarla crea anche l’occorrenza successiva con le regole dell’app (fine serie, giorni del mese, date personalizzate). Portare quel flusso sul server senza divergenze richiede un lavoro dedicato: è previsto come v1.1, solo se gli utenti dell’API lo chiedono. Pagare una rata invece si può già fare.

Come evito duplicati sincronizzando un gestionale?

Oggi con l’header Idempotency-Key sui retry della stessa richiesta. Un collegamento permanente con ID esterno (upsert) è previsto dopo la v1, al primo gestionale da sincronizzare davvero.

Dove vedo le scadenze create via API?

Nell’app con la normale sincronizzazione: arrivano sul telefono e programmano le notifiche come quelle create a mano.

Preferisci l'assistente AI?

Stessa chiave, protocollo MCP per Claude e Codex.

La guida MCP spiega il collegamento agli assistenti.

Guida MCP

Le tue scadenze, dentro i tuoi flussi

Cos'è l'API di Scadenzario

Una sola chiave per API e MCP

Endpoint

Leggere le scadenze

Creare una scadenza

Modificare una scadenza

Completare e riaprire

Pagare senza completare

Eliminare una scadenza

Etichette e riepilogo

Paginazione con cursore

Errori

Limiti

Usarla da n8n e Make

n8n — nodo HTTP Request

Make — modulo HTTP

Crea una scadenza da un nuovo record di un foglio

Domande frequenti

Stessa chiave, protocollo MCP per Claude e Codex.