打刻APIの仕様について
カテゴリ: Timecard
お世話になっております。
タイムカードの打刻API（https://timecard1.smaregi.dev/apidoc/#tag/%E6%89%93%E5%88%BB）の仕様について質問させて下さい。
現在、ICカードを使用した勤怠管理アプリの開発を進めておりますが、APIの仕様に若干の不明点があります。出勤時の打刻はshift_result_idなしでPOST可能なのに対し、退勤、休憩、復帰時の打刻にはshift_result_idを要求するPUTメソッドとなっている理解です。
しかし、この仕様に従うと、他のアプリを使って出勤・退勤処理を行った場合、shift_result_idの不整合が生じてしまい、私どものアプリが正常に機能しなくなる可能性があります。例えば、ICカードで出勤登録後、別のWEBアプリで退勤登録すると、私どものアプリではその情報を把握できず、保持しているshift_result_idとの間で競合が生じてしまいます。
このような背景から、shift_result_idなしで退勤・休憩・復帰処理を行うAPIの提供、または他の解決策があるかどうか、お教えいただけないでしょうか。
何卒、ご検討のほどよろしくお願い申し上げます。
答え
＠senbishi
弊社タイムカードの打刻は「出勤打刻」「退勤打刻」でそれぞれ独立しているわけではなく、ひとつの実績に対して出勤時間/退勤時間/休憩時間がセットで登録される仕様となります。
そのため出勤時間のみ空のテーブルに対して新規登録で、それ以外の打刻は出勤済みのテーブルの「shift_result_id」に対して時間を登録する方法となります。
すなわちshift_result_idなしで退勤・休憩・復帰処理を行うことはできません。
ご希望に添えず申し訳ございません。
ご回答まことにありがとうございます。
打刻がセットとなっている点は承知いたしました。
その場合、出勤・退勤関連のAPIは冪等ではなく、他のAPIで操作されてしまう、もしくはタイムカード本体で操作されてしまうとAPIのResponseが変わってしまう（エラーになってしまう）のですが、それは予期された挙動なのでしょうか？
APIを叩く側からすると、操作されているかどうかがわからないため、安定したアプリの挙動を達成できず困ってしまうため、なにかワークアラウンドなどございましたらご教授いただけると幸いです。
どうぞよろしくお願いいたします。
＠senbishi
一度出勤したら、その後退勤するまでは該当従業員に対しては同じshiftResultIdに対しての打刻時間の登録となり、途中で休憩打刻等を行ったとしてもshiftResultIdが変わることはございません。
なお一日のうちに複数回出勤打刻→退勤打刻を行った場合は、出勤→退勤までのそれぞれに実績に対して、別のshiftResultIdが採番されます。
（例：12/27 9時に出勤打刻をして12時に退勤打刻→shiftResultId:1、17時に出勤打刻をして19時に退勤打刻→shiftResultId:2）
出勤打刻APIをご利用の場合は出勤時のレスポンスデータからshiftResultIdを確認していただき、出勤打刻APIを利用していない場合や出勤打刻以外のタイミングでshiftResultIdを確認したい場合は「出勤中の従業員取得API」「日別勤怠（従業員別）取得API」を利用する方法をご検討ください。
◎参考仕様書
出勤打刻
出勤中の従業員取得
日別勤怠（従業員別）取得
スマレジ 清谷様
お世話になっております。ご回答ありがとうございます。
私の説明が拙く、大変申し訳ございません。
それぞれ別のアプリで出勤・退勤処理を行った場合を想定しており、例えば
という状況を想定しております。
私共の方で、アプリAのような出退勤アプリを作成することを想定しているため、このように従業員のステータスについて不一致が発生してしまうのでは、と思うのですが、いかがでしょうか？
＠senbishi
ご質問の意図をくみ取れておらず申し訳ございません。
タイムカード・アプリとアプリA（貴社アプリ）の両方で打刻を行う可能性があるというご状況ですね。
その場合ご認識いただいている通り、タイムカード・アプリで打刻するとshiftResultID：1が終了し、そのあとアプリAでshiftResultID：1に対して退勤打刻APIで更新をかけようとするとエラーになります。
そのため現状は以下のいずれかのAPIで事前に出退勤状況を取得した上で、適切なAPIで打刻していただく方法をご検討ください。
なるほど、ありがとうございます！
勤怠取得をAsyncで動かして必要になり次第アップデートする形にいたします。