マーケットプレイスアプリケーション開発ガイド

Blesiumアプリは、Shopify App StoreやSlackアプリのように、ダッシュボードや製品（CRM、ERP、E-Commerce、Mailなど）に新しい機能を追加するアドオンである。 携帯電話にインストールされたアプリケーションではありません。

ワーキングモデル

あなたのアプリケーションは「リモートHTTP」モデルで動作します。コードはBlesiumにロードされません。サーバ上のネットワーク境界を超えて動作し、署名されたSSRF保護の速度制限RESTコールで通信します。 データベースへの直接アクセスはありません。

• ブレシウムで →アプリケーションのアイデンティティ，カテゴリ，ターゲット製品，要求権限，価格，バージョン履歴
• あなたは一人 また，アプリケーション自体については，ビジネスロジック，インタフェース，データ処理などを述べた。
• データアクセス → API を通じてのみ、テナントが承認した権限の範囲内でのみ

1. アプリケーションを定義

コンソールから新しいアプリケーションを作成するときに入力するフィールド:

• ネーム →店内に表示される名前
• スラグ →住所付け;小文字、数字、ハイフンのみ
• カテゴリ →以下の正典一覧のうちの一つ
• 説明 プログラムの機能
• ターゲット製品 →crm · erp · b2b · メール · コールセンター · ショップ · musavir
• 必要な権限 あなたのアプリケーションが動作する必要のある範囲
• 価格 →無料・一度のみ・加入制

分類は正規リストから来なければなりません。リストの外のキーは提出を拒否します。

• 統合 → Blesium を外部システムに接続
• 報告 → 報告書/指標をダッシュボードに追加
• テーマ 視覚的テーマ
• 自動化 ワークフロー自動化
• 売上チャンネル →販売チャンネル
• メッセージチャンネル メッセージチャンネル
• 船の運送 貨物
• ウィジェット ウィジェットパネル
• セクターパック →セクターパッケージ
• 言語パッケージ 言語パッケージ
• その他 その他

2. 権限

アプリケーションは、要求される権限と、テナントがインストール中に承認した権限でのみ実行されます。 権限を少なくする: 不必要に広い権限はインストールの認証に対する信頼を失います。

3. 認証

ＢｌｅｓｉｕｍＡＰＩへの各要求は，ＡＰＩキーで署名される。 鍵形式はblsk_{ortam}_{kimlik}_{gizli}であり、秘密部分は作成時に一度だけ表示される。

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

4. webhook でイベントをリストアップ

いつも質問するのではなく 事件が起きたら連絡を取れ 各配達は3つのヘッダを持っている。

• ブレシウム 事象の名前 (または) 請求書が出ました
• ブレシウムの発送 → 配送ID;重複を除去するために使用
• x-blesyum-signature のみ →原文のＨＭＡＣ‐ＳＨＡ２５６署名（ヘキサ）

購読可能なイベントとそれらがトリガされる時期:

• 作成された 新しい請求書を作成
• 請求書が支払われた →請求書支払い
• 請求書返却 →請求書返却
• 更新しました →加入更新
• プラン変更 →加入プラン変更
• 加入キャンセル → 購読キャンセル
• ユーザ.招待 →チームに招待されたユーザ
• ユーザが加入しました → 招待ユーザが加入
• チケットが作られた →サポート依頼開設
• チケットは出た →サポート依頼に応じた

固定時間比較を使って、原始ボディとの署名を検証します (JSON に変換した場合は違います。空白の差が署名を破壊します):

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. リリース

バージョンを公開するときに入力するフィールド:

• チャンネル →安定版またはベータ版
• 拡散 →0～100%の段階的開放
• 硬質 →放送・撤回

出版フロー:

1. バージョンを送信 — バージョン番号、チャンネル、変更ノートを入力します。
2. 徐々に解凍する - 先に小さなスライスにリリースを与え、分散率を与える。
3. Wait for Review - アプリがレビューを通過すると、ストアにリリースされる。
4. 必要なら復元 - 問題のバージョンを復元します。レコードは削除されず、以前のバージョンに戻ります。

コンソールにアプリケーションの状態を表示する:

6. プレリリースチェックリスト

• 必要な権限を最小化しました。
• ウェブフック署名を検証すると、繰り返し送信を再処理しない。
• サーバ側のみ API キーが存在します。リークバックアップストリームは準備完了です。
• あなたのアプリケーションは、失敗した場合にテナントの作業を停止しません。
• 説明とスクリーンショットは実際にアプリが何をするのかを示している。