Ugrás a fő tartalomra

Adományozási végpontok

Az Adományozási modul az adományokat, alapokat, a fizetésfeldolgozást, az előfizetéseket és a kapcsolódó pénzügyi műveleteket kezeli. Több fizetési átjárót támogat (Stripe, PayPal), kezeli az egyszeri és ismétlődő adományokat, nyomon követi az adománykötegeket, és webhook-feldolgozást biztosít az aszinkron fizetési eseményekhez.

Alapútvonal: /giving

Adományok​

Alapútvonal: /giving/donations

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/JWTDonations.View vagy saját personIdAz összes adomány listázása. Szűrés ?batchId= vagy ?personId= paraméterrel. A ?personId= használatakor a nem levonható alapokra adott ajándékok kimaradnak (ahogy az adókimutatásokon is), kivéve ha a Donations.View jogosultságú hívó hozzáadja az &includeNonDeductible=1 paramétert, amit a B1Admin személyi rekordja megtesz
GET/:idJWTDonations.ViewAdomány lekérése azonosító alapján
GET/myJWT—Az aktuális felhasználó adományainak lekérése
GET/my/summary?year=JWT—Az aktuális felhasználó éves adományösszege (alapértelmezés: az idei év): { year, total, count, currency, isConverted }, az összegek az egyház pénznemére átszámítva. A tagok kezdőlapján látható adománynézetet táplálja
GET/?startDate=&endDate=JWTDonations.ViewA megadott tartományba (a határokat is beleértve) eső adományok. Mindkét dátum kötelező, ÉÉÉÉ-HH-NN formátumban, különben 400. A B1Admin adókimutatás oldalai ezzel a módszerrel egy naptári évet kérnek le az egyház teljes előzményei helyett
GET/summaryJWTDonations.ViewSummaryAdomány-összesítő lekérése. Szűrés ?startDate=&endDate=&type= paraméterekkel. A type=person értékkel személyenkénti bontás kérhető
GET/testEmailNyilvános—Teszt-e-mail küldése (fejlesztéshez és hibakereséshez)
POST/JWTDonations.Edit vagy Donations.EnterAdományok (köteg) létrehozása vagy frissítése. Csak Donations.Enter esetén a célkötegnek, és frissítésnél az adomány jelenlegi kötegének is nyitottnak kell lennie. Átjárón keresztül érkezett ajándékok (amelyekhez transactionId tartozik) nem módosíthatók. Egyébként 403 { "error": "This batch is closed." } a válasz
DELETE/:idJWTDonations.Edit vagy Donations.EnterAdomány törlése. Csak Donations.Enter esetén: az adománynak nyitott kötegben kell lennie, és nem lehet átjárós ajándék, különben 403

Példa: Adományok listázása köteg szerint​

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"
}
]

Példa: Adomány-összesítő lekérése​

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
}
]

Adománykötegek​

Alapútvonal: /giving/donationbatches

A GenericCrudController osztályt bővíti a következő CRUD útvonalakkal: getById, getAll, post, delete. A törlési művelet a kötegen belüli összes adományt is eltávolítja.

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/JWTDonations.ViewSummary vagy Donations.EnterAz összes adománykköteg listázása
GET/:idJWTDonations.ViewSummary vagy Donations.EnterAdománykötegek lekérése azonosító alapján
POST/JWTDonations.Edit vagy Donations.EnterAdománykötegek létrehozása vagy frissítése. Csak Donations.Enter esetén: a meglévő köteg frissítéséhez annak nyitottnak kell lennie, különben 403 { "error": "This batch is closed." }. A status mezőt itt a rendszer figyelmen kívül hagyja, így a köteg mentésével nem lehet újra megnyitni
POST/:id/closeJWTDonations.EditKöteg lezárása: a status értékét closed-ra, a closedDate értékét az aktuális időpontra, a closedBy értékét pedig a hívó felhasználó azonosítójára állítja. A köteget adja vissza
POST/:id/reopenJWTDonations.EditKöteg újranyitása: a status értékét open-re állítja, és törli a closedDate és closedBy mezőket. A köteget adja vissza
DELETE/:idJWTDonations.EditA köteg és az összes hozzá tartozó adomány törlése

Minden köteg tartalmazza a status (open vagy closed; az új és a korábbi kötegek open állapotúak), a closedDate és a closedBy mezőket. A Donations.Edit bármely köteg adományait módosíthatja. A Donations.Enter jogosultság (a szerepkör-szerkesztőben Adományok rögzítése néven jelenik meg) csak nyitott köteg adományait és alapmegosztásait tudja hozzáadni, módosítani vagy törölni.

Adakozás​

Alapútvonal: /giving/donate

Kezeli a nyilvános adakozási folyamatot: terheléseket, előfizetéseket, webhookokat és díjszámítást. Alapértelmezett CRUD útvonalak nincsenek engedélyezve; minden végpont egyedi.

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/gateways/:churchIdNyilvános—Az egyház elérhető fizetési átjáróinak lekérése (csak nyilvános kulcsok)
POST/client-tokenJWT—Kliens-token generálása az átjáró inicializálásához
POST/create-orderJWT—Fizetési megrendelés létrehozása (PayPal-stílusú fizetés)
POST/chargeJWT—Egyszeri adomány terhelésének feldolgozása
POST/subscribeJWT—Ismétlődő adományozási előfizetés létrehozása
POST/logNyilvános—Adomány naplózása. Törzs: { donation, fundData }
POST/webhook/:providerNyilvános—Fizetési webhook-események fogadása (Stripe, PayPal). A ?churchId= megadása kötelező
POST/replay-stripe-eventsJWTDonations.EditStripe-események újrajátszása egy dátumtartományra. Törzs: { startDate, endDate, dryRun }
POST/feeNyilvános—Tranzakciós díjak kiszámítása. Törzs: { type, provider, gatewayId, amount, currency }. A ?churchId= megadása kötelező
POST/captcha-verifyNyilvános—reCAPTCHA-token ellenőrzése. Törzs: { token, churchId? }. Emberi válasz esetén { response: "human", pass } érkezik, ahol a pass egy aláírt vendég-adakozási engedély, amely 10 percig érvényes (és csak a megadott churchId-ra vonatkozik, ha az el lett küldve)

Ha az Api CAPTCHA_ENFORCE=true beállítással fut, a nem bejelentkezett (vendég) hívásoknak a /giving/donate/create-order, /charge, /subscribe, /giving/paymentmethods/addcard és /giving/paymentmethods/ach-setup-intent-anon végpontokon (valamint a vendégek díjköteles POST /content/registrations/register hívásainak) a kérés törzsében tartalmazniuk kell a captchaPass értéket, különben 403 Captcha verification required hibát kapnak. Az engedély a lejáratáig többször felhasználható, mert a Stripe-os vendégfolyamat két hívást tesz (kártya hozzáadása, majd terhelés). A bejelentkezett hívásokat nem érinti. A CAPTCHA_ENFORCE alapértelmezett értéke false; a @churchapps/apphelper vendég-adakozási űrlapjai automatikusan elküldik az engedélyt.

Példa: Adomány terhelésének feldolgozása​

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"
}

Példa: Ismétlődő előfizetés létrehozása​

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"
}

Alapok​

Alapútvonal: /giving/funds

A GenericCrudController osztályt bővíti a következő CRUD útvonalakkal: getById, getAll, post, delete. A view jogosultság null, vagyis az alapok megtekintéséhez nincs szükség jogosultságra.

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/JWT—Az összes alap listázása
GET/:idJWT—Alap lekérése azonosító alapján
GET/churchId/:churchIdNyilvános—Egy adott egyház összes alapjának lekérése (nyilvános)
GET/public/:churchId/:fundId/total?startDate=&endDate=Nyilvános—Egy alap adományösszegének lekérése: { fundId, totalAmount, donationCount }. A weboldal-szerkesztő campaignProgress elemét táplálja
POST/JWTDonations.EditAlapok létrehozása vagy frissítése
DELETE/:idJWTDonations.EditAlap törlése

Alapadományok​

Alapútvonal: /giving/funddonations

Azt követi nyomon, hogyan oszlanak meg az egyes adományok az alapok között. Alapértelmezett CRUD útvonalak nincsenek engedélyezve; minden végpont egyedi.

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/JWTDonations.ViewAlapadományok listázása. Szűrés ?donationId=, ?personId=, ?fundId= vagy ?fundName= paraméterrel. Opcionálisan dátumszűrés: ?startDate=&endDate=
GET/:idJWTDonations.ViewAlapadomány lekérése azonosító alapján
GET/myJWT—Az aktuális felhasználó alapadományainak lekérése
POST/JWTDonations.Edit vagy Donations.EnterAlapadományok (köteg) létrehozása vagy frissítése. Csak Donations.Enter esetén: a szülő adománynak nyitott kötegben kell lennie, és nem lehet átjárós ajándék, különben 403
DELETE/:idJWTDonations.Edit vagy Donations.EnterAlapadomány törlése. Donations.Enter esetén ugyanez a nyitott köteg szabály érvényes

Átjárók​

Alapútvonal: /giving/gateways

Fizetési átjáró-konfigurációkat kezel (Stripe, PayPal stb.). Alapértelmezett CRUD útvonalak nincsenek engedélyezve; minden végpont egyedi. Az átjárók titkos kulcsai nyugalmi állapotban titkosítva vannak.

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/JWT—Az egyház összes átjárójának listázása
GET/:idJWTSettings.EditÁtjáró lekérése azonosító alapján
GET/churchId/:churchIdNyilvános—Egy egyház átjáróinak lekérése (csak nyilvános kulcsok)
GET/configured/:churchIdNyilvános—Ellenőrzi, hogy az egyházhoz van-e beállított fizetési átjáró
POST/JWTSettings.EditÁtjárók létrehozása vagy frissítése (titkosítja a kulcsokat, webhookokat és termékeket hoz létre)
PATCH/:idJWTSettings.EditÁtjáró részleges frissítése
DELETE/:idJWTSettings.EditÁtjáró törlése (a hozzá tartozó webhookokat is eltávolítja)

Példa: Átjáró-konfiguráció ellenőrzése​

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

Ügyfelek​

Alapútvonal: /giving/customers

A GenericCrudController osztályt bővíti a következő CRUD útvonalakkal: getAll, delete. A személyeket összekapcsolja a fizetési átjáró ügyfélrekordjaival.

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/JWTDonations.ViewSummaryAz összes ügyfél listázása
GET/:idJWTDonations.ViewSummary vagy saját rekordÜgyfél lekérése azonosító alapján
GET/:id/subscriptionsJWTDonations.ViewSummary vagy saját rekordEgy ügyfél átjáró-előfizetéseinek lekérése
DELETE/:idJWTDonations.EditÜgyfél törlése

Előfizetések​

Alapútvonal: /giving/subscriptions

Az ismétlődő adományozási előfizetéseket kezeli. Alapértelmezett CRUD útvonalak nincsenek engedélyezve; minden végpont egyedi.

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/JWTDonations.ViewSummaryAz összes előfizetés listázása
GET/:idJWTDonations.ViewSummaryElőfizetés lekérése azonosító alapján
POST/JWTDonations.Edit vagy saját előfizetésElőfizetések frissítése a fizetési átjáróval
DELETE/:idJWTDonations.Edit vagy saját előfizetésElőfizetés lemondása és eltávolítása az adatbázisból. Törzs: { provider, reason }

Előfizetési alapok​

Alapútvonal: /giving/subscriptionfunds

Az ismétlődő előfizetések alaphozzárendeléseit követi nyomon. Alapértelmezett CRUD útvonalak nincsenek engedélyezve; minden végpont egyedi.

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/JWTDonations.View vagy saját előfizetésElőfizetési alapok listázása. Szűrés ?subscriptionId= paraméterrel
GET/:idJWTDonations.ViewSummaryElőfizetési alap lekérése azonosító alapján
DELETE/:idJWTDonations.EditElőfizetési alap törlése
DELETE/subscription/:idJWTDonations.Edit vagy saját előfizetésEgy előfizetés összes alapjának törlése

Fizetési módok​

Alapútvonal: /giving/paymentmethods

Tárolt fizetési módokat (kártyákat, bankszámlákat) kezel a fizetési átjárók API-jain keresztül. Alapértelmezett CRUD útvonalak nincsenek engedélyezve; minden végpont egyedi.

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/personid/:idJWTDonations.View vagy saját personIdEgy személy összes tárolt fizetési módjának lekérése (kártyák, bankszámlák)
POST/addcardJWT—Kártya fizetési módjának csatolása. Törzs: { id, personId, customerId, email, name, churchId, provider }
POST/updatecardJWTDonations.Edit vagy saját personIdKártyaadatok frissítése. Törzs: { personId, paymentMethodId, cardData, provider }
POST/ach-setup-intentJWTDonations.Edit vagy saját personIdStripe ACH SetupIntent létrehozása banki összekapcsoláshoz. Törzs: { personId, customerId, email, name, churchId }
POST/ach-setup-intent-anonNyilvános—Anonim ACH SetupIntent létrehozása vendég-adományokhoz. Törzs: { email, name, churchId, gatewayId }
POST/addbankaccountJWTDonations.Edit vagy saját personIdBankszámla hozzáadása tokenen keresztül (elavult; helyette használja az ach-setup-intent végpontot). Törzs: { id, personId, customerId, email, name }
POST/updatebankJWTDonations.Edit vagy saját personIdBankszámla adatainak frissítése. Törzs: { paymentMethodId, personId, bankData, customerId }
POST/verifybankJWTDonations.Edit vagy saját ügyfélBankszámla ellenőrzése apró összegű visszautalásokkal (micro-deposits). Törzs: { paymentMethodId, customerId, amountData }
DELETE/:id/:customeridJWTDonations.Edit vagy saját ügyfélFizetési mód (kártya vagy bankszámla) törlése

Eseménynapló​

Alapútvonal: /giving/eventLog

A GenericCrudController osztályt bővíti a következő CRUD útvonalakkal: getById, getAll, post, delete. A fizetési átjáró webhook-eseményeit naplózza ellenőrzés és duplikációszűrés céljából.

MetódusÚtvonalHitelesítésJogosultságLeírás
GET/JWTDonations.ViewSummaryAz összes eseménynapló listázása
GET/:idJWTDonations.ViewSummaryEseménynapló lekérése azonosító alapján
GET/type/:typeJWTDonations.ViewSummaryEseménynaplók lekérése eseménytípus szerint szűrve
POST/JWTDonations.EditEseménynaplók létrehozása vagy frissítése
DELETE/:idJWTDonations.EditEseménynapló törlése

Kapcsolódó oldalak​