目次 2 of 45 1 序章目的改版履歴チーム名チームの使命メンバー名簿電子レシート API の利用基本フロー例外フローアプ

Size: px

Start display at page:

Download "目次 2 of 45 1 序章目的改版履歴チーム名チームの使命メンバー名簿電子レシート API の利用基本フロー例外フローアプ"

ふじよしいさし
5 years ago
Views:

1 1 of 45 電子レシート API 仕様書 V

2 目次 2 of 45 1 序章目的改版履歴チーム名チームの使命メンバー名簿電子レシート API の利用基本フロー例外フローアプリケーションの利用申請アプリケーションの権限ユースケース会員権限と企業権限についてそれぞれの一般的なユースケースを紹介します会員権限のアプリケーションでレシートを取得する会員権限のアプリケーションがレシートを登録する企業権限のアプリケーションがレシートを登録する会員権限のアプリケーションの概要アプリケーション情報の取得アクセストークンの取得リクエストの例... 15

3 電子レシート API 仕様書改訂日 : of 企業権限のアプリケーションの概要...17 アプリケーション情報の取得...17 アクセストークンの取得...17 リクエストの例 API 一覧電子レシート API の一覧会員 API 認証 API...20 リクエスト...20 レスポンス企業 API 認証 API...23 リクエスト...23 レスポンスレシート API レシート一覧取得 API...25 リクエスト...25 レスポンスレシート詳細取得 API...29 リクエスト...29 レスポンスレシート印字文字列取得 API...33

4 電子レシート API 仕様書改訂日 : of 45 リクエストレスポンスレシート PDF 取得 API リクエストレスポンスレシート登録 API リクエストレスポンス JSON Web Token JWT の構造ヘッダーペイロードシグネチャ JWT 改ざんの検出 JWT の利用認可された状態のリセット参照未解決の課題... 45

5 5 of 45 1 序章 1.1 目的本書は.NET 流通システム協議会の電子レシート分科会が作成した国際標準仕様である ARTS Digital Receipt V3.1.0 の日本国内での普及促進を目的とした標準電子レシート API のマニュアルである本仕様は従来ベンダー別業種業態別小売企業個別などで作成されていたレシートの印字項目を網羅的に洗い出しデータ活用の観点から同じ意味の項目は同じタグに格納することにより活用しやすくするデータ活用の為の器を提供することが目的である 1.2 改版履歴バージョンイベント変更日付初版修正レシート詳細取得 API のレスポンスの値引きオブジェクトを修正変更追加変更ログイン API を認証 API に変更クライアントの登録について追加 JWT の JSON の例に cid を追加追加レシート登録 API を追加変更クライアントの識別方式を変更追加変更企業認証 API を追加クライアントをアプリケーションに名称変更

6 6 of 45 追加追加アプリケーションの利用申請の説明を追記レシート登録 API の詳細を追記変更エラーの内容を変更変更追加三章の構成を変更レシート登録 API のヘッダーに Authorization を追加変更正式リリースの為の全体的な文書の見直しチーム名主幹.NET 流通システム協議会電子レシート分科会協力団体一般社団法人オープンフードサービスシステムコンソーシアムデジタルレシート分科会一般社団法人 FinTech 協会電子レシート分科会一般社団法人 XBRL Japan 1.4 チームの使命本チームの使命は販売時点の取引処理に完全なペーパーレス化が求められる現在の小売環境において ARTS で策定した国際標準仕様である ARTS Digital Receipt V3.1.0 の XML スキーマを参照しつつ日本国内要件に絞ってリファレンスマニュアルを作成することで電子レシートフォーマットの理解を容易にし JSON と REST を採用した最新テクノロジ環境への適用を実現して電子レシートの採用を促進することにある 1.5 メンバー名簿議長 ( 日本 ): Masanori Sambe 貢献者 ( 日本 ): TOSHIBA TEC CORPORATION

7 7 of 45 Jin Hashiba Daisaku Kashima Yasuo Sakami Yoshio Yamada Akira Matsuyoshi Koji Sasaki Soichi Fujii Akio Tajima Takuro Miyuki Kazutoshi Ota Tadashi Furuhata Ryo Hirukawa Yusuke Udagawa Takao Tamura Eiki Murakami Kenichi Nagai Masaaki Morishita Ayako Shimazaki Takahide Kubota Toyohiro Yasumoto 事務局 ( 日本 ): Soichi Fujii Dai Nippon Printing Co., Ltd Dai Nippon Printing Co., Ltd Foresight Co.,Ltd. FUJITSU LIMITED Insight Corporation LOG NOTE Co.,Ltd. Microsoft Japan Co., Ltd. NCR Japan, Ltd. NEC Platforms, Ltd. OK Systems Seiko Epson Corporation Sharp Business Solutions Corporation SHARP CORPORATION Sorimachi Giken Co.,Ltd Sorimachi Giken Co.,Ltd STAR MICRONICS CO., LTD. STAR MICRONICS CO., LTD. The Distribution System Research Institute TOSHIBA TEC CORPORATION VINX CORP. Microsoft Japan Co, Ltd. フードサービス仕様の貢献者 ( 日本 ): Tadashi Furuhata Seiko Epson Corporation Yoshio Ohba Seiko Instruments Inc. Yuu Kusama Open Foodservice Systems Consortium (OFSC) Kenji Oohashi DYNAC CO., LTD. Umetsu Noriyuki Fujitsu Isotec Limited Shinya Oikawa Public university corporation Miyagi university Kazuhiro Kobayashi Teraoka Seiko Co., Ltd. Masanori Murai ASKA-T3 Co., Ltd. Shigeru Okada Open Foodservice Systems Consortium(OFSC) Jun Watanabe NEC Platforms Limited Tsuneo Yashima Just planning Inc. Kiyoshi Kurokura CITIZEN SYSTEMS JAPAN CO. LTD. Koichi Shibata Seiko Solutions Inc. Ohko Fujii MOS FOOD SERVICES, INC. Kenichi Nagai STAR MICRONICS CO., LTD.

8 8 of 45 Makoto Yoshimura Naonori Nagata Yasuo Sakami TOSHIBA TEC CORPORATION TOSHIBA TEC CORPORATION Open Foodservice Systems Consortium (OFSC)

9 9 of 45 2 電子レシート API の利用 2.1 基本フロー電子レシート API の利用について基本フローを下図に示します基本フローでは電子レシート会員 ( 消費者 ) がアプリケーションを通して認証 API を利用しアクセストークンを取得するフローとそのアクセストークンを利用してレシート情報を取得するフローを表しています

10 10 of 例外フロー電子レシート API の利用について例外フローとして 2 例を以下に示します 1 つ目の例として認証 API で認証に失敗した場合のフローを下図に示します

11 11 of 45 2 つ目の例としてレシート一覧取得 API でアクセストークンを設定しなかった場合のフローを下図に示します

3 アプリケーションの利用申請 12 of 45 セキュリティー確保の為電子レシート API を利用するアプリケーション ( 家計簿ソフトや会計ソフト健康管理ソフト等 ) が予め利用申請を要する仕組みを提供します 3.1 アプリケーションの権限アプリケーションの権限は下記の 2 種類があります 1. 会員権限消費者のアプリケーションとしてのアクセス権限 2.

12 3 アプリケーションの利用申請 12 of 45 セキュリティー確保の為電子レシート API を利用するアプリケーション ( 家計簿ソフトや会計ソフト健康管理ソフト等 ) が予め利用申請を要する仕組みを提供します 3.1 アプリケーションの権限アプリケーションの権限は下記の 2 種類があります 1. 会員権限消費者のアプリケーションとしてのアクセス権限 2. 企業権限小売事業者のPOSアプリケーション等のアクセス権限 3.2 ユースケース会員権限と企業権限についてそれぞれの一般的なユースケースを紹介します会員権限のアプリケーションでレシートを取得する会員権限ではレシートの取得が可能です会員権限で登録されたレシートと企業権限で登録されたレシートの両方が取得できます ( 下図 ) ただしレシート PDF 取得 API は企業権限で登録されたレシートのみ取得できます

13 会員権限のアプリケーションがレシートを登録する 13 of 45 会員権限のアプリケーションはレシートの登録が可能です会員権限のアプリケーションから登録されたレシートはそのアプリケーション独自のレシートとして登録されるため電子レシートセンターでは発行元が不明なレシートとして登録されます会員権限でレシートを登録するユースケースとしては電子レシートセンターと連携していない他サービスセンターのデータ連携や会員が独自に作成したレシートの登録となります ( 下図 )

14 企業権限のアプリケーションがレシートを登録する 14 of 45 企業権限のアプリケーションはレシートの登録のみ可能です登録されるレシートは電子レシートセンターに信頼された発行元のレシートとして登録されます企業権限を利用するユースケースとしては他サービスセンターから電子レシートセンターへのレシート情報の連携や POS レジからの登録となります ( 下図 ) また企業権限ではレシートの取得はできませんまた同じ ID のレシートが会員権限と企業権限の両方から登録された場合企業権限のレシートが優先されます同じ ID のレシートが同じ権限で複数回登録された場合最後に登録したレシートが優先されます

15 3.3 会員権限のアプリケーションの概要 15 of 45 会員権限のアプリケーションは認証された会員のレシートの取得と発行元の不明なレシートの登録を行うことが可能です会員権限のアプリケーションで登録されたレシートは公的な書類 ( タイムスタンプ付きレシート PDF ファイル等 ) として利用することはできませんアプリケーション情報の取得セキュリティー確保の為にアプリケーションを一意に識別する為の ID (applicationid) とアプリケーションを識別するために利用する秘密の文字列 (applicationsecret) を使用したアプリケーション認証機能を提供しますアクセストークンの取得会員権限のアプリケーションから API を利用するには会員権限向けの認証 API でアクセストークンを取得しアクセストークンを利用し各種 API を利用しますリクエストの例認証 API の例を下記に示します Method POST URI /members/auth Headers Content-Type: application/json Body プロパティ名型サイズ必須備考 applicationid String 20 アプリケーションを一意に識別する ID です applicationsecret String 40 アプリケーションを識別するための秘密の文字列です accountid String 電子レシートシステムのログインに利用する電話番号または E メールアドレスです password String 電子レシートシステムのログインに利用するパスワードです Body の例 "applicationid": APPLICATION_ID, "applicationsecret": APPLICATION_SECRET, "accountid": "name@example.jp",

16 16 of 45 "password": "password" APPLICATION_ID と APPLICATION_SECRET にはシステム運営会社が発行 / 管理するアプリケーション ID とアプリケーションシークレットを設定します

17 17 of 企業権限のアプリケーションの概要企業権限のアプリケーションは認証された企業のレシートの登録を行うことが可能です企業権限のアプリケーションで登録されたレシートは公的な書類 ( タイムスタンプ付きレシート PDF ファイル等 ) として利用することができますアプリケーション情報の取得アプリケーション ID はアプリケーションを一意に識別する ID で一度登録されたものは変更することはできませんアプリケーションシークレットはアプリケーションを識別するために利用する秘密の文字列ですアクセストークンの取得企業権限のアプリケーションから API を利用するには企業権限向けの認証 API でアクセストークンを取得しアクセストークンを利用し各種 API を利用しますリクエストの例認証 API の例を下記に示します Method POST URI /companies/auth Headers Content-Type: application/json Body プロパティ名型サイズ必須備考 applicationid String 20 アプリケーションを一意に識別する ID です applicationsecret String 40 アプリケーションを識別するための秘密の文字列です companycode String 13 企業コードです Password String 電子レシートシステムにより発行されるパスワードです Body の例 applicationid : APPLICATION_ID, applicationsecret : APPLICATION_SECRET, companycode : , password : password

18 18 of 45 APPLICATION_ID と APPLICATION_SECRET にはシステム運営会社が発行 / 管理するアプリケーション ID とアプリケーションシークレットを設定します

19 4 API 一覧 4.1 電子レシート API の一覧電子レシート API の一覧を以下に示します 19 of 45 API 名 URI メソッド概要会員認証 API *1 /members/auth POST 会員の認証を行い認証トークンを発行します企業認証 API *1 /companies/auth POST 企業の認証を行い認証トークンを発行しますレシート一覧取得 API *1 レシート詳細取得 API *1 レシート印字文字列取得 API *1 レシート PDF 取得 API *1 レシート登録 API *2 /receipts GET 認証された会員のレシート一覧情報を取得します /receipts/receiptid GET 認証された会員の指定された receiptid のレシート詳細情報を取得します /receipts/receiptid/ stringarray /receipts/receiptid/ pdf GET GET 認証された会員の指定された receiptid のレシート印字文字列を取得します認証された会員の指定された receiptid のレシート PDF ファイルを取得します /receipts POST レシート情報を登録します *1 URI 例 : の後に続く様に記述します *2 URI 例 : の後に続く様に記述します特記事項

20 5 会員 API 20 of 45 電子レシート会員 ( 消費者 ) のアプリケーション等が利用することを前提にした API です 5.1 認証 API 電子レシート会員の認証を行います認証に成功した場合レシート API のアクセストークンを発行しますアクセストークンには JSON Web Token(JWT) を利用する事を前提としています JWT については JSON Web Token の章を参照くださいリクエスト Method POST URI /members/auth Headers Content-Type: application/json Body プロパティ名型サイズ必須備考 applicationid String 20 アプリケーションを一意に識別する ID です applicationsecret String 40 アプリケーションを識別するための秘密の文字列です accountid String 電子レシートシステムのログインに利用する電話番号または E メールアドレスです password String 電子レシートシステムのログインに利用するパスワードです Body の例 "applicationid": APPLICATION_ID, "applicationsecret": APPLICATION_SECRET, "accountid": "name@example.jp", "password": "password" 正常レスポンス Status Code 200 Headers Content-Type: application/json

21 21 of 45 Body プロパティ名型サイズ必備考須 access_token String - JSON Web Token です Body の例 "access_token": "eyjhbgcioijiuzi1niisinr5cci6ikpxvcj9.eyjzdwiioiixmjm0nt Y3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E 2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ" エラー Status Code 4xx Headers Content-Type: application/json Body プロパティ名型サイズ必須備考 error Object - エラーのオブジェクトです message String - エラーメッセージです type String - エラータイプです Body の例 "error": "message": "Error message.", "type": "ErrorType" エラーの内容 Status Code Type Message 備考 400 ApiVersionErr or Application is not supported for this API version. API バージョンが不正 401 MemberAuthErr or 403 AccountLockOu terror Account ID or passw ord is incorrect. Account is locked o ut. 会員認証情報の誤り会員認証の連続失敗によるアカウントのロックアウト

22 22 of ApplicationAu therror Application ID or a pplication secret i s incorrect. アプリケーション認証情報の誤り特記事項なし

23 6 企業 API 23 of 45 企業のアプリケーション (POS 等 ) が利用することを前提にした API です 6.1 認証 API 企業の認証を行います認証に成功した場合レシート API の認証トークンを発行します認証トークンには JSON Web Token(JWT) の利用を前提としています JWT については JSON Web Token の章を参照くださいリクエスト Method POST URI /companies/auth Headers Content-Type: application/json Body プロパティ名型サイズ必須備考 applicationid String 20 アプリケーションを一意に識別する ID です applicationsecret String 40 アプリケーションを識別するための秘密の文字列です companycode String 13 企業コードです password String 電子レシートシステムにより発行されるパスワードです Body の例 "applicationid": APPLICATION_ID, "applicationsecret": APPLICATION_SECRET, "companycode": " ", "password": "password" 正常レスポンス Status Code 200 Headers Content-Type: application/json Body プロパティ名型サイズ必須備考

24 24 of 45 access_token String - JSON Web Token です Body の例 "access_token": "eyjhbgcioijiuzi1niisinr5cci6ikpxvcj9.eyjzdwiioiixmjm0nt Y3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E 2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ" エラー Status Code 4xx Headers Content-Type: application/json Body プロパティ名型サイズ必須備考 error Object - エラーのオブジェクトです message String - エラーメッセージです type String - エラータイプです Body の例 "error": "message": "Error message.", "type": "ErrorType" エラーの内容 Status Code Type Message 備考 400 ApiVersionErr or Application is not supported for this API version. API バージョンが不正 401 CompanyAuthEr ror 401 ApplicationAu therror Company code or pas sword is incorrect. Application ID or a pplication secret i s incorrect. 企業認証情報の誤りアプリケーション認証情報の誤り

25 7 レシート API 電子レシート情報の取得等に関する API です 25 of レシート一覧取得 API JWT により認証された会員の電子レシート一覧情報を取得します一覧情報の絞り込み条件としてクエリパラメータを利用することが出来ますリクエスト Method GET URI /receipts Headers Authorization: Bearer JWT Query Parameters パラメータ名型サイズ必須備考 companycode String 13 企業コードを指定します標準電子レシートフォーマットの Org に対応します companyname String 企業名を指定します部分一致で検索されます標準電子レシートフォーマットの Org anizationhierarchy.#value に対応します storecode String 13 拠点 ( 店舗 ) コードを指定します標準電子レシートフォーマットの Bus inessunit.unitid.#value に対応します storename String 拠点 ( 店舗 ) 名を指定します部分一致で検索されます標準電子レシートフォーマットの Bus inessunit.unitid.@@name に対応します from String 14 from 以降の取引日時を指定します標準電子レシートフォーマットの Rec eiptdatetime に対応します to String 14 to 以前の取引日時を指定します標準電子レシートフォーマットの Rec eiptdatetime に対応します Query Parameters の例

26 26 of 45 /receipts?companycode= &from= &to= 正常レスポンス Status Code 200 Headers Content-Type: application/json Body 標準フォーマットのレシート情報の配列を持つオブジェクトです項目については下記の例と ARTS Digital Receipt Specification v3.1.0 を参照ください Body の例 "DigitalReceiptIndex": [ "DigitalReceipt": "@@MajorVersion": "3", "@@MinorVersion": "1", "@@FixVersion": "0", "ReceiptID": " ", "Transaction": "@@TypeCode": "SaleTransaction", "BusinessUnit": "UnitID": "#value": " ", "@@Name": " 拠点 ( 店舗 ) 名 ", "TypeCode": "RetailStore", "OrganizationHierarchy": "#value": " 企業名 ", "@@ID": " ", "@@Level": "OperatingCompany", "ReceiptDateTime": " T10:00:00+09:00", "ReceiptNumber": "1234", "RetailTransaction": "Total": [ "#value": "1000", "@@TotalType": "TransactionGrandAmount"

27 , "#value": "80", "TransactionTaxAmount" ], "WorkstationID": "0001" ] 27 of 45 エラー Status Code 4xx Headers Content-Type: application/json Body プロパティ名型サイズ必須備考 error Object - エラーのオブジェクトです message String - エラーメッセージです type String - エラータイプです Body の例 "error": "message": "Error message.", "type": "ErrorType" エラーの内容 Status Code Type Message 備考 400 ApiVersionErr or Application is not supported for this API version. API バージョンが不正 400 RequestParame tersinvalider ror Request parameters are invalid or miss ing. リクエストパラメータが不正

28 28 of TokenMissingE rror 401 TokenIncorrec terror 401 TokenExpiredE rror Token is required. Authorization ヘッダがない Bearer スキームがない Token is incorrect. JWT が不正 Token is expired. JWT が有効期限切れ特記事項なし

29 7.2 レシート詳細取得 API 29 of 45 JWT により認証された会員の receiptid により指定された電子レシートの詳細情報を取得します receiptid とはレシート一覧取得 API のレスポンスに含まれる DigitalReceipt.Rece iptid を指しますこの ID はレシートを一意に特定する為の ID でシステムにより自動的に発行されることを想定しています詳細情報には企業情報店舗情報レジ番号レシート番号取引日時購買情報店舗ロゴ画像販促ビットマップ画像が含まれます Method URI Headers 正常リクエストレスポンス GET /receipts/receiptid Authorization: Bearer JWT Status Code 200 Headers Content-Type: application/json Body 標準フォーマットのレシート情報です項目については下記の例と ARTS Digital Receipt Specification v3.1.0 を参照ください Body の例 "DigitalReceipt": "3", "1", "0", "Transaction": "SaleTransaction", "BusinessUnit": "UnitID": " 拠点 ( 店舗 ) 名 ", "#value": " ", "TypeCode": "RetailStore", "OrganizationHierarchy": "@@Level": "OperatingCompany",

30 " ", "#value": " 企業名 ", "WorkstationID": "0001", "ReceiptDateTime": " T10:00:00+09:00", "ReceiptNumber": "1234", "RetailTransaction": "LineItem": [ "Sale": "ItemID": "@@Name": " 商品名 ", "#value": " ", "MerchandiseHierarchy": "@@ID": "J1", "@@Level": "Category", "ActualSalesUnitPrice": "1000", "Quantity": "1", "SequenceNumber": "1", "Discount": "SequenceNumber": "1", "Amount": "@@Action": "Subtract", "#value": "100", "SequenceNumber": "2" ], "Total": [ "@@TotalType": "TransactionGrandAmount", "#value": "900", "@@TotalType": "TransactionTaxAmount", "#value": "72" ], "Customer": "CustomerID": " " 30 of 45

31 , "Logo": "JPG", "FileName": " "Advertising": [ "AdvertisingID": "1", "ImageURI": " "AdvertisingID": "2", "ImageURI": " ] エラー 31 of 45 Status Code 4xx Headers Content-Type: application/json Body プロパティ名型サイズ必須備考 error Object - エラーのオブジェクトです message String - エラーメッセージです type String - エラータイプです Body の例 "error": "message": "Error message.", "type": "ErrorType" エラーの内容 Status Code Type Message 備考 400 ApiVersionErr or Application is not supported for this API version. API バージョンが不正

32 32 of TokenMissingE rror 401 TokenIncorrec terror 401 TokenExpiredE rror 404 ReceiptNotExi sterror Token is required. Authorization ヘッダがない Bearer スキームがない Token is incorrect. JWT が不正 Token is expired. JWT が有効期限切れ Receipt not exists. 指定されたレシートが存在しない特記事項なし

33 7.3 レシート印字文字列取得 API 33 of 45 JWT により認証された会員の receiptid により指定された電子レシートの印字文字列を取得します receiptid とはレシート一覧取得 API のレスポンスに含まれる DigitalReceipt.Rece iptid を指しますこの ID はレシートを一意に特定する為の ID でシステムにより自動的に発行されることを想定しています通常の POS からプリンターに送付される一般的な印字命令例えばエスケープシーケンスと呼称される Code 等は含まれません Method URI Headers 正常リクエストレスポンス GET /receipts/receiptid/stringarray Authorization: Bearer JWT Status Code 200 Headers Content-Type: application/json Body レシート印字文字列店舗ロゴ販促イメージです項目については下記の例と ARTS Digital Receipt Specification v3.1.0 を参照ください Body の例 "DigitalReceipt": "3", "1", "0", "Transaction": "ReceiptImage": "ReceiptLine": [ "receipt text", "receipt text", "receipt text", "receipt text", "receipt text", "receipt text", "receipt text", "receipt text",

34 "receipt text" ], "Logo": "JPG", "FileName": " "Advertising": [ "AdvertisingID": "1", "ImageURI": " "AdvertisingID": "2", "ImageURI": " ] 34 of 45 エラー Status Code 4xx Headers Content-Type: application/json Body プロパティ名型サイズ必須備考 error Object - エラーのオブジェクトです message String - エラーメッセージです type String - エラータイプです Body の例 "error": "message": "Error message.", "type": "ErrorType" エラーの内容 Status Code Type Message 備考

35 35 of ApiVersionErr or 401 TokenMissingE rror 401 TokenIncorrec terror 401 TokenExpiredE rror 404 ReceiptNotExi sterror Application is not supported for this API version. Token is required. Token is incorrect. JWT が不正 Token is expired. API バージョンが不正 Authorization ヘッダーがない Bearer スキームがない JWT が有効期限切れ Receipt not exists. 指定されたレシートが存在しない特記事項なし

36 7.4 レシート PDF 取得 API 36 of 45 JWT により認証された会員の receiptid により指定された電子レシートのタイムスタンプと電子署名付き PDF ファイルを取得します receiptid とはレシート一覧取得 API のレスポンスに含まれる DigitalReceipt.Rece iptid を指しますこの ID はレシートを一意に特定する為の ID でシステムにより自動的に発行されることを想定していますリクエスト Method GET URI /receipts/receiptid/pdf Headers Authorization: Bearer JWT 正常レスポンス Status Code 200 Headers Content-Type: application/pdf Body PDF file がダウンロードされますエラー Status Code 4xx Headers Content-Type: application/json Body プロパティ名型サイズ必須備考 error Object - エラーのオブジェクトです message String - エラーメッセージです type String - エラータイプです Body の例 "error": "message": "Error message.", "type": "ErrorType" エラーの内容 Status Code Type Message 備考

37 37 of ApiVersionErr or 401 TokenMissingE rror 401 TokenIncorrec terror 401 TokenExpiredE rror 404 ReceiptNotExi sterror 404 ReceiptUnauth enticationerr or Application is not supported for this API version. Token is required. Token is incorrect. JWT が不正 Token is expired. API バージョンが不正 Authorization ヘッダがない Bearer スキームがない JWT が有効期限切れ Receipt not exists. 指定されたレシートが存在しない Receipt is not trus ted. 指定されたレシートの発行元が不明特記事項なし

38 7.5 レシート登録 API レシートの登録を行いますリクエスト Method POST URI /receipts Headers Content-Type: application/json Authorization: Bearer JWT Body 標準電子レシートフォーマットの JSON です Body の例 "DigitalReceipt": "3", "1", "0", "Transaction": "SaleTransaction", "BusinessUnit": "UnitID": " 店舗名 ", "RetailStore", "#value": " ", "OrganizationHierarchy": "#value": " 企業名 ", " ", "OperatingCompany", "Logo": "BMP", "FileName": "logo.bmp", "ReceiptDateTime": " T10:20:30+09:00", "ReceiptImage": "ReceiptLine": [ "receipt text", "receipt text", "receipt text", "receipt text", 38 of 45

39 "receipt text", "receipt text", "receipt text", "receipt text" ], "ReceiptNumber": "0001", "RetailTransaction": "Customer": "CustomerID": "1", "LineItem": [ "Sale": "ItemID": "@@Name": " 商品名 1", "#value": " ", "MerchandiseHierarchy": "@@ID": "J01", "@@Level": "Class", "@@Name": " カテゴリ名 ", "@@Type": "Retailer", "ActualSalesUnitPrice": " 1000", "ExtendedAmount": "2000", "Quantity": "2", "SequenceNumber": "1", "Sale": "ItemID": "@@Name": " 商品名 2", "#value": " ", "MerchandiseHierarchy": "@@ID": "J02", "@@Level": "Class", "@@Name": " カテゴリ名 ", "@@Type": "Retailer" 39 of 45

40 , "ActualSalesUnitPrice": " 100", "ExtendedAmount": "100", "Quantity": "1", "SequenceNumber": "2" ], "Total": [ "@@TotalType": "TransactionGrossAmount", "#value": "2100", "@@TotalType": "TransactionTaxAmount", "#value": "168" ], "WorkstationID": "0001" 40 of 45 レスポンス正常 Status Code 200 Headers Content-Type: text/plain エラー Status Code 400 / 401 Headers Content-Type: application/json Body プロパティ名型サイズ必須備考 error Object - エラーのオブジェクトです message String - エラーメッセージです type String - エラータイプです Body の例 "error":

41 "message": "Error message.", "type": "ErrorType" エラーの内容 41 of 45 Status Code Type Message 備考 400 ApiVersionErr or Application is not supported for this API version. API バージョンが不正 400 ReceiptDataEr ror 401 TokenMissingE rror 401 TokenIncorrec terror 401 TokenExpiredE rror 401 MemberAuthErr or 401 CompanyAuthEr ror Digital receipt is invalid data. Token is required. Token is incorrect. JWT が不正 Token is expired. Account ID or passw ord is incorrect. Company code or pas sword is incorrect. 電子レシートのデータが不正 Authorization ヘッダがない Bearer スキームがない JWT が有効期限切れ会員認証情報の誤り企業認証情報の誤り特記事項なし

42 42 of 45 8 JSON Web Token JSON Web Token(JWT) は改ざんの検出が可能な JSON を使ったトークンで OAuth2 でも利用されている技術です JWT を作る方法には JSON Web Signature(JWS) と呼ばれる電子署名または MAC (Message Authentication Code) を利用する方法や JSON Web Encryption (JWE) と呼ばれる暗号化を利用する方法 JWS と JWE の両方を利用する方法がありますが電子レシート API では JWS を使った JWT を利用しています 8.1 JWT の構造 JWT はヘッダーペイロードシグネチャの 3 パーツから構成されますこれら 3 つをドット (.) で結合した値が JWT となりますヘッダーヘッダーは JWT のアルゴリズム (alg) とトークンタイプ (typ) を持つ JSON を Base64URL エンコードした値です電子レシート API ではアルゴリズムとトークンタイプは常に同じ値を利用するためヘッダーは固定値となりますヘッダー JSON の例 "alg": "HS256", "typ": "JWT" ヘッダーの例 eyjhbgcioijiuzi1niisinr5cci6ikpxvcj9 ペイロードペイロードは任意の JSON を Base64URL エンコードした値です電子レシート API では API を利用するアプリケーションの ID(aid) と電子レシートシステムの会員 ID から生成した値 (mid) または企業 ID(cid) トークンの有効期限 (exp) アプリケーションの権限を表す (prm) を持つ JSON を使用します mid は標準電子レシートフォーマットの CustomerID と 1 対 1 対応する値ですペイロード JSON の例 "aid": 1, "mid": , "exp": " T09:08:42.806Z ",

43 43 of 45 "prm": "member" ペイロードの例 eyjzdwiioiixmjm0nty3odkwiiwibmftzsi6ikpvag4grg9liiwiywrtaw4ionrydwv9 シグネチャシグネチャ ( 署名 ) はヘッダーとペイロードをドットで結合した値について共通鍵で暗号化し Base64URL エンコードした値ですヘッダー. ペイロードの例 eyjhbgcioijiuzi1niisinr5cci6ikpxvcj9.eyjzdwiioiixmjm0nty3odkwiiwibmftz SI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9 シグネチャの例 TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ JWT JWT は上述したヘッダーペイロードシグネチャをドットで結合した値です JWT の例 eyjhbgcioijiuzi1niisinr5cci6ikpxvcj9.eyjzdwiioiixmjm0nty3odkwiiwibmftz SI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZge FONFh7HgQ 8.2 改ざんの検出 JWT のシグネチャはヘッダーとペイロードを暗号化した結果のためシグネチャを復号した値と JWT のヘッダーやペイロードを比較することで改ざんを検出することが出来ます 8.3 JWT の利用認可情報として JWT を利用する場合 Headers の Authorization の Bearer スキームに JWT を設定してください Authorization の例 Authorization: Bearer eyjhbgcioijiuzi1niisinr5cci6ikpxvcj9.eyjzdwiioii xmjm0nty3odkwiiwibmftzsi6ikpvag4grg9liiwiywrtaw4ionrydwv9.tjva95orm7e2 cbab30rmhrhdcefxjoyzgefonfh7hgq

44 8.4 認可された状態のリセット 44 of 45 JWT を破棄すること ( 利用しないこと ) で認可された状態をリセットすることができます再度 JWT を取得する場合認証 API を実行してください特記事項なし

45 9 参照 ARTS Digital Receipt Specification v3.1.0 RFC JSON Web Token (JWT) RFC The OAuth 2.0 Authorization Framework: Bearer Token Usage RFC Hypertext Transfer Protocol (HTTP/1.1): Authentication 45 of 未解決の課題

ステップ 1:Cisco Spark にサインアップして試してみよう 1. Spark のホームページ ( で電子メールアドレスを入力し指示に従って Spark アカウントを作成します注 : 自身の電子メールアカウントにアクセスして Spar

ステップ 1:Cisco Spark にサインアップして試してみよう 1. Spark のホームページ ( で電子メールアドレスを入力し指示に従って Spark アカウントを作成します注 : 自身の電子メールアカウントにアクセスして Spar ご利用のコンピュータを設定する方法事前設定された dcloud ラボを使用してこのラボに取り組む場合はイベントの事前準備 [ 英語 ] とラボの設定 [ 英語 ] の両モジュールを確認してください自身のコンピュータでこのラボの作業を行うには Postman という Chrome http クライアントをインストールする必要がありますまた Spark アカウントも必要です Spark:Spark

目次 2 of 45 1 序章 目的 改版履歴 チーム名 チームの使命 メンバー名簿 電子レシート API の利用 基本フロー 例外フロー アプ

目次 2 of 45 1 序章目的改版履歴チーム名チームの使命メンバー名簿電子レシート API の利用基本フロー例外フローアプ