跳到主要内容

Giving 端点

Giving 模块负责管理奉献、基金、支付处理、订阅以及相关的财务操作。它支持多种支付网关(Stripe、PayPal),处理一次性和定期奉献,追踪奉献批次,并为异步付款事件提供 webhook 处理。

基础路径: /giving

奉献​

基础路径:/giving/donations

方法路径身份验证权限说明
GET/JWTDonations.View 或本人的 personId列出所有奉献。可按 ?batchId= 或 ?personId= 筛选。使用 ?personId= 时,不可抵税基金的奉献会被排除(与奉献报表一致),除非具有 Donations.View 权限的调用者添加 &includeNonDeductible=1(B1Admin 的人员记录会这样做)
GET/:idJWTDonations.View根据 ID 获取奉献
GET/myJWT—获取当前用户的奉献
GET/my/summary?year=JWT—当前用户某一年的奉献总额(默认为今年):{ year, total, count, currency, isConverted },金额已换算为教会货币。为成员主页上的奉献预览提供数据
GET/?startDate=&endDate=JWTDonations.View日期在范围内(含首尾)的奉献。两个日期均为必填,格式为 YYYY-MM-DD,否则返回 400。B1Admin 的奉献报表页面以此方式请求一个自然年,而不是整个教会的全部历史
GET/summaryJWTDonations.ViewSummary获取奉献汇总。可按 ?startDate=&endDate=&type= 筛选。使用 type=person 可按人员细分
GET/testEmailPublic—发送测试邮件(用于开发/调试)
POST/JWTDonations.Edit 或 Donations.Enter创建或更新奉献(批次)。仅具有 Donations.Enter 时,目标批次以及(更新时)奉献当前所属的批次都必须是开放的,且网关奉献(带有 transactionId 的)不可更改;否则返回 403 { "error": "This batch is closed." }
DELETE/:idJWTDonations.Edit 或 Donations.Enter删除奉献。仅具有 Donations.Enter 时:奉献必须位于开放的批次中,且不能是网关奉献,否则返回 403

示例:按批次列出奉献​

GET /giving/donations?batchId=abc-123
Authorization: Bearer <token>
[
{
"id": "don-456",
"batchId": "abc-123",
"personId": "per-789",
"donationDate": "2025-03-15T00:00:00.000Z",
"amount": 100.00,
"method": "card"
}
]

示例:获取奉献汇总​

GET /giving/donations/summary?startDate=2025-01-01&endDate=2025-12-31
Authorization: Bearer <token>
[
{
"week": "2025-01-06",
"fund": "General Fund",
"totalAmount": 2500.00,
"count": 15
}
]

奉献批次​

基础路径:/giving/donationbatches

继承 GenericCrudController,提供 CRUD 路由:getById、getAll、post、delete。删除操作也会删除批次内的所有奉献。

方法路径身份验证权限说明
GET/JWTDonations.ViewSummary 或 Donations.Enter列出所有奉献批次
GET/:idJWTDonations.ViewSummary 或 Donations.Enter根据 ID 获取奉献批次
POST/JWTDonations.Edit 或 Donations.Enter创建或更新奉献批次。仅具有 Donations.Enter 时:更新已有批次需要该批次处于开放状态,否则返回 403 { "error": "This batch is closed." }。此处会忽略 status,因此保存批次无法将其重新开放
POST/:id/closeJWTDonations.Edit关闭批次:将 status 设为 closed,closedDate 设为当前时间,closedBy 设为调用者的用户 ID。返回该批次
POST/:id/reopenJWTDonations.Edit重新开放批次:将 status 设为 open,并清除 closedDate 和 closedBy。返回该批次
DELETE/:idJWTDonations.Edit删除批次及其所有奉献

每个批次都包含 status(open 或 closed;新建批次和已有批次均为 open)、closedDate 和 closedBy。Donations.Edit 可以更改任何批次中的奉献;Donations.Enter(在角色编辑器中显示为 Enter Donations(录入奉献))只能在批次处于开放状态时添加、更改或删除奉献及基金拆分。

捐献(Donate)​

基础路径:/giving/donate

处理面向公众的捐献流程,包括扣款、订阅、webhook 和手续费计算。此处未启用基础 CRUD 路由;所有端点均为自定义端点。

方法路径身份验证权限说明
GET/gateways/:churchIdPublic—获取某教会可用的支付网关(仅公钥)
POST/client-tokenJWT—生成用于初始化网关的客户端令牌
POST/create-orderJWT—创建支付订单(PayPal 风格的结账)
POST/chargeJWT—处理一次性奉献扣款
POST/subscribeJWT—创建定期奉献订阅
POST/logPublic—记录一笔奉献。请求体:{ donation, fundData }
POST/webhook/:providerPublic—接收支付 webhook 事件(Stripe、PayPal)。需要 ?churchId=
POST/replay-stripe-eventsJWTDonations.Edit重放某日期范围内的 Stripe 事件。请求体:{ startDate, endDate, dryRun }
POST/feePublic—计算交易手续费。请求体:{ type, provider, gatewayId, amount, currency }。需要 ?churchId=
POST/captcha-verifyPublic—验证 reCAPTCHA 令牌。请求体:{ token, churchId? }。通过人机验证时返回 { response: "human", pass },其中 pass 是一个有效期为 10 分钟的已签名访客奉献通行证(若发送了 churchId,则仅对该教会有效)

当 API 以 CAPTCHA_ENFORCE=true 运行时,访客(未登录)调用 /giving/donate/create-order、/charge、/subscribe、/giving/paymentmethods/addcard 和 /giving/paymentmethods/ach-setup-intent-anon(以及访客的付费 POST /content/registrations/register 调用)时,请求体中必须包含该 captchaPass,否则将返回 403 Captcha verification required。由于 Stripe 访客流程会进行两次调用(先添加银行卡,再扣款),通行证在过期前可以重复使用。已登录的调用不受影响。CAPTCHA_ENFORCE 默认为 false;@churchapps/apphelper 的访客奉献表单会自动发送该通行证。

示例:处理一次性奉献扣款​

POST /giving/donate/charge
Authorization: Bearer <token>

{
"provider": "stripe",
"amount": 50.00,
"currency": "usd",
"person": { "id": "per-123", "email": "donor@example.com" },
"funds": [{ "id": "fund-001", "name": "General Fund", "amount": 50.00 }],
"church": { "name": "First Church", "subDomain": "firstchurch" }
}
{
"id": "ch_abc123",
"status": "succeeded",
"provider": "stripe"
}

示例:创建定期订阅​

POST /giving/donate/subscribe
Authorization: Bearer <token>

{
"provider": "stripe",
"amount": 100.00,
"customerId": "cus_abc123",
"interval": { "interval_count": 1, "interval": "month" },
"billing_cycle_anchor": 1710460800,
"person": { "id": "per-123", "email": "donor@example.com" },
"funds": [{ "id": "fund-001", "name": "General Fund", "amount": 100.00 }],
"church": { "name": "First Church", "subDomain": "firstchurch" }
}
{
"id": "sub_xyz789",
"status": "active",
"provider": "stripe"
}

基金​

基础路径:/giving/funds

继承 GenericCrudController,提供 CRUD 路由:getById、getAll、post、delete。view 权限为 null(查看基金无需权限)。

方法路径身份验证权限说明
GET/JWT—列出所有基金
GET/:idJWT—根据 ID 获取基金
GET/churchId/:churchIdPublic—获取某教会的所有基金(公开)
GET/public/:churchId/:fundId/total?startDate=&endDate=Public—获取某基金的奉献总额:{ fundId, totalAmount, donationCount }。为网站构建器的 campaignProgress 元素提供数据
POST/JWTDonations.Edit创建或更新基金
DELETE/:idJWTDonations.Edit删除基金

基金奉献​

基础路径:/giving/funddonations

追踪单笔奉献如何分配到各个基金。此处未启用基础 CRUD 路由;所有端点均为自定义端点。

方法路径身份验证权限说明
GET/JWTDonations.View列出基金奉献。可按 ?donationId=、?personId=、?fundId= 或 ?fundName= 筛选。可选择添加 ?startDate=&endDate= 进行日期筛选
GET/:idJWTDonations.View根据 ID 获取基金奉献
GET/myJWT—获取当前用户的基金奉献
POST/JWTDonations.Edit 或 Donations.Enter创建或更新基金奉献(批次)。仅具有 Donations.Enter 时:所属的父级奉献必须位于开放的批次中,且不能是网关奉献,否则返回 403
DELETE/:idJWTDonations.Edit 或 Donations.Enter删除基金奉献。对于 Donations.Enter,适用相同的开放批次规则

网关​

基础路径:/giving/gateways

管理支付网关配置(Stripe、PayPal 等)。此处未启用基础 CRUD 路由;所有端点均为自定义端点。网关密钥在存储时会被加密。

方法路径身份验证权限说明
GET/JWT—列出教会的所有网关
GET/:idJWTSettings.Edit根据 ID 获取网关
GET/churchId/:churchIdPublic—获取某教会的网关(仅公钥)
GET/configured/:churchIdPublic—检查某教会是否已配置支付网关
POST/JWTSettings.Edit创建或更新网关(加密密钥,并配置 webhook 和产品)
PATCH/:idJWTSettings.Edit部分更新网关
DELETE/:idJWTSettings.Edit删除网关(同时删除其 webhook)

示例:检查网关配置​

GET /giving/gateways/configured/church-123
{
"configured": true
}

客户​

基础路径:/giving/customers

继承 GenericCrudController,提供 CRUD 路由:getAll、delete。将人员与其支付网关的客户记录相关联。

方法路径身份验证权限说明
GET/JWTDonations.ViewSummary列出所有客户
GET/:idJWTDonations.ViewSummary 或本人记录根据 ID 获取客户
GET/:id/subscriptionsJWTDonations.ViewSummary 或本人记录获取某客户在网关中的订阅
DELETE/:idJWTDonations.Edit删除客户

订阅​

基础路径:/giving/subscriptions

管理定期奉献订阅。此处未启用基础 CRUD 路由;所有端点均为自定义端点。

方法路径身份验证权限说明
GET/JWTDonations.ViewSummary列出所有订阅
GET/:idJWTDonations.ViewSummary根据 ID 获取订阅
POST/JWTDonations.Edit 或本人订阅在支付网关中更新订阅
DELETE/:idJWTDonations.Edit 或本人订阅取消订阅并从数据库中删除。请求体:{ provider, reason }

订阅基金​

基础路径:/giving/subscriptionfunds

追踪定期订阅的基金分配。此处未启用基础 CRUD 路由;所有端点均为自定义端点。

方法路径身份验证权限说明
GET/JWTDonations.View 或本人订阅列出订阅基金。可按 ?subscriptionId= 筛选
GET/:idJWTDonations.ViewSummary根据 ID 获取订阅基金
DELETE/:idJWTDonations.Edit删除订阅基金
DELETE/subscription/:idJWTDonations.Edit 或本人订阅删除某订阅的所有基金

付款方式​

基础路径:/giving/paymentmethods

通过支付网关 API 管理已保存的付款方式(银行卡、银行账户)。此处未启用基础 CRUD 路由;所有端点均为自定义端点。

方法路径身份验证权限说明
GET/personid/:idJWTDonations.View 或本人 personId获取某人已保存的所有付款方式(银行卡、银行账户)
POST/addcardJWT—绑定银行卡付款方式。请求体:{ id, personId, customerId, email, name, churchId, provider }
POST/updatecardJWTDonations.Edit 或本人 personId更新银行卡信息。请求体:{ personId, paymentMethodId, cardData, provider }
POST/ach-setup-intentJWTDonations.Edit 或本人 personId为绑定银行账户创建 Stripe ACH SetupIntent。请求体:{ personId, customerId, email, name, churchId }
POST/ach-setup-intent-anonPublic—为访客奉献创建匿名 ACH SetupIntent。请求体:{ email, name, churchId, gatewayId }
POST/addbankaccountJWTDonations.Edit 或本人 personId通过令牌添加银行账户(已弃用;请使用 ach-setup-intent)。请求体:{ id, personId, customerId, email, name }
POST/updatebankJWTDonations.Edit 或本人 personId更新银行账户信息。请求体:{ paymentMethodId, personId, bankData, customerId }
POST/verifybankJWTDonations.Edit 或本人客户通过小额测试打款验证银行账户。请求体:{ paymentMethodId, customerId, amountData }
DELETE/:id/:customeridJWTDonations.Edit 或本人客户删除付款方式(银行卡或银行账户)

事件日志​

基础路径:/giving/eventLog

继承 GenericCrudController,提供 CRUD 路由:getById、getAll、post、delete。用于记录支付网关 webhook 事件,以便审计和去重。

方法路径身份验证权限说明
GET/JWTDonations.ViewSummary列出所有事件日志
GET/:idJWTDonations.ViewSummary根据 ID 获取事件日志
GET/type/:typeJWTDonations.ViewSummary按事件类型获取事件日志
POST/JWTDonations.Edit创建或更新事件日志
DELETE/:idJWTDonations.Edit删除事件日志

相关页面​