Guide de développement d'applications Marketplace

Les apps Blesium sont des add-ons qui ajoutent de nouvelles fonctionnalités aux tableaux de bord et produits (CRM, ERP, E-Commerce, Mail…) — comme les apps Shopify App Store ou Slack. Pas d'applications mobiles installées sur le téléphone.

Modèle de travail

Votre application fonctionne sur le modèle "HTTP distant" : le code n'est pas chargé dans Blesium, il s'exécute au-delà de la limite du réseau sur votre serveur et communique avec des appels REST signés, protégés par SSRF et limités en vitesse. Pas d'accès direct à la base de données.

• Au Blesium. → L'identité de l'application, la catégorie, les produits cibles, les autorisations demandées, la tarification et l'historique des versions
• Vous en avez un. → L’application elle-même : logique métier, interface, traitement des données
• Accès aux données → Uniquement via API, uniquement dans les limites des autorisations approuvées par le locataire

1. Définissez votre application

Champs à remplir lors de la création d'une nouvelle application depuis la console:

• Nom → Nom affiché en magasin
• Slug → Pièce jointe d'adresse; seulement minuscules, chiffres et traits d'union
• Catégorie → Une des listes canoniques suivantes
• Désignation → Ce que l'application fait
• Produits cibles → crm · erp · b2b · courrier · centre d'appels · boutique · musavir
• Permissions requises → Les domaines d'application dont votre application a besoin pour fonctionner
• Prix → Gratuit · Une fois · Abonnement

La catégorie doit provenir de la liste canonique; une clé en dehors de la liste rejettera la soumission.

• intégration → Connecte Blesium à un système externe
• Rapport → Ajoute rapport/indicateur au tableau de bord
• thème → Thème visuel
• Automatisation → Automatisation des workflows
• canal_vente → Canal de vente
• Messagerie → Messagerie canal
• expédition → Cargo/sevkiyat
• widget → Panneau de widget
• sector_pack → Paquet secteur
• Langue_de_l'entreprise → Paquet de langue
• Autres → Autres

2. Autorisations

Votre application ne s'exécutera qu'avec les autorisations qu'elle demande et que le client approuve lors de l'installation. Demander moins de permissions : des permissions inutilement larges vont faire perdre confiance dans l’autorisation d’installation.

3. Authentification

Chaque requête à l'API Blesium est signée avec une clé API. Le format de la clé est blsk_{ortam}_{kimlik}_{gizli}, et la partie secrète n'est affichée qu'une seule fois au moment de la création.

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

4. Écouter les événements avec des webhooks

Au lieu de poser constamment des questions, contactez-le quand cela se produit. Chaque livraison est livrée avec trois rubriques:

• x-blesyum-event Le nom de l'événement (ou. (Facture.payée)
• x-blesyum-delivery → ID de livraison; utiliser pour éliminer les doublons
• x-blesyum-signature → Signature HMAC-SHA256 du corps brut (hex)

Événements auxquels vous pouvez vous abonner et quand ils sont déclenchés:

• invoice.created → Nouvelle facture créée
• facture.payée → Facture payée
• invoice.refunded → Facture retournée
• abonnement.renouvelé → Abonnement renouvelé
• subscription.plan_changed → Plan d'abonnement modifié
• abonnement.annulé → Abonnement annulé
• user.invited → Utilisateur invité à rejoindre l'équipe
• user.joined → Utilisateur invité a rejoint
• ticket.created → Demande de support ouverte
• ticket.answered → Demande de support répondue

Vérifiez la signature par rapport au corps brut, en utilisant une comparaison à temps fixe (pas convertie en JSON — les différences d'espace briseront la signature) :

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. Libération

Champs que vous saisissez lors de la publication d'une version:

• Canal → stable ou bêta
• Spread → Ouverture progressive de 0 à 100%
• État → Diffusé ou retiré

Flux de publication:

1. Soumettre la version — Entrez le numéro de version, le canal et la note de modification.
2. Déballer progressivement — Donnez la libération à une petite tranche d'abord avec un pourcentage de diffusion.
3. Attendre l’examen — Lorsque l’application passe l’examen, elle est publiée dans le magasin.
4. Rétablir si nécessaire — Rétablit la version du problème ; l'enregistrement n'est pas supprimé, la version précédente est restaurée.

Affichez l'état de votre application dans la console:

6. Checklist de pré-release

• Vous avez réduit les autorisations requises.
• Vous validez la signature du webhook, vous ne retraiterez pas la livraison répétée.
• La clé API est uniquement côté serveur; votre flux de sauvegarde de fuite est prêt.
• Votre application n'arrête pas le travail du locataire en cas de panne (soft drop).
• La description et les captures d'écran montrent ce que l'application fait réellement.