mixi Developer Center (ミクシィ デベロッパーセンター)

mixiアプリ

mixiアプリ » 技術仕様(Graph API方式) » モバイル » リクエストAPIについて

リクエストAPIについて

リクエストAPIを利用することで、ユーザは友人に「花束を贈りますので受け取ってください」といった要求を送信することができます。

ユーザ認可の取得

リクエストAPIを利用するためには、mixi_apps2スコープのユーザ認可を取得する必要があります。
詳しくは ユーザ認可について を参照ください。

友人にリクエストを送信する

mixiアプリモバイルからリクエストAPIを利用するには、招待機能を利用する場合と同様に、invite:friendsユーザフローを利用します。

invite:friends?callback=[エスケープ済みURL]

リクエストAPIにおけるinvite:friendsユーザフローの利用は、formタグを使ったPOSTメソッドによるHTTPリクエストとなります。具体的なリクエストの内容は、type属性がhiddenであるinputタグを使って記述します。指定可能なパラメータは、以下となります。

callback リクエスト送信完了画面(*)へ遷移するエスケープ済みのURLを指定します。
*SAPサーバに用意していただく必要があります。
recipients カンマ区切りで1つ以上のユーザIDが指定された場合は、そのユーザが初期選択状態&優先的に表示されます。
message メッセージの本文。
image メッセージに含める画像のURL。末尾にMIME typeをカンマ区切りで指定する必要があります。但し4KB以上の画像を受信すると相手にはNo Imageの画像が表示されます。
filter_type リクエストの対象となるユーザの種別。joined, not_joined, bothのいずれかを指定。
url リクエストをユーザがクリックした際の飛び先のURL(for PC, Touch)。
mobile_url リクエストをユーザがクリックした際の飛び先のURL(for Mobile)。
target_users ユーザに表示したい友人のリスト。友人全員を表示するのではなく、特定の友人に限定したい場合に、カンマ区切りで表示したい友人のユーザIDを列挙します。
description 友人の選択を促す説明文をmixiアプリ側で変更したい場合に使用します。
exclude_users ユーザの表示から除外する友人のリスト。カンマ区切りで除外する友人のユーザIDを列挙します。

また、ユーザがアクセスしている端末のキャリアがドコモの場合には、”guid=ON”パラメータも付加してください。

なお、パラメータで指定した値が長い場合、キャリアによっては送信できる上限に達する場合がありますので、ご注意ください。

リクエスト例
<form action="invite:friends?callback=[エスケープ済みURL]&guid=ON" method="POST">
  <input type="hidden" name="recipients" value="xxxx,yyyy" />
  <input type="hidden" name="message" value="花束を贈りますので受け取ってください" />
  <input type="hidden" name="filter_type" value="joined" />
  <input type="hidden" name="image" value="http://server.name/image.gif,image/gif" />
  <input type="hidden" name="url" value="http://mixi.jp/run_appli.pl?id=[アプリID]&appParams=..." />
  <input type="hidden" name="mobile_url" value="http://ma.mixi.net/[アプリID]/?..." />
  <input type="submit" value="送信!" />
</form>

appParamsはJSON形式で表しURIエスケープします。
appParams以外のパラメータ名を指定した場合でもアプリの起動URLとしてパラメータは付与されますが、
TouchにおいてはappParamsで指定したパラメータのみバックエンドサーバへ送信されます。
(例:「{"uid":"1569"}」をURIエスケープして「%7B%22uid%22%3A%221569%22%7D」)

appParams=%7B%22uid%22%3A%221569%22%7D

もし友人全員ではなく、限定した友人のみを表示したい場合は、以下のようにtarget_usersを指定します。この場合、xxxx, yyyy以外の友人は表示されず、その中でyyyyのユーザにチェックが入った状態となります。

<form action="invite:friends?callback=[エスケープ済みURL]&guid=ON" method="POST">
  ....
  <input type="hidden" name="recipients" value="yyyy" />
  <input type="hidden" name="target_users" value="xxxx,yyyy" />
  <input type="submit" value="送信!" />
</form>

また、特定の友人を除外して表示したい場合は、以下のようにexclude_usersを指定します。この場合、xxxx,yyyy以外の友人が表示されます。

<form action="invite:friends?callback=[エスケープ済みURL]&guid=ON" method="POST">
  ....
  <input type="hidden" name="exclude_users" value="xxxx,yyyy" />
  <input type="submit" value="送信!" />
</form>

また、もし各mixiアプリが説明文を変更したい場合は、以下のようにしてdescriptionを指定します。

<form action="invite:friends?callback=[エスケープ済みURL]&guid=ON" method="POST">
  ....
  <input type="hidden" name="description" value="ギフトを贈りたい人を15人までで選択してください!" />
  <input type="submit" value="送信!" />
</form>

送信したユーザおよびリクエストIDの取得について

ユーザが確認画面で”はい”を押すと、指定したコールバックURLにリダイレクトされます。実際にユーザが誰に送信したかは、コールバックURLに対してQuery String形式でデータが送信されます。”request_member”パラメータにユーザIDがカンマ区切り形式で渡されます。また、同時に作成されたリクエストのIDに関しても、”request_id”パラメータとして渡されます。リクエストIDはSAP側で保持し、後に対象のリクエストを削除したいときに利用可能です。

http://example.com/foo?request_member=xxxx,yyyy,zzzz&request_id=abc

エラーコード

もし何らかのエラーが発生した場合は、コールバックURLが呼び出される際に、resultパラメータにfalseが、errorパラメータに具体的なエラーコードが指定されます。エラーコードの詳細は以下となります。

エラーコード 概要
401 (UNAUTHORIZED) mixi_apps2スコープの認可を保持していないとき
400 (BAD_REQUEST) パラメータ指定エラー(不正なrecipients指定、不正なmessage指定、不正なcallback指定、不正なimage指定、不正なfilter_type指定、不正なurl指定、不正なmobile_url指定、不正なtarget_users指定、不正なexclude_users指定)
403 (FORBIDDEN) ユーザがキャンセルした(アプリに戻るリンクを押下した)
500 (INTERNAL_SERVER_ERROR) mixi側の内部エラー

リクエストの削除について

送信されたリクエストをSAP側から削除する際には、Graph APIを使用します。詳しくは以下のページを参照ください。

リクエスト削除API

このページの上部へ