Перейти к основному содержимому

Эндпоинты Giving

Модуль Giving управляет пожертвованиями, фондами, обработкой платежей, подписками и связанными финансовыми операциями. Он поддерживает несколько платёжных шлюзов (Stripe, PayPal), обрабатывает разовые и регулярные пожертвования, ведёт учёт пакетов пожертвований и обрабатывает вебхуки для асинхронных платёжных событий.

Базовый путь: /giving

Пожертвования​

Базовый путь: /giving/donations

МетодПутьAuthПраваОписание
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. Операция удаления также удаляет все пожертвования внутри пакета.

МетодПутьAuthПраваОписание
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) может только добавлять, изменять или удалять пожертвования и распределение по фондам, пока их пакет открыт.

Пожертвование​

Базовый путь: /giving/donate

Обрабатывает публичный поток пожертвований, включая списания, подписки, вебхуки и расчёт комиссий. Базовые маршруты CRUD не включены; все эндпоинты пользовательские.

МетодПутьAuthПраваОписание
GET/gateways/:churchIdPublic—Получить доступные платёжные шлюзы церкви (только публичные ключи)
POST/client-tokenJWT—Сгенерировать клиентский токен для инициализации шлюза
POST/create-orderJWT—Создать платёжный заказ (checkout в стиле PayPal)
POST/chargeJWT—Провести списание разового пожертвования
POST/subscribeJWT—Создать подписку на регулярное пожертвование
POST/logPublic—Записать пожертвование в журнал. Тело: { donation, fundData }
POST/webhook/:providerPublic—Принимать события платежей через вебхуки (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 (для просмотра фондов право не требуется).

МетодПутьAuthПраваОписание
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 не включены; все эндпоинты пользовательские.

МетодПутьAuthПраваОписание
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 не включены; все эндпоинты пользовательские. Секреты шлюзов хранятся в зашифрованном виде.

МетодПутьAuthПраваОписание
GET/JWT—Список всех шлюзов церкви
GET/:idJWTSettings.EditПолучить шлюз по ID
GET/churchId/:churchIdPublic—Получить шлюзы церкви (только публичные ключи)
GET/configured/:churchIdPublic—Проверить, настроен ли платёжный шлюз у церкви
POST/JWTSettings.EditСоздать или обновить шлюзы (шифрует ключи, создаёт вебхуки и продукты)
PATCH/:idJWTSettings.EditЧастично обновить шлюз
DELETE/:idJWTSettings.EditУдалить шлюз (также удаляет его вебхуки)

Пример: проверка настройки шлюза​

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

Клиенты​

Базовый путь: /giving/customers

Расширяет GenericCrudController маршрутами CRUD: getAll, delete. Связывает людей с записями клиентов в платёжном шлюзе.

МетодПутьAuthПраваОписание
GET/JWTDonations.ViewSummaryСписок всех клиентов
GET/:idJWTDonations.ViewSummary или собственная записьПолучить клиента по ID
GET/:id/subscriptionsJWTDonations.ViewSummary или собственная записьПолучить подписки клиента в платёжном шлюзе
DELETE/:idJWTDonations.EditУдалить клиента

Подписки​

Базовый путь: /giving/subscriptions

Управляет подписками на регулярные пожертвования. Базовые маршруты CRUD не включены; все эндпоинты пользовательские.

МетодПутьAuthПраваОписание
GET/JWTDonations.ViewSummaryСписок всех подписок
GET/:idJWTDonations.ViewSummaryПолучить подписку по ID
POST/JWTDonations.Edit или собственная подпискаОбновить подписки в платёжном шлюзе
DELETE/:idJWTDonations.Edit или собственная подпискаОтменить подписку и удалить её из базы данных. Тело: { provider, reason }

Фонды подписок​

Базовый путь: /giving/subscriptionfunds

Отслеживает распределение по фондам для регулярных подписок. Базовые маршруты CRUD не включены; все эндпоинты пользовательские.

МетодПутьAuthПраваОписание
GET/JWTDonations.View или собственная подпискаСписок фондов подписок. Фильтр: ?subscriptionId=
GET/:idJWTDonations.ViewSummaryПолучить фонд подписки по ID
DELETE/:idJWTDonations.EditУдалить фонд подписки
DELETE/subscription/:idJWTDonations.Edit или собственная подпискаУдалить все фонды подписки

Способы оплаты​

Базовый путь: /giving/paymentmethods

Управляет сохранёнными способами оплаты (картами, банковскими счетами) через API платёжных шлюзов. Базовые маршруты CRUD не включены; все эндпоинты пользовательские.

МетодПутьAuthПраваОписание
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. Ведёт журнал событий вебхуков платёжных шлюзов для аудита и дедупликации.

МетодПутьAuthПраваОписание
GET/JWTDonations.ViewSummaryСписок всех журналов событий
GET/:idJWTDonations.ViewSummaryПолучить запись журнала событий по ID
GET/type/:typeJWTDonations.ViewSummaryПолучить записи журнала по типу события
POST/JWTDonations.EditСоздать или обновить записи журнала событий
DELETE/:idJWTDonations.EditУдалить запись журнала событий

Связанные страницы​