Requiere:

• Charitable Pro (Plus, Pro o Elite) 1.8.17+
• Recibos Personalizados de Charitable 1.0.0+
• Donaciones Recurrentes 2.2.1+ (opcional)

Recibos Personalizados te permite decidir qué ve un donante en pantalla justo después de donar. Esa página (la página de agradecimiento a la que llega un donante una vez que su donación se ha procesado) es uno de los momentos de mayor atención en todo el flujo de donaciones, y por defecto, cada campaña comparte el mismo recibo en todo el sitio.

Este complemento cambia eso. Cada campaña puede:

• Mantener el recibo predeterminado (sin cambios, exactamente como hoy).
• Redirigir a los donantes a una página que ya has creado, o a cualquier URL.
• Mostrar un recibo personalizado que diseñas en el editor de bloques de WordPress, utilizando bloques conscientes de los recibos que rellenan el nombre real del donante, la cantidad, la campaña y los detalles del regalo en el momento de la visualización.

Empiezas desde un diseño integrado, lo ajustas para que se adapte a tu organización, lo previsualizas con datos de ejemplo y guardas tus propios diseños para reutilizarlos en diferentes campañas.

Qué es (y qué no es) un recibo personalizado

Ayuda ser preciso sobre lo que este complemento afecta:

• Solo personaliza la página de recibo en pantalla, la página que un donante ve inmediatamente después de donar.
• No cambia tus correos electrónicos de recibo de donación. Esos siguen controlados en la configuración de correo electrónico de Charitable.
• No reemplaza el complemento de Recibos PDF. Si usas recibos PDF, seguirán funcionando, e incluso hay un bloque que enlaza directamente a los donantes con su PDF.

Piénsalo como la página de agradecimiento, no como el papeleo.

Cuándo usarlo

Algunas razones comunes por las que las organizaciones recurren a recibos personalizados:

• Haz que el momento de agradecimiento se sienta personal. Cambia la confirmación simple por un mensaje cálido, tu logo y una línea sobre el impacto del regalo.
• Envía a los donantes importantes a un lugar especial. Usa una condición para que una nota de agradecimiento de “500 € o más” solo aparezca para donaciones importantes.
• Dirige a los donantes a un siguiente paso. Un botón de “Donar de Nuevo”, “Compartir” o “Seguir mi Donación” convierte un regalo único en un compromiso continuo.
• Convierte un regalo único en apoyo mensual. Añade el bloque de Upsell Recurrente para invitar a los donantes únicos a convertir su regalo en una donación recurrente (requiere el complemento de Donaciones Recurrentes).
• Adapta el recibo a la campaña. Una campaña conmemorativa y una colecta de fin de año pueden tener su propia página de agradecimiento.
• Reutiliza una página de redirección que ya hayas creado. Si tienes una página de “agradecimiento” personalizada en tu tema, simplemente apunta la campaña hacia ella.

Antes de empezar

Recibos Personalizados necesita algunas cosas en su lugar:

• Charitable Pro con una licencia activa (Plus, Pro o Elite).
• Charitable core 1.8.17 o posterior. El complemento se renderiza a través de un filtro principal que se añadió en la versión 1.8.17, por lo que en versiones anteriores el recibo personalizado no se mostrará. Si tu núcleo está desactualizado, verás un aviso en el administrador pidiéndote que actualices.
• WordPress 6.2+ y PHP 7.4+.
• Donaciones recurrentes 2.2.1 o posterior (opcional). Solo es necesario si deseas los bloques de Venta adicional recurrente y Detalles recurrentes o la condición de Tipo de regalo.

Una vez que el complemento esté activo, no hay una página de configuración separada para configurarlo. Todo sucede por campaña.

Elección de un modo de recibo

Cada campaña tiene su propio modo de recibo. Encontrarás la configuración en el editor de campaña que utilices.

En el Generador de campañas visual

Abre una campaña en el Generador de campañas y ve a:

Configuración > Recibo

En el editor de configuración de campaña heredado

Si utilizas el editor de campañas clásico, las mismas opciones se encuentran en el metabox Recibo, en las pestañas de configuración avanzada de la campaña, junto a Opciones de donación y Actualizaciones. El selector de modo se ve y se comporta exactamente igual que el panel del Generador de campañas que se muestra arriba.

Los tres modos

Predeterminado deja todo como está. El donante ve tu recibo normal en todo el sitio. Elige esto para cualquier campaña que no quieras modificar.

Redireccionar envía al donante a otro lugar en el momento en que su donación se completa. Eliges uno de dos destinos:

• Una página en este sitio, elegida de un menú desplegable de tus páginas publicadas.
• Una URL externa, escrita directamente. Debe comenzar con https://.

Personalizado muestra un recibo que diseñas en el editor de bloques. Cuando eliges Personalizado, el complemento crea un documento de recibo vinculado a esa campaña y te proporciona un botón para abrirlo en el editor.

Diseño de un recibo personalizado

Elegir el modo Personalizado abre el recibo en una versión enfocada del editor de bloques de WordPress. Parece la edición de una página, con una diferencia importante: los bloques que colocas son conscientes del recibo. Un bloque de Resumen de donación no te pide que escribas una cantidad, muestra la cantidad real de cada donación cuando el donante ve su recibo.

El recorrido de bienvenida

La primera vez que abras un recibo, un breve recorrido guiado te presentará el editor, el selector de diseño y el botón de vista previa.

Consejo: ¿Quieres volver a ver el recorrido más tarde? Añade &charitable_cr_guide=1 al final de la URL del editor de recibos y la guía de bienvenida y los consejos de primera ejecución se reproducirán, sin importar cuántas veces los hayas descartado antes.

Empezar con un diseño incorporado

Rara vez empiezas desde una página en blanco. Abre el panel Diseños en la barra lateral del editor y elige un punto de partida. Cada diseño muestra un pequeño esquema para que puedas ver la disposición de un vistazo.

Hacer clic en un diseño rellena el editor con los bloques de ese diseño, listo para que lo edites. Nada cambia para los donantes hasta que guardas. Siempre puedes cambiar a un punto de partida diferente más tarde con Cambiar diseño.

Bueno saberlo: Aplicar un diseño lo copia en tu recibo. Si editas la definición subyacente de un diseño incorporado más tarde (por ejemplo, a través de un filtro), los recibos que ya creaste no cambian. Para incorporar la versión más reciente de un diseño, vuelve a aplicarlo con Cambiar diseño.

Los cinco diseños incorporados

Diseño	Mejor para
Estándar	Un recibo limpio y cotidiano: resumen de donación, la declaración oficial del recibo y un mensaje de agradecimiento.
Agradecimiento e Impacto	Un cálido agradecimiento y un mensaje de impacto además de los detalles requeridos del recibo.
Recibo Fiscal	Declaración al frente y minimalista, para acuses de recibo formales y de estilo fiscal.
Elegante	Un recuerdo refinado y centrado con un medallón, un cálido agradecimiento y una línea de regalo personalizada encima de los detalles.
Exhibición	Un recibo moderno, liderado por imágenes, con un banner principal sobre secciones de tarjetas para gratitud, impacto, detalles y acciones.

Los bloques del recibo

Recibos Personalizados añade un conjunto dedicado de bloques que leen datos de donación en vivo. Abra el insertador de bloques dentro de un recibo y los encontrará agrupados.

Dos bloques son la base de todo recibo válido:

• Resumen de Donación – el monto, fecha, número de recibo, campaña y método de pago del regalo.
• Declaración del Recibo – el nombre de su organización, ID fiscal / EIN y la declaración oficial de recibo de donación que los donantes necesitan para sus registros.

El resto son piezas opcionales, que se pueden mezclar y combinar:

Bloquear	Lo que muestra
Mensaje de Agradecimiento	Un encabezado, mensaje e icono personalizados, con estilos desde simple hasta certificado y medallón.
Impacto	Un breve mensaje sobre lo que el regalo hace posible, opcionalmente diferente según el monto de la donación.
Contenido Personalizado	Un contenedor cuyo contenido aparece solo cuando la donación coincide con sus reglas (ver abajo).
Icono	Un solo icono: un emoji, un SVG incorporado o una imagen que usted suba.
Banner Principal del Recibo	Un banner principal con una imagen de fondo, superposición, icono opcional, subtítulo, encabezado y una línea de regalo dinámica.
Detalles de la Organización	El logo, nombre, dirección, teléfono, correo electrónico y sitio web de su organización.
Detalles del Donante	El nombre, correo electrónico y dirección de facturación del donante de la donación.
Detalles del Recibo Fiscal	El monto deducible de impuestos y la declaración de cumplimiento de bienes y servicios.
Regalos pareados	Un aviso para que los donantes comprueben si su empleador iguala las donaciones.
Donar de nuevo	Un botón que devuelve al donante a la campaña para que done de nuevo.
Compartir	Botones para compartir en redes sociales (Facebook, X, LinkedIn, WhatsApp, correo electrónico) y un enlace de referencia.
Imprimir o Guardar como PDF	Un botón que abre el diálogo de impresión del navegador para que el donante pueda imprimir o guardar la página.
Descargar recibo en PDF	Un botón que enlaza al recibo en PDF del donante (utiliza los recibos en PDF integrados de Charitable Pro).
Seguimiento de sus donaciones	Un enlace al panel del donante, con un enlace seguro de inicio de sesión por correo electrónico para donantes invitados.
Código QR	Un código escaneable generado en su propio servidor (ver más abajo).
Oferta de suscripción recurrente	Una invitación para que los donantes únicos cambien a donaciones mensuales.
Detalles recurrentes	El estado, las fechas y el importe de un plan recurrente (requiere el complemento Recurring; se oculta a sí mismo para donaciones únicas).

Contenido Personalizado

El bloque Contenido Personalizado es un contenedor: todo lo que coloque dentro solo aparecerá cuando la donación cumpla las reglas que establezca. Seleccione el bloque, abra su configuración y añada una o más condiciones.

Puede crear reglas a partir de cualquiera de estos:

Condición	Coincide con
Importe	Un rango de importe de donación (un mínimo, un máximo o ambos).
Tipo de regalo	Donaciones únicas frente a recurrentes (requiere el complemento Recurring).
Tributo	Si el regalo es un tributo (requiere el complemento Tributes).
Método de pago	La pasarela que utilizó el donante (Stripe, PayPal, etc.).
Donante	Reglas basadas en el donante, como la primera vez frente a la recurrente.
Campaña	Una campaña específica.
País	El país de facturación del donante.
Fecha	Un rango de fechas para cuándo se realizó la donación.

Algunos ejemplos

• Agradece a los donantes importantes. Envuelve una invitación a un evento en un bloque de Contenido Personalizado con una condición de Importe de 250 € o más, para que solo las donaciones más grandes la vean.
• Da la bienvenida a los colaboradores mensuales. Usa una condición de Tipo de donación establecida en recurrente para mostrar una nota de “gracias por hacerte donante mensual” (requiere el complemento de Donaciones Recurrentes).
• Muestra un mensaje específico del país. Añade una condición de País establecida en Reino Unido para mostrar un recordatorio de Gift Aid solo a los donantes del Reino Unido.
• Guía a los donantes offline. Usa una condición de Método de pago para pagos offline o por cheque para mostrar tu dirección postal y a quién hacer el cheque.

Puedes combinar condiciones en un bloque. Todas deben coincidir para que el contenido se muestre (por ejemplo, Importe 250 € o más y País Reino Unido).

Previsualizar como

Dado que el contenido personalizado está oculto hasta que una donación coincide, puede ser difícil de diseñar. El selector Previsualizar como en la barra lateral del editor te permite simular ser diferentes donantes (una donación grande, un donante recurrente, un país específico) y ver los bloques aparecer y desaparecer en tiempo real, sin salir del editor.

El bloque de Código QR

El bloque Código QR añade un código escaneable a tu recibo. Es un buen detalle en un recibo impreso: un donante puede escanearlo con su teléfono para saltar directamente a un enlace que tú elijas.

Tú eliges a dónde apunta el código:

• Donar de nuevo (el formulario de donación de la campaña), la opción predeterminada.
• Este recibo.
• La página de la campaña.
• Una URL personalizada que introduzcas.

También puedes establecer el color y el tamaño del código. El código se genera en tu propio servidor sin llamadas externas, por lo que nada sobre la donación se envía a un servicio de QR de terceros.

Diseño: ancho y marco de tarjeta

Dos controles en la barra lateral del recibo dan forma al aspecto general:

• Ancho: qué tan ancho es el contenido del recibo: Estrecho, Estándar, Ancho o Completo. El lienzo del editor se redimensiona para coincidir, por lo que lo que ves mientras editas coincide con el front-end.
• Tarjeta: un marco blanco opcional (“tarjeta”) (con relleno, borde y una sombra suave) alrededor de todo el recibo, para que destaque en una página concurrida.

Previsualizar en tu sitio

La edición te muestra el diseño, pero para ver el recibo exactamente como lo haría un donante, abre el panel Previsualizar en la barra lateral del editor y haz clic en Previsualizar en el sitio. Abre tu tema en vivo en una nueva pestaña y renderiza el recibo con datos de donación de muestra realistas. (Guarda el recibo una vez para habilitar el botón).

Dado que utiliza datos de muestra, puedes previsualizar de forma segura sin hacer una donación de prueba.

Guarda y reutiliza tus propios diseños

Una vez que tengas un recibo que te guste, puedes guardarlo como una plantilla reutilizable. En la barra lateral del editor, abre el panel Plantilla de recibo, haz clic en Guardar como plantilla y asígnale un nombre. Tu plantilla guardada aparecerá junto a los diseños integrados en el panel Diseños para cada campaña.

Para renombrar o eliminar plantillas guardadas más tarde, utiliza la pantalla de gestión de plantillas a la que se accede desde el menú de ayuda del editor.

Cómo funciona con otros complementos de Charitable

Recibos personalizados está diseñado para cooperar con el resto de la familia Charitable:

• Donaciones recurrentes. Los bloques Detalles recurrentes y Venta adicional recurrente se activan y la condición Tipo de regalo se vuelve disponible. Si tu recibo ya incluye un bloque de Detalles recurrentes, el complemento suprime la sección recurrente duplicada que de otro modo añadiría Recurrente, para que los donantes no la vean dos veces.
• Tributos. Las donaciones de tributos conservan su recibo dedicado de Tributos. Recibos personalizados se hace a un lado para esos regalos, de modo que la experiencia del tributo (honrado, mensaje y detalles) se preserve. Los regalos que no son de tributo en la misma campaña siguen utilizando tu recibo personalizado.
• Recibos PDF / Charitable Pro. El bloque Descargar recibo PDF enlaza a los donantes con el PDF generado por los recibos PDF integrados de Charitable Pro. La generación de códigos QR también utiliza una utilidad de Charitable Pro.
• Alivio de comisiones. Las cifras de donación mostradas por los bloques de recibo reflejan las cantidades que registra el núcleo de Charitable, por lo que los detalles de alivio de comisiones fluyen a través de los datos estándar de la donación.

Preguntas frecuentes

¿Requiere esto Charitable Pro? Sí. Recibos personalizados requiere una licencia activa de Charitable Pro (Plus, Pro o Elite) y Charitable core 1.8.17 o posterior.

¿Afecta a mis correos electrónicos de recibo de donación o a mis recibos PDF? No. Este complemento solo personaliza la página de recibo en pantalla. Tus correos electrónicos de recibo y el complemento de Recibos PDF no se ven afectados.

¿Qué sucede con una donación de tributo? Los regalos de tributo conservan su recibo dedicado de Charitable Tributes. El recibo personalizado se desactiva para esas donaciones para preservar la experiencia del tributo.

Si cambio un diseño integrado más tarde, ¿se actualizan mis recibos existentes? No. Aplicar un diseño lo copia en el recibo de esa campaña, por lo que cada recibo permanece independiente y editable. Para obtener la última versión de un diseño, vuelve a aplicarlo con Cambiar diseño.

¿El código QR llama a un servicio externo? No. Los códigos QR se generan en tu propio servidor. No se realizan solicitudes HTTP externas.

---

Referencia del desarrollador

Todo lo que sigue es para desarrolladores que deseen extender o tematizar recibos personalizados. Si solo estás configurando recibos en el administrador, puedes detenerte aquí.

Cómo funciona la renderización

Custom Receipts engancha el filtro principal charitable_donation_receipt_custom_body, agregado en Charitable 1.8.17. Cuando la campaña de una donación está en modo Personalizado, el complemento devuelve el marcado del bloque de recibo renderizado a través de ese filtro; de lo contrario, devuelve null y se utiliza el recibo predeterminado. Es por eso que 1.8.17 es un requisito estricto: en versiones anteriores del núcleo, el filtro no existe y no se renderiza nada.

Los recibos se almacenan como un tipo de publicación personalizada no pública, charitable_receipt, una publicación por campaña que utiliza el modo Personalizado. Los diseños guardados también son publicaciones charitable_receipt, marcadas como plantillas y no vinculadas a una campaña.

Claves meta

Establecido en la campaña:

Clave de metadatos	Propósito
_charitable_receipt_mode	default, redirect o custom.
_charitable_receipt_redirect_type	page o url (modo Redirección).
_charitable_receipt_redirect_target	ID de página o URL completa https:// (modo Redirección).
_charitable_receipt_id	ID de la publicación charitable_receipt vinculada (modo Personalizado).

Establecido en la publicación del recibo:

Clave de metadatos	Propósito
_charitable_cr_design	ID del diseño aplicado (builtin:standard, un ID de plantilla de publicación, etc.).
_charitable_receipt_width	narrow, standard, wide o full.
_charitable_receipt_card	Si el marco de la tarjeta está habilitado.

Filtros

Filtro	Propósito
charitable_custom_receipts_render_for_donation	Devuelve false para excluir una donación específica de la renderización personalizada (así es como Tributes se aparta).
charitable_custom_receipts_render	Filtra el HTML final del recibo renderizado.
charitable_custom_receipts_built_in_themes	Agrega, elimina o modifica los diseños integrados.
charitable_custom_receipts_template_options	Modifica la lista completa de diseños (integrados más guardados) que se muestran en los selectores.
charitable_custom_receipts_condition_types	Registra o modifica tipos de condiciones de Contenido Personalizado.
charitable_custom_receipts_widths	Define o modifica las opciones de ancho y sus restricciones de píxeles.
charitable_custom_receipts_layout_classes	Modifica las clases CSS del contenedor del recibo.
charitable_custom_receipts_seed_content	Proporciona el marcado de bloque inicial para un recibo recién creado.
charitable_custom_receipts_preview_context	Modifica los datos de donación de ejemplo utilizados en las previsualizaciones.
charitable_custom_receipts_docs_url	Anula el enlace "Lee la documentación" en la incorporación del editor.
charitable_custom_receipts_qr_alt	Personaliza el texto alternativo de la imagen del código QR.
charitable_custom_receipts_dashboard_url	Personaliza el enlace "Seguimiento de tus donaciones".
charitable_custom_receipts_pdf_download_url	Personaliza el enlace "Descargar recibo en PDF".
charitable_custom_receipts_recurring_upsell_url	Personaliza el enlace de conversión de "Oferta de donaciones recurrentes".

Acciones

Acción	Se dispara cuando
charitable_custom_receipts_init	El complemento se ha iniciado y ha confirmado que Charitable Pro está activo. Pasa el contenedor de servicios. Úsalo para registrar integraciones o condiciones personalizadas.
charitable_custom_receipts_template_applied	Se aplica un diseño o plantilla guardada a un recibo de campaña. Pasa el ID de la campaña, el ID del recibo y el ID de la plantilla.

Ejemplos

Inserta cualquiera de estos en un plugin específico del sitio o en el archivo functions.php de tu tema.

Apunta el enlace de documentación del editor a tu propia página de incorporación:

add_filter( 'charitable_custom_receipts_docs_url', function () {
	return home_url( '/staff/receipt-guide/' );
} );

Añade una opción adicional de ancho de recibo:

add_filter( 'charitable_custom_receipts_widths', function ( $widths ) {
	// slug => [ content width px, wide width px ].
	$widths['xwide'] = array( 960, 1200 );
	return $widths;
} );

Nunca generes un recibo personalizado para una campaña específica, independientemente de su modo:

add_filter( 'charitable_custom_receipts_render_for_donation', function ( $render, $donation ) {
	return ( 123 === (int) $donation->get_campaign_id() ) ? false : $render;
}, 10, 2 );

Haz algo después de aplicar un diseño (por ejemplo, vacía la caché de la página):

add_action( 'charitable_custom_receipts_template_applied', function ( $campaign_id, $receipt_id, $template_id ) {
	// Your cache invalidation here.
}, 10, 3 );

Relacionado

• Recibos PDF de Charitable – recibos PDF descargables para donantes y administradores.
• Donaciones recurrentes de Charitable – desbloquea los bloques recurrentes y la condición de Tipo de regalo.
• Tributos de Charitable – regalos en memoria y en honor con su propio recibo.
• Uso del Creador de Campañas – donde reside el panel de Recibos por campaña.

---