Riseact – API & Developer Guide

• Guide
• Integrarsi con Riseact
• Entità di Riseact
• Campagne, progetti, forms e checkout
• Forms e checkouts
• Donazioni e pagamenti
• Canali di pubblicazione
• Applicazioni private
• Creare un'applicazione privata
• Utilizzo delle APIs (private apps)
• Applicazioni partner
• Creare un account partner
• Creare un'applicazione partner
• Autenticazione con OAuth
• Utilizzo delle APIs (partner apps)
• Interfaccia utente dell'applicazione
• Webhook di Applicazione
• Webhook di Organizzazione
• Pubblicazione
• API - GraphQL
• Utilizzo delle API GraphQL
• GraphQL - Queries
• GraphQL - Mutations
• GraphQL - Objects
• GraphQL - Enums
• GraphQL - Input objects
• GraphQL - Scalars
• API - REST
• Utilizzo delle API REST
• RiseAct Admin API
• REST - Activity Create
• REST - Campaigns Get
• REST - Campaigns List
• REST - Checkout Create
• REST - Checkouts Get
• REST - Checkouts List
• REST - Donations Get
• REST - Donations List
• REST - Payments Get
• REST - Payments List
• REST - Supporters Create
• REST - Supporters Get
• REST - Supporters List
• REST - Supporters Update
• REST - Supporters Delete
• REST - Webhooks Create
• REST - Webhooks Get
• REST - Webhooks List
• REST - Webhooks Update
• REST - Webhooks Delete
• CLI e SDK
• Panoramica CLI
• Struttura dell'app
• Riseact Totem
• Introduzione a Riseact Totem
• Configurazione di Riseact Totem
• Personalizzazione Riseact Totem

Guide

Integrarsi con Riseact

Riseact offre 2 modi per integrarsi con la piattaforma: tramite applicazioni private o applicazioni partner. Le applicazioni private possono essere installate solo dalla stessa organizzazione che le crea, mentre le applicazioni partner possono essere installate da una o più organizzazioni Riseact. In entrambi i casi, è necessario autenticarsi e ottenere un token di accesso per utilizzare le API di Riseact e accedere ai dati della tua organizzazione. In questa guida, esploreremo cosa sono e quali sono i casi d'uso per le applicazioni private e partner.

Applicazioni partner

Le applicazioni partner possono essere installate da una o più organizzazioni Riseact. Le applicazioni partner possono richiedere l'accesso a risorse e dati delle organizzazioni che le installano. Le applicazioni Partner richiedono un processo di approvazione da parte di Riseact per garantire che rispettino le linee guida e le politiche della piattaforma, devono essere accessibili tramite un URL pubblico per poter garantire l'autenticazione tramite OAuth 2. Segui le indicazioni riportate in questa guida per integrarti con Riseact tramite applicazione partner.

Applicazioni private

Le applicazioni private possono essere installate dalla sola organizzazione che la crea. Le applicazioni private possono richiedere l'accesso a risorse e dati della sola organizzazione che le installa, e utilizzano un sistema di autenticazione a token per accedere ai servizi di Riseact. Segui le indicazioni riportate in questa guida per integrarti con Riseact tramite applicazione privata.

Contenuto importato da https://dev.riseact.org/docs/getting-started il 2026-04-23 durante la migrazione iniziale della KB Metadonors. Aggiornare se il sorgente cambia.

Entità di Riseact

Riseact dispone di diverse entità che consentono di gestire le iniziative di raccolta fondi delle organizzazioni non profit. In questa guida, esploreremo le diverse entità di Riseact e come funzionano.

• Campagne: Le campagne sono le iniziative o progetti specifici all'interno di Riseact. Ogni campagna può essere associata a un form e pubblicata su diversi canali. Per ulteriori dettagli su come funzionano le campagne, puoi consultare la Guida alle Campagne su Riseact.

• Progetti: I progetti sono aggregazioni di campagne correlate. Consentono di organizzare le iniziative e le campagne in modo strutturato. Per una guida più dettagliata sui progetti, puoi consultare la Guida ai Progetti su Riseact.

• Forms: I forms rappresentano la configurazione con cui viene generato un checkout per una campagna specifica. Puoi personalizzare i campi e le opzioni di donazione nel form. Per una guida approfondita sui forms, puoi consultare la Guida ai Forms su Riseact.

• Checkouts: I checkouts sono le pagine in cui i sostenitori possono effettuare donazioni per le campagne. Puoi monitorare lo stato dei checkouts e gestire i pagamenti associati. Per maggiori informazioni sui checkouts, puoi consultare la Guida ai Checkouts su Riseact.

• Canali: I canali rappresentano le diverse piattaforme o applicazioni su cui puoi pubblicare le campagne. Puoi selezionare i canali desiderati per raggiungere il pubblico appropriato. Per una guida completa sui canali, puoi consultare la Guida ai Canali di Pubblicazione su Riseact.

• Donazioni: Le donazioni rappresentano i contributi dei sostenitori all'organizzazione non profit. Puoi gestire le donazioni, distinguendo tra oneoff (unica) e ricorrenti (periodiche). Per una guida dettagliata sulle donazioni, puoi consultare la Guida alle Donazioni su Riseact.

• Pagamenti: I pagamenti sono le transazioni effettive associate alle donazioni. Puoi registrare i pagamenti e associarli alle donazioni corrispondenti. Per una guida completa sui pagamenti, puoi consultare la Guida ai Pagamenti su Riseact.

Contenuto importato da https://dev.riseact.org/docs/guides/entities il 2026-04-23 durante la migrazione iniziale della KB Metadonors. Aggiornare se il sorgente cambia.

Campagne, progetti, forms e checkout

Campagne

Le campagne sono entità che rappresentano iniziative specifiche. Ogni campagna può essere associata ad un solo form e pubblicata su diversi canali. È possibile configurare l'immagine, il titolo, la descrizione e i metadati per la SEO di ogni campagna. Inoltre, è possibile impostare un obiettivo di raccolta fondi per la campagna che verrà mostrato sulla pagina della campagna e aggiornato automaticamente alla chiusura di ogni checkout.

Progetti

I progetti sono aggregazioni di campagne correlate. Consentono di organizzare le iniziative e le relative campagne in modo strutturato. Ogni progetto può includere più campagne.

Forms

I forms sono set di configurazioni per la generazione dei checkouts delle le campagne. Un form definisce le informazioni richieste durante il processo di donazione, come nome, indirizzo e altre informazioni. Ogni campagna può essere associata a un form specifico. Per maggiori informazioni sui forms, consulta la guida Forms.

Checkouts

I checkouts sono pagine generate dalla configurazione di form e campagna in cui i sostenitori possono effettuare donazioni che verranno associate ad una campagna. I checkouts possono avere diversi stati, come bozza, attivo, scaduto, completato o revocato. Le donazioni vengono registrate solo se lo stato del checkout è attivo o completato. I dati del checkout diventano effettivi quando lo stato è completato, e i sostenitori vengono registrati nel sistema solo se non erano già presenti. Per maggiori informazioni sui checkouts, consulta la guida Checkouts.

Contenuto importato da https://dev.riseact.org/docs/guides/campaings-and-forms il 2026-04-23 durante la migrazione iniziale della KB Metadonors. Aggiornare se il sorgente cambia.

Forms e checkouts

Riseact offre funzionalità avanzate per la gestione dei form e dei checkouts, semplificando il processo di fundraising per le organizzazioni. In questa guida, esploreremo come funzionano i form e i checkouts su Riseact.

Form

Un form rappresenta la configurazione con cui viene generato un checkout. Ogni form può essere associato a più campagne, consentendo di utilizzare la stessa configurazione di checkout per diverse iniziative di raccolta fondi. Ogni campagna, a sua volta, può essere associata a un solo form, garantendo una corrispondenza diretta tra campagna e configurazione di checkout. Durante la configurazione del form, puoi prendere decisioni importanti come quali campi mostrare al sostenitore e quali di essi devono essere obbligatori. Inoltre, puoi specificare il tipo di donazione (oneoff o ricorrente) e definire gli importi consentiti, inclusa la possibilità di inserire un importo personalizzato.

Checkout

Il checkout rappresenta la pagina in cui i sostenitori possono effettuare le donazioni. Esso viene generato prendendo informazioni sia dal form che dalla campagna associata. Durante il processo di donazione, il checkout può essere in uno stato "aperto" o "chiuso". Quando un checkout viene completato, avvengono diverse operazioni significative. Viene creata una donazione, che può essere di tipo "oneoff" o "ricorrente", associata alla campagna corrispondente. Viene generato un pagamento, ad esempio tramite carta di credito, se la transazione è immediata. Se il sostenitore non è già registrato nel sistema, viene creato un nuovo profilo di sostenitore. In caso contrario, il pagamento viene associato a un sostenitore esistente. Infine, lo stato del checkout viene aggiornato a "chiuso" e l'importo totale della campagna viene visualizzato sulla relativa pagina, se presente, permettendo di monitorare il progresso verso l'obiettivo di raccolta fondi.

L'utilizzo dei form e dei checkouts su Riseact consente di creare un'esperienza di donazione personalizzata e intuitiva per i sostenitori. Gestendo le configurazioni dei form e monitorando gli stati dei checkouts, è possibile tenere traccia delle donazioni ricevute e visualizzare l'importo totale raggiunto per ciascuna campagna.

Contenuto importato da https://dev.riseact.org/docs/guides/forms-and-checkouts il 2026-04-23 durante la migrazione iniziale della KB Metadonors. Aggiornare se il sorgente cambia.

Donazioni e pagamenti

Su Riseact esistono 2 entita' per la gestione della raccolta fondi, le donazioni e i pagamenti. Ogni pagamento è associato ad una donazione e corrisponde all'effettiva transazione di denaro dal sostenitore all'ente. le donazioni posso essere di 2 tipi: oneoff, e ricorrenti le donazioni oneoff possono essere bozze (promesse), scadute (abbandonate) o completate. In caso di completate il pagamento è associato alla donazione. le donazioni ricorrenti possono essere bozze (promesse), attive o revocate. In caso di ricorrenti attive, i pagamenti verranno associati alla donazione ad ogni transazione, che ricorrerà ogni mese nel giorno di attivazione della donazione. I pagamenti sono creati in automatico (in caso di utilizzo di gateway di pagamento esterni, come Stripe o Paypal) o manualmente (in caso di utilizzo di bonifici bancari o altri metodi di pagamento non automatizzati), e possono essere creati sul pannello di amministrazione o tramite APIs.

Riseact offre due entità principali per la gestione della raccolta fondi delle organizzazioni non profit: le donazioni e i pagamenti. In questa guida, esploreremo come funzionano le donazioni e i pagamenti su Riseact.

Donazioni

Le donazioni rappresentano le promesse o i contributi dei sostenitori all'organizzazione. Le donazioni possono essere di due tipi:

1. Donazioni Oneoff: Le donazioni oneoff sono contributi unici o singoli. Possono trovarsi in uno dei seguenti stati:

   • Bozza: Le donazioni oneoff possono essere create come bozze, rappresentando una promessa di donazione. In questo stato, la donazione non è ancora completata o associata a un pagamento.
   • Scaduta: Se una donazione oneoff viene abbandonata o non completata entro un certo periodo di tempo, assume lo stato di "scaduta". In questo caso, la donazione non viene associata a un pagamento.
   • Completata: Quando una donazione oneoff viene effettivamente completata, viene associata a un pagamento corrispondente. Questo rappresenta l'effettiva transazione di denaro dal sostenitore all'organizzazione non profit.

2. Donazioni Ricorrenti: Le donazioni ricorrenti rappresentano contributi periodici che si ripetono nel tempo. Possono essere in uno dei seguenti stati:

   • Bozza: Le donazioni ricorrenti possono essere create come bozze, indicando una promessa di donazione periodica. In questo stato, la donazione non è ancora attiva o associata a un pagamento.
   • Attiva: Quando una donazione ricorrente è attiva, i pagamenti verranno associati ad essa ad ogni transazione periodica. Questi pagamenti si ripeteranno ogni mese nel giorno di attivazione della donazione.
   • Revocata: Se una donazione ricorrente viene revocata o annullata, assume lo stato di "revocata". In questo caso, i pagamenti futuri non saranno più associati alla donazione.

Pagamenti

I pagamenti su Riseact rappresentano le transazioni effettive di denaro associato a una donazione. I pagamenti possono essere associati a una donazione specifica e rappresentano l'effettiva transazione di denaro dal sostenitore all'organizzazione. Questi possono essere creati automaticamente utilizzando gateway di pagamento esterni come Stripe o Paypal. In questo caso, il pagamento viene creato automaticamente al momento della transazione. In alternativa, i pagamenti possono essere creati manualmente se vengono utilizzati metodi di pagamento non automatizzati, come bonifici bancari o altri mezzi. In questo caso, l'amministratore può creare manualmente il pagamento nel pannello di amministrazione di Riseact o tramite APIs.

Riseact offre un'interfaccia intuitiva per gestire le donazioni e i pagamenti. Grazie alla registrazione e all'associazione dei pagamenti alle donazioni, è possibile tenere traccia delle transazioni finanziarie e monitorare il flusso di denaro delle donazioni all'interno dell'organizzazione.

Contenuto importato da https://dev.riseact.org/docs/guides/donations-and-payments il 2026-04-23 durante la migrazione iniziale della KB Metadonors. Aggiornare se il sorgente cambia.

Canali di pubblicazione

I canali di pubblicazione rappresentano le diverse piattaforme o applicazioni su cui è possibile pubblicare le campagne. Ogni campagna può essere pubblicata su uno o più canali, consentendo una maggiore visibilità e la possibilità di raggiungere diversi tipi di pubblico.

Riseact offre alcuni canali di pubblicazione predefiniti, che sono:

1. Sito Web: Il sito web dell'organizzazione è uno dei canali principali di pubblicazione. Le campagne possono essere visualizzate sul sito web, consentendo ai visitatori di effettuare donazioni direttamente dalla pagina della campagna.

2. Totem: Riseact Kiosk è un'applicazione che funge da totem o chiosco per la raccolta fondi. Le campagne possono essere pubblicate sul Totem, consentendo alle persone di effettuare donazioni tramite l'app Riseact Kiosk.

3. Point of Donation (POD): Riseact POD è un'applicazione mobile che consente alle organizzazioni di raccogliere donazioni direttamente in punti fisici, come eventi o fiere. Le campagne possono essere pubblicate su Riseact POD, offrendo un modo facile per i partecipanti effettuare donazioni.

Oltre ai canali predefiniti, è possibile installare applicazioni esterne che fungono da canali di pubblicazione aggiuntivi. Ogni volta che viene installata un'applicazione esterna, questa verrà visualizzata come un canale di pubblicazione su Riseact. È possibile selezionare se pubblicare una campagna su quella specifica applicazione e raggiungere un pubblico più ampio.

Utilizzo dei Canali di Pubblicazione

Per pubblicare una campagna su un determinato canale, è sufficiente selezionare il canale desiderato durante la configurazione della campagna. Questo consente di scegliere dove la campagna sarà visibile e accessibile al pubblico. Puoi selezionare uno o più canali di pubblicazione per ogni campagna, garantendo una maggiore visibilità e la possibilità di raggiungere diversi tipi di pubblico.

Con l'utilizzo dei canali di pubblicazione su Riseact, puoi promuovere le tue campagne attraverso diverse piattaforme e raggiungere un pubblico più ampio. Questo aumenta le possibilità di coinvolgere sostenitori e ricevere donazioni per le tue iniziative di raccolta fondi.

Contenuto importato da https://dev.riseact.org/docs/guides/channels il 2026-04-23 durante la migrazione iniziale della KB Metadonors. Aggiornare se il sorgente cambia.

Applicazioni private

Creare un'applicazione privata

Per utilizzare le API di Riseact e accedere ai dati della tua organizzazione, è necessario autenticarsi e ottenere un token di accesso. Il token di accesso è un codice univoco che ti permette di accedere ai servizi di Riseact in modo sicuro e controllato. I token di Riseact possono essere configurati per fornire diversi livelli di accesso e autorizzazioni, in base alle tue esigenze. In questa guida, esploreremo come ottenere un token di accesso per utilizzare le API di Riseact.

Richiesta del token

Accedi alla tua organizzazione Riseact, vai alla sezione "Applicazioni", clicca su "Applicazioni private" e poi su "Nuova applicazione privata". Inserisci un nome per la tua applicazione, seleziona i permessi che vuoi fornire ad essa e clicca su "Crea". Una volta creata l'applicazione, verrà generato un token di accesso univoco per la tua organizzazione.

Contenuto importato da https://dev.riseact.org/docs/private-apps/getting-started il 2026-04-23 durante la migrazione iniziale della KB Metadonors. Aggiornare se il sorgente cambia.

Utilizzo delle APIs (private apps)

Riseact offre 2 modi per consumare le APIs: tramite GraphQL o REST. Per utilizzare le APIs GraphQL, puoi inviare una richiesta HTTP POST al server GraphQL di Riseact, specificando il token di accesso come header di autorizzazione.

Authorization: Bearer <YOUR TOKEN>

Contenuto importato da https://dev.riseact.org/docs/private-apps/api-usage il 2026-04-23 durante la migrazione iniziale della KB Metadonors. Aggiornare se il sorgente cambia.

Applicazioni partner

Creare un account partner

Per poter pubblicare le tue applicazioni e temi per le organizzazioni presenti su Riseact, è necessario creare un account Partner. Segui i passaggi di seguito per creare il tuo account Partner:

1. Visita il sito web di Riseact e accedi alla pagina di registrazione tramite il seguente link: https://accounts.riseact.org/signup/.
2. Una volta sulla pagina di registrazione, nella parte superiore destra della pagina, troverai l'icona del tuo avatar. Fai clic sull'icona per aprire il menu a tendina.
3. All'interno del menu a tendina, individua l'opzione "Diventa un partner" e selezionala.
4. Verrà visualizzata una schermata in cui dovrai inserire il nome del tuo profilo partner. Assicurati di scegliere un nome appropriato e rappresentativo.
5. Dopo aver inserito il nome del profilo partner, fai clic su "Attiva il profilo" per completare il processo di creazione dell'account Partner.
6. Una volta completati questi passaggi, avrai creato con successo il tuo account Partner su Riseact. Ora sarai in grado di pubblicare le tue applicazioni e temi per le organizzazioni presenti sulla piattaforma. Assicurati di seguire le linee guida e i requisiti specifici forniti da Riseact per garantire la conformità e la qualità delle tue pubblicazioni.

Contenuto importato da https://dev.riseact.org/docs/partner-apps/getting-started il 2026-04-23 durante la migrazione iniziale della KB Metadonors. Aggiornare se il sorgente cambia.

Creare un'applicazione partner

Per poter interagire con le APIs di Riseact è necessario creare un applicazione. Segui i passaggi descritti in questa pagina per crearne una.

1. Accedi al tuo account Riseact Partner su Riseact.
2. Una volta effettuato l'accesso, troverai un menu laterale. Seleziona "Applicazioni" per accedere alla sezione delle applicazioni.
3. Clicca su "Crea applicazione" per iniziare la creazione della tua nuova applicazione.
4. Ora dovrai inserire alcune informazioni di base sull'applicazione:
   • Nome: Scegli un nome significativo per la tua applicazione.
   • Descrizione: Fornisci una breve descrizione dell'applicazione per spiegare di cosa si tratta.
   • Tipo di distribuzione: Seleziona "public" se desideri che l'applicazione sia disponibile per tutte le organizzazioni. Se preferisci che l'applicazione sia disponibile solo per organizzazioni selezionate, scegli "private".
   • Logo: Puoi scegliere di caricare un logo per l'applicazione. Questo passaggio è facoltativo.
   • URL dell'applicazione: Inserisci l'URL del sito web che verrà incorporato nell'admin di Riseact.
   • Homepage: Inserisci l'URL della homepage del sito di dettaglio dell'applicazione. Assicurati di fornire informazioni dettagliate sull'applicazione per coinvolgere gli utenti. Questo URL verrà mostrato solo nella pagina dell'applicazione nello store.
   • Redirect URL per OAuth: Questo è l'URL di reindirizzamento per il protocollo OAuth. Di solito è qualcosa come "https://url-della-tua-app.it/oauth/callback". Assicurati di inserire l'URL corretto per consentire l'autenticazione tramite OAuth.
5. Una volta completati tutti i campi richiesti, fai clic su "Salva" per salvare le modifiche e creare l'applicazione.

Seguendo questi passaggi, ti verranno forniti un client_id e client_secret che potrai utilizzare per ottenere un Access Token attraverso il processo di OAuth. Per ulteriori informazioni, consulta la prossima pagina Autenticazione con OAuth.

Una volta creata l'applicazione, potrai iniziare a sviluppare e distribuire l'applicazione su Riseact. Per semplicità, ti consigliamo di utilizzare la CLI di Riseact per creare e distribuire l'applicazione. Per maggiori informazioni, consulta la pagina Panoramica della CLI.

Contenuto importato da https://dev.riseact.org/docs/partner-apps/create-application il 2026-04-23 durante la migrazione iniziale della KB Metadonors. Aggiornare se il sorgente cambia.

Autenticazione con OAuth

L'implementazione dell'autenticazione OAuth è essenziale per ottenere un Access Token e poter utilizzare le API. Segui i passaggi di questa guida per comprendere il processo di OAuth e integrarlo correttamente nella tua applicazione.

1. Comprendi il concetto di OAuth: OAuth è un protocollo standard che consente di delegare l'autenticazione di un utente a un servizio terzo in modo sicuro. Il processo coinvolge tre attori principali: il client (la tua applicazione), il server di autorizzazione (Riseact Account) e il server di risorse (Riseact Core, che fornisce accesso alle APIs). OAuth garantisce che il client ottenga un Access Token valido per accedere alle risorse protette dal server a nome dell'organizzazione che installa l'applicazione.

2. Registra la tua applicazione: Prima di implementare l'autenticazione OAuth, è necessario registrare la tua applicazione su Riseact Parnters per ottenere le credenziali necessarie. Queste credenziali includono un Client ID e un Client Secret, che verranno utilizzati per identificare e autenticare la tua applicazione durante il processo di autorizzazione.

3. Configura l'autenticazione nel tuo backend: Nel tuo backend, dovrai implementare la logica per gestire il flusso di autorizzazione OAuth. Ciò comporta la creazione di un endpoint per l'autorizzazione che reindirizzerà l'utente al server di autorizzazione per l'autenticazione. Durante questa fase, dovrai includere il tuo Client ID e generare le chiavi PKCE che verranno utilizzate per scambiare il codice di autorizzazione nella callback e che quindi dovrai temporaneamente salvare. Quando un organizzazione installerà la tua applicazione su Riseact, dal pannello di amministrazione verrà visualizzato un iframe che punta all'url dell'app che hai indicato in fase di registrazione. Insieme all'url che hai fornito, verrà passato un parametro __organization che potrai utilizzare per identificare l'organizzazione che sta utilizzando la tua applicazione e saltare il roundtrip di selezione dell'organizzazione su Riseact Admin. Per farlo, dovrai reindirizzare l'utente al server di autorizzazione con un parametro __organization che contiene lo slug dell'organizzazione che hai ricevuto dal parametro __organization dell'url di reindirizzamento.

Ecco un esempio in node.js:

app.get('/oauth/authorize', (req, res) => {
  const { codeChallenge, codeVerifier } = generatePkceKeys();

  // Salva le chiavi PKCE come preferisci. In questo caso utilizziamo un database
  db.savePkceKey(codeChallenge, codeVerifier);

  const params = {
    client_id: "CLIENT_ID",
    redirect_uri: 'https://your-app.com/oauth/callback',
    response_type: 'code',
    code_challenge_method: 'S256',
    code_challenge: 'YOUR_CODE_CHALLENGE',
    __organization: req.query.__organization,
  };

  res.redirect(`https://accounts.riseact.org/oauth/authorize/?${qs.stringify(params)}`);
});

Esempio della chiamata con curl:

curl -X GET \
  "https://accounts.riseact.org/oauth/authorize/\
?client_id=CLIENT_ID\
&redirect_uri=https://your-app.com/oauth/callback\
&response_type=code\
&code_challenge_method=S256\
&code_challenge=YOUR_CODE_CHALLENGE\
&__organization=YOUR_ORGANIZATION"

4. Gestisci il reindirizzamento di callback: Dopo che l'utente si è autenticato con successo presso il server di autorizzazione, verrà reindirizzato alla tua applicazione tramite un URL di callback specificato nel precedente passaggio. Nel caso l'URL non corrispondesse a uno di quelli autorizzati in fase di registrazione la richiesta fallirà. Il tuo backend dovrà gestire questo reindirizzamento e recuperare il codice di autorizzazione restituito dal Riseact Accounts. Verifica l'autenticità della richiesta controllando che il codice di autorizzazione corrisponda a quello generato in precedenza. Utilizzando il codice di autorizzazione ricevuto, effettua una richiesta al server di autorizzazione per ottenere un Access Token. Questo Access Token sarà utilizzato per autenticare le successive richieste alle API protette.

Ecco un esempio in node.js:

app.get('/oauth/callback', async (req, res) => {
  const { code, state } = req.query;

  if (state !== 'YOUR_CODE_CHALLENGE') {
    return res.status(400).send('Invalid state');
  }

  // Recupera le chiavi PKCE dal database
  const { codeChallenge, codeVerifier } = await db.getPkceKey(state);

  const formData = {
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    grant_type: 'authorization_code',
    code,
    redirect_uri: 'https://your-app.com/oauth/callback',
    code_verifier: codeVerifier,
  };

  const { data } = await axios.post('https://accounts.riseact.org/oauth/token/', qs.stringify(formData), {
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
  });

  // Salva le credenziali ottenute come preferisci. In questo caso utilizziamo un database
  db.saveCredentials(data.access_token, data.refresh_token, data.expires_in);
});

Esempio della chiamata con curl:

curl -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=authorization_code" \
  -d "code=YOUR_CODE" \
  -d "redirect_uri=https://your-app.com/oauth/callback" \
  -d "code_verifier=YOUR_CODE_VERIFIER" \
  https://accounts.riseact.org/oauth/token/

5. Utilizza l'Access Token per accedere alle risorse protette dell'organizzazione: Ogni volta che desideri accedere alle risorse protette dalle API, dovrai includere l'Access Token nella tua richiesta nell'header Authorization. Le API utilizzeranno l'Access Token per verificare l'autenticità della richiesta e fornire le risorse richieste solo se l'Access Token è valido.

Ecco un esempio in node.js:

const { data } = await axios.get('https://core.riseact.org/admin/graphql/', {
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});

Esempio della chiamata con curl:

curl -X GET \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://core.riseact.org/admin/graphql/

6. Gestisci il rinnovo dell'Access Token: Gli Access Token hanno una durata limitata. Per garantire un'esperienza utente senza interruzioni, dovrai implementare la logica per rinnovare automaticamente l'Access Token prima che scada. Ciò può essere fatto utilizzando il processo di aggiornamento dell'Access Token fornito dal server di autorizzazione.

Ecco un esempio in node.js:

app.get('/oauth/refresh', async (req, res) => {
  const { refresh_token } = req.query;

  const formData = {
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    grant_type: 'refresh_token',
    refresh_token,
  };

  const { data } = await axios.post('https://accounts.riseact.org/oauth/token/', qs.stringify(formData), {
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
  });

  // Salva le credenziali ottenute come preferisci. In questo caso utilizziamo un database
  db.saveCredentials(data.access_token, data.refresh_token, data.expires_in);
});

Esempio della chiamata con curl:

curl -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  https://accounts.riseact.org/oauth/token/

Implementando correttamente l'autenticazione OAuth nella tua applicazione, sarai in grado di ottenere un Access Token valido e accedere alle risorse protette tramite le API. Assicurati di seguire le specifiche e le documentazioni fornite da Riseact per un'implementazione corretta e sicura. Buona implementazione!

Contenuto importato da https://dev.riseact.org/docs/partner-apps/oauth-authentication il 2026-04-23 durante la migrazione iniziale della KB Metadonors. Aggiornare se il sorgente cambia.

Utilizzo delle APIs (partner apps)

Riseact offre 2 modi per consumare le APIs: tramite GraphQL o REST. Per utilizzare le APIs GraphQL, puoi inviare una richiesta HTTP POST al server GraphQL di Riseact, specificando il token di accesso come header di autorizzazione.

Authorization: Bearer <YOUR TOKEN>

Contenuto importato da https://dev.riseact.org/docs/partner-apps/api-usage il 2026-04-23 durante la migrazione iniziale della KB Metadonors. Aggiornare se il sorgente cambia.

Interfaccia utente dell'applicazione

Le applicazioni di Riseact vengono renderizzate all'interno di un iframe incorporato nel portale di amministrazione nella pagina della tua applicazione. Se vuoi fornire una interfaccia dell'applicazione ai tuoi utenti, puoi farlo servendola all'url che hai fornito in fase di registrazione dell'applicazione.

Tieni presente che l'autenticazione tra il tuo frontend e il backend della tua app non è gestita da Riseact e dovrai implementarla tu stesso. Un sistema valido è sicuro potrebbe essere quelle di utilizzare un token JWT per autenticare le richieste al tuo backend. Ricorda che se il tuo backend necessita di accedere alle APIs di Riseact in momenti in cui non è presente un utente loggato (es per sincronizzazioni o invio email) dovrai salvare i token di autenticazione per OAuth in modo accessibile al backend (es in un database).

Contenuto importato da https://dev.riseact.org/docs/partner-apps/application-frontend il 2026-04-23 durante la migrazione iniziale della KB Metadonors. Aggiornare se il sorgente cambia.

Webhook di Applicazione

I webhook di applicazione sono webhook che vengono chiamati da Riseact quando si verificano determinati eventi in tutte le organizzazioni che che hanno installato l'applicazione. A differenza dei webhook di organizzazione, questi vengono registrati una sola volta (per esempio alla creazione dell'applicazione) e i riferimenti all'organizzazione saranno inclusi nel payload della chiamata.

Per aggiungere un webhook di applicazione, devi registrare l'URL del webhook e selezionare gli eventi che vuoi ricevere dalla pagina impostazioni dell'applicazione sul portale Riseact Partner.

Contenuto importato da https://dev.riseact.org/docs/partner-apps/application-webhooks il 2026-04-23 durante la migrazione iniziale della KB Metadonors. Aggiornare se il sorgente cambia.

Webhook di Organizzazione

I webhook di organizzazione sono webhook che vengono chiamati da Riseact quando si verificano determinati eventi in una organizzazione. Per aggiungere un webhook di organizzazione, devi registrare l'URL del webhook e selezionare gli eventi che vuoi ricevere con la chiamata al relativo endpoint o mutation.

Dettagli richiesta

Di seguito alcuni esempio di richiesta lanciata da Riseact verso il tuo webhook.

Webhooks di sostenitore

{
  "organization": "your-org-domain",
  "object": {
    "id": 75835,
    "create_date": "2023-08-17T16:10:45.354192+00:00",
    "update_date": "2023-08-17T16:10:45.367332+00:00",
    "image": "",
    "business_name": null,
    "first_name": "first name",
    "last_name": "last name",
    "supporter_type": "SupporterType.INDIVIDUAL",
    "email": "test@email.com",
    "phone": "phone",
    "mobile": "mobile",
    "sex": "Sex.MALE",
    "date_of_birth": "1970-01-01",
    "place_of_birth": "Place of birth",
    "ssn": "ssn",
    "vat": "vat",
    "address": "address",
    "address2": "secondary address",
    "city": "city",
    "locality": "locality",
    "country": "IT",
    "postal_code": "code",
    "certification_url": null,
    "privacy": false,
    "email_marketing": false,
    "phone_marketing": false,
    "sms_marketing": false,
    "postal_marketing": false,
    "note": "notes",
    "tags": [],
    "external_ref": null,
    "source_campaign": null,
    "organization": 33,
    "application": 1,
    "stripe_customer_id": null
  },
  "event": "supporter.created"
}

Webhooks di checkout

{
  "organization": "your-org-domain",
  "object": {
    "id": 901,
    "create_date": "2023-08-17T16:15:52.746141+00:00",
    "update_date": "2023-08-17T16:15:52.746165+00:00",
    "state": "OPEN",
    "amount": 10,
    "completed_date": null,
    "donation": null,
    "supporter": 75835,
    "frequency": null,
    "peer_campaign": null
  },
  "event": "checkout.created"
}

Webhooks di pagamento

{
  "organization": "your-org-domain",
  "object": {
    "id": 230,
    "create_date": "2023-08-17T16:27:04.647182+00:00",
    "update_date": "2023-08-17T16:27:04.647204+00:00",
    "state": "PAID",
    "amount": 10,
    "payment_date": "2023-08-17T16:26:59.889000+00:00",
    "payment_method": "MANUAL",
    "donation": 229,
    "supporter": 75835,
    "frequency": 0,
    "peer_campaign": null
  },
  "event": "payment.created"
}

Webhooks di donazione

{
  "organization": "your-org-domain",
  "object": {
    "id": 229,
    "create_date": "2023-08-17T16:27:04.542168+00:00",
    "update_date": "2023-08-17T16:27:04.542168+00:00",
    "code": "#1000",
    "state": "pending",
    "amount": 10,
    "frequency": 0,
    "completed_date": null,
    "campaign": 29,
    "peer_campaign": null,
    "supporter": 75835,
    "tags": [],
    "payment_method": "MANUAL"
  },
  "event": "donation.created"
}

Contenuto importato da https://dev.riseact.org/docs/partner-apps/organization-webhooks il 2026-04-23 durante la migrazione iniziale della KB Metadonors. Aggiornare se il sorgente cambia.

Pubblicazione

Una volta completata e testata la tua applicazione, puoi pubblicarla su Riseact im modo che sia a disposizione di tutti gli utenti. Per pubblicare la tua applicazione, devi andare alla pagina impostazioni della tua app e modificare la distribuzione dell'app da Privata a Pubblica.

Contenuto importato da https://dev.riseact.org/docs/partner-apps/publishing il 2026-04-23 durante la migrazione iniziale della KB Metadonors. Aggiornare se il sorgente cambia.

API - GraphQL

Utilizzo delle API GraphQL

Riseact fornisce un set di APIs GraphQL per consentire agli sviluppatori di interagire con le risorse di Riseact. Queste APIs sono disponibili per tutti gli sviluppatori che hanno creato un'applicazione su Riseact.

Per poter utilizzare le APIs GraphQL di Riseact, è necessario ottenere un Access Token attraverso i processi descritti in questa pagina.

Una volta ottenuto un token, puoi utilizzare le APIs GraphQL per interagire con le risorse di Riseact. Per ulteriori informazioni, consulta la pagina Risorse di Riseact e la pagina di references delle API GraphQL.

Esempio di utilizzo

curl 'https://core.riseact.org/admin/graphql/' \
  -H 'authorization: Bearer <YOUR TOKEN>' \
  --data-raw '{"query":"query Organization {\n  organization {\n    name\n    domain\n  }\n}","variables":{},"operationName":"Organization"}'

Contenuto importato da https://dev.riseact.org/docs/apis/graphql-api-usage il 2026-04-23 durante la migrazione iniziale della KB Metadonors. Aggiornare se il sorgente cambia.

GraphQL - Queries

activities

Type: ActivityConnection!

Arguments

activity

Type: Activity!

Arguments

article

Type: Article!

Arguments

articles

Type: ArticleConnection!

Arguments

blog

Type: Blog!

Arguments

blogs

Type: BlogConnection!

Arguments

campaign

Type: Campaign!

Arguments

campaignComment

Type: CampaignComment!

Arguments

campaignComments

Type: CampaignCommentConnection!

Arguments

campaigns

Type: CampaignConnection!

Arguments

campaignTags

Type: StrConnection!

Arguments

checkout

Type: Checkout!

Arguments

checkouts

Type: CheckoutConnection!

Arguments

checkoutsAbandoned

Type: CheckoutConnection!

Arguments

checkoutsAdminGenerated

Type: CheckoutConnection!

Arguments

customfieldDefinition

Type: CustomFieldDefinition!

Arguments

customfieldDefinitions

Type: [CustomFieldDefinition!]!

Arguments

donation

Type: Donation!

Arguments

donations

Type: DonationConnection!

Arguments

donationTags

Type: StrConnection!

Arguments

manualPaymentMethod

Type: PaymentMethod!

Arguments

manualPaymentMethods

Type: [PaymentMethod!]!

media

Type: MediaConnection!

Arguments

mediaSingle

Type: Media!

Arguments

menu

Type: Menu!

Arguments

menuByHandle

Type: Menu!

Arguments

menus

Type: [Menu!]!

organization

Type: Organization!

organizations

Type: [Organization!]!

Arguments

owner

Type: Staff!

page

Type: Page!

Arguments

pages

Type: PageConnection!

Arguments

payment

Type: Payment!

Arguments

paymentMethods

Type: [PaymentMethod!]!

payments

Type: PaymentConnection!

Arguments

peerCampaign

Type: PeerCampaign!

Arguments

peerCampaigns

Type: PeerCampaignConnection!

Arguments

privacyDefinition

Type: PrivacyDefinition!

Arguments

privacyDefinitions

Type: PrivacyDefinitionConnection!

Arguments

project

Type: Project!

Arguments

projects

Type: ProjectConnection!

Arguments

redirect

Type: Redirect!

Arguments

redirects

Type: RedirectConnection!

Arguments

segment

Type: Segment!

Arguments

segments

Type: SegmentConnection!

Arguments

stripe

Type: StripeAccount

stripeCustomerCards

Type: [StripeCard!]!

Arguments

sumupAccount

Type: SumUpAccount

supporter

Type: Supporter!

Arguments

supporters

Type: SupporterConnection!

Arguments

supporterTags

Type: StrConnection!

Arguments

terminal

Type: StripeTerminal!

Arguments

terminalLocation

Type: StripeTerminalLocation!

Arguments

terminalLocations

Type: [StripeTerminalLocation!]!

Arguments

terminals

Type: [StripeTerminal!]!

terminalsByLocation

Type: [StripeTerminal!]!

Arguments

Contenuto importato da https://dev.riseact.org/docs/graphql-references/queries il 2026-04-23 durante la migrazione iniziale della KB Metadonors. Aggiornare se il sorgente cambia.

GraphQL - Mutations

activityCreate

Type: ActivityResponse!

Arguments

activityDelete

Type: ActivityResponse!

Arguments

activityDone

Type: ActivityResponse!

Arguments

activityUndone

Type: ActivityResponse!

Arguments

activityUpdate

Type: ActivityResponse!

Arguments

articlesCreate

Type: ArticlesResponse!

Arguments

articlesDelete

Type: ArticlesResponse!

Arguments

articlesUpdate

Type: ArticlesResponse!

Arguments

blogsCreate

Type: BlogsResponse!

Arguments

blogsDelete

Type: BlogsResponse!

Arguments

blogsUpdate

Type: BlogsResponse!

Arguments

campaignCommentCreate

Type: CampaignCommentResponse!

Arguments

campaignCommentDelete

Type: CampaignCommentResponse!

Arguments

campaignCommentUpdate

Type: CampaignCommentResponse!

Arguments

campaignCreate

Type: CampaignResponse!

Arguments

campaignDelete

Type: CampaignResponse!

Arguments

campaignDuplicate

Type: CampaignResponse!

Arguments

campaignUpdate

Type: CampaignResponse!

Arguments

checkoutComplete

Type: CheckoutResponse!

Arguments

checkoutCreate

Type: CheckoutResponse!

Arguments

checkoutRegisterPayment

Type: CheckoutResponse!

Arguments

checkoutSendRecoveryEmail

Type: CheckoutResponse!

Arguments

checkoutUpdate

Type: CheckoutResponse!

Arguments

customfieldDefinitionCreate

Type: CustomFieldDefinitionResponse!

Arguments

customfieldDefinitionDelete

Type: CustomFieldDefinitionResponse!

Arguments

customfieldDefinitionUpdate

Type: CustomFieldDefinitionResponse!

Arguments

donationDelete

Type: Donation!

Arguments

donationExport

Type: String!

Arguments

donationImport

Type: Task!

Arguments

donationReceiptSend

Type: Boolean!

Arguments

donationRegisterPayment

Type: DonationResponse!

Arguments

donationRevoke

Type: Donation!

Arguments

donationUpdate

Type: Donation!

Arguments

manualPaymentMethodCreate

Type: PaymentMethodResponse!

Arguments

manualPaymentMethodDelete

Type: PaymentMethodResponse!

Arguments

manualPaymentMethodUpdate

Type: PaymentMethodResponse!

Arguments

mediaCreate

Type: Media!

Arguments

mediaDelete

Type: MediaResponse!

Arguments

menuCreate

Type: MenuResponse!

Arguments

menuDelete

Type: MenuResponse!

Arguments

menuUpdate

Type: MenuResponse!

Arguments

organizationUpdate

Type: OrganizationResponse!

Arguments

organizationUpdateLegalData

Type: OrganizationResponse!

Arguments

pagesCreate

Type: PagesResponse!

Arguments

pagesDelete

Type: PagesResponse!

Arguments

pagesUpdate

Type: PagesResponse!

Arguments

paymentExport

Type: String!

Arguments

paymentRefund

Type: PaymentResponse!

Arguments

paymentUpdate

Type: PaymentResponse!

Arguments

peerCampaignCreate

Type: PeerCampaignResponse!

Arguments

peerCampaignDelete

Type: PeerCampaignResponse!

Arguments

peerCampaignUpdate

Type: PeerCampaignResponse!

Arguments

privacyDefinitionCreate

Type: PrivacyDefinitionResponse!

Arguments

privacyDefinitionDelete

Type: PrivacyDefinitionResponse!

Arguments

privacyDefinitionUpdate

Type: PrivacyDefinitionResponse!

Arguments

projectCreate

Type: ProjectResponse!

Arguments

projectDelete

Type: ProjectResponse!

Arguments

projectRemoveItem

Type: ProjectResponse!

Arguments

projectUpdate

Type: ProjectResponse!

Arguments

projectUpdateItems

Type: ProjectResponse!

Arguments

redirectsCreate

Type: RedirectResponse!

Arguments

redirectsDelete

Type: RedirectResponse!

Arguments

redirectsUpdate

Type: RedirectResponse!

Arguments

satispayPaymentCreate

Type: SatispayPaymentResponse!

Arguments

segmentCreate

Type: SegmentResponse!

Arguments

segmentDelete

Type: SegmentResponse!

Arguments

segmentUpdate

Type: SegmentResponse!

Arguments

stripeActivate

Type: StripeAccount!

stripeCheckoutIntentCreate

Type: StripeCheckoutResponse!

Arguments

stripeGenerateDashboardLink

Type: StripeLink!

stripeGenerateOnboardingLink

Type: StripeLink!

stripeTerminalCheckoutIntentCreate

Type: StripeCheckoutResponse!

Arguments

sumupAccountCreate

Type: SumUpAccount!

Arguments

sumupAccountUpdate

Type: SumUpAccount!

Arguments

supporterBulkTags

Type: Boolean!

Arguments

supporterCreate

Type: Supporter!

Arguments

supporterDelete

Type: Supporter!

Arguments

supporterExport

Type: String!

Arguments

supporterImport

Type: Task!

Arguments

supporterMerge

Type: Supporter!

Arguments

supporterRemovePrivacy

Type: SupporterResponse!

Arguments

supporterSendTaxCertificate

Type: Supporter!

Arguments

supporterSetPrivacy

Type: SupporterResponse!

Arguments

supporterUpdate

Type: Supporter!

Arguments

terminalConnectionTokenCreate

Type: String!

Arguments

terminalDelete

Type: String!

Arguments

terminalLocationCreate

Type: StripeTerminalLocation!

Arguments

terminalLocationDelete

Type: Void

Arguments

terminalLocationUpdate

Type: StripeTerminalLocation!

Arguments

terminalRegister

Type: StripeTerminal!

Arguments

terminalUpdateLabel

Type: StripeTerminal!

Arguments

Contenuto importato da https://dev.riseact.org/docs/graphql-references/mutations il 2026-04-23 durante la migrazione iniziale della KB Metadonors. Aggiornare se il sorgente cambia.

GraphQL - Objects

AccessToken

Fields

Activity

Fields

ActivityConnection

Fields

ActivityEdge

Fields

ActivityResponse

Fields

ActivityStaff

Fields

Application

Fields

AppMutation

Fields

AppQuery

Fields