Skip to content

gmail_utils endpoints — Utilities & analysis

Utility endpoints for PDF analysis, bulk searches, CSV/XLSX reports, and special-purpose helpers used during invoice recovery and evaluation.

Major routes (high-level)

  • POST /analyze-pdfs-folder/{year}
  • Analyze all PDFs in invoices/rechnungen-{year}/{year} and create combined CSV/XLSX reports.

  • Returns processing statistics and paths to generated csv / xlsx outputs.

  • POST /analyze-pdfs-custom-folder

  • Same as above but for an arbitrary folder_path supplied in the request body.

  • POST /test/debug (number, query)

  • Quick utility to test a Gmail search and return email body / metadata for a single invoice number.

  • POST /rechnungskorrektur/ (file upload CSV)

  • Checks invoice numbers from an uploaded CSV for "Rechnungskorrektur" emails and returns an Excel (.xlsx) report.

  • POST /numbers/by/label (label_name)

  • Scans all emails under a specified Gmail label (with pagination) and extracts invoice/order numbers using multiple regex heuristics.

  • Returns extracted numbers and a CSV file path when available.

  • GET /eval/invoice-without-email

  • Walks Invoice_Without_Email folders, inspects metadata.json files and associated files, and returns an XLSX evaluation file summarizing which items have email, parfumdreams, and combined PDFs.

  • POST /fix/metadata-emails

  • Normalize from and to fields inside metadata.json files under Invoice_Without_Email (extracts email addresses from complex structures).

  • POST /check/for/Rechnung (CSV upload)

  • For each invoice number in CSV, searches Gmail and returns an Excel file indicating whether "Ihre Bestellung ist auf dem Weg", confirmations, or Rechnungskorrektur were found.

  • POST /download/Rechnungskorrektur (CSV upload)

  • Searches Gmail for "{invoice_number} Rechnungskorrektur" and downloads attachments into a Rechnungskorrekturen/Download_{timestamp} folder. Returns summary JSON and a generated Excel report path.

  • POST /invoice/by/mail (CSV upload)

  • For each invoice number: searches Gmail, saves full email HTML, renders PDF (WeasyPrint/pdfkit/imgkit/Playwright fallback), attempts to fetch Parfumdreams PDF via Parfumdreams_Manager, and writes metadata.json + merged PDFs into Invoice_Without_Email/{invoice}.

  • Returns a JSON summary per invoice.

  • POST /invoice/check-parfumdreams-cancelled (CSV upload)

  • Reads local email.html files for invoice numbers and checks Parfumdreams order cancellation via Parfumdreams_Manager.check_canceled.

PDF extraction helpers (internal / referenced)

  • process_downloaded_pdfs(files) and process_downloaded_pdfs_chunked(files, chunk_size=...)

  • Extract invoice numbers, dates, addresses and amounts using PyPDF2 + regex; returns extracted_data, successful_files, failed_files, and paths to csv / xlsx outputs.

  • extract_pdf_metadata(file_path)

  • Attempts to identify invoice vs correction documents and normalize German number formats (e.g. 1.234,56 → 1234.56). Returns dict with keys: Rechnungsnummer, Datum, Rechnungsart, Anschrift, 19%, Nettobetrag, Rechnungsbetrag, Währung, Dateiname.

Operational notes

  • These utilities are I/O and CPU intensive when processing many PDFs; prefer the chunked processing endpoints and run during off-peak times.
  • Several endpoints return XLSX files created with openpyxl and apply formatting; the service writes temporary files to the system temp directory.
  • Regex heuristics are intentionally permissive; review invoice_patterns and exclude_patterns in source if false-positives occur for particular vendors.

Example: extract invoice numbers from a label (curl):

curl -X POST "http://localhost:8000/api/v1/invoice/numbers/by/label" \
  -H "Content-Type: application/json" \
  -d '{"label_name":"INVOICES-2024"}'