HubSpot APIの会社一括作成処理のステータス取得について

[nnyamau]

現在、HubSpotの会社一括作成エンドポイント(/crm/v3/objects/companies/batch/create)を使用して複数の会社レコードを一括登録しています。

APIドキュメントによると、このエンドポイントからのレスポンスとして "status": "PENDING" が返される場合があります。これは処理がまだ完了していないことを示していると理解しています。

私のアプリケーションでは、各レコードの登録が「成功」か「失敗」かという最終結果のみが必要で、"PENDING"状態のまま処理を完了させたくありません。

質問：

1. "PENDING"ステータスが返された場合、最終的な処理結果（成功/失敗）を取得するための推奨される方法はありますか？

2. ポーリングや非同期処理など、どのようなアプローチが最適でしょうか？

3. 最終結果を取得するためのエンドポイントや推奨されるタイムアウト設定はありますか？

実装上の具体的なアドバイスを教えてください。

[natsumimori]

@nnyamau さん、コミュニティーへの投稿ありがとうございます。

日本語版コミュニティーには開発者の方があまり多くいらっしゃらないので、英語でのコミュニケーションとなりますがこちらのDeveloper専用フォーラムやDeveloper向けSlackチャネルのほうが他のユーザーから反応が得られるかもしれません。よろしければチェックしてみてください。

@skimura さん> こちらのご相談内容にアドバイスできる点があれば、ぜひお願いいたします！🙏

[nnyamau]

@skimura さん
上記の質問に関連して、追加で以下の点についてご存知であれば教えていただけますでしょうか？

APIレスポンスに "status": "PENDING" が含まれる場合の挙動について、以下を確認したいです：

• "status": "PENDING" は、各会社レコードごとに返却されるのでしょうか？
  　もしそうであれば、最終的な登録可否を確認するために /crm/v3/objects/companies/search を各レコードごとに呼び出す必要があり、効率面で懸念があります。

• 逆に、PENDINGステータスがバッチ全体に対して返されるものであれば、
  　そのバッチに一意なIDなどは付与されているのでしょうか？
  　また、そのIDをもとに後からバッチ全体の処理結果を問い合わせる手段はあるのでしょうか？

お忙しいところ恐れ入りますが、もしご存知でしたらアドバイスいただけると幸いです。

[skimura · Accepted solution]

@nnyamau 

以下は私見となります。

>1. "PENDING"ステータスが返された場合、最終的な処理結果（成功/失敗）を取得するための推奨される方法はありますか？

レスポンスから判断することはできないと思います。

会社が作成されたかを検索APIで探すことになりそうです。

（確実に処理の終了を判断するためには、一括作成（Batch API）ではなく1件ずつ作成（Basic API）するのが良いと思います）

余談：

同じpendingでもhttp status code が201の場合は時間が経てば成功しそうです。

http status codeが207の場合は何らかの理由で一部が失敗となっています。

参考：会社一括作成APIのレスポンス

https://developers.hubspot.jp/docs/reference/api/crm/objects/companies#post-%2Fcrm%2Fv3%2Fobjects%2F...

>2. ポーリングや非同期処理など、どのようなアプローチが最適でしょうか？

確実に全ての会社が作成されていることの保証が必要なのであれば

Basicの「会社レコードを1件ずつ作成」とするのはいかがでしょうか。

>3. 最終結果を取得するためのエンドポイントや推奨されるタイムアウト設定はありますか？

すみません、わかりません。

>"status": "PENDING" は、各会社レコードごとに返却されるのでしょうか？

一括作成処理全体のステータスだと考えています。

→各会社レコード毎ではない

根拠：

レスポンスを見るとstatusはresults配列の外に1項目だけ存在しています

https://developers.hubspot.jp/docs/reference/api/crm/objects/companies#post-%2Fcrm%2Fv3%2Fobjects%2F...

>もしそうであれば、最終的な登録可否を確認するために >/crm/v3/objects/companies/search を各レコードごとに呼び出す必要があり、効率面で懸念があります。

上に記述しましたが、確実な保証が必要な場合は、

一括作成ではなく1件ずつ作成されるのはいかがでしょうか。

>逆に、PENDINGステータスがバッチ全体に対して返されるものであれば、
>そのバッチに一意なIDなどは付与されているのでしょうか？
>また、そのIDをもとに後からバッチ全体の処理結果を問い合わせる手段はあるのでしょうか？

hubspot apiのエラーレスポンス時によく設定されているcorrelationIdが設定されておらず、すれっぽいパラメータがない為、一意なIDはなさそうです。

前提として

hubspotの一括作成APIではstatus="complete"の場合が多いです。

参考

https://community.hubspot.com/t5/APIs-Integrations/How-to-handle-status-of-PENDING-on-contact-upsert...

とはいえ後続の処理等の為、全件の完了の保証が必要な場合は

面倒ですが1件ずつ作成（APIの呼び出し制限を考慮しながら）が必要だと思います。

私は、一括作成APIの利用は

夜間のバッチ処理等、後続の処理がなく即時の実行完了を保証する必要がない場合に使用しています。

参考になりましたら幸いです。

@nnyamau 

お知らせいただきありがとうございます。

[nnyamau]

@skimura さん
ご丁寧なご回答ありがとうございます。
追加で、余談に記載いただいた以下の点について確認させてください：

同じ PENDING でも http status code が 201 の場合は時間が経てば成功しそうです。
http status code が 207 の場合は何らかの理由で一部が失敗となっています。

この点について、以下のように理解していますが、もし誤っている点があればご指摘いただけると幸いです。

【確認したいポイント】
http status code = 201 で "status": "PENDING" が返された場合：
　→ バッチで送信した全レコードは最終的に「すべて確実」に作成されると考えてよいでしょうか？（時間が経てば全件成功）

http status code = 207 の場合：
　→ レスポンスに含まれる失敗した会社の情報は「すべて」返却されると考えてよいでしょうか？
　→ また、それ以外の会社については、時間経過により「確実」に作成されるとみなしてよいでしょうか？

[skimura]

@nnyamau 

＞http status code = 201 で "status": "PENDING" が返された場合：

＞　→ バッチで送信した全レコードは最終的に「すべて確実」に作成されると考えてよいでしょうか？（時間が経てば全件成功）

個人的な意見ですが

「確実に」ということであれば一括作成APIではなく1件ずつ作成APIを呼ぶ、とされたほうがよいです。

201でpendingであってもhubspot側での登録処理時にたまたま失敗する可能性はあると思います。

＞http status code = 207 の場合：
＞　→ レスポンスに含まれる失敗した会社の情報は「すべて」返却されると考えてよいでしょうか？

207の場合、レスポンスのerrorsを見ると配列なのでレスポンス時にエラーとなった会社情報は複数返却されそうですが（要検証）

レスポンス段階での結果なので、レスポンス以降の登録時にエラーが発生する可能性を考えると「すべて」返却は保証されないと思います。

＞　→ また、それ以外の会社については、時間経過により「確実」に作成されるとみなしてよいでしょうか？

201の場合と同様に「確実」ではないと思います。

よろしくお願いします。