This directory contains Python scripts designed to integrate with the SuperOffice CRM API, primarily for data extraction and analysis related to sales and customer product information.

Authentication

Authentication is handled via the AuthHandler class, which uses a refresh token flow to obtain access tokens. Ensure that the .env file in the project root is correctly configured with SO_CLIENT_ID, SO_CLIENT_SECRET, SO_REFRESH_TOKEN, SO_REDIRECT_URI, SO_ENVIRONMENT, and SO_CONTEXT_IDENTIFIER.

Key SuperOffice Entities and Data Model Observations

During the development of reporting functionalities, the following observations were made regarding the SuperOffice data model:

1. Sale Entity

Primary Source for Product Information: Contrary to initial expectations, product information is frequently stored as free-text within the Heading field of the Sale object (e.g., "2xOmnie CD-01 mit Nachlass"). This appears to be a common practice in the system, rather than utilizing structured product catalog items linked via quotes.
Contact Association: A significant number of Sale objects (Sale?$filter=Contact ne null) are not directly linked to a Contact object (Contact: null), making it challenging to attribute sales to specific customers programmatically. Our reporting scripts specifically filter for sales where a Contact is present.
No Direct Quote/QuoteLine Linkage: Attempts to retrieve Quote or QuoteLine objects directly via Sale/{saleId}/Quotes, Contact/{contactId}/Quotes, or Sale/{saleId}/Activities resulted in 500 Internal Server Errors or empty result sets. This indicates that direct, API-accessible linkages between Sales and structured QuoteLines are often absent or not exposed via these endpoints.

2. Product Information Storage (Hypothesis & Workaround)

Free-Text in Heading: The primary source for identifying products associated with a sale is the Heading field of the Sale entity itself. This field often contains product codes, descriptions, and other relevant details as free-text.
User-Defined Fields (UDFs): While UserDefinedFields were inspected for structured product data (e.g., RR-02-017-OMNIE), no such patterns were found in the sale_id=342243 example. This suggests that UDFs are either not consistently used for product codes or are named in a way that doesn't align with common product terminology.

Scripts

`list_products.py`

Purpose: Fetches and displays a list of all defined product families from the SuperOffice product catalog (/List/ProductFamily/Items).
Usage: python3 list_products.py

`generate_customer_product_report.py`

Purpose: Generates a CSV report of customer sales, extracting product information from the Sale.Heading field using keyword matching.
Methodology:
1. Retrieves the latest SALE_LIMIT (e.g., 1000) Sale objects, filtering only those with an associated Contact ($filter=Contact ne null).
2. Extracts SaleId, CustomerName, and SaleHeading for each relevant sale.
3. Searches the SaleHeading for predefined PRODUCT_KEYWORDS (e.g., OMNIE, CD-01, Service).
4. Outputs the results to product_report.csv.
Usage: python3 generate_customer_product_report.py

Future Work

Analyse der leeren product_report.csv: Untersuchen, warum die product_report.csv auch nach der Filterung nach Sale-Objekten mit Contact-Verknüpfung leer bleibt. Es ist entscheidend zu verstehen, ob es keine solchen Verkäufe gibt oder ob ein Problem mit der Datenabfrage oder -verarbeitung vorliegt.
Manuelle Inspektion gefilterter Sale-Objekte: Wenn der Report leer ist, müssen wir einige Sale-Objekte, die die Bedingung Contact ne null erfüllen, manuell inspizieren, um ihre Struktur zu verstehen und festzustellen, ob das Heading-Feld oder andere Felder Produktinformationen enthalten.
Verfeinerung der PRODUCT_KEYWORDS: Die Liste der Produkt-Schlüsselwörter muss möglicherweise erweitert werden, basierend auf einer detaillierteren manuellen Analyse der Verkaufsüberschriften.
Erforschung alternativer API-Pfade: Falls der aktuelle Ansatz weiterhin Schwierigkeiten bereitet, müssen wir tiefer in die SuperOffice-API eintauchen, um strukturierte Produktdaten zu finden, auch wenn sie nicht direkt mit den Verkäufen verknüpft sind.