Saltar al contenido principal

💳 Formularios de donación y actualización: guía de uso

🧩 PARTE 1: Uso de los formularios (qué hacen y cómo se usan)

🎯 Objetivo​

Este proyecto fue creado para que cada organización pueda gestionar distintos tipos de formularios de donación de forma simple y sin intervención manual.

Incluye, por ejemplo:

  • Formularios de alta de donantes
  • Formularios para actualización de donaciones
  • Flujos personalizados según cada organización

Además, está pensado para que ustedes mismos puedan:

  • Ajustar textos
  • Modificar el diseño
  • Adaptarlo a sus necesidades
  • Crear nuevas variantes de formularios

👉 Es decir, no dependen de soporte técnico para realizar cambios funcionales o visuales en el formulario.

🌐 Sobre el proyecto​

El código fuente de este proyecto se encuentra en un repositorio público de GitHub.

Cada organización debe crear una copia del proyecto (Fork) en su propia cuenta para poder administrarlo de manera independiente.

⚠️ Recomendaciones al crear el Fork​

Al momento de crear la copia del repositorio recomendamos:

  • Mantener un nombre que identifique claramente a la organización (por ejemplo: forms-salesforce-nombreong o forms-salesforce-fundacionxyz).
  • Esto facilita identificar rápidamente el proyecto en caso de necesitar asistencia o colaboración.

🤝 Colaboración y contribuciones​

Aunque cada organización tendrá su propio repositorio, el proyecto continúa evolucionando.

Si necesitan ayuda para implementar una mejora o corregir algún comportamiento, podemos colaborar de manera ágil mediante Pull Requests (PRs) sobre su repositorio, siempre que nos otorguen acceso.

De esta forma:

  • Ustedes mantienen el control del proyecto.
  • Las mejoras pueden revisarse antes de incorporarlas.
  • El historial de cambios queda documentado.

🚀 Sobre Vercel​

En esta documentación se utiliza Vercel para publicar el formulario porque ofrece una experiencia muy simple:

  • Publicación automática.
  • Despliegues en pocos minutos.
  • Integración directa con GitHub.
  • Actualizaciones automáticas después de cada cambio.

Por este motivo es la opción que recomendamos y sobre la cual se basa esta guía.

Sin embargo, Vercel no es un requisito.

Si cuentan con un equipo de desarrollo o prefieren otra infraestructura, el proyecto puede desplegarse y mantenerse en cualquier entorno. Son libres de administrarlo utilizando la plataforma o el proceso de despliegue que mejor se adapte a su organización.

🧩 ¿Qué incluye este proyecto?​

El sistema ya viene preparado con distintos tipos de formularios listos para usar.

Por ejemplo:

Tipo de formularioUso
Alta de donantesRegistrar nuevas donaciones
Actualización de donaciónPermitir que un donante cambie su medio de pago o monto
Formularios personalizadosAdaptados a campañas o necesidades específicas

Cada formulario tiene su propia URL y puede personalizarse de manera independiente.

💡 ¿En qué casos se usa?​

Formularios de alta​

Se utilizan para que nuevos donantes puedan:

  • Completar sus datos.
  • Elegir un monto.
  • Cargar un medio de pago.
  • Comenzar una donación.

Formularios de actualización​

Se utilizan cuando:

  • Una tarjeta es rechazada.
  • No hay fondos suficientes.
  • El medio de pago ya no es válido.

En lugar de perder la donación, se le envía al donante un enlace para que actualice su información.

🔄 ¿Cómo funciona el proceso del formulario de modificación?​

Cada donación (Opportunity en Salesforce) tiene un ID único.

Con ese ID se arma un enlace como este:

https://tu-app.vercel.app/flow/{!Opportunity.Id}

Paso 2: Se envía el email​

Desde Salesforce se envía un correo con ese enlace.

Paso 3: El donante completa el formulario​

  • Puede modificar el monto.
  • Puede actualizar su medio de pago.

Paso 4: Actualización automática​

El sistema actualiza automáticamente:

  • Opportunity.
  • Donación recurrente.
  • Medio de pago.

🧩 PARTE 2: Configuración paso a paso (v0 + Vercel)

🌐 Herramientas utilizadas​

  • v0 → donde se edita el formulario
  • Vercel → donde se publica el formulario (el link que usan los donantes)

🆕 PASO 1: Crear cuentas

Crear cuenta en Vercel​

  1. Ir a: https://vercel.com
  2. Click en Sign Up
  3. Registrarse con Google (recomendado)

form

form

form

form

form

Crear cuenta en v0​

  1. Ir a: https://v0.dev
  2. Iniciar sesión con la misma cuenta

📦 PASO 2: Subir el proyecto (MUY IMPORTANTE)

👉 GitHub se utiliza para guardar y administrar el proyecto del formulario.

⚠️ La cuenta que creen será la propietaria del proyecto publicado.

🌐 Crear cuenta en GitHub​

  1. Ingresar a: https://github.com/signup
  2. Completar:
    • Email
    • Contraseña
    • Nombre de usuario
  3. Confirmar la cuenta desde el email recibido

👉 Recomendado: guardar el usuario y contraseña en un lugar seguro.

form

form

🌐 Crear una copia del proyecto en GitHub (Fork)​

Ya con la cuenta creada e iniciada sesión en GitHub, el siguiente paso es crear una copia del proyecto oficial en su propia cuenta.

👉 Esto es necesario para poder editarlo y publicarlo en Vercel.

🔎 1. Entrar al repositorio original​

Abrir este link en el navegador:

https://github.com/debipro/forms-salesforce

Cuando se cargue la página, van a ver el proyecto completo del formulario.

🍴 2. Crear el Fork (hacer la copia)​

Una vez dentro del repositorio:

  1. Mirar la parte superior derecha de la pantalla (arriba del listado de archivos)
  2. Buscar el botón que dice Fork

📌 El botón “Fork” es el que permite copiar el proyecto a su propia cuenta.

form

👤 3. Elegir su cuenta​

Al hacer click en Fork, GitHub va a preguntar:

  • Dónde quieren crear la copia

Ahí deben seleccionar:

👉 Su usuario personal de GitHub

Ejemplo: github.com/tu-usuario

form

⏳ 4. Esperar la creación​

GitHub va a tardar unos segundos en generar la copia.

Cuando termine, los va a redirigir automáticamente a un nuevo repositorio.

📌 Este nuevo repositorio ya es suyo (editable).

Va a verse así: https://github.com/TU-USUARIO/forms-salesforce

form

form

✅ 5. Confirmación​

Van a saber que está bien hecho si:

  • El link ya tiene su usuario en la URL
  • Ven los mismos archivos del proyecto original
  • Pueden navegar carpetas y archivos

⚠️ Importante​

  • No editar el repositorio original (debipro/forms-salesforce)
  • Siempre trabajar sobre el Fork (el que está dentro de su usuario)
  • Este repositorio es el que luego se conecta con Vercel

🚀 PASO 3: Publicar el formulario en Vercel

  1. Ingresar a https://vercel.com
  2. Hacer click en Add New → Project
  3. Seleccionar el repositorio copiado desde GitHub.
  4. Si aparece el mensaje "Choose a Git provider to continue":
    • seleccionar GitHub en Git Scope,
    • o hacer click en Add GitHub Account para conectar la cuenta.
  5. Verificar que el repositorio correcto aparezca seleccionado.
  6. Hacer click en Create.

👉 Vercel detecta automáticamente la configuración necesaria y comienza el deploy del proyecto.

🔗 PASO 4: Ver aplicación desplegada

  1. Esperar a que Vercel finalice el deploy.
  2. Hacer click en Visit para abrir la aplicación.
  3. Continuar con los siguientes pasos de esta documentación.

🎥 Video paso a paso​

🔐 PASO 5: Generar y cargar las credenciales (IMPORTANTE)

👉 El formulario necesita credenciales seguras para conectarse con Salesforce y Debi.
👉 Estas credenciales pueden generarse directamente desde herramientas seguras, sin necesidad de solicitarlas a soporte.

🧩 Qué variables necesita el sistema​

El proyecto utiliza 5 variables obligatorias.

Salesforce​

  • SF_INSTANCE_URL
  • SF_REFRESH_TOKEN
  • SF_LOGIN_URL

Debi​

  • DEBI_PUBLIC_KEY
  • DEBI_SECRET_KEY

👉 Todas deben cargarse en Vercel para que los formularios funcionen correctamente.

🌐 PARTE 1: Generar las credenciales de Salesforce

🔗 Ingresar al asistente​

Entrar a:

https://forms.tc-cloud-partners.net/connect

🛡️ Importante antes de comenzar​

  • Deben iniciar sesión con un usuario que tenga acceso a Salesforce
  • El proceso solo debe hacerse una vez por entorno
  • Las credenciales son privadas y no deben compartirse
  • La pantalla expira automáticamente luego de unos minutos por seguridad

⚠️ El SF_REFRESH_TOKEN funciona como una contraseña de acceso a Salesforce.

No compartirlo por:

  • Emails
  • Chats
  • Capturas de pantalla
  • Tickets
  • Documentos públicos

🧩 Qué hace esta herramienta​

La herramienta genera automáticamente las variables necesarias para conectar el formulario con Salesforce.

Al finalizar obtendrán:

  • SF_INSTANCE_URL
  • SF_REFRESH_TOKEN
  • SF_LOGIN_URL

Listas para copiar en Vercel.

👉 Las credenciales no se almacenan en base de datos ni quedan guardadas permanentemente.

🏢 Elegir el entorno correcto​

Al ingresar, el sistema preguntará qué tipo de organización usan.

Producción​

Usar esta opción en la mayoría de los casos.

Corresponde a:

https://login.salesforce.com

Sandbox​

Usar solamente si trabajan en un entorno de pruebas de Salesforce.

Corresponde a:

https://test.salesforce.com

👉 Generalmente las URLs Sandbox incluyen .sandbox.

🔗 Autorizar Salesforce​

  1. Hacer click en Conectar con Salesforce
  2. Iniciar sesión en Salesforce
  3. Autorizar la aplicación Debi Forms Onboarding
  4. Volver automáticamente a la pantalla final

📋 Copiar las variables​

La pantalla mostrará las variables listas para usar.

Copiar:

  • SF_INSTANCE_URL
  • SF_REFRESH_TOKEN
  • SF_LOGIN_URL

🔑 PARTE 2: Obtener las claves de Debi

🌐 Ingresar al panel de desarrolladores​

Entrar a:

https://debi.pro/dashboard/developers

📋 Copiar las claves​

Buscar y copiar:

  • DEBI_PUBLIC_KEY
  • DEBI_SECRET_KEY

👉 Las claves suelen comenzar con:

  • pk_live_
  • sk_live_

⚠️ Importante: La DEBI_SECRET_KEY es privada y no debe compartirse.

No compartirla por:

  • Emails
  • Chats
  • Capturas de pantalla
  • Tickets
  • Documentos públicos

⚙️ Cómo cargar las variables en Vercel​

  1. Ir a https://vercel.com
  2. Abrir el proyecto
  3. Entrar a: Settings → Environment Variables
  4. Crear estas 5 variables:
  • SF_INSTANCE_URL
  • SF_REFRESH_TOKEN
  • SF_LOGIN_URL
  • DEBI_PUBLIC_KEY
  • DEBI_SECRET_KEY
  1. Pegar los valores correspondientes en cada una

👉 Una vez guardadas, el formulario ya podrá conectarse correctamente con Salesforce y Debi.

🔁 Paso 6 (muy importante)​

Después de completar las claves:

  1. Ir a https://vercel.com
  2. Entrar al proyecto
  3. Ir a Deployments
  4. Buscar el último deploy
  5. Click en los 3 puntitos (⋯)
  6. Click en Redeploy

👉 Esto aplica correctamente las claves al sistema.

⏳ Esperar 1–2 minutos

🎥 Video paso a paso​

🌍 PASO 7: Obtener el link

  1. Hacer click en Visit
  2. Copiar la URL

Ejemplo: https://tu-proyecto.vercel.app

🔗 PASO 8: Probar el formulario

Usar un ID real de Salesforce:

https://tu-proyecto.vercel.app/flow/006XXXXXXXXXXXX

🎥 Video paso a paso​

⚠️ IMPORTANTE

  • El link sin ID no funciona
  • Debe usarse un ID real de Opportunity
  • Si no cargan las claves → no funciona

📝 EDITAR DOMINIO

🎥 Video paso a paso​

ℹ️ En el video se muestra cómo editar el dominio automático generado por Vercel (*.vercel.app).

También es posible utilizar un dominio propio personalizado (por ejemplo: midominio.com) para que la URL no muestre vercel.app.

Para eso:

  1. Comprar o tener un dominio propio
  2. Agregarlo desde Vercel → Settings → Domains
  3. Configurar los registros DNS que indique Vercel

Una vez configurado, el sitio quedará accesible desde el dominio personalizado.

🧩 Múltiples formularios

El sistema permite tener distintos formularios dentro del mismo proyecto.

Por ejemplo:

  • Alta de donantes
  • Actualización de medios de pago
  • Campañas específicas
  • Formularios para distintas organizaciones

Cada formulario tiene su propia URL y puede personalizarse de manera independiente.

✏️ Cómo hacer cambios

El formulario puede modificarse fácilmente desde v0, sin necesidad de programar.

Cómo hacerlo​

  1. Ir a https://v0.dev
  2. Abrir el proyecto del formulario
  3. Escribir en el chat qué cambio quieren hacer

👉 Funciona como hablar con un asistente: describen el cambio y el sistema lo aplica.

🎥 Video paso a paso​

💾 Guardar y publicar los cambios​

Después de realizar cambios en V0:

  1. Revisar la preview (vista previa) que aparece a la derecha para validar que los cambios se reflejen correctamente antes de publicarlos.

    👉 La preview es en tiempo real.
    Si un cambio no se ve ahí, probablemente el componente correcto todavía no fue modificado.

  2. Una vez conforme con los cambios, hacer click en Create PR.

    👉 Esto crea un Pull Request (PR) en GitHub con todos los cambios realizados.

  3. Luego hacer click en Merge PR.

    👉 Este paso es el que realmente guarda y aplica los cambios en el repositorio conectado al proyecto.

  4. Después del merge, Vercel detecta automáticamente los cambios y realiza un nuevo deploy.

  5. Para verificar que el deploy terminó correctamente:

    • Ir a Vercel → Deployments
    • Esperar a que el estado figure como Ready

  6. Finalmente, abrir el dominio del formulario

Ejemplos de cambios que pueden pedir​

📝 Textos​

  • “Cambiar el texto del botón a ‘Actualizar donación’”
  • “Modificar el mensaje de error por uno más amigable”
  • “Cambiar el título a ‘Actualizá tu medio de pago’”
  • “Agregar una descripción debajo del título”

🎨 Diseño y colores​

  • “Cambiar los colores a los institucionales de la ONG”
  • “Hacer el botón principal de color verde”
  • “Cambiar el fondo del formulario”
  • “Aumentar el tamaño de los títulos”

🔤 Tipografía​

  • “Cambiar la tipografía por una más moderna”
  • “Usar una fuente similar a la de nuestra web”
  • “Hacer el texto más grande para mejor lectura”

🧾 Campos del formulario​

  • “Agregar un campo de mensaje para el donante”

🧩 Estructura​

  • “Hacer el formulario más corto”
  • “Ordenar los campos de otra manera”
  • “Separar en pasos (pantallas)”
  • “Agregar un mensaje de confirmación al finalizar”

🖼️ Contenido visual​

  • “Agregar el logo de la ONG arriba”
  • “Agregar una imagen al inicio”
  • “Centrar el logo”

🧪 Recomendación​

Siempre después de un cambio:

  • Probar el formulario completo
  • Verificar que funcione correctamente
  • Revisar que los datos se actualicen en Salesforce

⚠️ Importante​

  • No modificar configuraciones técnicas
  • No cambiar integraciones
  • Si algo no funciona, consultar

📧 Cómo configurar el envío de emails con el link del formulario

Para que cada donante reciba su link personalizado, deben configurar una plantilla de correo en Salesforce.

🎯 Objetivo​

Que el link se genere automáticamente con el ID de la Opportunity, sin tener que completarlo manualmente.

🔗 Cómo funciona​

El link del formulario es así:

https://tu-app.vercel.app/flow/{!Opportunity.Id}

👉 Salesforce reemplaza automáticamente {!Opportunity.Id} por el ID real de cada donación.

🛠️ Paso a paso: crear la plantilla​

  1. Ingresar a Salesforce
  2. Ir a Setup
  3. Buscar: Email Templates
  4. Hacer click en New Email Template

✏️ Crear el contenido​

Completar:

  • Nombre: Actualización de donación
  • Asunto: Actualizá tu medio de pago

Ejemplo de mensaje​

Copiar y adaptar:

Hola {!Contact.FirstName},

Tuvimos un inconveniente al procesar tu donación.

Podés actualizar tu información desde el siguiente link:
`https://tu-app.vercel.app/flow/{!Opportunity.Id}`

Muchas gracias por tu apoyo.

📌 Importante​

  • No modificar {!Opportunity.Id}
  • Ese valor se completa automáticamente
  • Cada donante recibe su link único

🧪 Recomendación​

Antes de usarlo masivamente:

  1. Enviar un email de prueba
  2. Verificar que el link funcione
  3. Confirmar que abre el formulario correcto

⚙️ Opcional (automatización)​

El envío puede ser:

  • Manual (desde cada Opportunity)
  • Automático (con Flow o Process Builder)

👉 Recomendado: automatizar para ahorrar tiempo

🧠 Resumen​

  • Se crea una plantilla en Salesforce
  • Se usa {!Opportunity.Id} en el link
  • Salesforce completa el ID automáticamente
  • Cada donante recibe su link personalizado

✅ Conclusión

Con estos pasos pueden:

  • Publicar el formulario
  • Configurarlo
  • Usarlo sin conocimientos técnicos

👉 Y mantenerlo sin depender de soporte