Integración Shopify → SAP Business One (snobbycl y on-chile)

Pipeline de integración de órdenes de Shopify a SAP Service Layer:
Invoice de reserva, pago con tarjeta o transferencia por transacción,
solicitud de traslado, traslado de stock y entrega.

- Invoice igual a lo cobrado; fulfillments limitados a lo facturado
- Estados terminales integrated, timeout, ignored y cancelled
- Idempotencia contra SAP: adopta documentos existentes en vez de duplicar
- Reintentos de red en el cliente de Shopify
- Secretos fuera de los JSON de tienda (${VARIABLE} resuelta desde .env)
- Herramientas de consulta, integración puntual y carga de pruebas
- Documentación en docs/ (flujo, casos especiales, mapeo, configuración)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

README.md

@@ -0,0 +1,52 @@
+# Integración Shopify → SAP Business One
+
+Descarga órdenes de tiendas Shopify y crea en SAP Business One (Service Layer) los documentos de venta:
+Invoice (reserva), pago con tarjeta o transferencia, solicitud de traslado (ITR) y, si se despacha desde una
+tienda física, traslado de stock y entrega. Una tienda = un archivo en `config/stores/`.
+Tiendas actuales: `snobbycl` y `on-chile-distributor-prod`.
+
+## Puesta en marcha
+
+```bash
+python -m venv .venv && .venv/bin/pip install -r requirements.txt
+cp .env.example .env        # completar tokens y contraseñas de cada tienda
+```
+
+1. Copiar `config/stores/_example.json` a `config/stores/<tienda>.json` y completarlo
+   (`docs/configuracion_tienda.md`). Los secretos van como `${VARIABLE}` y su valor en `.env`.
+2. Ejecutar el scheduler: `.venv/bin/python main.py` (ventanas y frecuencia en `scheduler.json`; una sola
+   instancia a la vez, con lock).
+
+Variables opcionales: `LOG_LEVEL`, `APP_TIMEZONE` (zona para mostrar horas, ej. `America/Santiago`).
+
+## Cómo funciona (resumen)
+
+1. Cada ciclo baja cabeceras nuevas (desde `max(id en BD, initial_since_id)`) a SQLite (`data/shopify_sap.db`).
+2. Toma las órdenes no terminales, trae el detalle y las transacciones de pago, y crea los documentos en SAP.
+   Retoma donde quedó si un documento falló, y adopta documentos que ya existan en SAP para no duplicar.
+3. Estados: `pending`, `not_eligible`, `in_progress`, `error` (se reintentan) e `integrated`, `timeout`,
+   `ignored`, `cancelled` (terminales).
+
+## Herramientas (`tools/`, ejecutar con `.venv/bin/python -m tools.<nombre>`)
+
+| Herramienta | Uso |
+|---|---|
+| `consultar` | `resumen`, `descargadas`, `integradas`, `errores`, `orden --name "#8064"` (solo lectura) |
+| `integrar_ordenes` | dry-run o integración (`--apply`) de órdenes puntuales |
+| `probar_pago` | payload del pago sobre la Invoice real |
+| `descargar_ordenes_especiales` | guarda en `download/` el JSON de los casos especiales |
+| `cargar_items_faltantes`, `entrada_mercancia_ordenes` | artículos y stock para pruebas |
+
+Las herramientas que escriben en SAP son dry-run por defecto y requieren `--apply`.
+
+## Documentación (`docs/`)
+
+| Documento | Contenido |
+|---|---|
+| `flujo_pipeline.md` | flujo caso por caso y reglas vigentes |
+| `casos_especiales.md` | casos fuera del flujo normal, con órdenes de ejemplo de cada tienda |
+| `mapeo_campos.md` | campos de Shopify → SAP por documento |
+| `configuracion_tienda.md` | guía del archivo de cada tienda, `payment_methods` y secretos |
+| `esquema_base_datos.md` | tablas y estados de SQLite |
+| `pendientes.md` | roadmap, decisiones abiertas y pruebas pendientes |
+| `analisis_tiempos.md` | capacidad y tiempos por orden |