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 设置 → 开发者 → API 密钥

必需的权限范围

权限范围	操作
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..."

速率限制

• 每分钟 100 个请求
• 自动使用指数退避重试

费用

免费——Attio API 提供宽松的免费套餐。

安全说明

凭证处理

• 将 ATTIO_API_KEY 存储在 .env 文件中（切勿提交到 git）
• 在 Attio 中生成密钥：设置 > 开发者 > API 密钥
• 定期轮换密钥，或在密钥泄露时立即轮换
• 切勿在脚本输出中记录或打印 API 密钥

数据隐私

• CRM 包含敏感的客户和潜在客户信息
• 公司记录包含业务详情和联系信息
• 人员记录包含个人身份信息（姓名、电子邮件、电话号码）
• 备注可能包含机密的会议讨论内容
• 避免不必要地导出完整的 CRM 数据

访问权限范围

• 仅申请最低限度的必要权限范围：
  • record:read - 读取公司和人员（只读）
  • record:write - 创建／更新记录（写入权限）
  • note:read - 读取备注（只读）
  • note:write - 创建备注（写入权限）
• API 密钥可限定为特定权限

合规性注意事项

• 个人身份信息保护：客户数据受隐私法规约束
• GDPR：欧盟客户数据需要符合 GDPR
• 数据最小化：仅访问／导出所需的数据
• 审计跟踪：记录 CRM 操作，以便进行合规审计
• 数据保留：遵循组织的数据保留政策
• 访问控制：仅向授权用户分发 API 密钥
• 客户同意：确保已获得数据处理的适当同意

故障排除

常见问题

问题：字段 ID／slug 无效

**症状：**出现“未找到字段”或“属性无效”错误 **原因：**字段 slug 与 Attio 工作区配置不匹配 解决方法：

• 在 Attio 中检查字段 slug：设置 > 对象 > 字段
• 字段 slug 区分大小写（例如，使用 company_name，而不是 Company_Name）
• 自定义字段有唯一的 slug，请核对拼写是否准确
• 如不确定，请使用 API 列出可用字段

问题：触发速率限制

**症状：**返回 429 状态代码或“超出速率限制” **原因：**超过每分钟 100 个请求的限制 解决方法：

• 在请求之间实施指数退避
• 尽可能将多个操作合并到单个请求中
• 在连续请求之间增加延迟（600 毫秒以上）
• 将请求加入队列并逐步处理

问题：未找到记录

**症状：**已知记录却出现“未找到记录”错误 **原因：**记录 ID 无效、记录已删除或对象类型错误 解决方法：

• 从 Attio URL 或之前的 API 响应中核实记录 ID
• 检查记录是否已删除或合并
• 确保使用正确的对象类型（公司或人员）
• 使用搜索端点通过名称／电子邮件查找记录

问题：API 密钥无效

**症状：**出现 401 未授权或“API 密钥无效” **原因：**密钥已过期、已撤销或配置不正确 解决方法：

• 在 Attio 中重新生成 API 密钥：设置 > 开发者 > API 密钥
• 确认 .env 中已正确设置 ATTIO_API_KEY
• 检查密钥是否包含开头或结尾的空格
• 确保密钥具有执行操作所需的权限范围

问题：权限不足

**症状：**出现“Forbidden”错误或数据缺失 **原因：**API 密钥缺少必需的作用域 解决方案：

• 在 Attio 中检查密钥作用域：Settings > Developers > API Keys
• 创建具有所需作用域（record:read、record:write 等）的新密钥
• 对于笔记：确保具有 note:read 和 note:write 作用域
• 工作区管理员可能需要授予额外权限

问题：创建了重复记录

**症状：**同一家公司／联系人出现多次 **原因：**创建时未进行去重，或字段值不同 解决方案：

• 创建前先搜索，检查是否已有记录
• 使用主要标识符（公司使用域名，联系人使用电子邮件）
• 考虑采用更新或创建模式
• 在 Attio 界面中手动合并重复项

资源

• 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 公司记录

将语音 Agent 数据添加到 CRM

**技能：**voice-agents → attio-crm **使用场景：**将 AI 通话摘要记录到 CRM 流程：

1. 语音 Agent 完成探索或反馈通话
2. 提取通话摘要和关键见解
3. 在 Attio 记录中添加包含通话摘要和后续步骤的笔记