1. Zenback 連携 API 概要
シックス・アパート株式会社

2. 概要
 Zenback（無料版）を、サイトプロバイダサービ
スに組み込むAPIです。
 サービサー様用にZenbackアカウントIDとキー
(APIの実行キー)を発行します。そのキーを使っ
て、ユーザ運営の各サイト用のZenbackのスクリ
プトコードを取得/削除できます。
※現在は、ユーザごとの表示内容のカスタマイズ
はできません。
 ユーザは管理画面のZenback表示ON/OFFボタン
で簡易にZenbackを自サイトに設置できます。

3. API 仕様概要
※仕様詳細は別スライド
 ADD API概要
 指定のEndpointに対しPOSTで各パラメータ情報（API KEY/アカウン
トID/URL/Signature/Twitter ID）を送信すると、サイトIDと成功/エ
ラーメッセージをJSON形式で返します。
 サービサー側では、URL／アカウントID／(APIより取得した)サイト
IDを使いZenbackスクリプトコードを組み立て、サイトの任意の位置
に設置します。また、関連精度を向上するために、Zenbackタグも同
時に設置します。（ZBタグはオプション、ですが強く推奨します）
 REMOVE API概要
 指定のEndpointに対しPOSTで各パラメータ情報（API KEY/アカウン
トID/サイトID/Signature）を送信すると、Zenback側でブログのNSID
とサイトの登録情報を破棄します。
 サービサー側では、サイトに設置したZenbackのスクリプトコードを
削除してください。

4. API利用フロー 通常時
ユーザ サービサー Zenback
管理画面よりZenback利用をON ADD API にリクエスト
ブログURLなどを送信:
http://www34.atwiki.jp/test/ APIリクエストを受け取り、
ブログIDを発行して返す
ブログIDを使ってZbコードを組み立
て、サイトテンプレート任意の位置に 取得するブログID例:
設置 89832934667764360
組み立てるZBコード例:
<!-- X:S ZenBackWidget -->（略）
base_uri=http://www34.atwiki.jp/test/
&nsid=
89179659941489196::89832934667764360
ユーザサイトにて （略）<!-- X:E ZenBackWidget 
Zenback 利用中
管理画面よりZenback利用をOFF REMOVE API にリクエスト、
ブログ登録情報を破棄
もしくはサイトを削除 サイト設置済みのコードを削除

5. API利用フロー スパム検知時
ユーザ サービサー Zenback
特定のサイトをスパム認定し、
メールにて削除依頼
対策（例）：
・ユーザへのアナウンスの有無
サイトにて
Zenback 利用中
・サイトからZBコード削除
・ZBへREMOVE APIコール
ブログ登録情報を破棄

6. ADD API 仕様書
 Endpoint: https://api.zenback.jp/v1/blog/add/
 HTTP method: POST
 Response format: JSON
 Parameter:
 api_key: API Key。指定必須。
 nsid: サービサーのzenbackで発行されたアカウントID。指定必須。
 このパラメータの指定フォーマットは数字形式で最大19桁まで可能。
 url: RSSフィードが取得できるブログのURL。指定必須。
 指定できるURL文字列の長さは、256文字まで。
 signature: パラメータ(signature自身は除く)の署名 (HMAC-SHA1による署名)。指定必須。
 twitter_id: 登録するブログにWidgetとして貼りつけられるFollowボタンに指定するTwitterアカウント。指定オプ
ション。
 指定がない場合は、zenbackのデフォルト(zebanckのTwitterアカウント)が指定される。
 指定できる文字列の長さは、256文字まで。
 Response (HTTP body):
 成功: {“status”: {“code”: 0,“msg”: “OK”},“result”: {“blog_nsid”: “103333333333”}}
 失敗 {“status”: {“code”: 1,“msg”: „‟No access is allowed”},“result” {}}
 HTTP status code:
 Success: 200
 Error: 400, 401, 500
 このAPIで成功したら、Zenback側はブログを登録する。サービサー側は NSIDを受け取るので、Zenbackのス
クリプトコードを生成しテンプレート内任意の箇所に設置。
 なお、スクリプトコード(scriptタグ)のNSIDには、”nsid::blog_nsid”の形式で指定すること。例：
89179659941489196::89832934667764360(“::”はエスケープ(%3A%3A)してください。)

7. REMOVE API 仕様書
 Endpoint: https://api.zenback.jp/v1/blog/remove/ (for Secure)
 HTTP method: POST
 Response format: JSON
 Parameter:
 api_key: API Key。指定必須。
 nsid: サービサーのzenbackで発行されたユーザーNSID。ユーザーNSIDはユーザーのIDで
ある。指定必須。このパラメータの指定フォーマットは数字形式で最大19桁まで可能。
 blog_nsid: zenbackで発行されたブログNSID。ブログNSIDはブログのIDである。指定必
須。add API でブログを登録した際にレスポンスで受け取ったブログNSID(resultオブジェ
クトのblog_nsid)を指定する。このパラメータの指定フォーマットは数字形式で最大19桁
まで可能。
 signature: パラメータ(signature自身は除く)の署名 (HMAC-SHA1による署名)。指定必
須。
 Response (HTTP body):
 成功のケース {“status”: {“code”: 0,“msg”: “OK”},“result”: {}}
 エラーのケース {“status”: {“code”: 1,“msg”: „‟No access is allowed”},“result” {}}
 HTTP status code:
 Success: 200
 Error: 400, 401, 500
 このAPIで成功したら、サービサーはZenbackのスクリプトコードをテンプレートから外す

8. API エラーコード
APIエラーコード(code) APIエラーメッセージ(msg) 説明
0 OK APIのコールが正常に完了
1 No access is allowed APIのコールの許可されていない
2 Missing parameter 何らかの必須パラメータが指定されていない。
指定された何らかのパラメータの中の値が不正の場合。
3 Invalid parameter （例：数字を指定するのにアルファベットが指定されてい
た）
4 Not registered nsid 指定したNSIDがzenbackに登録されていない
5 Not registered blog_nsid 指定したブログNSIDがzenbackに登録されていない
99 Not supported APIリクエストが未サポート
100 Occured internal error zenback 内部でエラーが発生
101 Occured unexpected error zenback で予期しないエラーが発生

9. HTTPステータスコード
HTTP ステータスコード 説明
200 ・API リクエストが正常に完了
・必須のパラメータが指定されていない
・パラメータの値が不正
400
・パラメータで指定した nsid が zenback に登録されていない
・パラメータで指定した blog_nsid が zenback に登録されていない
・API リクエストの認証が失敗
401
・オプションで指定するパラメータで空文字が指定されている
404 ・API リクエストが未サポート
500 ・zenback 内でエラー

10. Zenback スクリプトコード仕様
<!-- X:S ZenBackWidget --> <script type="text/javascript">
document.write(unescape("%3Cscript")+"
src='http://widget.zenback.jp/?base_uri=TARGET_BLOG_URL&nsid=TARGET_NS
ID&rand="+Math.ceil((new Date()*1)*Math.random())+"'
type='text/javascript'"+unescape("%3E%3C/script%3E")); </script> <!-- X:E
ZenBackWidget -->
 TARGET_BLOG_URL
 設置サイトのトップページURL
 例）http://www.example.com/
 wwwの有無は厳密に扱います（例、www有りURLでコード設置した場合にはwww無しで
ページを表示した際、Zenbackは表示されません）
 末尾の/は追加してください
 TARGET_NSID
 ZenbackのアカウントIDとサイトIDを組み合わせて生成。詳細は次ページ参照。
 "::"はURLエスケープを行う。 ":" -> "%3A”
 例
<!-- X:S ZenBackWidget --><script type="text/javascript">document.write(unescape("%3Cscript")+"
src='http://widget.zenback.jp/?base_uri=http%3A//sixapart.jp/&nsid=99179133006822097%3A%3A99179150723548980&rand="+Math.ceil((ne
w Date()*1)*Math.random())+"' type='text/javascript'"+unescape("%3E%3C/script%3E"));</script><!-- X:E ZenBackWidget -->

11. アカウントIDとサイトIDについて
 NSIDはアカウントIDとサイトIDを用いて生成す
る、
サイト固有のID。
 NSIDの形式
 [アカウントID]::[サイトID]
 36 bytes ([半角数字17-19文字] + "::" + [半角数字17-
19文字]) (可変)
 アカウントIDはサービサー毎に一つ付与
 サイトIDはブログごとに異なる
例
 99179133006822097::99179150723548980
※（前半がアカウントID）:: (後半がサイトID)

12. Zenbackタグの設置
 Zenbackタグとは？
 Zenbackの記事インデックス用クローラが各
記事のタイトルと本文を正しく検知するため
に、サイトに設置しておくタグです。HTML
のコメントタグを使います。
 関連精度向上のため、設置を強く推奨します
 詳細は下記ページをご覧ください
 http://nanapi.jp/29761/

13. Zenbackタグ／スクリプトコードの
設置位置
 添付の atwiki_zenback_setting.png 画像
をご覧ください。

14. APIの諸注意事項
 Twitter_idのようなパラメータの指定がオプショ
ンの場合、空文字を指定した場合は、レスポンス
は、HTTP のステータスコードは 401 になり、
zenback のステータスコード(レスポンスで受け
取ったstatusオブジェクト)は(statusオブジェクの
codeプロパティ) 1 になります。
 オプション系のパラメータは、指定しない場合は
zenbackのデフォルト値が設定されます。オプ
ション系のパラメータを指定する場合は、デフォ
ルト値以外にしたい場合は、必ず何らかの値を設
定してください。

15. ユーザ向けアナウンス＆
インターフェース

16. 管理画面インターフェース（例）
記事下部にZenbackを表示する
▲
表示する ▼
表示しない
Zenbackの利用規約に同意しました。
※ドロップダウン、ON/OFFトグルなど、排他的に表示/非表示を
選ぶことが出来る設定画面をご用意ください。
※Zenbackの利用規約に同意してもらう項目を追加してください。
利用規約にチェックしないと、利用できないようにしてください。
利用規約リンク先：http://blog.zenback.jp/terms.html

17. 設置に関する諸注意事項
（ユーザ向けアナウンス）
 Zenbackのコードを貼ってから、「関連記事」「関連
リンク」が表示されるまで、数時間～最大数日ほど
かかる場合があります。ご了承ください。
 Zenbackのコードを貼ってから、「Twitter」「はてな
ブックマーク」が表示されるまで、数分～最大数時
間ほどかかる場合があります。ご了承ください。
 Twitter、はてなブックマーク、Facebookなどの連携
サービス元で問題が発生して、Zenbackに最新の情報
が表示されない場合があります。ご了承ください。
 RSSを出していないサイトではZenbackを貼ることが
できませんので、ご注意ください。
 パスワード保護されているサイトではZenbackを貼る
ことができませんので、ご注意ください。