attio-crm

Attio CRM

概要

Attio CRM と連携し、会社、連絡先、メモ、取引をプログラムから管理します。

クイック判断ツリー

What do you need?
│
├── Get/search companies
│   └── references/api-guide.md
│   └── Script: scripts/attio_api.py get-company / search-companies
│
├── Create/update company
│   └── Script: scripts/attio_api.py create-company / update-company
│
├── Create/link contacts
│   └── Script: scripts/attio_api.py create-person
│
├── Add notes to records
│   └── Script: scripts/attio_api.py create-note
│
└── Parse Attio URLs
    └── Script: scripts/attio_api.py parse-url

環境のセットアップ

# Required in .env
ATTIO_API_KEY=your_api_key_here

API キーを取得します：Attio Settings → Developers → API Keys

必要なスコープ

スコープ	操作
record:read	会社と人物の取得／検索
record:write	会社と人物の作成／更新
note:read	メモの一覧表示と取得
note:write	メモの作成と削除

一般的な使用方法

会社を検索する

python scripts/attio_api.py search-companies "Acme Corp" --limit 10

会社を取得する

python scripts/attio_api.py get-company <record_id>

会社を作成する

python scripts/attio_api.py create-company "Microsoft" --domain "microsoft.com"

連絡先を作成する

python scripts/attio_api.py create-person "[email protected]" --first-name "John" --last-name "Smith"

メモを追加する

python scripts/attio_api.py create-note <record_id> "Meeting Notes" "Discussion summary..."

レート制限

• 1 分あたり 100 リクエスト
• 指数バックオフによる自動再試行

費用

無料 - Attio API には充実した無料プランがあります。

セキュリティに関する注意事項

認証情報の取り扱い

• ATTIO_API_KEY は .env ファイルに保存します（git に絶対にコミットしないでください）
• Attio でキーを生成します：Settings > Developers > API Keys
• キーは定期的に、または漏えいした場合にローテーションします
• スクリプトの出力に API キーを記録したり表示したりしないでください

データのプライバシー

• CRM には、機密性の高い顧客情報や見込み顧客情報が含まれます
• 会社レコードには、事業の詳細や連絡先情報が含まれます
• 人物レコードには PII（氏名、メールアドレス、電話番号）が含まれます
• メモには、機密性の高い会議の議論が含まれる場合があります
• 不必要に CRM データ全体をエクスポートしないでください

アクセススコープ

• 必要最小限のスコープをリクエストします：
  • record:read - 会社と人物の読み取り（読み取り専用）
  • record:write - レコードの作成／更新（書き込みアクセス）
  • note:read - メモの読み取り（読み取り専用）
  • note:write - メモの作成（書き込みアクセス）
• API キーには、特定の権限を設定できます

コンプライアンスに関する考慮事項

• PII の保護：顧客データにはプライバシー規制が適用されます
• GDPR：EU の顧客データには GDPR への準拠が必要です
• データの最小化：必要なデータのみを参照／エクスポートしてください
• 監査証跡：コンプライアンス監査に備え、CRM の操作を記録してください
• データ保持：組織のデータ保持ポリシーに従ってください
• アクセス制御：API キーの配布を許可されたユーザーに限定してください
• 顧客の同意：データ処理について適切な同意を得てください

トラブルシューティング

よくある問題

問題：フィールド ID／スラッグが無効

症状：「Field not found」または「Invalid attribute」エラー **原因：**フィールドのスラッグが Attio ワークスペースの設定と一致していません 解決方法：

• Attio でフィールドのスラッグを確認します：Settings > Objects > Fields
• フィールドのスラッグでは大文字と小文字が区別されます（例：Company_Name ではなく company_name）
• カスタムフィールドには固有のスラッグがあります。正確な綴りを確認してください
• 不明な場合は、API を使って利用可能なフィールドを一覧表示します

問題：レート制限に達した

**症状：**429 ステータスコードまたは「rate limit exceeded」 **原因：**1 分あたり 100 リクエストの上限を超過しています 解決方法：

• リクエスト間に指数バックオフを実装します
• 可能であれば、複数の操作を 1 つのリクエストにまとめます
• 連続するリクエストの間に遅延（600ms 以上）を追加します
• リクエストをキューに入れ、段階的に処理します

問題：レコードが見つからない

**症状：**既知のレコードに対して「Record not found」エラーが発生します **原因：**レコード ID が無効、レコードが削除済み、またはオブジェクトタイプが間違っています 解決方法：

• Attio の URL または以前の API レスポンスからレコード ID を確認します
• レコードが削除または統合されていないか確認します
• 正しいオブジェクトタイプ（companies または people）を使用していることを確認します
• 検索エンドポイントを使って、名前／メールアドレスからレコードを探します

問題：API キーが無効

**症状：**401 Unauthorized または「invalid API key」 **原因：**キーの有効期限切れ、取り消し、または設定ミスです 解決方法：

• Attio で API キーを再生成します：Settings > Developers > API Keys
• .env で ATTIO_API_KEY が正しく設定されていることを確認します
• キーの先頭または末尾に空白がないか確認します
• 操作に必要なスコープがキーに設定されていることを確認します

問題：権限が不足しています

症状： 「Forbidden」エラーが表示される、またはデータが欠落している 原因： API キーに必要なスコープがありません 解決策：

• Attio でキーのスコープを確認します：Settings > Developers > API Keys
• 必要なスコープ（record:read、record:write など）を設定した新しいキーを作成します
• メモの場合：note:read と note:write のスコープがあることを確認します
• ワークスペースの管理者による追加の権限付与が必要な場合があります

問題：レコードが重複して作成されます

症状： 同じ会社または人物が複数回表示される 原因： 作成時に重複排除を行っていない、またはフィールド値が異なっている 解決策：

• 既存のレコードがないか、作成前に検索します
• 主識別子（会社の場合はドメイン、人物の場合はメールアドレス）を使用します
• 更新または作成のパターンを検討します
• Attio UI で重複を手動で統合します

リソース

• references/api-guide.md - API ドキュメントの完全版
• references/integration.md - CRM 統合パターン

統合パターン

ミーティングのメモから CRM へ

スキル： transcript-search → attio-crm ユースケース： ミーティングの要約を会社レコードに追加します フロー：

1. transcript-search でクライアントとのミーティングを検索します
2. 重要なポイント、アクションアイテム、要約を抽出します
3. ミーティングの詳細を記載したメモを Attio の会社レコードに作成します

リサーチから CRM へ

スキル： parallel-research → attio-crm ユースケース： リサーチデータで CRM レコードを充実させます フロー：

1. parallel-research で会社の最新情報を調査します
2. 資金調達、チームの規模、技術スタック、ニュースを抽出します
3. 充実させたフィールドで Attio の会社レコードを更新します

音声エージェントから CRM へ

スキル： voice-agents → attio-crm ユースケース： AI 通話の要約を CRM に記録します フロー：

1. 音声エージェントがディスカバリーコールまたはフィードバックコールを完了します
2. 通話の要約と重要な知見を抽出します
3. 通話の要約と次のステップを記載したメモを Attio のレコードに追加します