replace cta with social_media question; add SocialMedia field to landing_session

2026-05-28 20:49:35 -05:00
parent 06d85dc0bf
commit 52ce8638a8
4 changed files with 243 additions and 10 deletions
@@ -0,0 +1,133 @@
+# Bold — Solicitar y consumir enlaces de pago
+
+## Requisitos previos
+
+Tener configurada la pasarela Bold con una API key activa. Se gestiona desde:
+
+```
+POST /pasarelas/bold/save
+```
+
+---
+
+## 1. Crear un enlace de pago
+
+**Endpoint:** `POST /pasarelas/bold/crear-link`  
+**Autenticación:** requerida (sesión o token)
+
+### Request
+
+```http
+POST /pasarelas/bold/crear-link
+Content-Type: application/json
+Authorization: <token>
+```
+
+```json
+{
+  "total_amount": 50000,
+  "description": "Renovación plan básico",
+  "reference": "REF-UNICA-001",
+  "payer_email": "cliente@correo.com",
+  "callback_url": "https://tudominio.com/pago-resultado"
+}
+```
+
+| Campo          | Tipo   | Requerido | Descripción                                         |
+|----------------|--------|-----------|-----------------------------------------------------|
+| `total_amount` | int64  | ✅        | Monto en COP sin centavos (ej. `50000` = $50.000)   |
+| `description`  | string | ✅        | Descripción visible en el checkout Bold             |
+| `reference`    | string | ✅        | Referencia única por pago (usada para identificarlo)|
+| `payer_email`  | string | ❌        | Email del pagador (prellenado en el checkout)       |
+| `callback_url` | string | ❌        | URL de redirección tras el pago (override del config)|
+
+### Response `200 OK`
+
+```json
+{
+  "payment_link": "pl_abc123xyz",
+  "url": "https://checkout.bold.co/payment/pl_abc123xyz"
+}
+```
+
+- `url` → redirige al usuario a esta URL para que complete el pago.
+- `payment_link` → ID del link, guárdalo para consultar su estado después.
+
+---
+
+## 2. Consultar el estado de un enlace
+
+**Endpoint:** `GET /pasarelas/bold/link/:linkID`  
+**Autenticación:** requerida
+
+```http
+GET /pasarelas/bold/link/pl_abc123xyz
+Authorization: <token>
+```
+
+### Response `200 OK`
+
+```json
+{
+  "data": "{ ...payload crudo de la API de Bold... }"
+}
+```
+
+---
+
+## 3. Webhook (notificación automática de Bold)
+
+Bold notifica los pagos a:
+
+```
+POST /webhooks/bold
+```
+
+Esta ruta es **pública** (sin autenticación). Bold la llama automáticamente al completarse un pago. El sistema valida la firma HMAC-SHA256 y registra el evento en `bold_webhook_log`.
+
+---
+
+## 4. Usar el servicio directamente en Go
+
+```go
+import (
+    "github.com/sujit-baniya/fiber-boilerplate/pkg/models"
+    "github.com/sujit-baniya/fiber-boilerplate/pkg/services"
+)
+
+cfg, err := models.GetBoldConfig()
+if err != nil {
+    // sin configuración activa
+}
+
+result, err := services.CreateBoldPaymentLink(cfg, services.BoldPaymentLinkRequest{
+    AmountType: "CLOSE",
+    Amount: services.BoldAmountField{
+        Currency:    "COP",
+        TotalAmount: 50000,
+    },
+    Description: "Renovación plan X",
+    Reference:   "REF-UNICA-001",
+    PayerEmail:  "cliente@correo.com",
+})
+if err != nil {
+    // error de la API Bold
+}
+
+checkoutURL := result.Payload.URL
+linkID      := result.Payload.PaymentLink
+```
+
+---
+
+## 5. Polling automático
+
+El sistema verifica pagos pendientes cada **15 minutos** mediante un cron job (`VerificarPagosBoldPendientes`). Esto cubre los casos donde el webhook no llega.
+
+---
+
+## Notas
+
+- `reference` debe ser **única por transacción**. Reutilizarla puede causar conflictos al resolver el pago.
+- El modo activo (`test` / `production`) y las API keys se configuran en la tabla `bold_config`. Solo un registro puede estar activo a la vez.
+- En modo `test` la `secret_key` es cadena vacía según la documentación oficial de Bold.