cashea-web-checkout-sdk/README.md

SDK para integrar pagos con Cashea

# Cashea Web Checkout SDK 🛒
🔹 SDK para integrar Web Checkout mediante clase configurable.


## 📌 Instalación
Puedes instalar el SDK mediante npm:

```
npm install cashea-web-checkout-sdk
```
O importar directamente en un archivo HTML:

```
<script src="dist/bundle.js"></script>
```
## 🚀 Cómo Usarlo
### 1️⃣ Instanciar el SDK
Debes configurar la API key al instanciar el SDK:

```javascript
import CheckoutSDK from "cashea-web-checkout-sdk";

const sdk = new CheckoutSDK({
  apiKey: 'TU_API_KEY',
});
```

### 2️⃣ Configuración del Payload - Creación de orden

```
const payload = {
  deliveryMethod: 'IN_STORE',
  redirectUrl: 'https://mi-sitio.com/retorno',
  merchantName: 'Mi Comercio',
  orders: [
    {
      store: {
        id: 123,
        name: 'Mi Tienda',
        enabled: true,
      },
      products: [
        {
          id: 'prod-001',
          name: 'Producto A',
          price: 50,
          quantity: 2,
          sku: "SKU-123",
          description: "descripcion",
          imageUrl: "https://mi-sitio.com/imagen.jpg",
          tax: 0,
          discount: 0,
        },
      ],
    },
  ],
  identificationNumber: '123456789',
  invoiceId: 'inv-001',
  externalClientId: '351',
  deliveryPrice: 0,
};
```

### Campos del Payload

* **deliveryMethod** (Cadena de texto)
   - **Descripción**: Método de entrega de la orden.
   - **Valores posibles**: 'IN_STORE', 'DELIVERY'
   - **Ejemplo**: 'IN_STORE'
   - **Requerido**: Sí

* **identificationNumber** (Cadena de texto)
   - **Descripción**: Número de identificación del cliente.
   - **Ejemplo**: '123456789'
   - **Requerido**: Sí

* **orders** (Arreglo de objetos)
   - **Descripción**: Lista de órdenes de compra.
   - **Requerido**: Sí
   - **Campos del objeto**:
     - **storeId** (Número)
       - **Descripción**: ID de la tienda.
       - **Ejemplo**: 123
       - **Requerido**: Sí
     - **products** (Arreglo de objetos)
       - **Descripción**: Lista de productos en la orden.
       - **Requerido**: Sí
       - **Campos del objeto**:
         - **storeId** (Número)
           - **Descripción**: ID de la tienda.
           - **Ejemplo**: 123
           - **Requerido**: Sí
         - **enabled** (Booleano)
           - **Descripción**: Indica si el producto está habilitado.
           - **Ejemplo**: true
           - **Requerido**: Sí
         - **name** (Cadena de texto)
           - **Descripción**: Nombre del producto.
           - **Ejemplo**: 'Producto A'
           - **Requerido**: Sí
         - **sku** (Cadena de texto)
           - **Descripción**: SKU del producto.
           - **Ejemplo**: 'SKU123'
           - **Requerido**: Sí
         - **description** (Cadena de texto)
           - **Descripción**: Descripción del producto.
           - **Ejemplo**: 'Descripción del producto'
           - **Requerido**: Sí
         - **imageUrl** (Cadena de texto)
           - **Descripción**: URL de la imagen del producto.
           - **Ejemplo**: 'https://mi-sitio.com/imagen.jpg'
           - **Requerido**: Sí
         - **quantity** (Número)
           - **Descripción**: Cantidad del producto.
           - **Ejemplo**: 2
           - **Requerido**: Sí
         - **price** (Número)
           - **Descripción**: Precio del producto.
           - **Ejemplo**: 50
           - **Requerido**: Sí
         - **tax** (Número)
           - **Descripción**: Impuesto del producto.
           - **Ejemplo**: 10
           - **Requerido**: Sí
         - **discount** (Número)
           - **Descripción**: Descuento del producto.
           - **Ejemplo**: 5
           - **Requerido**: Sí

* **installmentPlanId** (Número)
   - **Descripción**: ID del plan de cuotas.
   - **Ejemplo**: 1
   - **Requerido**: No (valor por defecto: 1)

* **invoiceId** (Cadena de texto)
   - **Descripción**: ID de la factura asociada a la orden.
   - **Ejemplo**: 'inv-001'
   - **Requerido**: No (opcional)

* **externalClientId** (Cadena de texto)
   - **Descripción**: ID del cliente externo.
   - **Ejemplo**: '351'
   - **Requerido**: Sí

* **deliveryPrice** (Número)
   - **Descripción**: Precio del envío de la orden.
   - **Ejemplo**: 0
   - **Requerido**: No (opcional)

### 3️⃣ Agregar un Botón de Pago
El SDK permite crear un botón de pago que dirige al usuario al flujo de Web Checkout.

```
const container = document.getElementById("checkout-container");

sdk.createCheckoutButton({
  payload: payload,
  container: container,
});
```
  🔹 payload: Información de la orden.
  
  🔹 container: Elemento HTML donde se insertará el botón.

## 🔄 Confirmación y Cancelación de Órdenes
Una vez que el usuario complete el pago, será redirigido a la URL especificada en `redirectUrl` con un **idNumber**.

#### 📌 Ejemplo de Redirección
```
https://mi-sitio.com/retorno?idNumber=12345
```
🔹 El **idNumber** se usa para **confirmar o cancelar** la orden.


## 📝 Preguntas Frecuentes (FAQ)

#### ❓ ¿Cómo obtengo un API Key?
Debes solicitarlo al equipo de integración de Cashea.

#### ❓ ¿Cómo actualizo el SDK?
Simplemente corre:
```
npm update web-checkout-sdk
```

## 📌 Contribuciones y Soporte
Si encuentras un problema o quieres contribuir, puedes hacer un pull request en nuestro repositorio de GitHub:

🔗 [Repositorio en GitHub](https://github.com/The-Flock/Cashea).

Para soporte, puedes escribir a: soporte@cashea.com

## 📝 Licencia
Este SDK está licenciado bajo la **MIT License**.

## 🎉 ¡Listo! Ahora puedes integrar Web Checkout en minutos. 🚀

🔹 Si tienes dudas, revisa nuestra documentación o contáctanos.

🔹 ¡Gracias por usar Web Checkout SDK! 😊