Bağışlar ve Kampanyalar — Geliştirici Kılavuzu ve Yönetim Arayüzü
1. Kurulum ve Bağımlılıklar
Section titled “1. Kurulum ve Bağımlılıklar”pnpm add @vicacha-devs/strapi-plugin-donations2. Sunucu Yapılandırması (config/plugins.ts)
Section titled “2. Sunucu Yapılandırması (config/plugins.ts)”Strapi v5 projenizin config/plugins.ts dosyasına eklenti yapılandırmasını ekleyin:
export default ({ env }: { env: (key: string, defaultValue?: string) => string }) => ({ "donations": { enabled: true, config: { baseCurrency: "USD", autoIssueCertificateOnVerify: true, enableCertificatesBridge: true, }, },});
3. Strapi v5 Yönetim Arayüzü (Admin UI) Turu
Section titled “3. Strapi v5 Yönetim Arayüzü (Admin UI) Turu”Etkinleştirildiğinde eklenti, Strapi Design System v2 bileşenlerini kullanarak çalışma alanını ve ayarlarını yönetim paneline kaydeder:

Yerelleştirilmiş Arayüz Etiketleri (Türkçe)
Section titled “Yerelleştirilmiş Arayüz Etiketleri (Türkçe)”| Çeviri Anahtarı | Arayüz Metni |
|---|---|
evidence.type.paid_receipt |
Paid Utility / Service Bill Receipt |
donations.evidence.type.paid_receipt |
Paid Utility / Service Bill Receipt |
evidence.type.photo_gallery |
Equipment & Donated Assets Photo Galeri |
donations.evidence.type.photo_gallery |
Equipment & Donated Assets Photo Galeri |
evidence.type.delivery_report |
Seasonal / Aid Gift Distribution Report |
donations.evidence.type.delivery_report |
Seasonal / Aid Gift Distribution Report |
evidence.type.audit_document |
Financial Audit & Official Voucher |
donations.evidence.type.audit_document |
Financial Audit & Official Voucher |
4. İçerik Türü Varlıkları, Konumları ve Şemaları (strapi.documents)
Section titled “4. İçerik Türü Varlıkları, Konumları ve Şemaları (strapi.documents)”Registers two Collection Types (plugin::donations.campaign with draftAndPublish: true and i18n.localized: true, and plugin::donations.pledge) plus two Custom Fields (plugin::donations.currency and plugin::donations.country). Supports runtime schemaExtensions in config/plugins.ts.
Strapi v5 İçinde İçerik Türü Varlıkları Nerede Bulunur?
Section titled “Strapi v5 İçinde İçerik Türü Varlıkları Nerede Bulunur?”- Content Manager:
/admin/content-manager/collection-types/plugin::donations.campaign&/admin/content-manager/collection-types/plugin::donations.pledge(visible: true) - Content-Type Builder:
/admin/plugins/content-type-builderunder Collection Types + Custom Fieldsplugin::donations.currency&plugin::donations.country - Plugin Workspace & Settings:
/admin/plugins/donations(Campaigns, Utility Bills, Pledges, Nisab Calculator) and/admin/settings/donations - Database Tables:
vicacha_donation_campaignsandvicacha_donation_pledges
plugin::donations.campaign — Donation Campaign & Invoice
Section titled “plugin::donations.campaign — Donation Campaign & Invoice”Generic fundraising campaign, operational utility invoice, or micro-need
Kind:
collectionType· DB Table:vicacha_donation_campaigns· Admin Location:/admin/content-manager/collection-types/plugin::donations.campaign· Draft & Publish:Yes· i18n:Yes
| Alan (Attribute) | Strapi Türü | Zorunlu | Kısıtlamalar / İlişki |
|---|---|---|---|
title |
string |
Yes | — |
slug |
uid |
Yes | — |
description |
text |
Yes | — |
body |
richtext |
No | — |
campaignKind |
enumeration |
Yes | enum: major_campaign, utility_invoice, micro_need; default: "major_campaign" |
categoryKey |
string |
Yes | default: "general_fund" |
goalAmount |
decimal |
Yes | — |
raisedAmount |
decimal |
No | default: 0 |
currency |
customField |
Yes | customField: plugin::donations.currency; default: "COP" |
donorCount |
integer |
No | default: 0 |
isUrgent |
boolean |
No | default: false |
isFeatured |
boolean |
No | default: false |
isActive |
boolean |
No | default: true |
startDate |
date |
No | — |
endDate |
date |
No | — |
dueDate |
date |
No | — |
billingPeriod |
string |
No | — |
invoiceReference |
string |
No | — |
invoiceProvider |
string |
No | — |
invoiceStatus |
enumeration |
No | enum: open, partially_funded, paid, overdue; default: "open" |
suggestedAmounts |
json |
No | — |
allowCustomAmount |
boolean |
No | default: true |
allowFullBalancePayoff |
boolean |
No | default: true |
ctaLabel |
string |
No | — |
ctaHref |
string |
No | — |
coverUrl |
string |
No | — |
invoiceDocumentUrl |
string |
No | — |
paymentGatewayUrl |
string |
No | — |
icon |
string |
No | — |
evidences |
json |
No | — |
plugin::donations.pledge — Donation Pledge & Contribution
Section titled “plugin::donations.pledge — Donation Pledge & Contribution”Donor pledge, utility bill payment, or verified donation record
Kind:
collectionType· DB Table:vicacha_donation_pledges· Admin Location:/admin/content-manager/collection-types/plugin::donations.pledge· Draft & Publish:No· i18n:No
| Alan (Attribute) | Strapi Türü | Zorunlu | Kısıtlamalar / İlişki |
|---|---|---|---|
referenceCode |
string |
Yes | — |
donorName |
string |
Yes | — |
donorEmail |
email |
Yes | — |
donorPhone |
string |
No | — |
donorTaxId |
string |
No | — |
donorTaxIdType |
string |
No | — |
isAnonymous |
boolean |
No | default: false |
amount |
decimal |
Yes | — |
currency |
customField |
Yes | customField: plugin::donations.currency; default: "COP" |
convertedBaseAmount |
decimal |
No | default: 0 |
categoryKey |
string |
Yes | default: "general_fund" |
campaignSlug |
string |
No | — |
campaignKind |
enumeration |
No | enum: major_campaign, utility_invoice, micro_need; default: "major_campaign" |
coversRemainingBalance |
boolean |
No | default: false |
paymentChannel |
enumeration |
Yes | enum: bank_transfer, digital_wallet, card_gateway, qr_code, cash, other; default: "bank_transfer" |
paymentProvider |
string |
No | — |
transactionReference |
string |
No | — |
receiptProofUrl |
string |
No | — |
donorNotes |
text |
No | — |
status |
enumeration |
Yes | enum: pending, verified, rejected, certificate_issued; default: "pending" |
verifiedAt |
datetime |
No | — |
verifiedBy |
string |
No | — |
certificateSerialNumber |
string |
No | — |
certificateVerifyUrl |
string |
No | — |
locale |
string |
No | default: "en" |
Strapi v5 İçerik Yöneticisi (Content Manager) Entegrasyonu (/admin/content-manager)
Section titled “Strapi v5 İçerik Yöneticisi (Content Manager) Entegrasyonu (/admin/content-manager)”İçerik Yöneticisi Kenar Çubuğu Grubu:
Donations & Certificates
İçerik Yöneticisi Varlıkları ve Bileşenleri
Section titled “İçerik Yöneticisi Varlıkları ve Bileşenleri”plugin::donations.campaign(Donation Campaign & Invoice —/admin/content-manager/collection-types/plugin::donations.campaign)plugin::donations.pledge(Donation Pledge & Contribution —/admin/content-manager/collection-types/plugin::donations.pledge)- Custom Fields
plugin::donations.currency&plugin::donations.country

Bu Eklenti Neden Content Manager Varlıkları Oluşturur?
Section titled “Bu Eklenti Neden Content Manager Varlıkları Oluşturur?”@vicacha-devs/strapi-plugin-donations registers Donation Campaign & Invoice (plugin::donations.campaign, with i18n.localized: true and draftAndPublish: true) and Donation Pledge & Contribution (plugin::donations.pledge) in the Strapi v5 Content Manager so fundraising and accounting teams get full multilingual publishing and ledger auditing:
- Multilingual (
i18n) Campaign & Utility Invoice Authoring: Translate campaign titles, descriptions, and impact stories acrossen,es,ar, andtrusing Content Manager’s locale switcher (?plugins[i18n][locale]=en) while sharing unified financial progress. - Draft & Publish Staging for Fundraising Appeals: Prepare Ramadan, Zakat, or emergency relief campaigns in
Draftmode, attach Media Library invoice PDFs or cover images, and publish when ready. - Accounting & Pledge Reconciliation: Filter
Donation Pledge & Contribution(plugin::donations.pledge) in Content Manager bystatus(pending,verified,refunded),paymentMethod,currency,isZakatEligible, or linkedcertificateSerial.
Strapi Content Manager İçinde Nasıl Kullanılır? (Adım Adım)
Section titled “Strapi Content Manager İçinde Nasıl Kullanılır? (Adım Adım)”- Open in Content Manager: Navigate to Content Manager -> Collection Types -> Donations & Certificates and select Donation Campaign & Invoice (
/admin/content-manager/collection-types/plugin::donations.campaign?plugins[i18n][locale]=en) or Donation Pledge & Contribution (/admin/content-manager/collection-types/plugin::donations.pledge). - Create Major Campaigns or Utility Invoices: Click + Create new entry in Donation Campaign & Invoice, choose
campaignKind(major_campaignorutility_invoice), setgoalAmount,currency(plugin::donations.currency), and for utility bills populateutilityProvider,invoiceReference, anddueDate. - Translate Across Locales: Use the top-right locale dropdown (
English (en),Spanish (es),Arabic (ar),Turkish (tr)) in Content Manager to localize campaign copy. - Workspace vs. Content Manager: Use Content Manager for multilingual campaign authoring, media uploads, and accounting filters; use the Donations Workspace (
/admin/plugins/donations) for real-time KPI dashboards, 1-click pledge verification, and Nisab threshold testing.
Content Manager ve Eklenti Çalışma Alanı Senkronizasyonu
Section titled “Content Manager ve Eklenti Çalışma Alanı Senkronizasyonu”Content Manager Kullanım Senaryoları ve Editöryal İş Akışları
Section titled “Content Manager Kullanım Senaryoları ve Editöryal İş Akışları”Content Manager Use Case 1 — Publishing Localized Crowdfunding Campaigns & Monthly Utility Bills
Section titled “Content Manager Use Case 1 — Publishing Localized Crowdfunding Campaigns & Monthly Utility Bills”- Amacı ve Neden Kullanıldığı: Manage both major Waqf/social campaigns (
major_campaign) and monthly electricity/water/fiber invoices (utility_invoice) with localized descriptions in Content Manager. - Content Manager İçinde Uygulama Adımları: Open
/admin/content-manager/collection-types/plugin::donations.campaign?plugins[i18n][locale]=en, editEducational Endowment & Scholarship FundorMonthly Natural Gas Utility Bill, switch locales to translate, and click Publish.
Content Manager Use Case 2 — Reconciling Verified Pledges & Linked Tax Certificate Serials
Section titled “Content Manager Use Case 2 — Reconciling Verified Pledges & Linked Tax Certificate Serials”- Amacı ve Neden Kullanıldığı: Filter verified Zakat and Sadaqah contributions in Content Manager and verify their issued Ed25519 tax certificate serial numbers.
- Content Manager İçinde Uygulama Adımları: Open
/admin/content-manager/collection-types/plugin::donations.pledgeand filter bystatus = verifiedandcertificateSerial is not null.
5. Uçtan Uca Kullanım Senaryoları ve İş Akışları
Section titled “5. Uçtan Uca Kullanım Senaryoları ve İş Akışları”Use Case 1 — Multi-Currency Crowdfunding Campaigns (major_campaign)
Section titled “Use Case 1 — Multi-Currency Crowdfunding Campaigns (major_campaign)”- What it is for: Run localized (
en,es,ar,tr) fundraising campaigns with real-time progress bars (goalAmount,raisedAmount,donorCount). - How it works: Publish a
plugin::donations.campaignentity (campaignKind: 'major_campaign'), list viaGET /api/donations/campaigns, and submit pledges viaPOST /api/donations/pledges.

Use Case 2 — Operational Utility Invoice Sponsorship (utility_invoice)
Section titled “Use Case 2 — Operational Utility Invoice Sponsorship (utility_invoice)”- What it is for: Allow community members to pay off specific monthly utility bills (electricity, water, internet) partially or in full (
coversRemainingBalance). - How it works: Create a
plugin::donations.campaignwithcampaignKind: 'utility_invoice',invoiceReference,dueDate, andinvoiceDocumentUrl; query viaGET /api/donations/utility-bills.

Use Case 3 — HMAC-SHA256 Payment Gateway Webhooks & Auto-Certificate Bridge
Section titled “Use Case 3 — HMAC-SHA256 Payment Gateway Webhooks & Auto-Certificate Bridge”- What it is for: Automatically verify pledges from Wompi/Stripe webhooks, increment campaign totals, and issue an Ed25519 tax certificate.
- How it works:
POST /api/donations/webhookverifies the signature, marksplugin::donations.pledgeasverified, updatesraisedAmount, and callsstrapi.plugin('certificates').service('issuance').

Use Case 4 — Precious-Metal Threshold (Zakat / Nisab) Calculation
Section titled “Use Case 4 — Precious-Metal Threshold (Zakat / Nisab) Calculation”- What it is for: Provide donors with an interactive calculator based on live gold/silver gram thresholds in their local currency.
- How it works: Call
POST /api/donations/calculate-thresholdwith asset balances and liabilities to compute net zakatable wealth and recommended contribution.
6. REST API Uç Noktaları (content-api ve admin)
Section titled “6. REST API Uç Noktaları (content-api ve admin)”| Metot | Uç Nokta Yolu | Kapsam | Denetleyici (Handler) | Kimlik Doğrulama |
|---|---|---|---|---|
GET |
/api/donations/campaigns |
content-api |
content-api.listCampaigns |
Public |
GET |
/api/donations/invoices |
content-api |
content-api.listUtilityInvoices |
Public |
GET |
/api/donations/utility-invoices |
content-api |
content-api.listUtilityInvoices |
Public |
GET |
/api/donations/campaigns/{slug} |
content-api |
content-api.getCampaignBySlug |
Public |
GET |
/api/donations/calculator |
content-api |
content-api.getCalculatorAndDirectory |
Public |
POST |
/api/donations/calculate |
content-api |
content-api.calculateAssessment |
Public |
POST |
/api/donations/pledges |
content-api |
content-api.submitPledge |
Public |
POST |
/api/donations/webhook |
content-api |
content-api.handleWebhook |
Public |
GET |
/donations/settings |
admin |
admin.getSettings |
Bearer JWT |
PUT |
/donations/settings |
admin |
admin.updateSettings |
Bearer JWT |
GET |
/donations/overview |
admin |
admin.getOverview |
Bearer JWT |
POST |
/donations/campaigns |
admin |
admin.createCampaign |
Bearer JWT |
PUT |
/donations/campaigns/{identifier} |
admin |
admin.updateCampaign |
Bearer JWT |
POST |
/donations/campaigns/{identifier}/evidences |
admin |
admin.addEvidence |
Bearer JWT |
DELETE |
/donations/campaigns/{identifier}/evidences/{evidenceId} |
admin |
admin.removeEvidence |
Bearer JWT |
POST |
/donations/pledges/{referenceCode}/verify |
admin |
admin.verifyPledge |
Bearer JWT |
7. Sunucu Tarafı Programatik Kullanım (strapi.plugin ve strapi.documents)
Section titled “7. Sunucu Tarafı Programatik Kullanım (strapi.plugin ve strapi.documents)”// Registered services on plugin "donations": "settings", "campaign", "pledge"const pluginService = strapi.plugin("donations")?.service("campaign");
// Querying records via the Strapi v5 Document Service APIconst records = await strapi.documents("plugin::donations.campaign").findMany({ limit: 25, sort: "createdAt:desc",});8. Sorun Giderme ve Doğrulama
Section titled “8. Sorun Giderme ve Doğrulama”- Yönetim paneli değişiklikleri görünmüyor:
config/plugins.tsdosyasını güncelledikten sonrapnpm strapi buildkomutunu çalıştırın. - Strapi bağımlılık izolasyonu: React bağlam çakışmalarını önlemek için
pnpm-workspace.yamliçindehoistPattern: ["*", "!@strapi/*"]ayarını koruyun. - Sıkı TypeScript kontrolü: Hem
adminhem deserverpaketlerini doğrulamak içinpnpm checkkomutunu çalıştırın.