Ejemplo de Sincronización con API Valerdat

Este proyecto es un ejemplo práctico de cómo utilizar la API de Valerdat para sincronizar pedidos de compra con un sistema externo. El script se conecta a la API, obtiene los pedidos nuevos desde la última sincronización, los procesa y los almacena en un sistema local simulado mediante archivos JSON.

💡 Idea Principal

El objetivo es demostrar un flujo de trabajo común para la integración de sistemas:

1. Autenticación: Obtener un token de acceso para realizar peticiones seguras.
2. Consulta de Novedades: Preguntar a la API de Valerdat si hay pedidos nuevos o actualizados desde la última vez que se comprobó.
3. Obtención de Detalles: Recuperar la información completa de esos nuevos pedidos.
4. Sincronización Local: Comparar los datos recibidos con los que ya existen en el sistema local y decidir si se debe añadir un nuevo registro o actualizar uno existente.
5. Persistencia: Guardar el estado de la sincronización para saber qué pedidos ya se han procesado.

✨ Características

• Autenticación segura: Gestión de tokens para el acceso a la API.
• Sincronización incremental: Solo se procesan los pedidos nuevos desde la última ejecución, optimizando el rendimiento.
• Manejo de datos: Conversión de los datos JSON de la API a objetos tipados en Python (dataclasses) para un manejo más robusto y claro.
• Lógica de negocio: Implementa una lógica para añadir nuevos pedidos o reemplazar datos si un pedido se actualiza.
• Registro de actividad: Todas las operaciones importantes (adición, reemplazo, falta de novedades) se registran en el archivo sync_valerdat.log.
• Ejecución continua: El script se ejecuta en un bucle infinito para mantener la sincronización en tiempo real.

🛠️ Prerrequisitos

• Python 3.7 o superior.
• La librería requests para realizar las peticiones HTTP.

⚙️ Instalación y Configuración

1. Instalar dependencias:

   pip install requests

2. Crear archivos de datos locales: En la raíz del proyecto, crea los siguientes dos archivos JSON. Estos simulan la base de datos de tu sistema.

   • orders.json: Almacenará la información detallada de los pedidos sincronizados.

     {
         "orders": []
     }

   • uuid.json: Guardará los identificadores (UUID) de los pedidos ya procesados y la fecha de la última sincronización.

     {
         "uuid": [],
         "last_update": null
     }

     Nota: Puedes establecer una fecha de inicio en last_update (formato "YYYY-MM-DD") para que el script comience a buscar pedidos a partir de ese día. Si es null, comenzará desde el día actual.

▶️ Uso

Para iniciar el proceso de sincronización, simplemente ejecuta el archivo main.py:

python main.py

El script comenzará a ejecutarse en un bucle infinito, comprobando si hay nuevos pedidos cada 10 segundos. Toda la actividad relevante se registrará en el archivo sync_valerdat.log.

⚠️ Importante: Las credenciales de acceso (customer, username, password) están directamente en el código de main.py por simplicidad. En un entorno de producción, es fundamental gestionarlas de forma segura, por ejemplo, utilizando variables de entorno.

📝 Archivo de Log (sync_valerdat.log)

Este archivo es crucial para monitorizar el comportamiento del script. Cada línea en el log representa un evento importante y sigue un formato estándar:

YYYY-MM-DD HH:MM:SS,ms - LEVEL - Mensaje

• INFO: [INFO] No new orders to add in local system: Se ejecutó la comprobación, pero no se encontraron pedidos nuevos.
• INFO: [+] Adding new order to local system: Se ha detectado un nuevo pedido y se ha añadido al sistema local (orders.json).
• INFO: [*] Replacing order in local system: Se ha detectado una actualización en un pedido existente y se ha reemplazado en el sistema local.

Revisar este archivo es la mejor manera de verificar que la sincronización está funcionando como se espera.

📖 Explicación del Código

• main.py: Es el punto de entrada. Inicia el logging, crea una instancia de SyncOrders y ejecuta el proceso de sincronización periódicamente.
• sync_orders.py: Contiene la clase SyncOrders, que orquesta toda la lógica de sincronización. Lee el estado local (uuid.json), consulta la API para obtener novedades y decide cómo actualizar los datos locales (orders.json).
• api_valerdat.py: Se encarga de toda la comunicación con la API de Valerdat. Contiene la clase ApiValerdat que gestiona la autenticación y define los métodos para obtener los IDs de los pedidos (get_orders_ids) y los detalles de un pedido (get_order).
• dto.py: Define las clases de transferencia de datos (dataclasses) como OrderIdsResponseDto y OrderResponseDto. Esto permite trabajar con objetos estructurados y tipados en lugar de diccionarios genéricos, lo que hace el código más legible y menos propenso a errores.