Vai al contenuto principale

Endpoint Donazioni

Il modulo Giving (donazioni) gestisce le donazioni, i fondi, l'elaborazione dei pagamenti, gli abbonamenti e le relative operazioni finanziarie. Supporta più gateway di pagamento (Stripe, PayPal), gestisce donazioni una tantum e ricorrenti, tiene traccia dei lotti di donazioni e fornisce l'elaborazione dei webhook per gli eventi di pagamento asincroni.

Percorso base: /giving

Donazioni​

Percorso base: /giving/donations

MetodoPercorsoAutenticazionePermessoDescrizione
GET/JWTDonations.View oppure il proprio personIdElenca tutte le donazioni. Filtra con ?batchId= oppure ?personId=. Con ?personId=, le offerte destinate a fondi non deducibili vengono escluse (come nelle ricevute di donazione) a meno che un chiamante con Donations.View non aggiunga &includeNonDeductible=1, cosa che fa la scheda persona di B1Admin
GET/:idJWTDonations.ViewOttiene una donazione per ID
GET/myJWT—Ottiene le donazioni dell'utente corrente
GET/my/summary?year=JWT—Totale delle donazioni dell'utente corrente per un anno (per default l'anno in corso): { year, total, count, currency, isConverted }, con i totali convertiti nella valuta della chiesa. Alimenta l'anteprima delle donazioni nella home page del membro
GET/?startDate=&endDate=JWTDonations.ViewDonazioni con data compresa nell'intervallo (estremi inclusi). Entrambe le date sono obbligatorie nel formato YYYY-MM-DD, altrimenti 400. Le pagine delle ricevute di donazione di B1Admin richiedono in questo modo un anno solare anziché l'intera storia della chiesa
GET/summaryJWTDonations.ViewSummaryOttiene il riepilogo delle donazioni. Filtra con ?startDate=&endDate=&type=. Usa type=person per la suddivisione per persona
GET/testEmailPubblico—Invia un'email di prova (sviluppo/debug)
POST/JWTDonations.Edit oppure Donations.EnterCrea o aggiorna le donazioni (lotto). Con solo Donations.Enter, sia il lotto di destinazione sia (per un aggiornamento) il lotto attuale della donazione devono essere aperti, e le offerte dal gateway (quelle con un transactionId) non possono essere modificate; altrimenti 403 { "error": "This batch is closed." }
DELETE/:idJWTDonations.Edit oppure Donations.EnterElimina una donazione. Solo Donations.Enter: la donazione deve trovarsi in un lotto aperto e non essere un'offerta dal gateway, altrimenti 403

Esempio: elencare le donazioni per lotto​

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

Esempio: ottenere il riepilogo delle donazioni​

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

Lotti di donazioni​

Percorso base: /giving/donationbatches

Estende GenericCrudController con le rotte CRUD: getById, getAll, post, delete. L'operazione di eliminazione rimuove anche tutte le donazioni contenute nel lotto.

MetodoPercorsoAutenticazionePermessoDescrizione
GET/JWTDonations.ViewSummary oppure Donations.EnterElenca tutti i lotti di donazioni
GET/:idJWTDonations.ViewSummary oppure Donations.EnterOttiene un lotto di donazioni per ID
POST/JWTDonations.Edit oppure Donations.EnterCrea o aggiorna i lotti di donazioni. Solo Donations.Enter: l'aggiornamento di un lotto esistente richiede che sia aperto, altrimenti 403 { "error": "This batch is closed." }. status viene ignorato qui, quindi salvare un lotto non può riaprirlo
POST/:id/closeJWTDonations.EditChiude un lotto: imposta status su closed, closedDate sull'ora attuale e closedBy sull'ID utente del chiamante. Restituisce il lotto
POST/:id/reopenJWTDonations.EditRiapre un lotto: imposta status su open e azzera closedDate e closedBy. Restituisce il lotto
DELETE/:idJWTDonations.EditElimina un lotto e tutte le sue donazioni

Ogni lotto include status (open oppure closed; i lotti nuovi ed esistenti sono open), closedDate e closedBy. Donations.Edit può modificare le donazioni in qualsiasi lotto; Donations.Enter (mostrato come Inserisci donazioni nell'editor dei ruoli) può solo aggiungere, modificare o eliminare donazioni e ripartizioni tra fondi mentre il loro lotto è aperto.

Donazioni (pagamento)​

Percorso base: /giving/donate

Gestisce il flusso di donazione rivolto al pubblico, inclusi addebiti, abbonamenti, webhook e calcolo delle commissioni. Non sono abilitate rotte CRUD di base; tutti gli endpoint sono personalizzati.

MetodoPercorsoAutenticazionePermessoDescrizione
GET/gateways/:churchIdPubblico—Ottiene i gateway di pagamento disponibili per una chiesa (solo chiavi pubbliche)
POST/client-tokenJWT—Genera un token client per l'inizializzazione del gateway
POST/create-orderJWT—Crea un ordine di pagamento (checkout in stile PayPal)
POST/chargeJWT—Elabora un addebito di donazione una tantum
POST/subscribeJWT—Crea un abbonamento di donazione ricorrente
POST/logPubblico—Registra una donazione. Corpo: { donation, fundData }
POST/webhook/:providerPubblico—Riceve gli eventi webhook di pagamento (Stripe, PayPal). Richiede ?churchId=
POST/replay-stripe-eventsJWTDonations.EditRiproduce gli eventi Stripe per un intervallo di date. Corpo: { startDate, endDate, dryRun }
POST/feePubblico—Calcola le commissioni di transazione. Corpo: { type, provider, gatewayId, amount, currency }. Richiede ?churchId=
POST/captcha-verifyPubblico—Verifica il token reCAPTCHA. Corpo: { token, churchId? }. Una risposta umana restituisce { response: "human", pass }, dove pass è un lasciapassare firmato per le donazioni degli ospiti valido per 10 minuti (e solo per churchId quando ne viene inviato uno)

Quando l'API viene eseguita con CAPTCHA_ENFORCE=true, le chiamate degli ospiti (non connessi) a /giving/donate/create-order, /charge, /subscribe, /giving/paymentmethods/addcard e /giving/paymentmethods/ach-setup-intent-anon (e alle chiamate POST /content/registrations/register a pagamento fatte da ospiti) devono includere quel captchaPass nel corpo, altrimenti restituiscono 403 Captcha verification required. Il lasciapassare può essere riutilizzato finché non scade, perché il flusso Stripe per gli ospiti effettua due chiamate (aggiunta della carta, poi addebito). Le chiamate di utenti connessi non sono interessate. CAPTCHA_ENFORCE è impostato di default su false; i moduli di donazione per gli ospiti di @churchapps/apphelper inviano automaticamente il lasciapassare.

Esempio: elaborare un addebito di donazione​

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

Esempio: creare un abbonamento ricorrente​

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

Fondi​

Percorso base: /giving/funds

Estende GenericCrudController con le rotte CRUD: getById, getAll, post, delete. Il permesso view è null (per visualizzare i fondi non serve alcun permesso).

MetodoPercorsoAutenticazionePermessoDescrizione
GET/JWT—Elenca tutti i fondi
GET/:idJWT—Ottiene un fondo per ID
GET/churchId/:churchIdPubblico—Ottiene tutti i fondi di una specifica chiesa (pubblico)
GET/public/:churchId/:fundId/total?startDate=&endDate=Pubblico—Ottiene il totale delle donazioni di un fondo: { fundId, totalAmount, donationCount }. Alimenta l'elemento campaignProgress del costruttore di siti web
POST/JWTDonations.EditCrea o aggiorna i fondi
DELETE/:idJWTDonations.EditElimina un fondo

Donazioni per fondo​

Percorso base: /giving/funddonations

Tiene traccia di come le singole donazioni vengono ripartite tra i fondi. Non sono abilitate rotte CRUD di base; tutti gli endpoint sono personalizzati.

MetodoPercorsoAutenticazionePermessoDescrizione
GET/JWTDonations.ViewElenca le donazioni per fondo. Filtra con ?donationId=, ?personId=, ?fundId= oppure ?fundName=. Facoltativamente aggiungi ?startDate=&endDate= per filtrare per data
GET/:idJWTDonations.ViewOttiene una donazione per fondo per ID
GET/myJWT—Ottiene le donazioni per fondo dell'utente corrente
POST/JWTDonations.Edit oppure Donations.EnterCrea o aggiorna le donazioni per fondo (lotto). Solo Donations.Enter: la donazione padre deve trovarsi in un lotto aperto e non essere un'offerta dal gateway, altrimenti 403
DELETE/:idJWTDonations.Edit oppure Donations.EnterElimina una donazione per fondo. Stessa regola del lotto aperto per Donations.Enter

Gateway​

Percorso base: /giving/gateways

Gestisce le configurazioni dei gateway di pagamento (Stripe, PayPal, ecc.). Non sono abilitate rotte CRUD di base; tutti gli endpoint sono personalizzati. I segreti dei gateway sono cifrati a riposo.

MetodoPercorsoAutenticazionePermessoDescrizione
GET/JWT—Elenca tutti i gateway della chiesa
GET/:idJWTSettings.EditOttiene un gateway per ID
GET/churchId/:churchIdPubblico—Ottiene i gateway di una chiesa (solo chiavi pubbliche)
GET/configured/:churchIdPubblico—Verifica se una chiesa ha un gateway di pagamento configurato
POST/JWTSettings.EditCrea o aggiorna i gateway (cifra le chiavi, configura i webhook e i prodotti)
PATCH/:idJWTSettings.EditAggiorna parzialmente un gateway
DELETE/:idJWTSettings.EditElimina un gateway (rimuove anche i suoi webhook)

Esempio: verificare la configurazione del gateway​

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

Clienti​

Percorso base: /giving/customers

Estende GenericCrudController con le rotte CRUD: getAll, delete. Collega le persone ai record cliente del gateway di pagamento.

MetodoPercorsoAutenticazionePermessoDescrizione
GET/JWTDonations.ViewSummaryElenca tutti i clienti
GET/:idJWTDonations.ViewSummary oppure il proprio recordOttiene un cliente per ID
GET/:id/subscriptionsJWTDonations.ViewSummary oppure il proprio recordOttiene gli abbonamenti del gateway per un cliente
DELETE/:idJWTDonations.EditElimina un cliente

Abbonamenti​

Percorso base: /giving/subscriptions

Gestisce gli abbonamenti di donazione ricorrenti. Non sono abilitate rotte CRUD di base; tutti gli endpoint sono personalizzati.

MetodoPercorsoAutenticazionePermessoDescrizione
GET/JWTDonations.ViewSummaryElenca tutti gli abbonamenti
GET/:idJWTDonations.ViewSummaryOttiene un abbonamento per ID
POST/JWTDonations.Edit oppure abbonamento proprioAggiorna gli abbonamenti con il gateway di pagamento
DELETE/:idJWTDonations.Edit oppure abbonamento proprioAnnulla un abbonamento e lo rimuove dal database. Corpo: { provider, reason }

Fondi degli abbonamenti​

Percorso base: /giving/subscriptionfunds

Tiene traccia delle ripartizioni dei fondi per gli abbonamenti ricorrenti. Non sono abilitate rotte CRUD di base; tutti gli endpoint sono personalizzati.

MetodoPercorsoAutenticazionePermessoDescrizione
GET/JWTDonations.View oppure abbonamento proprioElenca i fondi degli abbonamenti. Filtra con ?subscriptionId=
GET/:idJWTDonations.ViewSummaryOttiene il fondo di un abbonamento per ID
DELETE/:idJWTDonations.EditElimina il fondo di un abbonamento
DELETE/subscription/:idJWTDonations.Edit oppure abbonamento proprioElimina tutti i fondi di un abbonamento

Metodi di pagamento​

Percorso base: /giving/paymentmethods

Gestisce i metodi di pagamento memorizzati (carte, conti bancari) tramite le API dei gateway di pagamento. Non sono abilitate rotte CRUD di base; tutti gli endpoint sono personalizzati.

MetodoPercorsoAutenticazionePermessoDescrizione
GET/personid/:idJWTDonations.View oppure il proprio personIdOttiene tutti i metodi di pagamento memorizzati di una persona (carte, conti bancari)
POST/addcardJWT—Collega un metodo di pagamento con carta. Corpo: { id, personId, customerId, email, name, churchId, provider }
POST/updatecardJWTDonations.Edit oppure il proprio personIdAggiorna i dettagli della carta. Corpo: { personId, paymentMethodId, cardData, provider }
POST/ach-setup-intentJWTDonations.Edit oppure il proprio personIdCrea un SetupIntent ACH di Stripe per il collegamento di un conto bancario. Corpo: { personId, customerId, email, name, churchId }
POST/ach-setup-intent-anonPubblico—Crea un SetupIntent ACH anonimo per le donazioni degli ospiti. Corpo: { email, name, churchId, gatewayId }
POST/addbankaccountJWTDonations.Edit oppure il proprio personIdAggiunge un conto bancario tramite token (obsoleto; usa ach-setup-intent). Corpo: { id, personId, customerId, email, name }
POST/updatebankJWTDonations.Edit oppure il proprio personIdAggiorna i dettagli del conto bancario. Corpo: { paymentMethodId, personId, bankData, customerId }
POST/verifybankJWTDonations.Edit oppure il proprio clienteVerifica un conto bancario con micro-depositi. Corpo: { paymentMethodId, customerId, amountData }
DELETE/:id/:customeridJWTDonations.Edit oppure il proprio clienteElimina un metodo di pagamento (carta o conto bancario)

Registro eventi​

Percorso base: /giving/eventLog

Estende GenericCrudController con le rotte CRUD: getById, getAll, post, delete. Tiene traccia degli eventi webhook del gateway di pagamento per audit e deduplicazione.

MetodoPercorsoAutenticazionePermessoDescrizione
GET/JWTDonations.ViewSummaryElenca tutti i registri eventi
GET/:idJWTDonations.ViewSummaryOttiene un registro evento per ID
GET/type/:typeJWTDonations.ViewSummaryOttiene i registri eventi filtrati per tipo di evento
POST/JWTDonations.EditCrea o aggiorna i registri eventi
DELETE/:idJWTDonations.EditElimina un registro evento

Pagine correlate​