Nico API Document (1.2.4)

変更履歴

バージョン 操作
1.2.4 全角で登録頂く項目に最大文字数を追加
1.2.3 契約形態ごとの必須項目条件記載を追加
1.2.2 契約申込APIの稼働時間を24/365に変更
1.2.1 API共通仕様を追加、契約申込注意点を追記
その他細かい仕様を追記
1.2 申込タイプに家賃保証/ネットを追加
保証契約管理システム連携に向けた代理店認証方式の説明内容修正
1.1.2 申込タイプにネット代理店領収を追加
1.1.1 契約者同一区分のデフォルト追加
1.1 契約申込注意点の説明を追加
1.0 代理店認証、保険契約申込操作の API 仕様書をリリース

機能一覧

Nico API は以下の機能を持ちます。

代理店認証

tag 操作 Endpoint Method 稼働時間
Agency-Auth 認可コード要求 /auth/agency/oauth GET 24/365
Agency-Auth 代理店ログイン /auth/agency/authorize GET 24/365
Agency-Auth 認可コード発行 /auth/agency/approve POST 24/365
Agency-Auth 代理店ログインキャンセル /auth/agency/cancel GET 24/365
Agency-Auth 代理店トークン発行 /auth/agency/token POST 24/365

保険契約申込操作

tag 操作 Endpoint Method 稼働時間
Entries 契約申込 /entries POST 24/365
Entries 契約状況照会 /entries/{contract_token} GET 24/365

代理店認証

概要

保険契約申込操作を行うAPIをコールする際には事前に代理店認証を行い、代理店トークンの発行を行う必要があります。

代理店認証方式

認証方式の種類

OAuth2.0( RFC 6749 )で定義されている、2種類のグラントに対応した認可・認証サービスを提供します。

  • 認可コードグラント
  • クライアントクレデンシャルグラント

※ 定義参照) RFC 6749: The OAuth 2.0 Authorization Framework

認可コードグラントで発行されるトークンも、クライアントクレデンシャルグラントも、リソースサーバ側では同じフォーマットのトークンとして検証され、トークン内部に記載されている scope 等により認可範囲が確認されます。

認証方式の種類の使い分け

認証方式により認可されるAPIの種類(scope)が異なります。
賃貸契約管理プラットフォームからの契約申込のように代理店ユーザからの要求に応じてコールを行うことが想定される場合は認可コードグラント、契約状況照会APIのようにバッチ処理等の自動処理でAPI要求を行うことがある場合はクライアントクレデンシャルグラントで取得する代理店トークンに認可を付与しています。

家賃保証会社の保有する保証契約管理システムで家賃保証申込が承認された際に契約申込をする場合など、代理店ユーザの要求がない情報連携に際してはクライアントクレデンシャルグラントで取得する代理店トークンにも契約申込の認可を付与する場合があります。 詳細は当社営業担当にお問い合わせ下さい。

認可コードグラントで取得した代理店トークンは3日間、クライアントクレデンシャルグラントで取得した代理店トークンは1日の有効期限があります。

事前準備

Nico API利用申込

当社営業担当に利用開始希望のご連絡をお願いします。
認可コードグラントをご利用される場合、事前に callback_uri を登録させていただきます。 クライアントクレデンシャルグラントを利用される場合、当社がご利用頂く代理店ごとに発行する client_id, client_secret の文字列を貴社システムに保持頂く必要があります。

認証方法に関わらずご提供する情報

認可コードグラント、クライアントクレデンシャルグラントを利用する場合のいずれも、プラットフォームIDをご連携いたします。 契約申込 API をリクエストする際、ご指定が必要となります。

認可コードグラント利用に必要な callback_uri 情報

認可コード要求リクエスト時、代理店ユーザを当社ログイン画面から貴社システムに画面遷移させるための redirect_uri(ログイン成功時の遷移先)、cancel_uri(戻るボタン押下時の遷移先) を指定いただきます。 redirect_uri と cancel_uri は事前登録頂く callback_uri と以下の方法で入力チェックを行いますので連携前にご用意が必要となります。

■ redirect_uri は callback_uri と前方一致で確認いたします。

例 )
callback_uri: https://www.n-ssi.co.jp/callback の場合

O redirect_uri: https://www.n-ssi.co.jp/callback?hoge=fuga
O redirect_uri: https://www.n-ssi.co.jp/callback
X redirect_uri: https://example.n-ssi.co.jp/callback

■ cancel_uri は callback_uri とホスト名一致で確認いたします。

例 )
callback_uri: https://www.n-ssi.co.jp/callback の場合

O cancel_uri: https://www.n-ssi.co.jp/callback?val=cancel
O cancel_uri: https://www.n-ssi.co.jp/cancel
O cancel_uri: https://www.n-ssi.co.jp/cancel?hoge=fuga
X cancel_uri: https://example.n-ssi.co.jp/callback

クライアントクレデンシャルグラント利用に必要な client_id, client_secret 情報

所定の情報連携方法にて代理店利用開始/終了の管理をさせていただきます。 利用開始前に当社が代理店ごとの client_id, client_secret を発行し、ご連携いたします。 代理店トークン取得時に利用できるよう、貴社システムにご登録をお願い致します。

利用登録後当社からお送りするパラメータ

項目名 内容
プラットフォームID 当社が不動産契約を識別するための不動産管理PF種別IDとなります。
契約申込APIで指定してください。
client_id クライアントクレデンシャルグラント認証に利用する
同名のパラメータとなりますが、認証コードグラントではこの値を利用しませんのでご注意ください。
client_secret クライアントクレデンシャルグラント認証に利用する

認可コードグラント認証シーケンス

クライアントクレデンシャルグラント認証シーケンス

クライアントクレデンシャルグラント認証シーケンス

クライアントクレデンシャルグラント認証シーケンス

API共通仕様

HEADERパラメータ

認証

代理店トークンの指定は Authorization: Bearer {{代理店トークン}} で指定してください。
例) CURLでの指定例
curl -H 'Authorization: Bearer {{代理店トークン}}'

BODYパラメータ

文字コード

本APIで利用する文字コードはUTF-8となります。
ただし契約申込APIで利用できる文字はSJISに変換可能な文字コードとなります。

文字数

本API仕様書に記載の最大文字数はSJIS換算でのバイト表記となります。
半角文字は1、全角文字は2としてカウントします。

日付パラメータの指定

日付を示すパラメータはYYYY/MM/DD(0埋めスラッシュ区切り)で指定してください。
例) 2023年12月1日 → 2023/12/01

郵便番号と電話番号

郵便番号と電話番号は数字のみで指定してください
例)
O 5300011
X 530-0011

O 09011112222
X 090-1111-2222

Agency-Auth

代理店認証

認可コード要求

認可コード要求を開始します

query Parameters
response_type
required
string
Value: "code"

認可コード要求のため 'code' という文字列をご指定ください。

pf_user_id
required
string

事前に登録した不動産管理PF種別IDと前方一致した pf_user_id を生成し指定してください。{ 不動産管理PF種別ID } + '-' + { PF内でユニークな user_id }

redirect_uri
required
string

申込時にご登録いただいた callback_uri をURLエンコード後指定してください。

cancel_uri
required
string

申込時にご登録いただいた cancel_uri をURLエンコード後指定してください。

state
required
string

不動産管理PFがリクエストを識別するためのパラメータ。リクエストごとに異なる値をご指定ください。

Responses

代理店ログイン

代理店ユーザのWebブラウザ上にて、代理店ログイン画面を表示します。/auth/agency/oauth のレスポンスヘッダーの location に指定された URL にリダイレクトします。

query Parameters
client_id
required
string

location ヘッダのリダイレクト先 URL に含まれる client_id をそのままご利用ください。

redirect_uri
required
string

location ヘッダのリダイレクト先 URL に含まれるリダイレクトURIをそのままご利用ください。

response_type
required
string

location ヘッダのリダイレクト先 URL に含まれる response_type をそのままご利用ください。

scope
required
string

location ヘッダのリダイレクト先 URL に含まれる要求スコープ をそのままご利用ください。

state
required
string

location ヘッダのリダイレクト先 URL に含まれる state をそのままご利用ください。

cancel_uri
required
string

location ヘッダのリダイレクト先 URL に含まれる cancel_uri をそのままご利用ください。

platform_id
required
string

location ヘッダのリダイレクト先 URL に含まれる不動産管理PF種別IDをそのままご利用ください。

Responses

認可コード発行

認可コード発行

Request Body schema: application/json
_token
required
string

代理店ログイン画面内 hidden 属性項目が利用されます。

client_id
required
string

代理店ログイン画面内 hidden 属性項目が利用されます。

auth_token
required
string

代理店ログイン画面内 hidden 属性項目が利用されます。

redirect_uri
required
string

代理店ログイン画面内 hidden 属性項目が利用されます。

nico_user_id
required
string

入力されたNicoのユーザーID

nico_password
required
string

入力されたNicoのパスワード

Responses

Request samples

Content type
application/json
{
  • "_token": "string",
  • "client_id": "string",
  • "auth_token": "string",
  • "redirect_uri": "string",
  • "nico_user_id": "string",
  • "nico_password": "string"
}

代理店ログインキャンセル

代理店ログイン画面でキャンセルボタンを押すと実行されます。

query Parameters
cancel_uri
required
string

キャンセル URI。事前登録したURLにリダイレクトされます。

Responses

代理店トークン発行

代理店トークン発行

Request Body schema: application/json
grant_type
required
string
Enum: "authorization_code" "client_credentials"

認可タイプの指定。認可コード(authorization_code)、クライアントクレデンシャル(client_credentials)

client_id
required
string

認可コード(authorization_code)の場合は前段のリクエストで利用したものをご指定ください。クライアントクレデンシャル(client_credentials)の場合は事前払い出しのものを指定してください。

redirect_uri
string

リダイレクトURI。前段のリクエストで利用したものをご指定ください。URLエンコードは行わないでください。認可コード(authorization_code)の場合は必ず指定してください。

code
string

一時認証コード。認可コード(authorization_code)の場合は必ず指定してください。

client_secret
string

クライアントクレデンシャル(client_credentials)の場合事前払い出しのものをご指定ください。

scope
string