ナカーマ
無料でコミュニティを開設

APIキーと公開APIを使う

APIキーを発行すると、外部ツールやスクリプトから公開API（/api/v1）を呼び出して、顧客や投稿などをプログラムから操作できます。Zapierなどの連携や社内の自動化に使えます。この記事では、APIキーの作成と使い方を説明します。この画面を開けるのはオーナーと管理者だけです（編集・経理・サポートのロールには表示されません）。

1. APIキーを作成する

左メニューの「設定」→「API」を開き、「APIキーを作成」を押します。用途が分かるキー名と、権限（スコープ）を設定します。

APIキーの作成フォーム
  • read：GET（一覧・詳細の取得）ができます。
  • write：POST/PUT（作成・更新・送付）ができます。

必要な権限だけを付けるのがおすすめです（読み取りだけならreadのみ）。

2. キーは作成時に一度だけ表示されます

「作成する」を押すと、キーがその場で一度だけ表示されます。この画面を離れると再表示できませんので、今すぐコピーして安全な場所に保管してください。キーはパスワードと同じ機密情報です。公開リポジトリやブラウザ側のコードには絶対に書かないでください。

作成したAPIキーの表示と一覧

作成したキーは一覧に並び、キー名・先頭の識別子・スコープ・最終使用日時が確認できます。不要になったキーはゴミ箱アイコンから削除でき、削除するとそのキーを使う連携は即座に動かなくなります（削除は取り消せません。同じキーを復活させることはできないので、必要になったら作り直してください）。キーが漏れたかもしれないときは、先に新しいキーを作って連携先を差し替えてから、古いキーを削除すると、連携を止めずに入れ替えられます。なお、キーの作成と削除は操作ログにも記録されます（ヘルプ記事「操作ログで運営の記録を確認する」）。

3. 使い方（呼び出しとレート制限）

作成したキーを Authorization: Bearer ヘッダーに付けて、公開API /api/v1 を呼び出します。

curl -H "Authorization: Bearer nk_live_..." \
  https://nakaama.com/api/v1/tenants/<コミュニティID>/contacts
  • GET（取得）にはreadスコープ、POST/PUT（作成・更新）にはwriteスコープが必要です。
  • レート制限はキー毎に毎分60リクエストです。ためられるのは60回分で、使った分は1秒に1回ずつ回復します（毎分ちょうどにまとめて戻るのではありません）。つまり60回まではまとめて叩けますが、そのあとは平均して1秒に1回のペースになります。超えると 429 が返るので、まとめて処理するときは1秒あたり1回を目安に間隔をあけてください。
  • 最終使用日時は1分ごとに更新されます。呼び出した直後に一覧を見ても変わっていないことがありますが、動いていないわけではありません。
  • 一覧は分けて返ってきます：一覧の取得（GET）は ?offset=0&limit=50 で位置と件数を指定できます。指定しないと50件、指定できるのは100件まで（それ以上を指定しても100件になります）。応答には items と、その条件での総件数 total が入っているので、offset を増やしながら total に届くまで繰り返せば全件を取得できます。

4. 取得・操作できるもの

公開APIでは、コミュニティの主要なデータを読み取れます。読み取り（GET）が中心で、書き込みができるのは顧客・商品・FAQ・問い合わせへの返信です。

  • 顧客：一覧・詳細の取得に加えて、作成・更新、さらにタグの付け外しとクーポンの付与ができます（/contacts）。外部フォームやCRMから流し込む用途に使えます。
  • ショップ：商品の一覧・詳細に加えて、商品の作成・更新（/products）。注文は一覧・詳細の取得のみ（/orders）。
  • FAQ：一覧の取得と、作成・更新（/faqs）。
  • サポート：問い合わせの一覧・詳細と、返信の送信（/inquiries）。
  • 会員：加入者の一覧・詳細（/members）。
  • 投稿：投稿の一覧（/posts）。
  • チケット：イベントの一覧・詳細と、イベントごとの購入者（/events）。
  • 予約：予約メニューと予約の一覧（/booking/menus・/bookings）。
  • プラン：料金プランと購読の一覧（/plans・/subscriptions）。
  • フォーム：フォームの一覧と、フォームごとの回答の取得（/forms）。

上の一覧はAPIリファレンス（OpenAPI）と同じ内容です。追加や変更があったときはリファレンス側が先に更新されるので、実装の前にそちらもご確認ください。

売上をスプレッドシートに集計する、会員名簿を社内システムと同期する、問い合わせを別のツールから返信する、といった使い方ができます。パラメータや戻り値の詳細は、管理画面の「API」右上の「APIリファレンスを見る」から確認できます。

外部サービスとの連携を自動化したいときは、ヘルプ記事「ワークフローで自動化する」もあわせてご覧ください。

5. Webhookでイベントを受け取る（APIを叩き続けなくてよくなります）

「新しい注文が入ったか」をAPIで何度も確認しにいく代わりに、できごとが起きた瞬間にナカーマ側から通知を送ることもできます。これがWebhookです。設定の「連携」を開き、「Webhook配信」の「Webhookを管理」を押すと一覧が開きます。ここで「Webhookを追加」から登録します。

登録するのは、通知を受け取るURLと、どのできごとを知らせるかの2つです。選べるできごとは次の12種類です。

  • 商品が購入されたら／チケットが購入されたら／予約が入ったら
  • フォームに回答があったら／問い合わせが届いたら
  • 新しい会員が入会したら／サブスク（月額プラン）が開始されたら／解約されたら
  • レビューが投稿されたら／記事にリアクションがついたら
  • 商品にコメントがついたら／イベントにコメントがついたら
Webhookを追加する画面（送信先URLと通知するイベントの一覧）

ZapierやMakeなどの自動化サービス、あるいは自社のサーバをURLに指定して、売上をスプレッドシートに追記する、社内チャットに通知する、といった使い方ができます。

6. 署名シークレットで「本物か」を確かめる

Webhookを登録すると、署名シークレットが発行されます。これは作成したときに一度だけ表示され、あとから見直すことはできません（あとから確認できるのは、Webhookの詳細画面に出る末尾4桁だけです）。その場でコピーして、安全な場所に保管してください。APIキーと同じく、パスワードと同等の機密情報です。

ナカーマから届く通知には X-Nakaama-Signature というヘッダが付きます。中身は sha256= に続けて、本文（リクエストボディ）を署名シークレットで HMAC-SHA256 した値を16進数で並べたものです。署名の対象は受け取った本文そのままなので、受信側でJSONを読み直して組み立て直した文字列で計算すると一致しません（生のバイト列のまま検証してください）。受信側でこのシークレットを使って署名を検証すると、その通知が本当にナカーマから来たものかを確かめられます。検証の具体的な手順は、管理画面の「API」右上の「APIリファレンスを見る」に載っています。

登録できるのは https のURLだけです。社内ネットワーク向けのアドレスなど、外から到達できない宛先は登録できません。

7. 届いているかを確かめる・止まったときは

  • テスト送信：Webhookの詳細画面から、サンプルの通知を実際に送って受信を確認できます。登録した直後の動作確認に使ってください。
  • 配信ログ：いつ・どのできごとを送って、相手が何を返したかが一覧で残ります。うまくつながらないときは、ここで原因を切り分けられます。残るのはWebhookごとに新しい順で100件までで、それを超えると古いものから消えていきます。失敗を調べるときは、あとの配信で押し流される前に見てください（件数の多いできごとを購読していると、数時間で入れ替わることもあります）。
  • 受信側は 2xx を返してください：ナカーマは応答が 200 などの成功でなければ「届かなかった」とみなします。処理に時間がかかる場合でも、いったん受け取って成功を返し、中身の処理は非同期にするのが安全です。
  • 転送（リダイレクト）は追いかけません：受信先のURLが別のURLへ転送する設定になっていると、その先までは届きません（安全のための制限です）。転送のない、最終的なURLを登録してください。
  • 失敗すると自動で再送します：1分後・5分後・30分後の3回まで送り直します。それでも届かなければ、その配信は失敗として記録されます。
  • 続けて失敗すると自動で停止します：再送しても届かない配信が20回続くと、そのWebhookは自動的に無効になり、通知センターでお知らせします（1回でも成功すれば数え直しになります）。受信先を直したら、詳細画面の「有効にする」で再開できます。再開すると失敗の数え直しはゼロに戻り、署名シークレットもそのままなので、受信側の設定を入れ直す必要はありません。

なお、ワークフローのアクションにも「Webhookを送る」があります。こちらは組み立てたフローの中の1ステップとして、条件を満たした人についてだけ送るものです。ここで説明しているWebhook配信は、コミュニティ全体のできごとを丸ごと受け取る仕組みで、目的が違います（ヘルプ記事「ワークフローで自動化する」）。