会員登録APIのレスポンスの型がメソッドによって違う
お世話になっております。
会員登録APIのレスポンスにおける、customerIdの型がメソッドによって違うようです。
POST（会員登録）ではcustomerIdはintegerとして返ってきます。
一方でGET（会員一覧取得）ではcustomerIdはstringとして返ってくるようです。
両者は同じリソースを指していると思われますので、どちらか一方が意図しない型になっているものと思われます。
参考まで、POS APIのドキュメントにおいては、両者stringとして表現されています。
（ただ、実際に渡される値は常に正の整数であるようですので、integerとして定義頂いた方が扱いやすいかと思われます）
ベストアンサー
-
@kogai 様
ご指摘ありがとうございます。
本来両者とも
stringを想定しておりましたが、現在は実際の動作を正（会員登録のレスポンスではinteger、会員一覧取得ではstring）とさせて頂きたいです。そのため近く会員登録APIの仕様書の記載を
integerに修正させていただきます（会員一覧取得APIはそのまま）。ですが、本来は両者とも
stringですので、時期は未定ですが将来的にはstringに変更を予定しています。そのため、レスポンス取得時に使いたい型にキャストするなどどちらの型でも大丈夫なように作っていただければ幸いでございます。
実際にレスポンスの型を変更する具体的な時期が決まりましたら、改めて全体へ通知させていただきます。
お手数をおかけいたしますが、よろしくお願いいたします。
-
本件、2021年4月9日時点で、本番環境のみ、会員登録のレスポンスのcustomerIdがstringに統一されているようです。
申し訳ございません。本件の調査に時間を要してしまいました。
調査の結果、POSのAPIリリースの最終日付は04/07です。
仕様書とレスポンスの型について乖離があることは以前のやり取りでお伝えしたとおりでございます。
しかし、APIの破壊的な変更（型の変更）は行っていない認識です。他のスレッドでも申し上げた通り、機能追加は行う予定ですが、破壊的変更は通知無しで行いません。
今回対応させていただく予定のものは仕様書の修正のみとなります。（こちらまだ未着手です。）
以上より
再三にわたって予告なくレスポンスの型が変更されているように観察され
このような現象は弊社では行っていないつもりです。
04/09時点 04/15時点で新しいバージョンのリリース等はしておりません。
最終更新は04/07の
---
スマレジ・プラットフォームAPI POSを更新しました。
以下の機能改善を行いました。
- 取引登録API、取置き登録API、仮販売登録APIにて、
取引明細（details）に商品ID（productId）を指定し、かつ同じ明細の部門ID（categoryId）に、商品IDで指定された商品に実際に紐つけられている部門IDとは異なる実在部門IDを指定した場合の、表示されるエラーメッセージをより分かりやすいものに改善しました。 - 【仕様書修正】取引登録API、商品登録API、商品更新APIにおける、
軽減税率ID（reduceTaxId）説明文を改善しました。
以下の不具合修正を行いました。
- 取引登録API、取置き登録API、仮販売登録APIにて、
取引明細（details）の商品ID（productId）に商品区分が回数券である商品のIDを指定した場合に500エラーが発生していたのを、回数券である商品は設定できない旨のエラーメッセージとともに400エラーが返るよう修正しました。 - 【仕様書修正】取引、取置き、仮販売系の大部分のAPIにおいて、
取引明細（details）のセールID（bargainId）において、実際にはbargainIdにはセールIDではなくセール商品IDが設定されるにも関わらずその記載がなかったため、セール商品IDが設定される旨の注記を追記しました。 - 【仕様書修正】一部の単一レコード取得APIにおいて、
RESPONSE SCHEMAの内容がArrayと表記されていたのを、オブジェクトの様式の表記に修正しました。 - 【仕様書修正】取引取得API、取引明細取得APIにおける、
修正税率（modifiedTaxRate）説明文を修正しました。
---
でございます。
この度はご迷惑をおかけし申し訳ございませんでした。
より良い開発ができるよう、努めて参りますので、今後もよろしくお願いいたします。
- 取引登録API、取置き登録API、仮販売登録APIにて、
-
@kogai 様
ご連絡ありがとうございます。
ご指摘を受けて再度調査をしましたところ、弊社の本部管理機能が有効の契約に対して会員登録APIを実行した場合に、会員IDが
stringで返ってしまっていることがわかりました。例示いただいた https://api.smaregi.jp/demo2/pos/customersの契約
demo2は本部管理機能が有効である契約のため、stringが返ってきてしまっています。本部管理機能が有効でない契約に対しては、
integerで返っている認識です。今後の対応について（いつ対応するか、型を寄せるべきか、等）開発チームで議論いたしましたが、他のアプリへの影響もあることから、すぐの修正はせず、慎重に検討させて頂けたらと思います。
しばらくの間は上記のように、アプリ利用者の契約によってcustomerIdがintegerになる場合、stringになる場合があるとして実装いただけたら幸いでございます。
（kogai様に置かれましては既にそのように実装いただけているようで、ご不便をおかけいたしております。）
この度は混乱、ご迷惑をかけてしまい大変申し訳ございませんでした。
重ねてお詫び申し上げます。
答え
本件、2021年4月9日時点で、本番環境のみ、会員登録のレスポンスのcustomerIdがstringに統一されているようです。
（サンドボックス環境は、既存の実装通りintegerで返ってきていました）
実際にレスポンスの型を変更する具体的な時期が決まりましたら、改めて全体へ通知させていただきます。
2021年4月6日付けの「お知らせ」には本件に関する告知はなかったように見受けられます。
弊社ではレスポンスの型を正確に取扱う前提で開発をしており、`"1"`と`1`を同一視するような実装は想定しておりません。
こういった変更は軽微ではあると思いますが、破壊的な変更でもあるという認識です。
事前告知の購読場所が違ったり、上記「お知らせ」以外の場所で告知されているようでしたらご教示下さいませ。
よろしくお願い致します。
蛇足ですが、こういったAPIの型にまつわるクライアント・サーバ間の認識差異は、現状のように人間向けのドキュメントベースでやり取りしている限り、避け得ないものと認識しております。
また、Schema Driven Development によってこういった問題をかなりの程度解決することが出来るという認識です。
https://community.smaregi.dev/discussion/comment/143 でもご提案申し上げていますが、ぜひOpen API Documentの公開をご検討下さいますよう、改めてよろしくお願い申し上げます。
https://community.smaregi.dev/discussion/comment/143 でもご提案申し上げていますが、ぜひOpen API Documentの公開をご検討下さいますよう、改めてよろしくお願い申し上げます。
遅れまして大変申し訳ございません。
こちら着手中ではございますが、その他バックログ消化中でございまして、なかなかいい連絡ができない状態です。
今しばらくお待ち下さい。
本件、2021年4月9日時点で、本番環境のみ、会員登録のレスポンスのcustomerIdがstringに統一されているようです。
本件、2021年4月15日時点で、本番環境のレスポンスのcustomerIdはintegerになっている様子です。
こちらは意図した挙動なのでしょうか？
再三にわたって予告なくレスポンスの型が変更されているように観察され、非常に困惑しています。
調査頂きありがとうございます。
また、APIの破壊的変更は行っていないというご認識の旨、承知致しました。
改めて認識を整理させて下さい。
会員登録のレスポンスについて、以下の認識でおりますが、相違ないでしょうか？
私共の主張としては以下の通りです。
上記2点については、それぞれ以下のようなサーバのログが残っております。
（JSONを当社で採用している言語のデータ構造へデシリアライズする際のエラーログとなっています）
また、本日同じAPIを試行したところ、customerIdはstringでレスポンスされているように観察されました。
以上を踏まえまして改めてご教示頂きたいのですが、APIドキュメント・実装の双方において、customerIdをどちらの型で定義しているというご認識でしょうか？
（蛇足ながら、私共の実装においては、customerIdの型は不定である想定の実装に変更済ですので、緊急の実用上の問題はございません）
@kogai
以上を踏まえまして改めてご教示頂きたいのですが、APIドキュメント・実装の双方において、customerIdをどちらの型で定義しているというご認識でしょうか？
以前ご指摘頂いたように型が不定となっております。
繰り返しになります、この度は誠に申し訳ございません。
会員登録のレスポンスについて、以下の認識でおりますが、相違ないでしょうか？
APIドキュメントにおいては、customerIdがstringと定義されている
レスポンスの実装においては、customerIdがintegerとして送信される
スマレジ様としては、実装もcustomerIdがstringになるように変更したい（ただし事前に告知する）
認識相違ないです。ただし、実装面は下記のようになります。
以上を踏まえまして改めてご教示頂きたいのですが、APIドキュメント・実装の双方において、customerIdをどちらの型で定義しているというご認識でしょうか？
実装
を返しています。こちらはご指摘頂いてからの実装が変わったわけではありません。
以前のコメントでも申し上げていますが、
実際にレスポンスの型を変更する具体的な時期が決まりましたら、改めて全体へ通知させていただきます。
の通りに進めさせていただきます。（ただし、事前に告知する。です。）
仕様書
現状反映されているものが全てです。
度々お手数をお掛けして恐縮です。
ご回答ありがとうございます。
私共の認識も整理できました。
会員登録・会員更新APIのresponseはinteger。
こちらですが、会員登録においてもcustomerIdをstringで返しているケースを観測しております。
例えば https://api.smaregi.jp/demo2/pos/customers に以下のリクエストボディでPOSTリクエストを送信したところ、
{ "customerCode": "12345678910", "firstName": "postman", "lastName": "from" }以下のようなレスポンスが得られました。
{ "customerId": "16779", "customerCode": "12345678910", "customerNo": null, "rank": null, "staffRank": null, "firstName": "postman", "lastName": "from", "firstKana": null, "lastKana": null, "postCode": null, "address": null, "phoneNumber": null, "faxNumber": null, "mobileNumber": null, "mailAddress": null, "mailAddress2": null, "mailAddress3": null, "companyName": null, "departmentName": null, "managerialPosition": null, "sex": "0", "birthDate": null, "pointExpireDate": null, "lastComeDateTime": null, "entryDate": null, "leaveDate": null, "pointGivingUnitPrice": null, "pointGivingUnit": null, "pinCode": null, "passportNo": null, "nationality": null, "alphabetName": null, "mailReceiveFlag": "1", "note": null, "note2": null, "favoriteList": null, "browsingList": null, "status": "0", "storeId": null, "insDateTime": "2021-04-16T11:33:56+09:00", "updDateTime": "2021-04-16T11:33:56+09:00" }コメント頂いた通り、integerで返せているケースにも遭遇しておりますが、上記のようにstringで返ってくる時もあるようです。
頂いたコメントからは、この状況が意図したものであるとは読み取れなかったのですが（あくまで仕様書と実装の型にズレがあるというお話という認識です）、上記のような「実装において、会員登録のレスポンスのcustomerIdは、integerにもstringにもなり得る」という状態は、把握されているという認識でよろしいでしょうか？
ありがとうございます！
状況確認出来てよかったです。
こちらこそ、調査でお手数をお掛け致しました。
今後ともどうぞよろしくお願い致します。