Documentacion y ejemplo

mariofix · Sep 29, 2024 · b97f95e · b97f95e
1 parent 89d6316
commit b97f95e
Show file tree

Hide file tree

Showing 21 changed files with 414 additions and 118 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # django-payments-chile
 
-**django-payments-chile** es una librería diseñada para facilitar la integración de pagos en aplicaciones Django a través de múltiples proveedores en Chile. Este proyecto ofrece una API simple y flexible para procesar pagos de manera segura, permitiendo a los desarrolladores concentrarse en construir sus aplicaciones sin complicarse con la lógica de integración de cada proveedor.
+`django-payments-chile` es una extensión para `django-payments`, una biblioteca que proporciona una interfaz universal para procesar pagos en aplicaciones Django. Este proyecto añade soporte específico para varios proveedores de pagos chilenos como Flow, Khipu, Webpay, y otros.
 
 ![PyPI - Status](https://img.shields.io/pypi/status/django-payments-chile)
 [![Downloads](https://pepy.tech/badge/django-payments-chile)](https://pepy.tech/project/django-payments-chile)

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -1,44 +1,23 @@
 # Changelog
 
-Cambios notables de Django Payments Flow
+Cambios notables de Django Payments Chile
 
 Formato basado en [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 y este proyecto se adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-## [2024.9.23] - 2024-09-23
+- Klap
+- Kushki
+- Pagofacil
+- Transbank WebPayPlus
+- Transbank OnePay
 
-### Cambiado
+## [2024.9.29]
 
-- Cambios en documentacion.
+- Cambios en Documentacion
+- Nuevos providers para: **Flow, Khipu, Payku**
 
-## [0.1.4] - 2023-07-20
+## [2024.9.23]
 
-### Agregado
-
-- Creacion de reembolso
-
-### Cambiado
-
-- Rollback de soporte openapi3
-
-## [0.1.3] - 2023-07-20
-
-### Agregado
-
-- Creacion de pago
-- Correccion Tests
-
-## [0.1.2] - 2023-07-12
-
-### Agregado
-
-- Algunos tests
-- Trabajo con pyFlowCL
-
-## [0.1.1] - 2023-07-05
-
-### Agregado
-
-- Estructura base
+- Commit Inicial
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -1,6 +1,6 @@
-# Guía de Colaboración para pyflowcl
+# Guía de Colaboración para django-payments-chile
 
-¡Gracias por tu interés en colaborar con pyflowcl! Este documento te guiará a través del proceso de contribución al proyecto.
+¡Gracias por tu interés en colaborar con django-payments-chile! Este documento te guiará a través del proceso de contribución al proyecto.
 
 ## Formas de Colaborar
 
@@ -27,15 +27,15 @@ Puedes clonar el repositorio de dos maneras:
 ### Usando Git
 
 ```shell
-git clone https://github.com/mariofix/pyflowcl.git
-cd pyflowcl
+git clone https://github.com/mariofix/django-payments-chile.git
+cd django-payments-chile
 ```
 
 ### Usando GitHub CLI
 
 ```shell
-gh repo clone mariofix/pyflowcl
-cd pyflowcl
+gh repo clone mariofix/django-payments-chile
+cd django-payments-chile
 ```
 
 ## Configuración del Entorno de Desarrollo
@@ -96,4 +96,4 @@ Al contribuir a este proyecto, aceptas que tus contribuciones se licenciarán ba
 
 Si tienes preguntas o necesitas ayuda, no dudes en crear un issue en GitHub.
 
-¡Gracias por tu contribución a pyflowcl!
+¡Gracias por tu contribución a django-payments-chile!
diff --git a/docs/index.md b/docs/index.md
@@ -1,6 +1,6 @@
 # django-payments-chile
 
-**django-payments-chile** es una extensión de **django-payments** que facilita la integración de proveedores de pago en aplicaciones Django para el mercado chileno. Actualmente soporta Flow, Khipu, Webpay, y más.
+`django-payments-chile` es una extensión para `django-payments`, una biblioteca que proporciona una interfaz universal para procesar pagos en aplicaciones Django. Este proyecto añade soporte específico para varios proveedores de pagos chilenos como Flow, Khipu, Webpay, y otros.
 
 ![PyPI - Status](https://img.shields.io/pypi/status/django-payments-flow)
 [![Downloads](https://pepy.tech/badge/django-payments-flow)](https://pepy.tech/project/django-payments-flow)
@@ -14,18 +14,22 @@
 
 ## Características
 
-- Soporte para múltiples proveedores de pago en Chile.
-- Compatible con la API de django-payments.
-- Extensión fácil de configurar.
+- Soporte para múltiples proveedores de pago en un solo proyecto.
+- API consistente para crear, procesar y verificar transacciones.
+- Fácil configuración y personalización.
+- Documentación clara para desarrolladores.
+- Soporte para eventos de éxito, fallo, y reembolsos de pagos.
 
 ## Inicio rápido
 
 ### Instalación
 
 ```bash
-pip install django-payments-chile[chile]
+pip install django-payments-chile[todos]
 ```
 
+Adicionalmente puedes instalar los extras para cada integrador:
+
 - **flow**: Instala extras para Flow.
 - **khipu**: Instala extras para Khipu.
 - **todos**: Instala todos los extras.
@@ -72,8 +76,6 @@ redirect_url = payment.get_process_url()
 return redirect(redirect_url)
 ```
 
-**Nota**: `django-payments` manejará la redirección al proveedor y la confirmación del estado del pago. Solo necesitas configurar correctamente los proveedores.
-
 Para más detalles sobre el flujo de pago y las respuestas de los proveedores, consulta la sección [configuración](configuration.md).
 
 ## Proveedores soportados

diff --git a/docs/uso.md b/docs/uso.md
@@ -1,53 +1,71 @@
-# ¿Qué es django-payments-chile?
+# Introducción a `django-payments-chile`
 
-`django-payments-chile` es una extensión de Django que te permite procesar pagos en Chile fácilmente. Funciona con `django-payments`, que es una biblioteca más general para manejar pagos en Django.
+`django-payments-chile` es una extensión para `django-payments`, una biblioteca que proporciona una interfaz universal para procesar pagos en aplicaciones Django. Este proyecto añade soporte específico para varios proveedores de pagos chilenos como Flow, Khipu, Webpay, y otros.
 
-## Paso 1: Preparar tu entorno
+Al ser una extensión de `django-payments`, su objetivo es facilitar la integración de múltiples proveedores de pago sin necesidad de que desarrolles un sistema desde cero para cada uno.
 
-Antes de empezar, asegúrate de tener:
+!!! note "TL;DR"
+    Si prefieres ver una implementación de ejemplo y comenzar rápidamente, puedes clonar el [Repositorio de ejemplo](https://github.com/mariofix/django-payments-chile/tree/main/ejemplo):
 
-1. Python instalado en tu computadora.
-2. Django instalado y un proyecto Django creado.
+## Requisitos
 
-Si no tienes Django, puedes instalarlo con:
+Antes de empezar, asegúrate de tener lo siguiente:
 
-```bash
-pip install django
-```
+- **Python** instalado en tu sistema.
+- **Django** para gestionar la aplicación web.
+- **django-payments** como el núcleo para gestionar los pagos.
+- **django-payments-chile** para integrar proveedores de pago en Chile.
 
-Y crear un nuevo proyecto Django con:
+## Instalación
 
-```bash
-django-admin startproject miproyecto
-cd miproyecto
-```
+### Instalación con Poetry
+
+1. Crea un nuevo proyecto y entorno virtual con Poetry:
+
+    ```bash
+    poetry new mi-tienda
+    cd mi-tienda
+    poetry env use python3.10  # Reemplaza con la versión de Python que prefieras
+    ```
 
-## Paso 2: Instalar las bibliotecas necesarias
+2. Instala Django, `django-payments` y `django-payments-chile`:
 
-Ahora, vamos a instalar `django-payments` y `django-payments-chile`:
+    ```bash
+    poetry add django django-payments django-payments-chile
+    poetry install
+    ```
+
+!!! note
+    Al instalar `django-payments-chile`, sus dependencias, como `django-payments` y `django`, se instalarán automáticamente.
+
+## Configuración del Proyecto
+
+### Crear el Proyecto
+
+Inicia un nuevo proyecto de Django y una aplicación para gestionar los pagos:
 
 ```bash
-pip install django-payments django-payments-chile
+poetry run django-admin startproject tienda .
+poetry run django-admin startapp pagos
 ```
 
-## Paso 3: Configurar tu proyecto Django
-
-### 3.1 Modificar settings.py
+### Modificar `settings.py`
 
-Abre el archivo `settings.py` en tu proyecto Django y agrega estas líneas:
+Abre el archivo `settings.py` de tu proyecto y agrega las siguientes configuraciones de `django-payments`:
 
 ```python
 INSTALLED_APPS = [
-    # ... tus otras apps ...
-    "payments",
+    # Otras aplicaciones de tu proyecto...
+    "payments",  # Core de django-payments
+    "pagos",  # Tu app personalizada para manejar pagos
 ]
 
-# Configuración para payments
-PAYMENT_HOST = 'tudominio.cl'  # Cambia esto por tu dominio real
-PAYMENT_USES_SSL = True  # Usa False si no tienes HTTPS
-PAYMENT_MODEL = 'pagos.modelos.Pago'
+# Configuración de django-payments
+PAYMENT_HOST = 'mi-tienda.cl'  # Reemplaza con tu dominio
+PAYMENT_USES_SSL = True  # Usa True si tienes HTTPS, False en caso contrario
+PAYMENT_MODEL = 'pagos.modelos.Pago'  # Modelo personalizado para pagos
 
-# Configuración para django-payments-chile (ejemplo con Flow)
+# Configuración para proveedores chilenos (ejemplo con Flow)
 PAYMENT_VARIANTS = {
     "flow": ("django_payments_chile.FlowProvider", {
         "api_key": "tu_api_key_de_flow",
@@ -56,55 +74,43 @@ PAYMENT_VARIANTS = {
 }
 ```
 
-Nota: Reemplaza 'tudominio.cl', 'tu_api_key_de_flow' y 'tu_api_secret_de_flow' con tus datos reales.
+!!! note
+    Asegúrate de reemplazar `'mi-tienda.cl'`, `'tu_api_key_de_flow'` y `'tu_api_secret_de_flow'` con tus datos reales.
 
-### 3.2 Modificar urls.py
+### Modificar `urls.py`
 
-Abre el archivo `urls.py` principal de tu proyecto y agrega esta línea:
+Incluye las rutas necesarias en el archivo `urls.py` de tu proyecto o aplicación:
 
 ```python
 from django.urls import include, path
 
 urlpatterns = [
-    # ... tus otras URLs ...
+    # Otras rutas...
     path('payments/', include('payments.urls')),
 ]
 ```
 
-## Paso 4: Crear un modelo de pago
+## Creación del Modelo de Pago
 
-Crea un nuevo archivo llamado `modelos.py` en una app de tu proyecto (por ejemplo, en una app llamada 'pagos') y agrega este código:
+Crea el modelo de pago en el archivo `pagos/modelos.py`, que gestionará los pagos y las redirecciones según el éxito o fracaso de los mismos:
 
 ```python
 from django.conf import settings
 from payments.models import BasePayment
 
 class Pago(BasePayment):
     def get_failure_url(self) -> str:
+        # Redirige a esta URL si el pago falla
         return f"https://{settings.PAYMENT_HOST}/payments/{self.pk}/failure"
 
     def get_success_url(self) -> str:
+        # Redirige a esta URL si el pago es exitoso
         return f"https://{settings.PAYMENT_HOST}/payments/{self.pk}/success"
 ```
 
-No olvides crear la app 'pagos' si no existe:
-
-```bash
-python manage.py startapp pagos
-```
-
-Y agrégala a INSTALLED_APPS en settings.py:
-
-```python
-INSTALLED_APPS = [
-    # ... otras apps ...
-    "pagos",
-]
-```
-
-## Paso 5: Usar django-payments-chile en tu vista
+## Implementación en las Vistas
 
-Ahora puedes usar django-payments-chile en tus vistas. Aquí tienes un ejemplo:
+Usa `django-payments` en tus vistas para procesar pagos con los distintos proveedores. Aquí tienes un ejemplo de cómo crear y procesar un pago:
 
 ```python
 from django.shortcuts import redirect
@@ -113,26 +119,21 @@ from payments import get_payment_model
 def crear_pago(request):
     Payment = get_payment_model()
     payment = Payment.objects.create(
-        variant='flow',  # Esto debe coincidir con lo que pusiste en PAYMENT_VARIANTS
+        variant='flow',  # Debe coincidir con el nombre en PAYMENT_VARIANTS
         description="Pago por Orden #123",
         total=10000,  # Monto en centavos (100 pesos)
         currency='CLP',
         billing_first_name='Juan',
         billing_last_name='Pérez',
         billing_email='juan.perez@example.com',
     )
+    # Redirige al usuario a la URL del proveedor de pagos
     return redirect(payment.get_process_url())
 ```
 
-## Paso 6: Crear las páginas de éxito y fracaso
-
-No olvides crear las páginas a las que se redirigirá después del pago (éxito o fracaso). Puedes hacerlo creando nuevas vistas y templates.
-
-## Consejos finales
-
-1. Siempre prueba en un entorno de desarrollo antes de ir a producción.
-2. Mantén seguros tus datos de API (keys, secrets). No los subas a repositorios públicos.
-3. Lee la documentación oficial de django-payments y django-payments-chile para más detalles.
-4. ¡No dudes en pedir ayuda en foros de Django si te atascas!
+## Consejos Finales
 
-Recuerda que cada paso puede requerir más configuración dependiendo de tu proyecto específico.
+- **Pruebas**: Asegúrate de probar la implementación en un entorno de desarrollo antes de desplegarla en producción.
+- **Seguridad**: No subas tus claves de API o secretos a repositorios públicos. Utiliza archivos de entorno o servicios seguros para gestionarlos.
+- **Documentación Adicional**: Consulta la documentación oficial de [django-payments](https://django-payments.readthedocs.io/) para conocer todas las opciones y configuraciones avanzadas.
+- **Soporte**: Si tienes dudas o problemas [haz tu pregunta](https://github.com/mariofix/django-payments-chile/discussions).
diff --git a/ejemplo/README.md b/ejemplo/README.md
@@ -0,0 +1,35 @@
+# Ejemplo para `django-payments-chile`
+
+Este repositorio contiene un ejemplo de cómo utilizar `django-payments-chile`, una extensión de `django-payments` que permite la integración de varios proveedores de pago en Chile.
+
+## Requisitos
+
+- Python 3.10 o superior
+- Poetry (para gestionar dependencias)
+
+## Instalación
+
+Sigue los pasos a continuación para poner en marcha el proyecto de ejemplo:
+
+1. Instala las dependencias utilizando `poetry`:
+
+    ```bash
+    poetry install -E todo
+    ```
+
+2. Aplica las migraciones para preparar la base de datos:
+
+    ```bash
+    poetry run python manage.py makemigrations
+    poetry run python manage.py migrate
+    ```
+
+3. Inicia el servidor de desarrollo:
+
+    ```bash
+    poetry run python manage.py runserver
+    ```
+
+## Configuración adicional
+
+Este proyecto ya incluye configuraciones predeterminadas para un entorno local. Asegúrate de modificar cualquier valor en el archivo `settings.py` si es necesario, como el dominio en `PAYMENT_HOST`, y las credenciales de los proveedores de pago en `PAYMENT_VARIANTS`.