開発者向け REST API

概要

Dashboardly Developer REST API を使用すると、利用資格のあるアカウントから、独自のクライアント向けダッシュボード、データウェアハウス、ERP、その他のバックエンドを、標準の HTTPS と JSON で Dashboardly に直接接続できます。

これは Model Context Protocol（MCP）とは別のものです。

Claude、ChatGPT、Cursor などの AI アシスタントに Dashboardly のデータについて質問する場合は、MCP を使用します。
独自のバックエンドコードで固定 URL からデータを取得し、JSON レスポンスを処理する場合は、Developer REST API を使用します。

Developer REST は通常、有効な Agency プランのアカウントに対して Dashboardly が利用を有効にした場合に使用できます。Dashboardly は、プランを変更せずに Brand アカウント固有の例外を承認することもできます。承認された例外は、その Brand サブスクリプションが有効または試用期間中である間だけ機能します。利用条件を満たすサブスクリプションが解約、一時停止、または支払い遅延となった場合、既存の Developer キーは、プランが再び有効な状態になるまで機能しなくなります。キー自体は削除されず、サブスクリプションが有効になるとアクセスが復旧します。ほとんどのルートは読み取り専用です。有効日付きの COGS と手動調整には別々の権限があり、アカウントの所有者または管理者が明示的に有効にする必要があります。

API ドキュメントを開く

対話型 Swagger：https://api.dashboardly.io/api/developer/docs
OpenAPI JSON：https://api.dashboardly.io/api/developer/openapi.json
API のベース URL：https://api.dashboardly.io/api/developer/v1

Swagger には、現在のすべてのルート、クエリ項目、リクエスト本文、権限、レスポンス構造、エラー仕様が記載されています。OpenAPI JSON から、使用する言語向けの型付きクライアントを生成できます。

Developer API キーを作成する

アカウントの所有者または管理者としてログインします。
設定 > API キー を開きます。
新しいAPIキー を選択し、用途がわかる名前を付けます。
一つのショップまたはすべてのショップを選択します。
非公開の開発者向けREST APIを許可 を有効にします。
信頼できる会計または倉庫のバックエンドに限り、必要に応じて 手動調整の変更を許可 または 日付指定の商品原価（COGS）のアップロードを許可 を有効にします。どちらの書き込みオプションも、一つのショップを選択する必要があります。
一度だけ表示されるシークレットを作成し、すぐにサーバーのシークレット管理ツールに保存します。

ブラウザーの JavaScript、モバイルアプリ、公開リポジトリ、分析ツール、ログにキーを公開しないでください。独自のバックエンドから Dashboardly を呼び出し、クライアント向けページに必要なデータだけを返してください。

リクエストを認証する

キーを Bearer トークンとして送信します。

curl https://api.dashboardly.io/api/developer/v1/account \
  -H "Authorization: Bearer $DASHBOARDLY_API_KEY"

最初に GET /account、次に GET /shops を使用します。キーが複数の接続済みショップにアクセスできる場合、モジュールへのリクエストには、選択した Dashboardly ショップの UUID を shopId として送信します。ID による単一の手動調整の読み取りも対象です。

利用できるデータ

API は Dashboardly の顧客向け分析モジュールに対応しています。

ダッシュボード概要と上位商品。
損益、公開済みのカスタム P&L、売上と利益。
キャッシュフローと支払台帳。
注文、ステータス統計、時間別・地域別集計、返金。
在庫、有効日付き COGS の設定状況、倉庫手数料。
顧客概要、仮名化された顧客 LTV、コホート、購入経路。
マーケティング概要、広告キャンペーン、LIVE、プロモーション、アフィリエイト実績。
手動調整台帳。

Cashflow、Marketing、LIVE、Affiliate のエンドポイントは、選択したショップで各機能が利用可能かどうかによっても制御されます。

この分析 API では、請求、サブスクリプション、共同作業者、API キー管理、インポート、Dashboardly の設定は公開されません。

プライバシー

注文のレスポンスには、購入者名、メールアドレス、電話番号、受取人の住所、追跡識別子が含まれません。顧客エンドポイントは、元の購入者識別子ではなく、集計データまたはアカウント内で安定した仮名を返します。顧客の行には、最初または最後の注文の具体的な ID は公開されません。小規模な地域グループは Other にまとめられます。

任意の書き込み

有効日付き COGS

POST /costs は、Dashboardly の商品/SKU ごとの Unit COG を有効日付きの履歴に書き込みます。TikTok Shop は変更されません。キーには write:costs が必要で、一つのショップに限定され、そのショップの商品/SKU を参照する必要があります。

手動調整

手動調整の書き込みには、write:manual-adjustments と、一つのショップに限定されたキーが必要です。調整の作成と COGS のインポートの両方で Idempotency-Key ヘッダーが必要です。これにより、タイムアウトしたリクエストを再試行しても、会計の記録が重複しません。API キーが更新、一時停止、再開、削除できるのは、選択したショップでそのキー自身が作成した調整だけです。日付は YYYY-MM-DD 形式の暦日で、終了日は開始日より前にできません。タイムゾーンには有効な IANA 名を使い、SKU ごとのカスタム金額は skuIds に記載された ID を参照する必要があります。

エラーとリクエスト制限

成功したレスポンスには data と meta が含まれます。エラーには error.code、error.message、meta.requestId が含まれます。サポートに問い合わせる際はリクエスト ID を控えておいてください。

403アクセスエラーの解決方法

Developer RESTへのアクセスは、アカウントと送信するキーの両方で有効にする必要があります。プランがAI連携に対応していても、MCPレポート用に作成したキーにDeveloper RESTの権限が自動的に付与されることはありません。

"Developer REST API access is not enabled for this credential." と表示される場合、そのキーにはREST専用の権限がありません。アカウントの承認後、所有者または管理者としてログインし、 非公開の開発者向けREST APIを許可 を選択してキーを作成してください。サーバーのシークレット設定を更新して、そのキーを使用します。MCP専用キーをローテーションしても既存の権限は保持され、RESTアクセスは追加されません。

"Developer REST API access is not enabled for this account." と表示される場合は、アカウントの承認と利用条件を満たすサブスクリプションをサポートに確認してください。キー作成フォームにRESTの選択肢がない場合は、追加のキーを作成する前にサポートへお問い合わせください。Brandアカウントの例外承認によってサブスクリプションのプランが変わることはありません。

お問い合わせの際は、Dashboardlyへのログイン用メールアドレス、設定 > API キー に表示されるキーの名前、リクエストのパス、および返された場合はリクエストIDをお知らせください。キー全体やAuthorizationヘッダーは共有しないでください。これらの情報により、サポートは対象のアカウントとアクセス権限を確認できます。

標準の制限はキーごとに毎分 120 リクエストで、追加の IP 単位の制限もあります。API が 429 を返した場合は、通知された retryAfter の時間だけ待ち、待機時間を指数的に増やしながら再試行してください。

サポートを受ける

Dashboardly は、権限スコープの選択、アカウント接続、連携テストをお手伝いできます。https://cal.com/dashboardly/onboarding からオンボーディングの通話を予約してください。

概要