806612a4db
- Renombrar 02-integraciones/ → 03-integraciones/ (resolver prefijo duplicado) - Renombrar 02-devops/ → 04-devops/ (resolver prefijo duplicado) - Renombrar architecture/ → 97-adr/ (agregar prefijo numerico) - Actualizar _MAP.md con nueva estructura y version 2.1.0 Estructura final: - 00-vision-general/ - 01-modulos/ - 02-especificaciones/ - 03-integraciones/ - 04-devops/ - 97-adr/ Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
131 lines
4.1 KiB
Markdown
131 lines
4.1 KiB
Markdown
---
|
|
id: "INT-001"
|
|
title: "Integracion Stripe Billing"
|
|
type: "Integration"
|
|
status: "Implemented"
|
|
priority: "P0"
|
|
provider: "Stripe"
|
|
category: "Payments"
|
|
multi_tenant: true
|
|
version: "1.0.0"
|
|
created_date: "2026-01-07"
|
|
updated_date: "2026-01-10"
|
|
---
|
|
|
|
# INT-001: Stripe Integration
|
|
|
|
## Metadata
|
|
| Campo | Valor |
|
|
|-------|-------|
|
|
| Codigo | INT-001 |
|
|
| Proveedor | Stripe Inc |
|
|
| Tipo | Pagos |
|
|
| Estado | Implementado |
|
|
| Multi-tenant | Si |
|
|
| Fecha integracion | 2026-01-10 |
|
|
|
|
---
|
|
|
|
**Documentacion completa:** Ver [SAAS-004-billing.md](../01-modulos/SAAS-004-billing.md)
|
|
|
|
## Resumen
|
|
|
|
Integracion con Stripe para pagos y suscripciones.
|
|
|
|
## Caracteristicas
|
|
|
|
- Suscripciones recurrentes (monthly/yearly)
|
|
- Webhooks para eventos de pago
|
|
- Billing portal para clientes
|
|
- Metered billing opcional
|
|
- Manejo de invoices y payments
|
|
|
|
## Configuracion
|
|
|
|
```env
|
|
STRIPE_SECRET_KEY=sk_...
|
|
STRIPE_WEBHOOK_SECRET=whsec_...
|
|
STRIPE_PUBLISHABLE_KEY=pk_...
|
|
```
|
|
|
|
## Endpoints/SDK Utilizados
|
|
|
|
| Operacion | Endpoint/Metodo | Descripcion |
|
|
|-----------|-----------------|-------------|
|
|
| Crear cliente | `stripe.customers.create()` | Crea customer en Stripe |
|
|
| Obtener cliente | `stripe.customers.retrieve()` | Obtiene datos de customer |
|
|
| Actualizar cliente | `stripe.customers.update()` | Actualiza datos de customer |
|
|
| Crear suscripcion | `stripe.subscriptions.create()` | Inicia nueva suscripcion |
|
|
| Cancelar suscripcion | `stripe.subscriptions.cancel()` | Cancela suscripcion activa |
|
|
| Pausar suscripcion | `stripe.subscriptions.update()` | Pausa cobros |
|
|
| Reanudar suscripcion | `stripe.subscriptions.resume()` | Reanuda suscripcion pausada |
|
|
| Crear checkout | `stripe.checkout.sessions.create()` | Crea sesion de checkout |
|
|
| Crear portal | `stripe.billingPortal.sessions.create()` | Acceso a portal de billing |
|
|
| Crear precio | `stripe.prices.create()` | Crea nuevo precio |
|
|
| Listar precios | `stripe.prices.list()` | Lista precios disponibles |
|
|
| Crear invoice | `stripe.invoices.create()` | Crea factura manual |
|
|
| Obtener invoice | `stripe.invoices.retrieve()` | Obtiene factura |
|
|
| Pagar invoice | `stripe.invoices.pay()` | Marca invoice como pagada |
|
|
| Crear payment intent | `stripe.paymentIntents.create()` | Inicia intent de pago |
|
|
| Confirmar payment | `stripe.paymentIntents.confirm()` | Confirma pago |
|
|
| Webhook handler | `stripe.webhooks.constructEvent()` | Valida webhooks |
|
|
|
|
## Rate Limits
|
|
| Limite | Valor | Accion si excede |
|
|
|--------|-------|------------------|
|
|
| Requests/seg | 100 | Retry con backoff exponencial |
|
|
| Requests/dia | Sin limite | N/A |
|
|
|
|
## Manejo de Errores
|
|
| Codigo | Descripcion | Accion |
|
|
|--------|-------------|--------|
|
|
| 400 | Bad Request | Log + no retry |
|
|
| 401 | Unauthorized | Renovar credenciales |
|
|
| 429 | Rate Limited | Backoff exponencial |
|
|
| 500 | Server Error | Retry con backoff |
|
|
|
|
## Fallbacks
|
|
|
|
### Estrategia si Stripe no disponible
|
|
|
|
| Escenario | Estrategia | Accion |
|
|
|-----------|------------|--------|
|
|
| API timeout | Reintentar con backoff | 3 reintentos: 1s, 2s, 4s |
|
|
| Webhook perdido | Verificacion periodica | Cron cada 5 min verifica estado |
|
|
| Pago fallido | Dunning automatico | 3 reintentos en 7 dias |
|
|
| Suscripcion cancelada | Periodo de gracia | 7 dias antes de suspender |
|
|
|
|
### Circuit Breaker
|
|
|
|
- Umbral apertura: 5 fallos consecutivos
|
|
- Timeout semi-abierto: 30 segundos
|
|
- Fallback: Cola BullMQ para retry posterior
|
|
|
|
## Multi-tenant
|
|
- Credenciales: Por tenant (cada tenant puede tener su propia cuenta Stripe Connect)
|
|
- Configuracion: Por tenant via tenant_config
|
|
- Aislamiento: Prefijo tenant_id en todas las operaciones
|
|
|
|
## Testing
|
|
### Sandbox/Test Mode
|
|
- Usar claves de prueba en desarrollo (sk_test_*, pk_test_*)
|
|
- Tarjetas de prueba: 4242424242424242 (exito), 4000000000000002 (decline)
|
|
- Fixtures disponibles para testing unitario
|
|
|
|
## Monitoreo
|
|
| Metrica | Descripcion | Alerta |
|
|
|---------|-------------|--------|
|
|
| Latencia | Tiempo de respuesta | >2s |
|
|
| Errores | Tasa de errores | >1% |
|
|
| Disponibilidad | Uptime del servicio | <99.9% |
|
|
|
|
## Referencias
|
|
|
|
- [Stripe API Documentation](https://stripe.com/docs/api)
|
|
- Modulo relacionado: SAAS-004-billing.md
|
|
|
|
---
|
|
|
|
**Ultima actualizacion:** 2026-01-10
|
|
**Version:** 1.0.0
|