Marketplace App Development Guide

Blesyum applications are plugins that add new capabilities to dashboards and products (CRM, ERP, E-Commerce, Email, etc.)—similar to apps in the Shopify App Store or Slack. They are not mobile apps installed on a phone.

Operating Model

Your application operates using the "remote HTTP" model: the code is not loaded into Blesyum; it runs on your server beyond the network boundary and communicates via signed, SSRF-protected, rate-limited REST calls. There is no direct access to the database.

• Available on Blesyum → The app’s ID, category, target products, required permissions, pricing, and version history
• On your end → The application itself: business logic, user interface, data processing
• Data access → Only via the API, strictly limited to the permissions approved by the tenant

1. Describe your application

Fields you fill out when creating a new application from the console:

• Name → Name displayed in the store
• Slug → URL suffix; only lowercase letters, numbers, and hyphens
• Category → One of the following canonical lists
• Description → What the application does
• Target Products → CRM · ERP · B2B · Email · Call Center · Shop · Consultant
• Required Permissions → The scopes your app needs to function
• Pricing → Free · One-time · Subscription

The category must come from the canonical list; submitting a key outside the list will result in rejection.

• integration → Connects Blesyum to an external system
• report → Adds a report/dashboard to the panel
• theme → Visual theme
• automation → Workflow automation
• sales_channel → Sales channel
• messaging_channel → Messaging channel
• shipping → Shipping/Delivery
• widget → Widget on the panel
• sector_pack → Sector package
• language_pack → Language pack
• other → Other

2. Permissions

Your app runs only with the permissions it requests and that the tenant approved during installation. Request fewer permissions: unnecessarily broad permissions erode trust during the installation approval process.

3. Authentication

Every request to the Blesyum API is signed with an API key. The key format is blsk_{ortam}_{kimlik}_{gizli}, and the secret portion is displayed only once at the time of creation.

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

4. Listen for events via webhooks

Instead of constantly checking, get notified when an event occurs. Each delivery comes with three headings:

• x-Blesyum-event → Event name (e.g., Invoice.paid)
• x-Blesyum-delivery → Delivery ID; use to filter out duplicates
• x-Blesyum-signature → HMAC-SHA256 signature of the raw body (hex)

Events you can subscribe to and when they are triggered:

• invoice.created → A new invoice was created
• invoice.paid → Invoice paid
• invoice.refunded → Invoice refunded
• subscription.renewed → Subscription renewed
• subscription.plan_changed → Subscription plan has changed
• subscription.canceled → Subscription canceled
• user.invited → The user was invited to the team
• user.joined → The invited user has joined
• ticket.created → Support request created
• ticket.answered → Support request answered

Verify the signature using a fixed-time comparison on the raw body (not the JSON-converted version—spacing differences will invalidate the 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. Publishing a Version

Fields you enter when publishing a version:

• Channel → stable or beta
• Spread → Gradual opening between 0% and 100%
• Status → Published or Unpublished

Publication workflow:

1. Submit a version — Enter the version number, channel, and release notes.
2. Roll out gradually — Release the version to a small segment first, based on the adoption rate.
3. Please wait for review — The app will be published in the store once it passes review.
4. Roll back if necessary — Roll back to the problematic version; the registration will not be deleted, and the previous version will be restored.

The status of your application is displayed in the console:

6. Pre-publication checklist

• You have minimized the required permissions.
• It verifies the webhook signature; you do not reprocess duplicate deliveries.
• The API key is server-side only; your rotation flow is ready in the leak.
• In the event of an error, your application does not interrupt the tenant's work (graceful fallback).
• Descriptions and screenshots explain what the application actually does.