Skip to content

README.en.md

Latest commit

 

History

History
84 lines (59 loc) · 4.49 KB

README.en.md

File metadata and controls

84 lines (59 loc) · 4.49 KB

Valerdat API Sync Example

This project is a practical example of how to use the Valerdat API to synchronize purchase orders with an external system. The script connects to the API, fetches new orders since the last sync, processes them, and stores them in a local system simulated with JSON files.

💡 Core Idea

The goal is to demonstrate a common workflow for system integration:

  1. Authentication: Obtain an access token to make secure requests.
  2. Check for Updates: Query the Valerdat API for new or updated orders since the last check.
  3. Fetch Details: Retrieve the complete information for those new orders.
  4. Local Sync: Compare the received data with the data that already exists in the local system and decide whether to add a new record or update an existing one.
  5. Persistence: Save the synchronization state to keep track of which orders have already been processed.

✨ Features

  • Secure Authentication: Token management for API access.
  • Incremental Sync: Only processes new orders from the last run, optimizing performance.
  • Data Handling: Converts JSON data from the API into typed Python objects (dataclasses) for more robust and clear handling.
  • Business Logic: Implements logic to add new orders or replace data if an order is updated.
  • Activity Logging: All important operations (add, replace, no new orders) are logged in the sync_valerdat.log file.
  • Continuous Execution: The script runs in an infinite loop to maintain real-time synchronization.

🛠️ Prerequisites

  • Python 3.7 or higher.
  • The requests library for making HTTP requests.

⚙️ Installation and Setup

  1. Install dependencies:

    pip install requests

  2. Create local data files: In the project root, create the following two JSON files. These simulate your system's database.

    • orders.json: Will store the detailed information of the synchronized orders.

      {
    "orders": []
}

    • uuid.json: Will save the identifiers (UUIDs) of the already processed orders and the date of the last synchronization.

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

      Note: You can set a start date in last_update (format "YYYY-MM-DD") for the script to start fetching orders from that day. If it is null, it will start from the current day.

▶️ Usage

To start the synchronization process, simply run the main.py file:

python main.py

The script will start running in an infinite loop, checking for new orders every 10 seconds. All relevant activity will be logged in the sync_valerdat.log file.

⚠️ Important: The access credentials (customer, username, password) are hardcoded in main.py for simplicity. In a production environment, it is crucial to manage them securely, for example, using environment variables.

📝 Log File (sync_valerdat.log)

This file is crucial for monitoring the script's behavior. Each line in the log represents an important event and follows a standard format:

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

  • INFO: [INFO] No new orders to add in local system: The check was performed, but no new orders were found.
  • INFO: [+] Adding new order to local system: A new order has been detected and added to the local system (orders.json).
  • INFO: [*] Replacing order in local system: An update has been detected in an existing order, and it has been replaced in the local system.

Reviewing this file is the best way to verify that the synchronization is working as expected.

📖 Code Explanation

  • main.py: The entry point. It initializes logging, creates an instance of SyncOrders, and runs the synchronization process periodically.
  • sync_orders.py: Contains the SyncOrders class, which orchestrates all the synchronization logic. It reads the local state (uuid.json), queries the API for updates, and decides how to update the local data (orders.json).
  • api_valerdat.py: Handles all communication with the Valerdat API. It contains the ApiValerdat class that manages authentication and defines methods to get order IDs (get_orders_ids) and order details (get_order).
  • dto.py: Defines the data transfer objects (dataclasses) like OrderIdsResponseDto and OrderResponseDto. This allows working with structured and typed objects instead of generic dictionaries, making the code more readable and less error-prone.