開発者向け

Naruko SIP API の使い方

お客様のシステム（CRM・一括管理ツール等）から、SIPプロファイルと 発信プレフィックスを登録・編集・削除・検索できます。利用には組織スコープの API キーが必要で、 Pro プランの組織でのみ使えます。

ベース URL: https://hub.naruko.app/api/naruko-sip/v1

事前準備（API キーの発行）

利用者画面の SIP → API キー画面でキーを発行します（組織管理者・Pro プランのみ）。キーは nrk_org_… 形式です。

平文キーは発行時に一度だけ表示されます（サーバーには sha256 ハッシュのみ保存され、再表示できません）。失くしたらローテーションで作り直します。
キーは失効（revoke）・ローテーション（rotate）できます。漏えい時はローテーションで即座に旧キーを無効化してください。

API キー画面。ラベルと環境（サンドボックス / 本番）を選んで発行し、発行済みキーの失効・ローテーションができる — API キー画面（発行・失効・ローテーション）

認証

各リクエストに API キーを付けます。Authorization: Bearer <key> を推奨、代替として X-Api-Key: <key> も使えます。

curl https://hub.naruko.app/api/naruko-sip/v1/sip-profiles \
  -H "Authorization: Bearer nrk_org_xxxxxxxx"

認証に失敗（未提示 / 無効 / 失効 / 期限切れ）すると 401 を返します。
Pro プラン以外の組織のキーは 403 になります。
レート制限は 1 分あたり 120 リクエスト（組織単位）。超過すると 429 を返します。

SIPプロファイル

メソッド	パス	用途
GET	/sip-profiles	一覧・検索（?tag=タグ / ?q=label 部分一致）
POST	/sip-profiles	登録（201）
GET	/sip-profiles/{id}	1件取得
PUT	/sip-profiles/{id}	編集
DELETE	/sip-profiles/{id}	削除

入力フィールド（すべて任意）: label, tags（配列）, display_name, server, sip_domain, transport, codecs（配列）, username, password ほか。

curl -X POST https://hub.naruko.app/api/naruko-sip/v1/sip-profiles \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"label":"本社","tags":["営業","東京"],"server":"sip.example.jp","username":"u1","password":"p1"}'

?tag=営業 でタグ絞り込み検索ができます。
レスポンスにパスワードは含まれません（has_credentials の真偽のみ）。
テンプレートの利用者への配信（割り当て）は利用者画面で行います。本 API はテンプレート自体の管理に限ります。

発信プレフィックス

メソッド	パス	用途
GET	/caller-id-prefixes	一覧・検索（?q=prefix/name 部分一致）
POST	/caller-id-prefixes	登録（sort_order 自動採番・201）
GET	/caller-id-prefixes/{id}	1件取得
PUT	/caller-id-prefixes/{id}	編集
DELETE	/caller-id-prefixes/{id}	削除

入力フィールド: prefix（必須・数字と * # のみ）, name（必須）, emoji（任意）。

エラー

401 認証エラー（キー未提示・無効・失効・期限切れ）
403 Pro プラン以外の組織
404 他組織のリソース・存在しない ID
422 バリデーションエラー（例: prefix に数字と * # 以外）
429 レート制限超過