API v1でデータの送受信を行う場合、XML形式を利用します。
リクエストフォーマット
<?xml version="1.0" encoding="UTF-8" ?>
<mail>
<!-- 認証パラメータ -->
<auth>
<site id="0"/><!-- アクセスするサイトID -->
<service id="0"/><!-- 利用するサービスID -->
<name><![CDATA[xxxxx]]></name><!-- ログインするユーザID -->
<pass><![CDATA[xxxxxx]]></pass><!-- ログインパスワード -->
</auth>
<!-- API個別データ部分。複数指定可。 -->
<delivery id="0"><!-- IDはXML内で一意とすると、結果判別が容易 -->
<action>個別処理名称</action><!-- 使用するAPI指定 -->
<!-- 各API個別内容-->
</delivery>
</mail>
<?xml version="1.0" encoding="UTF-8" ?>
<mail>
<auth>
<site id="0"/>
<service id="0"/>
<name><![CDATA[xxxxx]]></name>
<pass><![CDATA[xxxxxx]]></pass>
</auth>
<delivery id="0">
<action>個別処理名称</action>
</delivery>
</mail>
レスポンスフォーマット
レスポンスはエラーの発生タイミングによって2つのフォーマットがあります。
- API個別処理実施以前でエラーが発生した場合(deliveryタグなし)
<?xml version="1.0" encoding="UTF-8"?>
<mail>
<!-- API個別結果を含みません。 -->
<result code="0">エラーメッセージ</result >
<errors>
<error kind="xxxxxxxx" code="0000">エラーメッセージ</error>
</errors >
</mail>
- API個別処理にてエラーが発生した場合
<?xml version="1.0" encoding="UTF-8"?>
<mail>
<!-- API個別結果。複数指定有。 -->
<delivery id="x">
<!-- 各API個別内容 --><!-- エラー時は付与されない場合もあります -->
<!-- 処理結果 -->
<result code="0">エラーメッセージ</result><!-- 成功・失敗の表示 -->
<!-- 発生エラーリスト -->
<errors>
<!-- 複数のエラーが発生すれば、複数の情報が付与されます -->
<error kind="xxxxx" code="0000">エラーメッセージ</error>
</errors >
</delivery>
</mail>
リクエスト・レスポンス共通フォーマット
XML宣言
<?xml version="1.0" encoding="UTF-8"?>
上記表記で固定となり、必ず先頭に設定します。
XML内の文字コードはUTF-8で記述します。
<?xml version="1.0" encoding="UTF-8"?>
<mail>
<result code="0">エラーメッセージ</result >
省略
</mail>
ルート要素であり、API v1で使用するXMLをまとめる唯一の要素です。
以下の構成を含みますが、リクエスト・レスポンスで構成が異なります。
構成要素 | リクエスト時 | レスポンス時 |
auth |
〇 | ー |
delivery |
〇 | 〇 |
result |
ー | 〇 |
errors |
ー | 〇 |