Leitfaden zur Entwicklung von Marketplace-Anwendungen

Blesium-Apps sind Add-ons, die Dashboards und Produkten (CRM, ERP, E-Commerce, Mail usw.) neue Funktionen hinzufügen – wie Shopify App Store oder Slack-Apps. Nicht mobile Anwendungen auf dem Telefon installiert.

Arbeitsmodell

Ihre Anwendung läuft auf dem "remote HTTP"-Modell: Code wird nicht in Blesium geladen, er läuft jenseits der Netzwerkgrenze auf Ihrem Server und kommuniziert mit signierten, SSRF-geschützten, Geschwindigkeitsbegrenzten REST-Aufrufen. Kein direkter Zugriff auf die Datenbank.

• Im Blesium. → Identität, Kategorie, Zielprodukte, angeforderte Berechtigungen, Preise und Versionshistorie der Anwendung
• Du hast einen. → Die Anwendung selbst: Geschäftslogik, Schnittstelle, Datenverarbeitung
• Datenzugriff → Nur über API, nur innerhalb der vom Mandanten genehmigten Berechtigungen

1. Definieren Sie Ihre Anwendung

Felder, die beim Erstellen einer neuen Anwendung aus der Konsole ausgefüllt werden müssen:

• Bezeichnung → Name im Shop angezeigt
• Schnecke → Adressanhang; nur Kleinbuchstaben, Zahlen und Bindestriche
• Kategorie → Eine der folgenden kanonischen Listen
• Beschreibung → Was die Anwendung macht
• Zielprodukte → CRM · Erp · B2B · E-Mail · Callcenter · Shop · Musavir
• Berechtigungen erforderlich → Bereiche, in denen Ihre Anwendung arbeiten muss
• Preisgestaltung → Kostenlos · Einmalig · Abonnement

Die Kategorie muss aus der kanonischen Liste stammen; ein Schlüssel außerhalb der Liste wird die Einreichung ablehnen.

• integration → Verbindet Blesium mit einem externen System
• Bericht → Fügt Bericht/Anzeige zum Dashboard hinzu
• Thema → Visuelles Thema
• Automatisierung → Workflow-Automatisierung
• Vertriebskanal → Vertriebskanal
• Nachrichtenkanal → Messaging-Kanal
• Versand → Fracht/Versand
• widget → Widget-Panel
• sector_pack → Sektorpaket
• Sprachenpaket → Sprachpaket
• Andere → Sonstige

2. Berechtigungen

Ihre Anwendung wird nur mit den Berechtigungen ausgeführt, die sie anfordert und die der Mandant während der Installation genehmigt. Weniger Berechtigungen anfordern: Unnötig breite Berechtigungen verlieren das Vertrauen in die Installationsberechtigung.

3. Authentifizierung

Jede Anfrage an die Blesium API wird mit einem API-Schlüssel signiert. Das Schlüsselformat ist blsk_{ortam}_{kimlik}_{gizli}, und der geheime Teil wird nur einmal zum Zeitpunkt der Erstellung angezeigt.

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

4. Auf Ereignisse mit Webhooks achten

Anstatt ständig Fragen zu stellen, kontaktiere sie, wenn es passiert. Jede Lieferung enthält drei Überschriften:

• x-blesyum-Ereignis Der Name des Ereignisses (oder. (Rechnung.bezahlt)
• x-blesyum-Lieferung → Liefer-ID; verwenden Sie diese, um Duplikate zu eliminieren
• x-blesyum-Zeichen → HMAC-SHA256 Signatur des Rohkörpers (hex)

Ereignisse, die Sie abonnieren können und wann sie ausgelöst werden:

• Rechnung. → Neue Rechnung erstellt
• Rechnung.bezahlt → Rechnung bezahlt
• Rechnung.Rückerstattung → Rechnung zurückgesendet
• Abonnement.Verlängert → Abonnement verlängert
• Abonnement.plan_changed → Abonnementplan geändert
• Abonnement.abgebrochen → Abonnement gekündigt
• Eingeladen → Benutzer ins Team eingeladen
• user.joined → Eingeladener Benutzer ist beigetreten
• ticket.created → Supportanfrage eröffnet
• Ticket.beantwortet → Supportanfrage beantwortet

Überprüfen Sie die Signatur mit dem Rohtext, indem Sie einen Zeitvergleich verwenden (nicht wie in JSON konvertiert – Unterschiede im Leerzeichen unterbrechen die Signatur):

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. Freigabe

Felder, die Sie beim Veröffentlichen einer Version eingeben:

• Kanal → stabil oder beta
• Verbreitung → Stufenlose Öffnung von 0–100%
• Durum → Ausgestrahlt oder zurückgezogen

Publikationsfluss:

1. Version senden — Geben Sie die Versionsnummer, den Kanal und die Änderungshinweise ein.
2. Entpacken Sie allmählich — Geben Sie die Freigabe zuerst einer kleinen Schicht mit einem Prozentsatz der Verbreitung.
3. Warten auf Überprüfung – Wenn die App die Überprüfung bestanden hat, wird sie im Store veröffentlicht.
4. Rückgängig machen, wenn nötig — Stellt die Problemversion wieder her; der Datensatz wird nicht gelöscht, sondern die vorherige Version wird wiederhergestellt.

Zeigen Sie den Status Ihrer Anwendung in der Konsole an:

6. Pre-Release-Checkliste

• Sie haben die erforderlichen Berechtigungen minimiert.
• Sie validieren die Webhook-Signatur, verarbeiten die wiederholte Zustellung nicht erneut.
• Der API-Schlüssel ist nur auf der Serverseite; Ihr Leak-Backup-Stream ist bereit.
• Ihre Anwendung stoppt die Arbeit des Mandanten im Falle eines Ausfalls nicht (Soft Drop).
• Die Beschreibung und Screenshots zeigen, was die App tatsächlich tut.