Expediente del caso

PayQR España (bizum-qr)

Simbolo de la marca de la edicion del caso
Simbolo de la marca de la edicion del caso
Periodo
2026-05 al 2026-06
Estado
completed
Visibilidad
private
Stack
FastAPI, SvelteKit, PostgreSQL, Redis, Stripe, Redsys
  • technology:fastapi
  • technology:sveltekit
  • technology:postgresql
  • technology:redis
  • technology:stripe
  • technology:redsys
  • architecture:plugin
  • domain:payments
  • domain:bizum
  • domain:verifactu

Evidencias · PAYQR

Métricas

  • 153 commits
  • 3 niveles de tests (unitario, integracion, E2E)
SaaS B2B que funciona como mini-TPV movil: permite a comercios cobrar via Bizum mediante QR dinamico con importe exacto y emitir facturas simplificadas conformes a la normativa Verifactu espanola, con envio automatico a la AEAT. Capa de pasarelas de pago abstracta mediante `Protocol` runtime-checkable + factory soportando Redsys y Stripe de forma intercambiable. Webhooks con idempotencia y verificacion de firma, migraciones Alembic para multi-gateway, firma XML Verifactu (signxml/lxml), generacion de PDF (weasyprint) y QR (segno). Pipeline de tests en tres niveles sobre testcontainers y generacion de tipos OpenAPI a TypeScript en el frontend.

Expediente del caso

Motivación

Cobrar por Bizum en un comercio fisico pequeno no tiene la misma facilidad que con un datáfono. La motivacion fue construir un mini-TPV movil: el comercio muestra un QR dinamico con el importe exacto, el cliente paga con Bizum, y de paso la factura simplificada Verifactu queda emitida y enviada a la AEAT sin pasos manuales.

El reto

El reto era la doble cara del cumplimiento y la operativa: soportar dos pasarelas con comportamientos y firmas distintos sin acoplar el dominio, y generar facturas Verifactu validas (firma XML) que la AEAT acepte, con webhooks que no rompan por reintentos o duplicados.

Enfoque

Se abstrajo la pasarela con un `Protocol` runtime-checkable y una factory: Redsys y Stripe son implementaciones intercambiables detrás de la misma interfaz. Las migraciones Alembic preparan la base para multi-gateway. Los webhooks llevan idempotencia y verificacion de firma. La factura Verifactu se firma con signxml/lxml, el PDF sale de weasyprint y el QR de segno. Un pipeline de tests en tres niveles (unitario, integracion con testcontainers, E2E) sostiene el conjunto, y el frontend consume tipos generados desde el OpenAPI.

Aprendizaje

Un contrato de pasarela con `Protocol` + factory deja anadir o cambiar una pasarela sin tocar el flujo de cobro. La idempotencia en webhooks no es opcional cuando el emisor puede reintentar. Y el cumplimiento Verifactu se apoya en piezas pequenas (firma XML, PDF, QR) que conviene probar de forma aislada antes de integrarlas.

Estado actual

Completado. El proyecto cerro con 153 commits y un pipeline de tres niveles de tests. La arquitectura quedo lista para incorporar pasarelas adicionales y extender los casos de facturacion Verifactu.