Guida allo sviluppo di applicazioni Marketplace

Le app Blesium sono componenti aggiuntivi che aggiungono nuove funzionalità a dashboard e prodotti (CRM, ERP, E-Commerce, Mail…), come le app Shopify App Store o Slack. Non applicazioni mobili installate sul telefono.

Modello di lavoro

La tua applicazione funziona sul modello "HTTP remoto": il codice non viene caricato in Blesium, ma viene eseguito oltre i confini della rete sul tuo server e comunica con chiamate REST firmate, protette da SSRF e limitate in velocità. Nessun accesso diretto al database.

• Al Blesium. → L'identità dell'applicazione, la categoria, i prodotti di destinazione, le autorizzazioni richieste, i prezzi e la cronologia delle versioni
• Ne hai uno. → L’applicazione stessa: logica di business, interfaccia, elaborazione dati
• Accesso ai dati → Solo tramite API, solo entro i permessi approvati dal tenant

1. Definisci la tua applicazione

Campi da compilare quando si crea una nuova applicazione dalla console:

• Nome → Nome visualizzato in negozio
• Lumaca → Allegato indirizzo; solo lettere minuscole, numeri e trattini
• Categoria → Una delle seguenti liste canoniche
• Descrizione → Cosa fa l'applicazione
• Prodotti di destinazione → crm · erp · b2b · posta elettronica · call center · negozio · musavir
• Permessi richiesti → Scopi per cui la tua applicazione deve funzionare
• Prezzi → Gratuito · Una tantum · Abbonamento

La categoria deve provenire dalla lista canonica; una chiave al di fuori della lista rifiuterà la presentazione.

• integrazione → Collega Blesium ad un sistema esterno
• Relazione → Aggiunge report/indicatore alla dashboard
• tema → Tema visivo
• automazione → Automazione del workflow
• canale_vendite → Canale di vendita
• Messaggistica → Canale di messaggistica
• spedizione → Cargo/carico
• widget → Pannello Widget
• settore_pacco → Pacchetto settore
• lingua_pack → Pacchetto linguistico
• Altro → Altri prodotti

2. Permessi

L'applicazione verrà eseguita solo con le autorizzazioni richieste e approvate dal tenant durante l'installazione. Chiedere meno permessi: i permessi inutilmente ampi perderanno fiducia nell'autorizzazione all'installazione.

3. Autenticazione

Ogni richiesta all'API Blesium è firmata con una chiave API. Il formato della chiave è blsk_{ortam}_{kimlik}_{gizli}, e la parte segreta viene mostrata solo una volta al momento della creazione.

curl https://firmaniz.blescript.com/api/v1/me \
  -H "Authorization: Bearer blsk_live_ab12cd34_gizli-anahtariniz"

4. Ascolto di eventi con webhooks

Invece di fare costantemente domande, mettiti in contatto quando succede. Ogni consegna viene fornita con tre rubriche:

• x-blesium-evento Il nome dell'evento (o. fattura.pagato)
• x-blesyum-consegna → ID di consegna; utilizzare per eliminare i duplicati
• x-blesyum-signature → Firma HMAC-SHA256 del corpo grezzo (esadecimale)

Eventi a cui puoi iscriverti e quando vengono attivati:

• Fattura. → Creazione di una nuova fattura
• Fattura.pagata → Fattura pagata
• Fattura.rimborsata → Fattura restituita
• Abbonamento. → Abbonamento rinnovato
• abbonamento.plan_changed → Piano di abbonamento cambiato
• Abbonamento. → Abbonamento annullato
• utente.invitato → Utente invitato al team
• user.joined → Utente invitato si è unito
• ticket.created → Richiesta di supporto aperta
• biglietto.risposta → Richiesta di supporto risolta

Verificare la firma rispetto al corpo grezzo, utilizzando un confronto a tempo fisso (non come convertito in JSON — le differenze di spazio interromperanno la firma):

import crypto from "node:crypto";

export function imzaDogrula(rawBody, header, secret) {
  const beklenen = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(beklenen);
  const b = Buffer.from(header ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

5. Rilascio

Campi da inserire quando si pubblica una versione:

• Canale → stabile o beta
• Diffusione → Apertura graduale da 0–100%
• Stato → Trasmesso o ritirato

Flusso di pubblicazione:

1. Invia versione — Immettere il numero di versione, il canale e la nota di modifica.
2. Spacchetta gradualmente — Rilascia prima una piccola fetta con una percentuale di diffusione.
3. Attendi la revisione: quando l'app supera la revisione, viene rilasciata nello store.
4. Ripristina se necessario — Ripristina la versione problematica; il record non viene eliminato, ma viene ripristinata la versione precedente.

Mostra lo stato dell'applicazione nella console:

6. Checklist di pre-rilascio

• Hai ridotto al minimo le autorizzazioni richieste.
• Convalidi la firma del webhook, non rielabori la consegna ripetuta.
• La chiave API è solo sul lato server; il tuo flusso di backup delle perdite è pronto.
• La tua applicazione non interrompe il lavoro del tenant in caso di guasto (soft drop).
• La descrizione e le schermate mostrano cosa fa effettivamente l'app.