sales-reporting

信頼できる情報源

hubspot <command> --help が正式な情報源です。bulk-operations/SKILL.md を基盤にしてください。JSONL の形式、バッチ読み取りのルール、ページネーションはそこに記載されています。パターンの再形成: bulk-operations/resources/json-patterns.md。search/list は 1 回の呼び出しあたり最大 100 行です。結果がちょうど 100 件の場合はほぼ確実に切り捨てられているため、集計する前に bulk-operations/SKILL.md を使ってページネーションしてください。

プロパティと出力形式に関する注意

• すべての CRM プロパティ値は JSONL 内で 文字列 として返されます。ブール値も含まれます。hs_is_closed_won は "true"/"false"（文字列）として返され、amount は数値文字列です。算術には tonumber を使用し、クライアント側でフィルタリングする際はブール値を文字列として比較してください（== "true"）。
• 数値プロパティは未設定または空の場合、null または 空文字列（""）になる可能性があります。tonumber は "" で異常終了します。常に select(. != null and . != "") | tonumber でガードしてください。
• --filter 式では、hs_is_closed_won=true と hs_is_closed!=true が機能します。API が値を解析します。
• --properties は標準のネスト形式を返します: {"id":"123","properties":{"amount":"5000","dealname":"..."}}。jq ではフィールドを .properties.amount として参照してください。
• dealstage のステージ ID はポータル固有です。hubspot pipelines stages --type deals --pipeline <id> でマッピングするか（または hubspot pipelines list/get に埋め込まれた stages 配列を読む）してください。hubspot pipelines はアプリトークン専用です — 認証のセクションを参照してください。ユーザー OAuth では 403 になります。
• hubspot_owner_id は数値文字列です。hubspot owners list で名前に解決してください（フィールド: id、firstName、lastName、email）。hubspot owners list はユーザー OAuth（hubspot auth login）とサービスキーの両方で機能します。

1. 日次ブリーフィング

日付ウィンドウは macOS と GNU date で異なります:

# macOS
TODAY=$(date +%Y-%m-%d); NEXT_7=$(date -v+7d +%Y-%m-%d); YESTERDAY=$(date -v-1d +%Y-%m-%d)
# Linux
TODAY=$(date +%Y-%m-%d); NEXT_7=$(date -d '7 days' +%Y-%m-%d); YESTERDAY=$(date -d '1 day ago' +%Y-%m-%d)

今後 7 日間に成約する案件:

hubspot objects search --type deals \
  --filter "closedate>$TODAY AND closedate<$NEXT_7 AND hs_is_closed!=true" \
  --properties dealname,amount,closedate,hubspot_owner_id

過去 24 時間に更新された案件:

hubspot objects search --type deals \
  --filter "hs_lastmodifieddate>$YESTERDAY AND hs_is_closed!=true" \
  --properties dealname,amount,dealstage,hs_lastmodifieddate

オープンパイプラインのサマリー行:

hubspot objects search --type deals --filter "hs_is_closed!=true" --properties amount \
| jq -rs '{count: length, value: ([.[].properties.amount | select(. != null and . != "") | tonumber] | add // 0 | round)}
          | "Open pipeline: \(.count) deals, $\(.value)"'

2. パイプラインのスナップショット

ステージ別 — dealstage ごとの件数と金額:

hubspot objects search --type deals --filter "hs_is_closed!=true" \
  --properties dealstage,amount \
| jq -rs '
    group_by(.properties.dealstage)
    | map({stage: .[0].properties.dealstage, count: length,
           total: ([.[].properties.amount | select(. != null and . != "") | tonumber] | add // 0 | round)})
    | sort_by(-.total) | .[] | "\(.stage)\tcount: \(.count)\tvalue: $\(.total)"' \
| column -t -s$'\t'

担当者別:

hubspot objects search --type deals --filter "hs_is_closed!=true" \
  --properties amount,hubspot_owner_id \
| jq -rs '
    group_by(.properties.hubspot_owner_id)
    | map({owner: .[0].properties.hubspot_owner_id, count: length,
           total: ([.[].properties.amount | select(. != null and . != "") | tonumber] | add // 0 | round)})
    | sort_by(-.total) | .[] | "owner \(.owner)\tdeals: \(.count)\tvalue: $\(.total)"' \
| column -t -s$'\t'

担当者 ID に名前を付けるには、owners ファイルを一度ダンプして結合します:

hubspot owners list | jq -r '"\(.id)\t\(.firstName) \(.lastName) <\(.email)>"' > /tmp/owners.tsv

3. 勝敗分析

受注には hs_is_closed_won=true、失注には hs_is_closed=true AND hs_is_closed_won!=true でフィルタリングします。closedate>=YYYY-MM-DD AND closedate<YYYY-MM-DD でスコープを指定します。

期間内の受注 / 失注:

hubspot objects search --type deals \
  --filter "hs_is_closed_won=true AND closedate>=2026-04-01 AND closedate<2026-07-01" \
  --properties dealname,amount,closedate,hubspot_owner_id

hubspot objects search --type deals \
  --filter "hs_is_closed=true AND hs_is_closed_won!=true AND closedate>=2026-04-01 AND closedate<2026-07-01" \
  --properties dealname,amount,closedate,hubspot_owner_id

担当者別の勝率 — 期間内のすべてのクローズ済み案件を取得し、グループ化して除算します。注意: hs_is_closed_won は文字列として返されるため、== "true" で比較してください。

hubspot objects search --type deals \
  --filter "hs_is_closed=true AND closedate>=2026-01-01" \
  --properties hubspot_owner_id,hs_is_closed_won,amount \
| jq -rs '
    group_by(.properties.hubspot_owner_id)
    | map({owner: .[0].properties.hubspot_owner_id,
           total: length,
           won: ([.[] | select(.properties.hs_is_closed_won == "true")] | length),
           won_value: ([.[] | select(.properties.hs_is_closed_won == "true")
                       | .properties.amount | select(. != null and . != "") | tonumber] | add // 0 | round)})
    | map(. + {win_rate: ((.won / .total * 100) | round)})
    | sort_by(-.won_value)
    | .[] | "owner \(.owner)\twon: \(.won)/\(.total)\trate: \(.win_rate)%\twon: $\(.won_value)"' \
| column -t -s$'\t'

成約月別の売上（受注案件）:

hubspot objects search --type deals \
  --filter "hs_is_closed_won=true AND closedate>=2026-01-01" \
  --properties amount,closedate \
| jq -rs '
    group_by(.properties.closedate[0:7])
    | map({month: .[0].properties.closedate[0:7], count: length,
           revenue: ([.[].properties.amount | select(. != null and . != "") | tonumber] | add // 0 | round)})
    | sort_by(.month) | .[] | "\(.month)\tdeals: \(.count)\trevenue: $\(.revenue)"' \
| column -t -s$'\t'

4. 保存済みレポート

hubspot reports ファミリーは HubSpot の保存済みレポートと CRM-SQL レポートをサーバー側で実行するため、集計をクライアント側で再計算する必要はありません:

• reports list / get <id> — 保存済みレポートを閲覧・確認します。
• reports fetch-dataset <id> — 保存済みレポートをサーバー側で再実行し、そのデータセットを返します。
• reports create "<CRM SQL>" — CRM-SQL クエリからレポートを作成します（コンパニオンスキルで SQL を生成できます）。reports insights <id> は AI インサイトを生成します（非同期、完了までポーリング）。
• reports update <id> / clone <id> / favorite <id> / unfavorite <id> — レポートのメタデータを管理します。
• reports delete <id> — 不可逆、ダイジェストで保護: まず --dry-run、次に --digest <hash> --confirm "<report name>"（confirm = レポートの名前）。

全機能と CRM-SQL の文法については hubspot reports --help を実行してください。

5. 勝敗のコンテキスト: シーケンスの登録

hubspot sequences enrollments <contact_id> は、連絡先の Sales Hub シーケンス登録履歴を返します（読み取り専用）。アウトリーチに対する勝敗の帰属に役立ちます。各行: {"contactId":789,"enrollments":[{"sequenceName":"Q4 Outbound","state":"FINISHED","enrolledAt":"...","currentStepOrder":5,"totalSteps":6}]}。これを案件の関連連絡先に結合すると、「この案件はシーケンスを通じて対応されたか?」というビューが得られます。hubspot sequences enrollments --help を参照してください。

既知の制限事項

• 受注/失注ステージは hubspot pipelines stages から識別できます。各ステージの metadata には isClosed/probability が含まれます（例: jq -r 'select(.metadata.probability=="1.0") | .id'）。ディール自体の hs_is_closed_won も機能します。
• チームオブジェクトはありません。hubspot_owner_id でグループ化し、名前はクライアント側で hubspot owners list から解決してください。
• hubspot pipelines はアプリトークン専用であり、ユーザー OAuth では 403 になります。hubspot owners list はユーザー OAuth でも機能します。生の ID を保持して警告を出してください。pipelines が利用できない場合でもレポートを失敗させないでください。
• CRM の数値プロパティは null または "" になることがあります。常に tonumber を select(. != null and . != "") でガードしてください。