Reneva
IT EN Accedi

API

Chiavi per l'API REST di Reneva e registro delle chiamate, nella pagina Sviluppatori.

Sviluppatori è una pagina sola, senza tab. In alto trovi le chiavi per l'API REST di Reneva (/api/v1) condivise fra tutte le aziende; sotto, i webhook. In fondo trovi Registro API e Registro Webhook.

Chiavi API

Con Nuova chiave scegli un nome, i permessi di lettura e scrittura per ogni sezione e una scadenza (1, 3, 6, 12 mesi o "Non scade"). Le sezioni sono le stesse dei ruoli: Canoni, Progetti cliente, Clienti, Spese e fornitori, Documenti e registri, Listino e le altre. Ogni chiave ha un tetto fisso di chiamate al minuto.

Con Connessione MCP la stessa chiave serve anche agli assistenti AI collegati all'endpoint MCP della tab AI: l'assistente legge solo le liste delle sezioni con Lettura spuntata. Da solo quel permesso non apre le rotte qui sotto.

Copia la chiave appena la crei: Reneva non la mostra di nuovo. Il prefisso visibile in tabella serve solo a riconoscerla, non basta per accedere.

Ogni chiave vale per tutte le aziende permesse a chi l'ha creata e lavora con i suoi permessi attuali: uno scopo può solo restringere quello che l'utente può già fare, mai allargarlo. Lo stato di una chiave è uno tra Attiva, Spenta (dall'interruttore in elenco), Revocata o Chiave scaduta: le ultime due non si riaccendono.

Con Modifica cambi nome e permessi. Con Revoca la chiudi subito: una chiave revocata smette di funzionare e non si riattiva, resta solo nella tabella e nel registro come storico.

Rotte e scopi

Ogni richiesta porta la chiave come Bearer: Authorization: Bearer <prefisso>.<segreto>.

Indica l’azienda con il parametro company (id o codice), nella query o nel corpo JSON. Se l’utente può accedere a più aziende e il parametro manca, la richiesta viene rifiutata; con una sola azienda permessa, viene usata quella. Cambiare azienda nel pannello non cambia una richiesta API. Gli strumenti MCP con chiave richiedono l’azienda esplicita; i dati restano separati per azienda.

Uno scopo è la sezione più l'azione: renewals:read per leggere i canoni, renewals:write per scriverli. La sezione è quella dei ruoli: spot_jobs per i progetti cliente, expenses per spese e fornitori, documents per documenti e registri. Una chiave creata prima del 15/10 con i permessi Movimenti o Fornitori va riaperta con Modifica e salvata con le spunte nuove.

Letture

GET /api/v1/lists elenca le liste che la chiave può leggere. GET /api/v1/lists/{lista} legge una lista come la vedi nel pannello: stessi filtri di partenza, stesse colonne, stessi totali. Parametri, tutti facoltativi: search, from e to (date AAAA-MM-GG sulla data della lista), filters[nome]=valore, tab, columns[], group_by, sort, sort_direction e limit (fino a 50 righe).

La risposta porta count, totals (i totali della vista, già calcolati), rows in CSV e truncated quando le righe sono più del limite. La prima chiamata senza filtri dice anche filtri, colonne e schede disponibili.

Scritture

Sezione Scopo Percorso Metodi
Clienti clients:write /api/v1/clients POST, PATCH /{id}, POST /{id}/notes
Canoni renewals:write /api/v1/renewals POST, PATCH /{id}
Progetti cliente spot_jobs:write /api/v1/jobs POST, PATCH /{id}
Spese expenses:write /api/v1/expenses POST
Fornitori expenses:write /api/v1/suppliers POST, PATCH /{id}
Movimenti documents:write /api/v1/movements POST
Progetti interni internal_projects:write /api/v1/internal_projects POST, PATCH /{id}

[!NOTE] I documenti si leggono e basta. L'API non emette, non annulla e non corregge una fattura: quelli restano gesti dell'app.

Nelle scritture gli importi sono in centesimi e al netto dell'IVA. Su una voce di canone o di progetto cliente il prezzo è quello di una sola unità: il totale della riga lo fa la quantità.

In una modifica items è l'elenco completo delle voci: mandale tutte, anche quelle che non cambiano. Una riga con il suo id aggiorna quella voce e lascia dov'è tutto il resto — sconto, IVA, listino, costo. Una riga senza id è una voce nuova. Le voci che non elenchi vengono eliminate.

Le scritture passano dagli stessi motori del pannello. Se una regola dell'app dice di no — voci di un canone già fatturato, dati di un fornitore che ha già spese — la risposta è un errore con il motivo, non una scrittura di nascosto.

Esempi

L'elenco dei clienti:

curl -H "Authorization: Bearer <prefisso>.<segreto>" \
     -H "Accept: application/json" \
     "https://tuo-dominio/api/v1/lists/clients?company=GMK"

Un canone nuovo:

curl -X POST https://tuo-dominio/api/v1/renewals?company=GMK \
     -H "Authorization: Bearer <prefisso>.<segreto>" \
     -H "Content-Type: application/json" \
     -d '{"client_id":12,"title":"Hosting annuale","interval_months":12,"next_due_date":"2026-12-31","items":[{"description":"Hosting","amount_cents":12000,"category_id":3}]}'

Un progetto cliente da aggiornare:

curl -X PATCH https://tuo-dominio/api/v1/jobs/7?company=GMK \
     -H "Authorization: Bearer <prefisso>.<segreto>" \
     -H "Content-Type: application/json" \
     -d '{"title":"Restyling sito 2026","due_date":"2026-11-30"}'

Limiti

Ogni chiave può fare 60 chiamate al minuto, cioè una al secondo. Prima dell'autenticazione vale anche un tetto per indirizzo IP: 300 chiamate al minuto.

Oltre il tetto la risposta è 429. Porta l'intestazione Retry-After con i secondi da aspettare prima di riprovare.

Su ogni risposta trovi due intestazioni: X-RateLimit-Limit è il tetto, X-RateLimit-Remaining dice quante chiamate restano in questo minuto.

Ogni chiamata resta nel registro qui sotto, riuscita o fallita, con il suo stato e — se è fallita — il motivo in una parola.

Registro API

In fondo a Sviluppatori, dopo chiavi e webhook, il Registro API mostra le ultime richieste di tutte le aziende, con l’azienda, l’esito e la durata; una chiamata rifiutata (troppe chiamate, scopo mancante, chiave scaduta…) porta anche il motivo accanto al codice. Il registro non mostra mai la chiave né il corpo della richiesta. Le chiamate storiche senza azienda registrata mostrano un trattino, senza attribuzioni presunte.

Vedi anche