FundraiseUpAPI技能Skill fundraiseup

FundraiseUp API 技能

概览

这项技能使得 Claude 能够与 FundraiseUp REST API 交互，处理捐赠、管理定期计划、检索支持者数据以及访问筹款分析。FundraiseUp 是一个数字筹款平台，允许非营利组织从各种渠道处理捐赠。

配置

所需环境变量：

FUNDRAISEUP_API_KEY - API 密钥（例如，ABEDDDD_XSSSHwzZc98KR53CWQeWeclA）

基础 URL

https://api.fundraiseup.com/v1

认证

API 密钥生成

1. 前往 Dashboard > Settings > API keys
2. 点击 “Create API key”
3. 输入描述性名称
4. 选择数据模式：
   • Live data: 生产使用
   • Test data: 测试使用（密钥有 test_ 前缀）
5. 选择权限：
   • 检索捐赠数据
   • 创建新的捐赠
   • 生成捐赠者门户访问链接
6. 安全保存 API 密钥（仅显示一次）

认证头部

所有 API 请求必须包含带有 Bearer 令牌的 Authorization 头部：

Authorization: Bearer YOUR_API_KEY

重要说明

• API 密钥限定于特定账户/子账户
• 父账户 API 密钥不能为子账户创建捐赠
• 只有组织管理员才能创建 API 密钥
• 不要公开暴露 API 密钥

速率限制

• 每秒 8 个请求
• 每分钟 128 个请求
• 实现带有指数退避的重试逻辑以处理速率限制

必需头部

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_API_KEY

---

API 端点

1. 捐赠

列出捐赠

端点： GET /donations

描述： 使用基于游标的分页检索所有捐赠。

查询参数：

• limit （可选）：每页记录数（1-100，默认：10）
• starting_after （可选）：分页游标（捐赠 ID）
• ending_before （可选）：向后分页游标（捐赠 ID）
• 注意：starting_after 和 ending_before 互斥

示例请求：

curl --request GET \
  --url 'https://api.fundraiseup.com/v1/donations?limit=50' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}'

响应字段：

• id: 捐赠标识符
• created_at: ISO 8601 时间戳
• livemode: 布尔值（真实捐赠为 true，测试为 false）
• amount: 选定货币中的捐赠金额
• amount_in_default_currency: 组织默认货币中的金额
• currency: 三个字母的 ISO 代码（小写）
• status: 捐赠状态（例如，成功、待处理、失败）
• campaign: 活动详情（id、code、name）
• supporter: 支持者信息
• recurring_plan: 定期计划详情（如适用）
• designation: 基金/项目指定
• tribute: 致敬信息（如提供）
• custom_fields: 自定义字段值数组
• processing_fee: 处理费用详情
• platform_fee: 平台费用详情
• fees_covered: 捐赠者承担的费用金额

---

获取单个捐赠

端点： GET /donations/{id}

描述： 检索特定捐赠的详细信息。

路径参数：

• id （必需）：捐赠 ID

示例请求：

curl --request GET \
  --url 'https://api.fundraiseup.com/v1/donations/DFQLCFEP' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}'

---

创建捐赠

端点： POST /donations

描述： 创建一次性或定期捐赠。API 创建的捐赠将有 “API” 作为捐赠来源。

先决条件：

• 将 Stripe 账户连接到 FundraiseUp 并激活
• 带有货币支付方式的活动
• 具有 “创建新捐赠” 权限的 API 密钥
• Stripe 支付方式 ID（通过 Stripe API 创建）
• 满足 PCI 合规性要求

请求正文：

{
  "campaign_id": "FUNCPJTZZQR",
  "amount": "25.00",
  "currency": "usd",
  "payment_method_id": "pm_1234567890abcdef",
  "supporter": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "mailing_address": {
      "line1": "123 Main St",
      "line2": "Apt 4B",
      "city": "New York",
      "region": "NY",
      "postal_code": "10001",
      "country": "us"
    }
  },
  "recurring_plan": {
    "frequency": "monthly"
  },
  "designation": [
    {
      "id": "EHHJ9R36"
    }
  ],
  "tribute": {
    "type": "in_honor_of",
    "honoree": "Jane Smith"
  },
  "comment": "Monthly donation for general fund",
  "anonymous": false,
  "custom_fields": [
    {
      "name": "referral_source",
      "value": "Email Campaign"
    }
  ]
}

必需字段：

• campaign_id: 必须属于账户并且处于活动状态
• amount: 十进制字符串（例如，“9.99” 表示 USD，“200” 表示 JPY），最低 $1 或等值金额
• currency: 三个字母的 ISO 代码（小写）
• payment_method_id: Stripe 支付方式 ID
• supporter.first_name: 最多 256 个字符
• supporter.last_name: 最多 256 个字符
• supporter.email: 有效的电子邮件地址（API 不验证）
• supporter.phone: 最多 20 个字符（如果活动要求，则必需）
• supporter.mailing_address: 如果活动要求，则必需

可选字段：

• recurring_plan.frequency: 创建定期计划（“monthly”, “weekly”, “quarterly”, “yearly”, “daily”）
• designation: 指定 ID 数组
• tribute.type: “in_honor_of” 或 “in_memory_of”
• tribute.honoree: 被纪念人的姓名
• comment: 捐赠评论
• anonymous: 布尔值（默认：false）
• custom_fields: 自定义字段对象数组

示例请求：

curl --request POST \
  --url 'https://api.fundraiseup.com/v1/donations' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaign_id": "FUNCPJTZZQR",
    "amount": "50.00",
    "currency": "usd",
    "payment_method_id": "pm_1234567890",
    "supporter": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  }'

重要说明：

• 所有字符串参数都会进行修剪；空字符串转换为 null
• 地址和电子邮件不会被格式化或验证
• 目前仅支持信用卡支付
• 费用可能最初显示为 0，直到 Stripe 最终确定（使用 Events 端点获取最终费用）

---

更新捐赠

端点： PATCH /donations/{id}

描述： 更新捐赠。仅允许在创建后 24 小时内更新，且仅限于 API 创建的捐赠。

路径参数：

• id （必需）：捐赠 ID

限制：

• 只有 API 创建的捐赠才能更新
• 更新必须在创建后 24 小时内进行
• 不支持批量更新

---

2. 定期计划

列出定期计划

端点： GET /recurring_plans

描述： 检索所有定期捐赠计划。

查询参数：

• limit （可选）：每页记录数（1-100）
• starting_after （可选）：分页游标
• ending_before （可选）：向后分页游标

示例请求：

curl --request GET \
  --url 'https://api.fundraiseup.com/v1/recurring_plans?limit=50' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}'

响应字段：

• id: 定期计划标识符
• created_at: ISO 8601 时间戳
• frequency: “monthly”, “weekly”, “quarterly”, “yearly”, 或 “daily”
• amount: 定期捐赠金额
• currency: 三个字母的 ISO 代码
• status: 计划状态（active, paused, canceled）
• next_installment_at: 下一次预定捐赠日期
• ended_at: 结束日期（如果设置）
• campaign: 相关活动详情
• supporter: 支持者信息

---

获取单个定期计划

端点： GET /recurring_plans/{id}

描述： 检索特定定期计划的详细信息。

路径参数：

• id （必需）：定期计划 ID

示例请求：

curl --request GET \
  --url 'https://api.fundraiseup.com/v1/recurring_plans/RVSHJNPJ' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}'

---

更新定期计划

端点： PATCH /recurring_plans/{id}

描述： 更新定期计划。仅允许在创建后 24 小时内更新，且仅限于 API 创建的计划。

---

3. 支持者

列出支持者

端点： GET /supporters

描述： 检索所有支持者/捐赠者。

查询参数：

• limit （可选）：每页记录数（1-100）
• starting_after （可选）：分页游标
• ending_before （可选）：向后分页游标

示例请求：

curl --request GET \
  --url 'https://api.fundraiseup.com/v1/supporters?limit=50' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}'

响应字段：

• id: 支持者标识符
• created_at: ISO 8601 时间戳
• email: 电子邮件地址
• first_name: 名字
• last_name: 姓氏
• phone: 电话号码
• mailing_address: 地址详情
• mailing_list_subscribed: 布尔值
• anonymous: 布尔值
• employer: 雇主名称（如果提供）

---

获取单个支持者

端点： GET /supporters/{id}

描述： 检索特定支持者的详细信息。

路径参数：

• id （必需）：支持者 ID

示例请求：

curl --request GET \
  --url 'https://api.fundraiseup.com/v1/supporters/SXXXXXXX' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}'

---

4. 事件

列出事件

端点： GET /events

描述： 检索捐赠、定期计划和支持者的审计日志事件。

查询参数：

• limit （可选）：每页记录数（1-100）
• starting_after （可选）：分页游标
• ending_before （可选）：向后分页游标

示例请求：

curl --request GET \
  --url 'https://api.fundraiseup.com/v1/events?limit=50' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}'

用例：

• 跟踪费用最终确定时间（查找 donation.success 事件）
• 监控状态变化
• 合规性审计跟踪
• 集成调试

---

5. 活动

列出活动

端点： GET /campaigns

描述： 检索所有活动。

查询参数：

• limit （可选）：每页记录数（1-100）
• starting_after （可选）：分页游标
• ending_before （可选）：向后分页游标

示例请求：

curl --request GET \
  --url 'https://api.fundraiseup.com/v1/campaigns' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}'

响应字段：

• id: 活动标识符
• code: 活动代码
• name: 活动名称
• status: 活动状态

---

获取单个活动

端点： GET /campaigns/{id}

路径参数：

• id （必需）：活动 ID

---

6. 指定

列出指定

端点： GET /designations

描述： 检索所有基金/项目指定。

示例请求：

curl --request GET \
  --url 'https://api.fundraiseup.com/v1/designations' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}'

---

7. 捐赠者门户访问

生成支持者门户链接

端点： POST /donor_portal/access_links/supporters/{id}

描述： 为支持者生成一个安全的链接，以便他们无需登录即可访问他们的捐赠者门户。

路径参数：

• id （必需）：支持者 ID

先决条件：

• API 密钥启用了 “生成捐赠者门户访问链接” 权限

示例请求：

curl --request POST \
  --url 'https://api.fundraiseup.com/v1/donor_portal/access_links/supporters/64b0ba9d9a19ea001fa3516a' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}'

响应：

{
  "url": "https://yourorg.org/login/?auth=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

重要安全说明：

• 链接仅有效 1分钟
• 只能在捐赠者门户上下文中使用
• 不要 通过电子邮件、短信或公共渠道分享
• 提供对敏感数据的访问（支付方式、捐赠历史、收据）
• 在生成链接之前验证支持者所有权
• 实施自动重定向（不需要手动操作）

---

生成定期计划门户链接

端点： POST /donor_portal/access_links/recurring_plans/{id}

描述： 为支持者生成一个链接，以便他们访问捐赠者门户中的特定定期计划。

路径参数：

• id （必需）：定期计划 ID

可选查询参数：

• return_url （可选）：管理定期计划后返回的 URL

示例请求：

curl --request POST \
  --url 'https://api.fundraiseup.com/v1/donor_portal/access_links/recurring_plans/RVSHJNPJ' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}'

响应：

{
  "url": "https://yourorg.org/login/?auth=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

---

分页最佳实践

所有列表端点使用基于游标的分页：

1. 初始请求： 设置 limit 参数（1-100）
2. 下一页： 使用上一页最后一个项目的 id 在 starting_after
3. 前一页： 使用第一页第一个项目的 id 在 ending_before
4. 排序： 记录按创建日期排序（最新第一），然后按 ID 排序（Z 到 A）

示例分页流程：

# 第一页
GET /donations?limit=50

# 第二页（使用第一页最后一个捐赠 ID）
GET /donations?limit=50&starting_after=LAST_DONATION_ID

# 上一页
GET /donations?limit=50&ending_before=FIRST_DONATION_ID

---

错误处理

标准 HTTP 响应代码

• 200 OK: 成功的 GET 请求
• 201 Created: 成功的 POST 请求
• 400 Bad Request: 无效的请求参数
• 401 Unauthorized: 缺少或无效的 API 密钥
• 403 Forbidden: 权限不足
• 404 Not Found: 资源未找到
• 429 Too Many Requests: 速率限制超出
• 500 Internal Server Error: 服务器错误

最佳实践

1. 实现速率限制的指数退避
2. 记录所有 API 错误及请求详情
3. 发送到 API 之前验证数据
4. 优雅地处理空值
5. 使用 Events 端点检查最终费用

---

代码示例

Python 示例

import requests
import os

API_KEY = os.environ.get('FUNDRAISEUP_API_KEY')
BASE_URL = 'https://api.fundraiseup.com/v1'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
}

# 列出捐赠
def get_donations(limit=50):
    url = f'{BASE_URL}/donations'
    params = {'limit': limit}
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    return response.json()

# 创建捐赠
def create_donation(campaign_id, amount, currency, payment_method_id, supporter):
    url = f'{BASE_URL}/donations'
    data = {
        'campaign_id': campaign_id,
        'amount': str(amount),
        'currency': currency,
        'payment_method_id': payment_method_id,
        'supporter': supporter
    }
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    return response.json()

# 获取单个捐赠
def get_donation(donation_id):
    url = f'{BASE_URL}/donations/{donation_id}'
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    return response.json()

Node.js 示例

const axios = require('axios');

const API_KEY = process.env.FUNDRAISEUP_API_KEY;
const BASE_URL = 'https://api.fundraiseup.com/v1';

const headers = {
  'Authorization': `Bearer ${API_KEY}`,
  'Accept': 'application/json',
  'Content-Type': 'application/json'
};

// 列出捐赠
async function getDonations(limit = 50) {
  const response = await axios.get(`${BASE_URL}/donations`, {
    headers,
    params: { limit }
  });
  return response.data;
}

// 创建捐赠
async function createDonation(campaignId, amount, currency, paymentMethodId, supporter) {
  const response = await axios.post(`${BASE_URL}/donations`, {
    campaign_id: campaignId,
    amount: amount.toString(),
    currency,
    payment_method_id: paymentMethodId,
    supporter
  }, { headers });
  return response.data;
}

// 获取单个捐赠
async function getDonation(donationId) {
  const response = await axios.get(`${BASE_URL}/donations/${donationId}`, { headers });
  return response.data;
}

cURL 示例与环境变量

# 设置你的 API 密钥为环境变量
export FUNDRAISEUP_API_KEY="your_api_key_here"

# 列出捐赠
curl --request GET \
  --url 'https://api.fundraiseup.com/v1/donations?limit=50' \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $FUNDRAISEUP_API_KEY"

# 创建捐赠
curl --request POST \
  --url 'https://api.fundraiseup.com/v1/donations' \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $FUNDRAISEUP_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "campaign_id": "FUNCPJTZZQR",
    "amount": "25.00",
    "currency": "usd",
    "payment_method_id": "pm_1234567890",
    "supporter": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com"
    }
  }'

# 获取单个捐赠
curl --request GET \
  --url "https://api.fundraiseup.com/v1/donations/DFQLCFEP" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $FUNDRAISEUP_API_KEY"

---

测试

测试模式

• 生成 “Test data” 模式的 API 密钥
• 测试密钥有 test_ 前缀
• 测试模式数据不影响实时数据或银行网络
• 使用测试 Stripe 支付方式创建测试捐赠

测试 URL 参数

在任何 URL 添加 fundraiseupLivemode=no 进行测试，不处理真实捐赠

---

集成模式

历史数据同步

1. 使用 limit 参数获取批次（推荐：50-100）
2. 使用 starting_after 与最后记录 ID 获取下一批
3. 顺序处理批次
4. 实施错误处理和重试逻辑

实时轮询

1. 定期轮询 API（尊重速率限制）
2. 使用 Events 端点跟踪变化
3. 存储最后处理记录 ID
4. 使用 starting_after 获取仅新记录

基于事件的集成

• 使用 Zapier 进行事件触发（FundraiseUp 不支持直接 webhooks）
• 配置 Zapier 在 FundraiseUp 事件上触发
• 基于事件在你的系统中触发同步作业

---

常见用例

1. 处理线下捐赠

   • 面对面筹款
   • 直邮捐赠
   • 电话募捐承诺
   • 活动注册

2. CRM 集成

   • 将捐赠数据同步到 CRM（Salesforce、HubSpot 等）
   • 更新支持者记录
   • 跟踪定期计划
   • 生成报告

3. 分析和报告

   • 为 BI 工具导出捐赠数据
   • 跟踪活动表现
   • 分析捐赠者行为
   • 计算终身价值

4. 捐赠者门户集成

   • 从自定义门户进行无缝认证
   • 直接访问定期计划管理
   • 单点登录体验

---

安全最佳实践

1. API 密钥管理

   • 将 API 密钥存储在环境变量中（不要硬编码）
   • 为不同集成使用单独的密钥
   • 定期轮换密钥
   • 立即撤销泄露的密钥

2. 仅使用 HTTPS

   • 所有请求必须使用 HTTPS
   • 拒绝 HTTP 请求

3. 数据验证

   • 在发送到 API 之前验证所有输入
   • 清理用户提供的数据
   • 在处理之前检查响应数据

4. PCI 合规性

   • 不要在应用程序中处理原始卡数据
   • 使用 Stripe 支付方式 API 进行卡处理
   • 满足 PCI DSS 要求（直接 API 集成的 SAQ D）
   • 考虑使用 Stripe Elements 减少 PCI 范围

5. 捐赠者门户安全

   • 在生成访问链接之前验证支持者所有权
   • 使用自动重定向（不要手动链接）
   • 不要通过电子邮件或公共渠道分享访问链接
   • 访问链接在 1 分钟后过期

---

限制和考虑

1. 支付方式： 目前仅支持信用卡
2. 更新： 仅允许在创建后 24 小时内更新，仅限于 API 创建的记录
3. 批量操作： 不支持批量更新
4. Webhooks： 不支持直接 webhooks（使用 Zapier 处理事件）
5. 子账户： 父账户 API 密钥不能为子账户创建捐赠
6. 费用计算： 费用可能最初显示为 0；使用 Events 端点获取最终费用
7. 地址验证： API 不格式化或验证地址
8. 电子邮件验证： API 不验证电子邮件地址
9. 迁移： REST API 不是迁移机制（使用迁移服务）

---

额外资源

• 官方文档：https://fundraiseup.com/docs/rest-api/
• API 资源：https://fundraiseup.com/docs/rest-api-resources/
• 捐赠者门户集成：https://fundraiseup.com/docs/seamless-donor-portal/
• 支持：https://fundraiseup.com/support/

---

故障排除

常见问题

401 未授权

• 检查 API 密钥是否正确且有效
• 验证授权头部格式
• 确保 API 密钥具有所需权限

429 速率限制超出

• 实施指数退避
• 降低请求频率
• 尽可能批量操作

400 错误请求

• 验证所有必需字段是否存在
• 检查数据类型和格式
• 确保货币代码为小写
• 验证金额格式（十进制字符串）

费用显示为 0

• 费用异步最终确定
• 使用 Events 端点获取最终费用
• 查找 donation.success 事件

无法更新捐赠

• 验证捐赠是否通过 API 创建
• 确保更新在 24 小时内
• 检查 API 密钥权限

---

版本信息

• API 版本：v1
• 最后更新：2026年2月
• 支持的支付方式：仅限信用卡