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

Payload

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 クライアントクレデンシャル(client_credentials)の場合事前払い出しの権限範囲をご指定ください。

Responses

Response Schema: application/json; charset=UTF-8

token_type	string トークンタイプ
expires_in	integer 有効時間(秒)
access_token	string 代理店トークン

Request samples

Payload

Content type

application/json

Example

{"grant_type": "authorization_code",
"client_id": "40d1f87(中略)baff85e9",
"redirect_uri": "https://test.example.jp/redirect_uri",
"code": "def502001ee(中略)5d7d0c0a708df"
}

Response samples

200

Content type

application/json; charset=UTF-8

Example

{"token_type": "Bearer",
"expires_in": 604800,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ(中略)K-NA"
}

Entries

保険契約申込操作

保険契約の申込作成

契約申込注意点

個人・個人事業主契約の必須項目

以下の項目が必須項目となります。

契約者個人姓名
契約者個人姓名カナ
契約者生年月日

法人契約の必須項目

以下の項目が必須項目となります。

契約者法人名
契約者電話番号

氏名・住所の全角登録

契約者氏名、契約者法人名、契約者法人名サブ、契約者住所、被保険者氏名、対象物件住所は入力項目を全角に変換して登録します。

保険コース

保険コースは申込登録APIリクエストでコード指定するか、自動設定することが可能です。
当社代理店にはAPI連携開始前に単身/ファミリーと保険期間の組み合わせで、単身:2年、単身:1年、ファミリー:2年、ファミリー:1年の4パターンのコースを決定いただきます。
単身/ファミリーは以下の条件で判別を行います。

単身/ファミリー項目が指定された場合 → 指定したもの
総入居者数が指定された場合 → 1人の場合は単身、2人以上の場合はファミリー
平米数が指定された場合 → 45平米以下の場合は単身、45平米以上の場合はファミリー
間取りが指定された場合 → 1K, 1DK, 1R など 1から始まる場合は単身、それ以外はファミリー

契約形態

個人契約、個人事業主契約の場合、契約法人情報は連携されません。
法人契約の場合個人契約、個人事業主契約で利用する契約者氏名、契約者氏名カナは連携されません。契約者法人名の指定をお願いします。
法人契約、個人事業主契約の場合、法人特約を設定できます。

他社保険加入

「他社保険会社名」「他社保険証券番号」いずれかが指定された場合は「他社保険加入有無」を「1: あり」に設定します。

法人特約

法人特約を利用する場合被保険者情報の連携は不要となります。
連携が不要となるパラメータは「氏名」「氏名カナ」「電話番号」「生年月日」「性別」となります。

契約者住所

契約者住所は契約完了はがきをお送りする際の送付先となります。
不動産契約の申込者住所の場合旧住所が登録されている場合がありますが、保険契約の契約者住所は当社からの郵送物が届く住所をご指定ください。

契約者同一区分(続柄区分)

保険をかける対象物件に住む方(被保険者)が契約する場合と、一人暮らしのお子様のために親族の方が契約するなど保険契約者と保険契約者が異なる場合があります。
契約者と被保険者が異なる場合は2: 親族もしくは7: 第三者から選択してください。
また、契約者と被保険者が同一の場合でもセカンドハウスなど当社からの郵送物をお届けする住所(契約者住所)が保険対象物件(対象物件住所)と異なる場合があります。
契約者住所と対象物件住所が同一の場合は9: 本人、異なる場合は8: 本人(住所異なる) を選択してください。
契約者同一区分が9: 本人の場合、被保険者情報が契約者情報で上書きされ、リクエストパラメータは採用されません。
上書きされるパラメータは「氏名」「氏名カナ」「電話番号」「生年月日」「性別」「住所」となります。
契約者同一区分が9: 本人の場合、住所以外の被保険者情報が契約者情報で上書きされ、リクエストパラメータは採用されません。
上書きされるパラメータは「氏名」「氏名カナ」「電話番号」「生年月日」「性別」となります。

被保険者情報

契約形態が個人の場合、契約者同一区分(続柄区分)が8: 本人(住所異なる)または9: 本人の場合、被保険者情報は契約者情報で上書きされます。
上書きされる情報は姓名、姓名(カナ)、電話番号、生年月日の項目となります。
契約形態が個人の場合、契約者同一区分(続柄区分)が9: 本人の場合、保険の対象物件住所が契約者住所で上書きされます。
上書きされる情報は郵便番号、都道府県・市区町村・町名、丁目・番地、建物名、部屋番号となります。

Authorizations:

Request Body schema: application/json

	object 保険契約に関する情報を指定してください。
	object 契約者情報を指定してください。契約形態が法人の場合は契約者個人名(姓名・姓名カナ)、生年月日、性別は登録されません。
	object 法人契約者情報を指定してください。契約形態が個人/個人事業主の場合は登録されません。
	object 被保険者情報を指定してください。法人特約が付帯されている場合は、姓名(漢字)、姓名(カナ)、電話番号、生年月日、性別は登録されません。
	object Nico で登録されている代理店・店舗・募集人コードを指定してください認可コードグラントでログインした場合は自動指定されます。
required	object 不動産契約管理PFの情報を登録してください。

Responses

Response Schema: application/json

status	string ステータスコード
contract_token	string 契約トークン契約状況を照会するために保存してください。

Response Schema: application/json

status	string エラーコード
message	string エラーメッセージ

Response Schema: application/json

status	string エラーコード
message	string エラーメッセージ

Response Schema: application/json

status	string エラーコード
message	string エラーメッセージ

Response Schema: application/json

status	string エラーコード
message	string エラーメッセージ

Response Schema: application/json

status	string エラーコード
message	string エラーメッセージ

Request samples

Payload

Content type

application/json

{"contract": {"start_date": "2021/07/05",
"contractor_type": "2",
"has_corporate_condition": "1",
"is_instant_notificattion": "1",
"notification_method": "M"
},
"contractor": {"zip_code": "5300015",
"address": {"prefecture_city_street": "大阪府大阪市北区大深町",
"street_number": "1-1-5",
"apartment_name": "梅北マンション",
"room_number": "1004"
},
"phone": "08030303030",
"mail": "houjintarou@example.co.jp"
},
"corporate_contractor": {"corporate_type": "01",
"corporate_type_position": "B",
"corporate_name": "法人",
"corporate_name_kana": "ホウジン"
},
"agent": {"agency_cd": "100004",
"branch_cd": "002",
"agent_cd": "000402"
},
"source_platform": {"name": "nssi-web",
"contract_id": "nssi-web_YSsXeh(中略)4lDIQBmRFNsO"
}
}

Response samples

Content type

application/json

{"status": "200",
"contract_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuby(中略)dDboQSdkWGhZJi3Mcmw"
}

申し込み状況の照会

申し込み状況の照会を行います

Authorizations:

path Parameters

contract_token

required

string

申込API実行時に払いだされる契約トークン

query Parameters

agency_cd	string 代理店コード
branch_cd	string 店舗コード

Responses

Response Schema: application/json

status	string ステータスコード
	object 応答内容

Response Schema: application/json

status	string エラーコード
message	string エラーメッセージ

Response Schema: application/json

status	string エラーコード
message	string エラーメッセージ

Response Schema: application/json

status	string エラーコード
message	string エラーメッセージ

Response Schema: application/json

status	string エラーコード
message	string エラーメッセージ

Response Schema: application/json

status	string エラーコード
message	string エラーメッセージ

Response samples

Content type

application/json

{"status": 200,
"response": {"contract": {"policy_no": "110585600400",
"is_dupulicated": 0,
"status": "手続き中",
"entry_type": "ネット申込",
"entry_type_code": "N",
"application_date": "2021/06/30",
"payment_type": "一括",
"receipt_date": "2021/07/01",
"entry_accepted_date": "2021/07/01",
"notification_method": "S",
"notification_date": "2021/07/01",
"notification_result": 0,
"term": "2",
"start_date": "2021/07/05",
"start_time": 0,
"end_date": "2023/07/04",
"end_time": 24,
"recorded_date": "2021/07/01",
"fee": "20000円",
"total_fee": "20000円",
"insurance_name": "賃貸住宅総合保険２０２１",
"insurance_type_name": "住宅用・みんなの部屋保険Ｇ４",
"compensations": [{"name": "家財(主契約)",
"amount": 200
},
{"name": "賃貸住宅総合賠償責任特約2021",
"amount": 20000
}
]
},
"source_platform": {"contract_id": "nssi-web_personal_same_none_01"
}
}
}

	object 保険契約に関する情報を指定してください。
	object 契約者情報を指定してください。契約形態が法人の場合は契約者個人名(姓名・姓名カナ)、生年月日、性別は登録されません。
	object 法人契約者情報を指定してください。契約形態が個人/個人事業主の場合は登録されません。
	object 被保険者情報を指定してください。法人特約が付帯されている場合は、姓名(漢字)、姓名(カナ)、電話番号、生年月日、性別は登録されません。
	object Nico で登録されている代理店・店舗・募集人コードを指定してください認可コードグラントでログインした場合は自動指定されます。
required	object 不動産契約管理PFの情報を登録してください。