Pular para o conteúdo principal

Endpoints de Giving

O módulo Giving gerencia doações, fundos, processamento de pagamentos, assinaturas e operações financeiras relacionadas. Oferece suporte a vários gateways de pagamento (Stripe, PayPal), trata doações avulsas e recorrentes, acompanha os lotes de doações e processa webhooks para eventos assíncronos de pagamento.

Caminho base: /giving

Doações​

Caminho base: /giving/donations

MétodoCaminhoAutenticaçãoPermissãoDescrição
GET/JWTDonations.View ou o próprio personIdLista todas as doações. Filtre por ?batchId= ou ?personId=. Com ?personId=, as ofertas para fundos não dedutíveis ficam de fora (como nos extratos de doações), a menos que quem chama com Donations.View adicione &includeNonDeductible=1, o que o registro de pessoa do B1Admin faz
GET/:idJWTDonations.ViewObtém uma doação pelo ID
GET/myJWT—Obtém as doações do usuário atual
GET/my/summary?year=JWT—Total de ofertas do usuário atual em um ano (padrão: este ano): { year, total, count, currency, isConverted }, com os totais convertidos para a moeda da igreja. Alimenta a prévia de ofertas na página inicial do membro
GET/?startDate=&endDate=JWTDonations.ViewDoações com data dentro do intervalo (inclusive). As duas datas são obrigatórias no formato YYYY-MM-DD, caso contrário retorna 400. As páginas de extratos de doações do B1Admin pedem um ano-calendário dessa forma, em vez de todo o histórico da igreja
GET/summaryJWTDonations.ViewSummaryObtém o resumo de doações. Filtre por ?startDate=&endDate=&type=. Use type=person para o detalhamento por pessoa
GET/testEmailPública—Envia um e-mail de teste (desenvolvimento/depuração)
POST/JWTDonations.Edit ou Donations.EnterCria ou atualiza doações (lote). Somente com Donations.Enter, tanto o lote de destino quanto (em uma atualização) o lote atual da doação precisam estar abertos, e ofertas do gateway (as que têm um transactionId) não podem ser alteradas; caso contrário, 403 { "error": "This batch is closed." }
DELETE/:idJWTDonations.Edit ou Donations.EnterExclui uma doação. Somente Donations.Enter: a doação precisa estar em um lote aberto e não ser uma oferta do gateway, caso contrário 403

Exemplo: listar doações 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"
}
]

Exemplo: obter o resumo de doações​

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 doações​

Caminho base: /giving/donationbatches

Estende GenericCrudController com as rotas CRUD: getById, getAll, post, delete. A operação de exclusão também remove todas as doações do lote.

MétodoCaminhoAutenticaçãoPermissãoDescrição
GET/JWTDonations.ViewSummary ou Donations.EnterLista todos os lotes de doações
GET/:idJWTDonations.ViewSummary ou Donations.EnterObtém um lote de doações pelo ID
POST/JWTDonations.Edit ou Donations.EnterCria ou atualiza lotes de doações. Somente Donations.Enter: atualizar um lote existente exige que ele esteja aberto, caso contrário 403 { "error": "This batch is closed." }. status é ignorado aqui, então salvar um lote não pode reabri-lo
POST/:id/closeJWTDonations.EditFecha um lote: define status como closed, closedDate como agora e closedBy como o ID do usuário que chamou. Retorna o lote
POST/:id/reopenJWTDonations.EditReabre um lote: define status como open e limpa closedDate e closedBy. Retorna o lote
DELETE/:idJWTDonations.EditExclui um lote e todas as suas doações

Cada lote inclui status (open ou closed; lotes novos e preexistentes são open), closedDate e closedBy. Donations.Edit pode alterar doações em qualquer lote; Donations.Enter (exibido como Lançar doações no editor de funções) só pode adicionar, alterar ou excluir doações e divisões por fundo enquanto o lote estiver aberto.

Doar​

Caminho base: /giving/donate

Trata o fluxo público de doação, incluindo cobranças, assinaturas, webhooks e cálculos de taxas. Nenhuma rota CRUD base está habilitada; todos os endpoints são personalizados.

MétodoCaminhoAutenticaçãoPermissãoDescrição
GET/gateways/:churchIdPública—Obtém os gateways de pagamento disponíveis para uma igreja (somente chaves públicas)
POST/client-tokenJWT—Gera um token de cliente para a inicialização do gateway
POST/create-orderJWT—Cria um pedido de pagamento (checkout no estilo PayPal)
POST/chargeJWT—Processa uma cobrança de doação avulsa
POST/subscribeJWT—Cria uma assinatura de doação recorrente
POST/logPública—Registra uma doação. Corpo: { donation, fundData }
POST/webhook/:providerPública—Recebe eventos de webhook de pagamento (Stripe, PayPal). Exige ?churchId=
POST/replay-stripe-eventsJWTDonations.EditReenvia eventos do Stripe para um intervalo de datas. Corpo: { startDate, endDate, dryRun }
POST/feePública—Calcula as taxas de transação. Corpo: { type, provider, gatewayId, amount, currency }. Exige ?churchId=
POST/captcha-verifyPública—Verifica o token do reCAPTCHA. Corpo: { token, churchId? }. Uma resposta humana retorna { response: "human", pass }, em que pass é um passe assinado de doação de convidado válido por 10 minutos (e somente para o churchId quando um é enviado)

Quando a API roda com CAPTCHA_ENFORCE=true, as chamadas de convidados (não conectados) para /giving/donate/create-order, /charge, /subscribe, /giving/paymentmethods/addcard e /giving/paymentmethods/ach-setup-intent-anon (e as chamadas POST /content/registrations/register de convidados com preço) precisam incluir esse captchaPass no corpo; caso contrário, retornam 403 Captcha verification required. O passe pode ser reutilizado até expirar, porque o fluxo de convidado do Stripe faz duas chamadas (adicionar o cartão e depois cobrar). Chamadas de usuários conectados não são afetadas. CAPTCHA_ENFORCE vem como false por padrão; os formulários de doação de convidados do @churchapps/apphelper enviam o passe automaticamente.

Exemplo: processar uma cobrança de doação​

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

Exemplo: criar uma assinatura recorrente​

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

Fundos​

Caminho base: /giving/funds

Estende GenericCrudController com as rotas CRUD: getById, getAll, post, delete. A permissão view é null (não é necessária permissão para ver os fundos).

MétodoCaminhoAutenticaçãoPermissãoDescrição
GET/JWT—Lista todos os fundos
GET/:idJWT—Obtém um fundo pelo ID
GET/churchId/:churchIdPública—Obtém todos os fundos de uma igreja específica (público)
GET/public/:churchId/:fundId/total?startDate=&endDate=Pública—Obtém o total de doações de um fundo: { fundId, totalAmount, donationCount }. Alimenta o elemento campaignProgress do criador de sites
POST/JWTDonations.EditCria ou atualiza fundos
DELETE/:idJWTDonations.EditExclui um fundo

Doações por fundo​

Caminho base: /giving/funddonations

Acompanha como as doações individuais são alocadas nos fundos. Nenhuma rota CRUD base está habilitada; todos os endpoints são personalizados.

MétodoCaminhoAutenticaçãoPermissãoDescrição
GET/JWTDonations.ViewLista as doações por fundo. Filtre por ?donationId=, ?personId=, ?fundId= ou ?fundName=. Opcionalmente, adicione ?startDate=&endDate= para filtrar por data
GET/:idJWTDonations.ViewObtém uma doação por fundo pelo ID
GET/myJWT—Obtém as doações por fundo do usuário atual
POST/JWTDonations.Edit ou Donations.EnterCria ou atualiza doações por fundo (lote). Somente Donations.Enter: a doação-mãe precisa estar em um lote aberto e não ser uma oferta do gateway, caso contrário 403
DELETE/:idJWTDonations.Edit ou Donations.EnterExclui uma doação por fundo. Mesma regra de lote aberto para Donations.Enter

Gateways​

Caminho base: /giving/gateways

Gerencia as configurações de gateways de pagamento (Stripe, PayPal etc.). Nenhuma rota CRUD base está habilitada; todos os endpoints são personalizados. Os segredos dos gateways são criptografados em repouso.

MétodoCaminhoAutenticaçãoPermissãoDescrição
GET/JWT—Lista todos os gateways da igreja
GET/:idJWTSettings.EditObtém um gateway pelo ID
GET/churchId/:churchIdPública—Obtém os gateways de uma igreja (somente chaves públicas)
GET/configured/:churchIdPública—Verifica se uma igreja tem um gateway de pagamento configurado
POST/JWTSettings.EditCria ou atualiza gateways (criptografa as chaves, provisiona webhooks e produtos)
PATCH/:idJWTSettings.EditAtualiza parcialmente um gateway
DELETE/:idJWTSettings.EditExclui um gateway (também remove seus webhooks)

Exemplo: verificar a configuração do gateway​

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

Clientes​

Caminho base: /giving/customers

Estende GenericCrudController com as rotas CRUD: getAll, delete. Vincula pessoas aos seus registros de cliente no gateway de pagamento.

MétodoCaminhoAutenticaçãoPermissãoDescrição
GET/JWTDonations.ViewSummaryLista todos os clientes
GET/:idJWTDonations.ViewSummary ou o próprio registroObtém um cliente pelo ID
GET/:id/subscriptionsJWTDonations.ViewSummary ou o próprio registroObtém as assinaturas do gateway de um cliente
DELETE/:idJWTDonations.EditExclui um cliente

Assinaturas​

Caminho base: /giving/subscriptions

Gerencia as assinaturas de doação recorrente. Nenhuma rota CRUD base está habilitada; todos os endpoints são personalizados.

MétodoCaminhoAutenticaçãoPermissãoDescrição
GET/JWTDonations.ViewSummaryLista todas as assinaturas
GET/:idJWTDonations.ViewSummaryObtém uma assinatura pelo ID
POST/JWTDonations.Edit ou a própria assinaturaAtualiza assinaturas no gateway de pagamento
DELETE/:idJWTDonations.Edit ou a própria assinaturaCancela uma assinatura e a remove do banco de dados. Corpo: { provider, reason }

Fundos da assinatura​

Caminho base: /giving/subscriptionfunds

Acompanha as alocações de fundos das assinaturas recorrentes. Nenhuma rota CRUD base está habilitada; todos os endpoints são personalizados.

MétodoCaminhoAutenticaçãoPermissãoDescrição
GET/JWTDonations.View ou a própria assinaturaLista os fundos das assinaturas. Filtre por ?subscriptionId=
GET/:idJWTDonations.ViewSummaryObtém um fundo de assinatura pelo ID
DELETE/:idJWTDonations.EditExclui um fundo de assinatura
DELETE/subscription/:idJWTDonations.Edit ou a própria assinaturaExclui todos os fundos de uma assinatura

Formas de pagamento​

Caminho base: /giving/paymentmethods

Gerencia as formas de pagamento armazenadas (cartões, contas bancárias) por meio das APIs do gateway de pagamento. Nenhuma rota CRUD base está habilitada; todos os endpoints são personalizados.

MétodoCaminhoAutenticaçãoPermissãoDescrição
GET/personid/:idJWTDonations.View ou o próprio personIdObtém todas as formas de pagamento armazenadas de uma pessoa (cartões, contas bancárias)
POST/addcardJWT—Vincula uma forma de pagamento por cartão. Corpo: { id, personId, customerId, email, name, churchId, provider }
POST/updatecardJWTDonations.Edit ou o próprio personIdAtualiza os dados do cartão. Corpo: { personId, paymentMethodId, cardData, provider }
POST/ach-setup-intentJWTDonations.Edit ou o próprio personIdCria um SetupIntent ACH do Stripe para vincular conta bancária. Corpo: { personId, customerId, email, name, churchId }
POST/ach-setup-intent-anonPública—Cria um SetupIntent ACH anônimo para doações de convidados. Corpo: { email, name, churchId, gatewayId }
POST/addbankaccountJWTDonations.Edit ou o próprio personIdAdiciona uma conta bancária por token (obsoleto; use ach-setup-intent). Corpo: { id, personId, customerId, email, name }
POST/updatebankJWTDonations.Edit ou o próprio personIdAtualiza os dados da conta bancária. Corpo: { paymentMethodId, personId, bankData, customerId }
POST/verifybankJWTDonations.Edit ou o próprio clienteVerifica uma conta bancária com micro-depósitos. Corpo: { paymentMethodId, customerId, amountData }
DELETE/:id/:customeridJWTDonations.Edit ou o próprio clienteExclui uma forma de pagamento (cartão ou conta bancária)

Registro de eventos​

Caminho base: /giving/eventLog

Estende GenericCrudController com as rotas CRUD: getById, getAll, post, delete. Registra os eventos de webhook do gateway de pagamento para auditoria e deduplicação.

MétodoCaminhoAutenticaçãoPermissãoDescrição
GET/JWTDonations.ViewSummaryLista todos os registros de eventos
GET/:idJWTDonations.ViewSummaryObtém um registro de evento pelo ID
GET/type/:typeJWTDonations.ViewSummaryObtém os registros de eventos filtrados por tipo de evento
POST/JWTDonations.EditCria ou atualiza registros de eventos
DELETE/:idJWTDonations.EditExclui um registro de evento

Páginas relacionadas​