Donaciones y Campañas — Guía de Desarrollo y Admin UI
1. Instalación y Dependencias
Sección titulada «1. Instalación y Dependencias»pnpm add @vicacha-devs/strapi-plugin-donations2. Configuración del Servidor (config/plugins.ts)
Sección titulada «2. Configuración del Servidor (config/plugins.ts)»Agregue la configuración del plugin en el archivo config/plugins.ts de su aplicación Strapi v5:
export default ({ env }: { env: (key: string, defaultValue?: string) => string }) => ({ "donations": { enabled: true, config: { baseCurrency: "USD", autoIssueCertificateOnVerify: true, enableCertificatesBridge: true, }, },});
3. Recorrido por la Interfaz de Administración (Strapi v5 Admin UI)
Sección titulada «3. Recorrido por la Interfaz de Administración (Strapi v5 Admin UI)»Una vez habilitado, el plugin registra su espacio de trabajo y ajustes dentro del panel de administración de Strapi v5 utilizando Strapi Design System v2:

Etiquetas Localizadas de la Interfaz (Español)
Sección titulada «Etiquetas Localizadas de la Interfaz (Español)»| Clave de Traducción | Texto en Interfaz |
|---|---|
evidence.type.paid_receipt |
Recibo / Factura de Servicio Pagada |
donations.evidence.type.paid_receipt |
Recibo / Factura de Servicio Pagada |
evidence.type.photo_gallery |
Galería Fotográfica de Equipos y Bienes Donados |
donations.evidence.type.photo_gallery |
Galería Fotográfica de Equipos y Bienes Donados |
evidence.type.delivery_report |
Informe de Entrega de Regalos / Mercados (Kurban / Ramadán) |
donations.evidence.type.delivery_report |
Informe de Entrega de Regalos / Mercados (Kurban / Ramadán) |
evidence.type.audit_document |
Auditoría Financiera y Soporte Oficial |
donations.evidence.type.audit_document |
Auditoría Financiera y Soporte Oficial |
4. Entidades Content-Type, Ubicación y Esquemas (strapi.documents)
Sección titulada «4. Entidades Content-Type, Ubicación y Esquemas (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.
Dónde Encontrar las Entidades Content-Type en Strapi v5
Sección titulada «Dónde Encontrar las Entidades Content-Type en Strapi v5»- 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
Sección titulada «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
| Atributo | Tipo en Strapi | Requerido | Restricciones / Relación |
|---|---|---|---|
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
Sección titulada «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
| Atributo | Tipo en Strapi | Requerido | Restricciones / Relación |
|---|---|---|---|
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" |
Integración con el Content Manager de Strapi v5 (/admin/content-manager)
Sección titulada «Integración con el Content Manager de Strapi v5 (/admin/content-manager)»Grupo en la Barra Lateral del Content Manager:
Donations & Certificates
Entidades y Componentes en el Content Manager
Sección titulada «Entidades y Componentes en el Content Manager»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

Por Qué Este Plugin Crea e Integra Entidades en el Content Manager
Sección titulada «Por Qué Este Plugin Crea e Integra Entidades en el Content Manager»@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.
Cómo Usarlo en el Content Manager de Strapi (Paso a Paso)
Sección titulada «Cómo Usarlo en el Content Manager de Strapi (Paso a Paso)»- 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.
Sincronización entre el Content Manager y el Espacio del Plugin
Sección titulada «Sincronización entre el Content Manager y el Espacio del Plugin»Casos de Uso en el Content Manager y Flujos Editoriales
Sección titulada «Casos de Uso en el Content Manager y Flujos Editoriales»Content Manager Use Case 1 — Publishing Localized Crowdfunding Campaigns & Monthly Utility Bills
Sección titulada «Content Manager Use Case 1 — Publishing Localized Crowdfunding Campaigns & Monthly Utility Bills»- Para qué sirve y por qué usarlo: Manage both major Waqf/social campaigns (
major_campaign) and monthly electricity/water/fiber invoices (utility_invoice) with localized descriptions in Content Manager. - Cómo ejecutarlo en el Content Manager: 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
Sección titulada «Content Manager Use Case 2 — Reconciling Verified Pledges & Linked Tax Certificate Serials»- Para qué sirve y por qué usarlo: Filter verified Zakat and Sadaqah contributions in Content Manager and verify their issued Ed25519 tax certificate serial numbers.
- Cómo ejecutarlo en el Content Manager: Open
/admin/content-manager/collection-types/plugin::donations.pledgeand filter bystatus = verifiedandcertificateSerial is not null.
5. Casos de Uso y Flujos de Trabajo
Sección titulada «5. Casos de Uso y Flujos de Trabajo»Use Case 1 — Multi-Currency Crowdfunding Campaigns (major_campaign)
Sección titulada «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)
Sección titulada «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
Sección titulada «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
Sección titulada «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. Endpoints REST API (content-api y admin)
Sección titulada «6. Endpoints REST API (content-api y admin)»| Método | Ruta del Endpoint | Ámbito | Controlador | Autenticación |
|---|---|---|---|---|
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. Uso Programático en el Servidor (strapi.plugin y strapi.documents)
Sección titulada «7. Uso Programático en el Servidor (strapi.plugin y 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. Solución de Problemas y Verificación
Sección titulada «8. Solución de Problemas y Verificación»- Cambios no visibles en el panel Admin: Ejecute
pnpm strapi builddespués de editarconfig/plugins.ts. - Aislamiento de dependencias peer: Mantenga
hoistPattern: ["*", "!@strapi/*"]enpnpm-workspace.yamlpara evitar colisiones de contexto en React. - Verificación estricta de TypeScript: Ejecute
pnpm checkpara validaradmin/tsconfig.jsonyserver/tsconfig.json.