# Integración de Pagopar - Guía de Configuración

## 📋 Resumen
Esta guía te ayudará a integrar la pasarela de pago Pagopar en tu sistema de e-commerce.

---

## 🔑 Datos que necesitas solicitar a Pagopar

Para que la integración funcione, debes obtener las siguientes credenciales desde tu cuenta de **Pagopar.com**:

### 1. Accede a tu cuenta de Pagopar
- Ingresa a [https://www.pagopar.com](https://www.pagopar.com)
- Inicia sesión con tus credenciales

### 2. Obtén las credenciales API
- Ve a la sección **"Integrar con mi sitio web"** o **"API"**
- Encontrarás dos claves:
  
  **a) Public Key (Clave Pública)**
  ```
  Ejemplo: 63820974a40fe7c5c5c53c429af8b25bed599dbf
  ```
  
  **b) Private Key (Token Privado)**
  ```
  Ejemplo: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
  ```

### 3. Solicita acceso a entorno de desarrollo (opcional)
- Si quieres probar antes de ir a producción, solicita credenciales de desarrollo
- Pagopar te proporcionará credenciales separadas para pruebas

---

## ⚙️ Configuración del Sistema

### Paso 1: Configurar credenciales

Edita el archivo **`pagopar_config.php`** y reemplaza los valores:

```php
// IMPORTANTE: Solo necesitas cambiar estos dos valores
'public_key' => 'TU_PUBLIC_KEY_AQUI',   // ← Pega aquí tu Public Key
'private_key' => 'TU_PRIVATE_KEY_AQUI', // ← Pega aquí tu Private Key
```

**✅ Las URLs se generan automáticamente** - El sistema ahora detecta dinámicamente:
- Tu dominio
- El subdirectorio donde está instalado (`/shop` en tu caso)
- El protocolo (HTTP/HTTPS)

Así que las URLs del webhook y retorno se crean automáticamente como:
- `https://oietema.com/shop/webhook_pagopar.php`
- `https://oietema.com/shop/resultado_pago_pagopar.php`

### Paso 2: Crear la tabla en la base de datos

Ejecuta el script SQL ubicado en `sql/crear_tabla_pedidos_pagopar.sql`:

```bash
# Opción 1: Desde phpMyAdmin
# - Abre phpMyAdmin
# - Selecciona tu base de datos
# - Ve a la pestaña "SQL"
# - Copia y pega el contenido del archivo
# - Haz clic en "Continuar"

# Opción 2: Desde la línea de comandos
mysql -u tu_usuario -p tu_base_de_datos < sql/crear_tabla_pedidos_pagopar.sql
```

### Paso 3: Configurar URLs en Pagopar

En tu panel de Pagopar, debes configurar las siguientes URLs:

1. **URL de Notificación (Webhook)**
   ```
   https://oietema.com/shop/webhook_pagopar.php
   ```
   Esta URL será llamada por Pagopar cuando se realice un pago.

2. **URL de Retorno**
   ```
   https://oietema.com/shop/resultado_pago_pagopar.php
   ```
   
   *✅ Estas URLs se generan automáticamente según tu configuración*
   A esta URL se redirigirá al usuario después del pago.

### Paso 4: Verificar permisos de archivos

Asegúrate de que los archivos PHP tengan los permisos correctos:

```bash
chmod 644 *.php
chmod 755 .
```

---

## 🎯 Archivos creados

### Archivos principales:

1. **`pagopar_config.php`**
   - Archivo de configuración con credenciales y parámetros

2. **`iniciar_pago_pagopar.php`**
   - Inicia la transacción con Pagopar
   - Envía los datos del pedido a la API
   - Redirige al usuario al checkout de Pagopar

3. **`webhook_pagopar.php`**
   - Recibe las notificaciones de Pagopar sobre el estado del pago
   - Actualiza el estado del pedido en la base de datos

4. **`resultado_pago_pagopar.php`**
   - Muestra el resultado del pago al usuario
   - Página a la que regresa el cliente después de pagar

5. **`form_datos_comprador.php`**
   - Formulario para capturar datos del comprador
   - Se muestra antes de redirigir a Pagopar

6. **`carrito.php`** (modificado)
   - Ahora incluye el botón "Pagar con Pagopar"

### Archivos SQL:

7. **`sql/crear_tabla_pedidos_pagopar.sql`**
   - Script para crear la tabla en la base de datos

---

## 🚀 Flujo de Pago

```
1. Usuario en carrito.php
   ↓
2. Click en "Pagar con Pagopar"
   ↓
3. form_datos_comprador.php (si no hay datos del cliente)
   ↓
4. iniciar_pago_pagopar.php
   - Crea pedido en Pagopar
   - Obtiene hash del pedido
   - Guarda en base de datos
   ↓
5. Redirección a Pagopar
   - Usuario realiza el pago
   ↓
6. Pagopar notifica → webhook_pagopar.php
   - Actualiza estado del pedido
   ↓
7. Pagopar redirige → resultado_pago_pagopar.php
   - Usuario ve resultado del pago
```

---

## 🧪 Pruebas

### Modo Desarrollo

1. Configura `'environment' => 'desarrollo'` en `pagopar_config.php`
2. Usa las credenciales de desarrollo proporcionadas por Pagopar
3. Realiza pagos de prueba

### Datos de prueba (proporcionados por Pagopar)
- Pagopar te proporcionará tarjetas de prueba
- Consulta su documentación para números de tarjeta de prueba

---

## ✅ Lista de verificación antes de producción

- [ ] Credenciales de producción configuradas en `pagopar_config.php`
- [ ] `'environment'` cambiado a `'produccion'`
- [ ] URLs de webhook y retorno configuradas en panel de Pagopar
- [ ] Tabla `pedidos_pagopar` creada en la base de datos
- [ ] Pruebas realizadas en ambiente de desarrollo
- [ ] SSL/HTTPS activo en tu dominio
- [ ] Permisos de archivos correctos
- [ ] Logs de errores configurados (revisar `error_log`)

---

## 🔧 Solución de Problemas

### Error: "Token no coincide"
- Verifica que tu `private_key` sea correcta
- Asegúrate de usar el monto correcto (entero, sin decimales)
- Revisa que el `id_pedido_comercio` sea único

### Error: No se crea el pedido en Pagopar
- Verifica que `curl` esté habilitado en PHP
- Revisa los logs: `tail -f debug.log`
- Verifica que los datos del comprador estén completos

### El webhook no se ejecuta
- Verifica que la URL sea accesible públicamente
- Comprueba que no haya restricciones de firewall
- Revisa los logs del servidor

### El pago se realiza pero no se actualiza en la base de datos
- Revisa el archivo `webhook_pagopar.php`
- Verifica los logs: `error_log()`
- Comprueba que la estructura de datos de Pagopar coincida

---

## 📞 Soporte

### Documentación oficial de Pagopar
- [https://docs.pagopar.com](https://docs.pagopar.com)

### Contacto con Pagopar
- Soporte técnico: soporte@pagopar.com
- Panel de control: [https://www.pagopar.com](https://www.pagopar.com)

### Logs del sistema
```bash
# Ver logs de errores
tail -f debug.log

# Ver logs de PHP
tail -f /var/log/apache2/error.log  # Apache
tail -f /var/log/nginx/error.log    # Nginx
```

---

## 📝 Notas adicionales

### Formas de pago disponibles
El parámetro `'forma_pago' => 9` permite todos los medios de pago. Otros valores:
- 1: Tarjeta de crédito
- 2: Tarjeta de débito
- 3: Billetera electrónica
- 9: Todos los medios (recomendado)

### Moneda
Actualmente la integración está configurada para **Guaraníes (PYG)**.

Si necesitas cobrar en **dólares**, debes:
1. Cambiar el endpoint a: `iniciar-transaccion-divisa`
2. Ajustar el código en `iniciar_pago_pagopar.php`

### Validación de pagos duplicados
El sistema usa `id_pedido_comercio` único para evitar duplicados.
El formato es: `PED-{timestamp}-{random}`

---

## 🎉 ¡Listo!

Tu sistema ahora está configurado para recibir pagos con Pagopar.

**Recuerda:**
- Siempre prueba en desarrollo antes de producción
- Mantén tus credenciales seguras
- Revisa los logs regularmente
- Haz respaldos de la base de datos

---

**Fecha de creación:** Octubre 2025  
**Versión:** 1.0
