Saltar al contenido principal

Endpoints de Giving

El módulo Giving administra las donaciones, los fondos, el procesamiento de pagos, las suscripciones y las operaciones financieras relacionadas. Admite varias pasarelas de pago (Stripe, PayPal), gestiona donativos únicos y recurrentes, lleva el control de los lotes de donaciones y procesa webhooks para los eventos de pago asíncronos.

Ruta base: /giving

Donaciones​

Ruta base: /giving/donations

MétodoRutaAutenticaciónPermisoDescripción
GET/JWTDonations.View o su propio personIdEnumera todas las donaciones. Filtre con ?batchId= o ?personId=. Con ?personId=, se excluyen los donativos a fondos no deducibles (como en los estados de cuenta de donaciones), salvo que quien llama con Donations.View agregue &includeNonDeductible=1, lo que hace el registro de persona de B1Admin
GET/:idJWTDonations.ViewObtiene una donación por ID
GET/myJWT—Obtiene las donaciones del usuario actual
GET/my/summary?year=JWT—Total de donaciones del usuario actual para un año (por defecto, este año): { year, total, count, currency, isConverted }, con los totales convertidos a la moneda de la iglesia. Alimenta la vista previa de donaciones en el inicio del miembro
GET/?startDate=&endDate=JWTDonations.ViewDonaciones con fecha dentro del rango (inclusive). Ambas fechas son obligatorias en formato YYYY-MM-DD; de lo contrario, 400. Las páginas de estados de cuenta de donaciones de B1Admin piden un año calendario de esta forma, en lugar de todo el historial de la iglesia
GET/summaryJWTDonations.ViewSummaryObtiene el resumen de donaciones. Filtre con ?startDate=&endDate=&type=. Use type=person para el desglose por persona
GET/testEmailPública—Envía un correo de prueba (desarrollo y depuración)
POST/JWTDonations.Edit o Donations.EnterCrea o actualiza donaciones (por lote). Solo con Donations.Enter, tanto el lote de destino como (en una actualización) el lote actual de la donación deben estar abiertos, y las ofrendas de la pasarela (las que tienen transactionId) no pueden modificarse; de lo contrario, 403 { "error": "This batch is closed." }
DELETE/:idJWTDonations.Edit o Donations.EnterElimina una donación. Solo Donations.Enter: la donación debe estar en un lote abierto y no ser una ofrenda de la pasarela; de lo contrario, 403

Ejemplo: listar donaciones por lote​

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

Ejemplo: obtener el resumen de donaciones​

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

Lotes de donaciones​

Ruta base: /giving/donationbatches

Extiende GenericCrudController con las rutas CRUD getById, getAll, post y delete. La operación de eliminación también borra todas las donaciones del lote.

MétodoRutaAutenticaciónPermisoDescripción
GET/JWTDonations.ViewSummary o Donations.EnterEnumera todos los lotes de donaciones
GET/:idJWTDonations.ViewSummary o Donations.EnterObtiene un lote de donaciones por ID
POST/JWTDonations.Edit o Donations.EnterCrea o actualiza lotes de donaciones. Solo Donations.Enter: actualizar un lote existente requiere que esté abierto; de lo contrario, 403 { "error": "This batch is closed." }. status se ignora aquí, así que guardar un lote no puede reabrirlo
POST/:id/closeJWTDonations.EditCierra un lote: establece status en closed, closedDate en la fecha actual y closedBy en el ID de usuario de quien llama. Devuelve el lote
POST/:id/reopenJWTDonations.EditReabre un lote: establece status en open y limpia closedDate y closedBy. Devuelve el lote
DELETE/:idJWTDonations.EditElimina un lote y todas sus donaciones

Cada lote incluye status (open o closed; los lotes nuevos y los ya existentes son open), closedDate y closedBy. Donations.Edit puede modificar las donaciones de cualquier lote; Donations.Enter (que aparece como Enter Donations en el editor de roles) solo puede agregar, cambiar o eliminar donaciones y divisiones por fondo mientras su lote esté abierto.

Donar​

Ruta base: /giving/donate

Gestiona el flujo de donación de cara al público, incluidos los cargos, las suscripciones, los webhooks y el cálculo de comisiones. No hay rutas CRUD base habilitadas; todos los endpoints son personalizados.

MétodoRutaAutenticaciónPermisoDescripción
GET/gateways/:churchIdPública—Obtiene las pasarelas de pago disponibles para una iglesia (solo claves públicas)
POST/client-tokenJWT—Genera un token de cliente para inicializar la pasarela
POST/create-orderJWT—Crea una orden de pago (checkout estilo PayPal)
POST/chargeJWT—Procesa un cargo de donación única
POST/subscribeJWT—Crea una suscripción de donación recurrente
POST/logPública—Registra una donación. Cuerpo: { donation, fundData }
POST/webhook/:providerPública—Recibe eventos de webhook de pago (Stripe, PayPal). Requiere ?churchId=
POST/replay-stripe-eventsJWTDonations.EditVuelve a procesar eventos de Stripe en un rango de fechas. Cuerpo: { startDate, endDate, dryRun }
POST/feePública—Calcula las comisiones de la transacción. Cuerpo: { type, provider, gatewayId, amount, currency }. Requiere ?churchId=
POST/captcha-verifyPública—Verifica un token de reCAPTCHA. Cuerpo: { token, churchId? }. Una respuesta humana devuelve { response: "human", pass }, donde pass es un pase firmado de donación para invitados válido por 10 minutos (y solo para churchId cuando se envía uno)

Cuando la API se ejecuta con CAPTCHA_ENFORCE=true, las llamadas de invitados (no autenticados) a /giving/donate/create-order, /charge, /subscribe, /giving/paymentmethods/addcard y /giving/paymentmethods/ach-setup-intent-anon (y a las llamadas POST /content/registrations/register de invitados con precio) deben incluir ese captchaPass en el cuerpo; de lo contrario, devuelven 403 Captcha verification required. El pase puede reutilizarse hasta que venza, porque el flujo de invitados de Stripe hace dos llamadas (agregar tarjeta y luego cargar). Las llamadas con sesión iniciada no se ven afectadas. CAPTCHA_ENFORCE tiene como valor predeterminado false; los formularios de donación para invitados de @churchapps/apphelper envían el pase automáticamente.

Ejemplo: procesar un cargo de donación​

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

Ejemplo: crear una suscripción recurrente​

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

Fondos​

Ruta base: /giving/funds

Extiende GenericCrudController con las rutas CRUD getById, getAll, post y delete. El permiso view es null (no se requiere permiso para ver los fondos).

MétodoRutaAutenticaciónPermisoDescripción
GET/JWT—Enumera todos los fondos
GET/:idJWT—Obtiene un fondo por ID
GET/churchId/:churchIdPública—Obtiene todos los fondos de una iglesia específica (público)
GET/public/:churchId/:fundId/total?startDate=&endDate=Pública—Obtiene el total de donaciones de un fondo: { fundId, totalAmount, donationCount }. Alimenta el elemento campaignProgress del creador de sitios web
POST/JWTDonations.EditCrea o actualiza fondos
DELETE/:idJWTDonations.EditElimina un fondo

Donaciones por fondo​

Ruta base: /giving/funddonations

Registra cómo se distribuye cada donación entre los fondos. No hay rutas CRUD base habilitadas; todos los endpoints son personalizados.

MétodoRutaAutenticaciónPermisoDescripción
GET/JWTDonations.ViewEnumera las donaciones por fondo. Filtre con ?donationId=, ?personId=, ?fundId= o ?fundName=. Opcionalmente agregue ?startDate=&endDate= para filtrar por fecha
GET/:idJWTDonations.ViewObtiene una donación por fondo por ID
GET/myJWT—Obtiene las donaciones por fondo del usuario actual
POST/JWTDonations.Edit o Donations.EnterCrea o actualiza donaciones por fondo (por lote). Solo Donations.Enter: la donación padre debe estar en un lote abierto y no ser una ofrenda de la pasarela; de lo contrario, 403
DELETE/:idJWTDonations.Edit o Donations.EnterElimina una donación por fondo. La misma regla de lote abierto aplica a Donations.Enter

Pasarelas​

Ruta base: /giving/gateways

Administra la configuración de las pasarelas de pago (Stripe, PayPal, etc.). No hay rutas CRUD base habilitadas; todos los endpoints son personalizados. Los secretos de la pasarela se cifran en reposo.

MétodoRutaAutenticaciónPermisoDescripción
GET/JWT—Enumera todas las pasarelas de la iglesia
GET/:idJWTSettings.EditObtiene una pasarela por ID
GET/churchId/:churchIdPública—Obtiene las pasarelas de una iglesia (solo claves públicas)
GET/configured/:churchIdPública—Comprueba si una iglesia tiene una pasarela de pago configurada
POST/JWTSettings.EditCrea o actualiza pasarelas (cifra las claves, aprovisiona webhooks y productos)
PATCH/:idJWTSettings.EditActualiza parcialmente una pasarela
DELETE/:idJWTSettings.EditElimina una pasarela (también elimina sus webhooks)

Ejemplo: comprobar la configuración de la pasarela​

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

Clientes​

Ruta base: /giving/customers

Extiende GenericCrudController con las rutas CRUD getAll y delete. Vincula a las personas con sus registros de cliente en la pasarela de pago.

MétodoRutaAutenticaciónPermisoDescripción
GET/JWTDonations.ViewSummaryEnumera todos los clientes
GET/:idJWTDonations.ViewSummary o su propio registroObtiene un cliente por ID
GET/:id/subscriptionsJWTDonations.ViewSummary o su propio registroObtiene las suscripciones de pasarela de un cliente
DELETE/:idJWTDonations.EditElimina un cliente

Suscripciones​

Ruta base: /giving/subscriptions

Administra las suscripciones de donación recurrente. No hay rutas CRUD base habilitadas; todos los endpoints son personalizados.

MétodoRutaAutenticaciónPermisoDescripción
GET/JWTDonations.ViewSummaryEnumera todas las suscripciones
GET/:idJWTDonations.ViewSummaryObtiene una suscripción por ID
POST/JWTDonations.Edit o su propia suscripciónActualiza suscripciones con la pasarela de pago
DELETE/:idJWTDonations.Edit o su propia suscripciónCancela una suscripción y la elimina de la base de datos. Cuerpo: { provider, reason }

Fondos de suscripción​

Ruta base: /giving/subscriptionfunds

Registra las asignaciones de fondos de las suscripciones recurrentes. No hay rutas CRUD base habilitadas; todos los endpoints son personalizados.

MétodoRutaAutenticaciónPermisoDescripción
GET/JWTDonations.View o su propia suscripciónEnumera los fondos de suscripción. Filtre con ?subscriptionId=
GET/:idJWTDonations.ViewSummaryObtiene un fondo de suscripción por ID
DELETE/:idJWTDonations.EditElimina un fondo de suscripción
DELETE/subscription/:idJWTDonations.Edit o su propia suscripciónElimina todos los fondos de una suscripción

Métodos de pago​

Ruta base: /giving/paymentmethods

Administra los métodos de pago guardados (tarjetas, cuentas bancarias) mediante las API de las pasarelas de pago. No hay rutas CRUD base habilitadas; todos los endpoints son personalizados.

MétodoRutaAutenticaciónPermisoDescripción
GET/personid/:idJWTDonations.View o su propio personIdObtiene todos los métodos de pago guardados de una persona (tarjetas, cuentas bancarias)
POST/addcardJWT—Adjunta un método de pago con tarjeta. Cuerpo: { id, personId, customerId, email, name, churchId, provider }
POST/updatecardJWTDonations.Edit o su propio personIdActualiza los datos de la tarjeta. Cuerpo: { personId, paymentMethodId, cardData, provider }
POST/ach-setup-intentJWTDonations.Edit o su propio personIdCrea un SetupIntent ACH de Stripe para vincular una cuenta bancaria. Cuerpo: { personId, customerId, email, name, churchId }
POST/ach-setup-intent-anonPública—Crea un SetupIntent ACH anónimo para donaciones de invitados. Cuerpo: { email, name, churchId, gatewayId }
POST/addbankaccountJWTDonations.Edit o su propio personIdAgrega una cuenta bancaria mediante un token (obsoleto; use ach-setup-intent). Cuerpo: { id, personId, customerId, email, name }
POST/updatebankJWTDonations.Edit o su propio personIdActualiza los datos de la cuenta bancaria. Cuerpo: { paymentMethodId, personId, bankData, customerId }
POST/verifybankJWTDonations.Edit o su propio clienteVerifica una cuenta bancaria con micro-depósitos. Cuerpo: { paymentMethodId, customerId, amountData }
DELETE/:id/:customeridJWTDonations.Edit o su propio clienteElimina un método de pago (tarjeta o cuenta bancaria)

Registro de eventos​

Ruta base: /giving/eventLog

Extiende GenericCrudController con las rutas CRUD getById, getAll, post y delete. Registra los eventos de webhook de la pasarela de pago para auditoría y deduplicación.

MétodoRutaAutenticaciónPermisoDescripción
GET/JWTDonations.ViewSummaryEnumera todos los registros de eventos
GET/:idJWTDonations.ViewSummaryObtiene un registro de evento por ID
GET/type/:typeJWTDonations.ViewSummaryObtiene los registros de eventos filtrados por tipo de evento
POST/JWTDonations.EditCrea o actualiza registros de eventos
DELETE/:idJWTDonations.EditElimina un registro de evento

Páginas relacionadas​