Cómo funciona vueltito por dentro.

Resumen

vueltito habilita microdonaciones autorizadas sobre pagos cotidianos. En el checkout de un comercio integrado, el comprador acepta una donación —un monto fijo, un porcentaje chico de la compra o un redondeo— de forma visible. vueltito calcula la donación, registra el consentimiento y la asigna a una ONG verificada, con ledger auditable y conciliación.

La estrategia no depende de un acuerdo directo con una pasarela desde el día uno. El primer paso es una suite de plugins para comercios que ya cobran online; WooCommerce es la primera integración instalable.

Cómo se organiza

vueltito separa la operación en tres partes: el Core que registra las donaciones, la conciliación de remesas y los conectores de cada plataforma. Así el comercio puede sumar donaciones sin cambiar su forma de cobrar.

1 · Core de vueltito

El servicio central guarda reglas de aporte, ONGs, campañas, comercios, transacciones, consentimiento, ledger, conciliación, leaderboard y auditoría.

2 · Conciliación y remesas

Calcula saldos comercio-a-ONG, remesas reportadas y reversas por reembolsos. La donación no pasa por vueltito: el comercio cobra con su pasarela actual y luego reporta la remesa a la ONG.

3 · Integraciones de plataforma

Cada conector resuelve instalación, autenticación del comercio, lectura del carrito, consentimiento del comprador, envío del cálculo al Core y reporte de eventos de la orden.

Qué pasa en el checkout

1. El conector lee subtotal, moneda, ítems y comercio.
2. Le pide al Core las opciones de aporte: fijo, porcentaje, redondeo, límites mínimos/máximos y ONG/campaña elegida.
3. La interfaz muestra el aporte como una línea visible antes de pagar.
4. El comprador acepta y se registra el consentimiento con su snapshot.
5. El comercio cobra el pedido completo con su pasarela actual.
6. El conector informa el evento de orden pagada, cancelada o reembolsada.
7. El ledger registra compra, donación, reversas y saldo pendiente de remesa a la ONG.
8. El leaderboard se actualiza solo si el donante optó por participar.

Qué registra vueltito

• Ledger append-only: nunca se editan entradas históricas; los cambios se registran como reversas.
• Webhooks idempotentes: ningún evento puede crear un doble aporte ni una doble entrada de ledger.
• Snapshots de la regla y del consentimiento por cada transacción.
• Estados separados: orden, donación, asignación a ONG, remesa y facturación se modelan por separado.
• Sin PII en el leaderboard: alias por defecto y visibilidad opt-in.

Eventos principales del ledger

• purchase_observed: compra detectada en el canal.
• donation_authorized: donación aceptada por el comprador.
• ngo_allocated: asignación a ONG o campaña.
• remittance_reported: remesa reportada por el comercio.
• refund_reversed: reversa por cancelación o reembolso.
• adjustment: ajuste operativo auditado.

Canales de integración

Cada canal tiene requisitos distintos. La prioridad es empezar por donde el comercio puede instalar vueltito con menos fricción y con trazabilidad completa.

Seguridad y privacidad

• API keys, tokens de plataformas y credenciales operativas cifrados.
• Validación de firma de webhooks donde la plataforma la provea.
• No se guardan tarjetas ni datos sensibles de pago.
• Leaderboard opt-in y alias por defecto.
• Límites de aporte por transacción y por período.
• Audit log para cambios en ONGs, payouts y ajustes; permisos separados para admin, comercio y ONG.

Próximos pasos

• Fase 0 — Base: spec aprobado, modelo legal/fiscal, política de reembolsos y lista de ONGs demo.
• Fase 1 — Core + WooCommerce: Core API, ledger, leaderboard opt-in y demo end-to-end con orden WooCommerce.
• Fase 2 — Tiendanube: app OAuth, storefront spike y validación formal del checkout productivo.
• Fase 3 — Enterprise: conector VTEX (PPP) y módulo Adobe Commerce.
• Fase 4 — Shopify: según acceso a Plus / partner aprobado.
• Fase 5 — Presencial y alianzas: QR/Point y propuesta de alianza con una pasarela solo si no introduce custodia de donaciones.