開発者ドキュメント

開発者ダッシュボードでアプリ一覧と、各インストールの配信状況（webhookの送信結果）を確認できます。事業者の売上や顧客などの業務データは見えません。「インストール #45 への配信 #123 がHTTP 500で失敗」といった情報だけが表示されます。

{
  "key": "acme.puntos",
  "name": "Acme ポイント",
  "description": "購入ポイントプログラム",
  "category": "Crecimiento",
  "version": "1.0.0",
  "author": { "name": "Acme SRL", "url": "https://acme.dev" },
  "roles": ["owner", "admin"],
  "scopes": ["orders:read", "customers:read"],
  "events": ["order.paid"],
  "extensions": {
    "admin": ["dashboard.card"],
    "dna": [{ "key": "loyalty-widget", "name": "ポイントウィジェット" }],
    "automationActions": [{ "key": "add_points", "name": "ポイントを追加" }]
  },
  "endpoints": {
    "baseUrl": "https://acme.dev",
    "webhookPath": "/webhook"
  }
}

現在、*:read scopesで下記のPublic APIリソースを参照できます。*:write scopesは将来の利用向けです。事業者はインストール前に同意画面で権限を確認するため、アプリに必要な権限だけを要求してください。

利用可能なリソース（すべて読み取り専用、page/perPageでページ分割）:

curl "https://api.stockcito.com/api/public/v1/products?page=1&perPage=20" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Stockcito-Version: 2026-09"

# {"data":[...], "total":123, "page":1, "perPage":20}

extensions.adminにdashboard.cardを宣言すると、Stockcitoは{baseUrl}/stockcito-ui/dashboard-cardへ署名付きGETを送り、応答を事業者Dashboardのカードとして表示します。HTMLは送信しません。許可された値だけで構成する宣言型ノードツリーを返すため、想定外の内容は挿入できません。

// GET /stockcito-ui/dashboard-cardへの応答例
{
  "type": "card",
  "title": "ポイント残高",
  "children": [
    { "type": "text", "value": "有効ポイント 1,240", "weight": "bold" },
    { "type": "badge", "label": "今週 +80", "tone": "success" },
    { "type": "link", "label": "詳細を見る", "href": "https://acme.dev/panel" }
  ]
}

使用可能なノード: text、badge、link、stack（子要素を縦または横に配置）、card（他のノードを内包）。各階層は最大20個、応答は20KBまでです。サーバー停止、応答遅延、形式不正の場合、Stockcitoはカードだけを非表示にし、Dashboardには影響させません。

各署名付きリクエストにはX-Stockcito-TimestampとX-Stockcito-Signature: sha256=...が含まれます。署名は署名キー、timestamp、ピリオド、pathから計算したHMAC-SHA256です。サーバー側で検証し、リプレイ攻撃防止のため、現在時刻から5分以上離れたtimestampを拒否してください。

Node/Expressで署名を検証する例:

const crypto = require("crypto")

const SIGNING_KEY = process.env.STOCKCITO_SIGNING_KEY // インストール時にStockcitoから発行
const TOLERANCE_SECONDS = 300

app.get("/stockcito-ui/dashboard-card", (req, res) => {
  const timestamp = req.header("X-Stockcito-Timestamp")
  const signatureHeader = req.header("X-Stockcito-Signature") || ""
  const path = req.path // "/stockcito-ui/dashboard-card"

  const now = Math.floor(Date.now() / 1000)
  if (!timestamp || Math.abs(now - Number(timestamp)) > TOLERANCE_SECONDS) {
    return res.status(401).send("timestampが無効または期限切れです")
  }

  const expected = crypto
    .createHmac("sha256", SIGNING_KEY)
    .update(`${timestamp}.${path}`)
    .digest("hex")

  // timingSafeEqualでタイミング攻撃を防ぎます。
  
  const received = signatureHeader.replace("sha256=", "")
  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))

  if (!valid) return res.status(401).send("署名が無効です")

  res.json({
    type: "card",
    title: "ポイント残高",
    children: [{ type: "text", value: "有効ポイント 1,240", weight: "bold" }],
  })
})

extensions.dnaで、各モジュールの固定keyと表示名を宣言します。事業者はStudio → ホームデザインで追加するモジュールを選びます。Stockcitoは同じ署名付きUIプロトコルを使い、{baseUrl}/stockcito-ui/dna/{key}から内容を取得します。許可されたノード形式を検証し、事業者ごとに60秒間キャッシュします。公開ストアの訪問者にモジュールが表示されますが、アプリがストアやデータベースへ直接アクセスすることはありません。

GET https://acme.dev/stockcito-ui/dna/reviews-widget · X-Stockcito-Timestamp · X-Stockcito-Signature

extensions.automationActionsの各アクションは、事業者が「Xが起きたらYを実行」のようなルールを作ると利用できます。実行時にStockcitoはイベントデータをbodyに入れ、{baseUrl}/stockcito-actions/{actionKey}へ署名付きPOSTを送信します。

POST /stockcito-actions/add_points
Content-Type: application/json
X-Stockcito-Timestamp: 1735689600
X-Stockcito-Signature: sha256=<署名キーでbodyをHMAC>

{ "orderId": 4821, "total": 15400, "customerId": 92 }

UI拡張と同様に署名を検証しますが、ここではtimestamp、ピリオド、body（パスではなくJSON全体）がHMACの対象です。成功時はHTTP 2xxを返します。一時的なHTTP 4xx/5xx（サーバーの一時停止など）はbackoff付きで再試行されます。恒久的な失敗を検出した場合に2xxを返さないでください。Stockcitoは成功として扱います。

Nodeだけで動く最小構成のサーバー例: actionを受信し、bodyの署名を検証して応答します。

const http = require("http")
const crypto = require("crypto")

const SIGNING_KEY = process.env.STOCKCITO_SIGNING_KEY

http.createServer((req, res) => {
  if (req.method !== "POST" || req.url !== "/stockcito-actions/add_points") {
    res.writeHead(404).end()
    return
  }

  let body = ""
  req.on("data", (chunk) => { body += chunk })
  req.on("end", () => {
    const timestamp = req.headers["x-stockcito-timestamp"]
    const received = (req.headers["x-stockcito-signature"] || "").replace("sha256=", "")

    const expected = crypto
      .createHmac("sha256", SIGNING_KEY)
      .update(`${timestamp}.${body}`)
      .digest("hex")

    if (received.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))) {
      res.writeHead(401).end("署名が無効です")
      return
    }

    const { orderId, total, customerId } = JSON.parse(body)
    // ポイント加算、配送作成などの処理をここに記述します。
    console.log(`注文 ${orderId} / 顧客 ${customerId} / 合計 $${total}`)

    res.writeHead(200, { "Content-Type": "application/json" })
    res.end(JSON.stringify({ ok: true }))
  })
}).listen(3000)

/developersからご自身のMercado Pagoアカウントを接続すると、アプリに価格を設定できます。事業者のストア決済と同じOAuthフローを開発者として利用します。購入代金はご自身のMercado Pagoトークンに請求され、Stockcitoはプラットフォーム手数料を受け取ります。決済webhookで入金が確認されるまでアプリは無効です。

初期版のTypeScript SDK（packages/sdk-ts）はPublic APIリソースの型を提供します。npmなどの公開レジストリにはまだ公開されていません。現時点でサポートされる連携方法は、上記のHTTP + JSONです。どの言語からでも利用できます。