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

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.