Skip to content

download endpoints — Overview

This router implements the high-level orchestration for monthly invoice downloads and related utilities. It coordinates Sheets_Manager (to read invoices) and Gmail_Manager (to download attachments) and reports progress over WebSocket via Connection_Manager.

Main routes

  • WebSocket: GET /ws
  • Purpose: keep an open connection to receive progress updates (type: progress, status).

  • Messages received from server: JSON { type: "progress", progress: 42, message: "...", stats: {...} }.

  • Start download: POST /start

  • Body: StartDownloadRequest (JSON) — fields year (int), month (int).
  • Behavior: validates that no download is currently running, resets download_state, then starts download_process(year, month) in a background task using a new SessionLocal() DB session.
  • Response: { "message": "Download process started", "status": "running" }.

  • Notes: the background task uses connection_manager.send_progress_update() callbacks to stream progress updates to connected WebSocket clients.

  • Stop download: POST /stop

  • Behavior: sets connection_manager.download_state["is_running"] = False and sends a status update; returns { "message": "Download process stopped", "status": "stopped" }.

  • Status: GET /status

  • Returns: current download_state with keys is_running, progress, status, message, stats.

  • Download ZIP: GET /zip?month={m}&year={y}&include_shopping_table={bool}&include_platforms={bool}&include_reports={bool}&sort_platforms_in_folders={bool}&sort_reports_in_folders={bool}&batch_shopping_table={bool}&shopping_table_batch_size={n}

  • Streams a ZIP archive of invoice/report files for the selected month.
  • Shopping-Table: invoices/{year}/{month}/
  • Platforms: invoices/{vendor}/{year}/{month}/ (e.g. Hetzner, Sellerlogic, Tesla, …)
  • Reports (optional): reports/{year}/{month}/ (incl. bank_creditcard/) → ZIP Reports/.
  • ZIP layout: Reports/ + Invoices/Shopping-Table/ + Invoices/Platforms/
  • sort_platforms_in_folders (default false): when true, platforms keep Invoices/Platforms/<vendor>/; when false, all platform files are flat under Invoices/Platforms/ (colliding basenames get a {vendor}_ prefix).
  • sort_reports_in_folders (default false): when true, reports keep relative paths under Reports/; when false, all report files are flat under Reports/ (colliding basenames get a parent-folder prefix).
  • batch_shopping_table (default true in UI): when true, shopping-table files go into Invoices/Shopping-Table/1 … N.
  • shopping_table_batch_size (default 300, range 1–10000): files per numbered shopping-table batch folder.

  • Errors: 404 if no matching files are present.

  • Available ZIPs: GET /available_zips

  • Returns per month: shopping_table, platforms breakdown, total_file_count, zip_filename.

  • Manual platform invoices status: GET /platform-invoices/manual?year={y}&month={m}

  • Returns upload status for Tesla, Vodafone, ChatGPT, Urban Sports, Google Workspace.

  • See manual platform invoices.

  • Manual platform invoice upload: POST /platform-invoices/manual/upload?year={y}&month={m}&platform={key}

  • Multipart upload; stores file under invoices/{platform}/{year}/{month}/.

  • Allowed platforms: tesla, vodafone, chatgpt, urbansports, google_workspace.

  • Failed invoices status: GET /failed-invoices?year={y}&month={m}

  • Lists filenames recorded in invoices/{year}/{month}/eval_{year}_{month}.json under submitted_subsequently.

  • Used for invoices that failed automatic Gmail download and were uploaded manually.

  • Failed invoices upload: POST /failed-invoices/upload?year={y}&month={m}

  • Multipart field files (repeatable; folder picker sends many files).
  • Stores under invoices/{year}/{month:02d}/ (same as Shopping-Table downloads).
  • Appends new filenames to eval submitted_subsequently; skips names already listed or already on disk.

  • Does not update Google Sheets confirmation status.

  • Buchhaltung preview: GET /buchhaltung/preview?year={y}&month={m}&datev_link={url}&inventur_net_eur={value}

  • Builds the German accounting email preview and scans reports/{year}/{month:02d}/ and eval/{year}/{month:02d}/.
  • Response includes subject, body, recipient, inventur_date, attachments (with size_bytes), missing_attachments, manual_platform_invoices, missing_manual_platforms, bank_creditcard_reports, missing_bank_creditcard_reports, ready, requires_human_confirmation, and ionos_webmail_url.

  • See buchhaltung service for file naming conventions.

  • Buchhaltung attachments ZIP: GET /buchhaltung/attachments/zip?year={y}&month={m}

  • Returns a ZIP of all report/eval attachments when none are missing.

  • Used for manual upload in Ionos Webmail after human review.

  • Buchhaltung report upload: POST /buchhaltung/reports/upload?year={y}&month={m}&report_type={type}

  • report_type: otto_umsatz, plenty_umsatz, kontoauszuege, shopify_payouts, or shopify_order_transactions.

  • Saves CSV to reports/{year}/{month}/.

  • Bank / credit-card status: GET /buchhaltung/bank-creditcard?year={y}&month={m}

  • Lists all BANK_CREDITCARD_REPORTS with found/missing markers and ready.

  • Bank / credit-card upload: POST /buchhaltung/bank-creditcard/upload?year={y}&month={m}&report_key={key}

  • Multipart field: files (one or more).
  • Bank/credit-card keys store a single replaced file as reports/{year}/{month}/bank_creditcard/{key}.{ext}.
  • Otto fee keys (multi_file) store under reports/{year}/{month}/bank_creditcard/{key}/ and keep multiple filenames (duplicates skipped).
  • Keys: lage_volksbank, lage_sparkasse, kreditkarte_volksbank, paypal, revolut, american_express, otto_payment_fees, otto_financing_fees, otto_vat_receipts, otto_marketplace_fees, otto_service_fees.

  • Not included in email attachments ZIP / n8n payload. Required for ready / review & send (Otto: at least one file per fee type).

  • Buchhaltung send: POST /buchhaltung/send

  • Body: BuchhaltungSendRequest — year, month, optional datev_link, optional inventur_net_eur, confirmed (required, must be true).
  • Validates human confirmation, manual platform invoices, bank/credit-card/Otto fee statements, and all required report/eval files (ready === true), then POSTs to N8N_BUCHHALTUNG_WEBHOOK_URL.

  • Errors: 400 missing confirmation, manual platforms, bank/credit-card statements, or report files; 502 n8n HTTP error; 503 webhook URL not configured.

  • Health: GET /health

  • Returns a small health JSON and number of active WebSocket connections.

Operational details

  • download_process(year, month, db):
  • Steps: authenticate all active Google credentials, for each credential fetch invoices via get_invoices_for_month, filter already-confirmed invoices, download attachments using gmail_manager.download_invoices_async(invoices, progress_callback), write eval_{year}_{month}.json, and bulk-update confirmations in Sheets.
  • Progress: progress is reported in ranges (initialization → sheets retrieval → gmail download → file organization → completion) and sent via Connection_Manager.broadcast().

  • Error handling: exceptions broadcast an error message and set is_running False in download_state.

  • Background DB sessions: a dedicated DB session is created inside the background coroutine and closed when finished to prevent session lifetime issues.

Examples

  • Start a month download (curl):
curl -X POST "http://localhost:8000/api/v1/invoice/start" \
  -H "Content-Type: application/json" \
  -d '{"year":2024, "month":3}'
  • WebSocket message format (progress):
{
  "type": "progress",
  "progress": 55,
  "message": "Gmail download: 120/200 invoices",
  "stats": { "processedEmails": 120, "totalEmails": 200 }
}
  • Manual platform status (curl):
curl "http://localhost:8002/api/v1/invoice/download/platform-invoices/manual?year=2026&month=7" \
  -H "Authorization: Bearer $TOKEN"
  • Buchhaltung preview (curl):
curl "http://localhost:8002/api/v1/invoice/download/buchhaltung/preview?year=2026&month=6" \
  -H "Authorization: Bearer $TOKEN"
  • Buchhaltung send (curl):
curl -X POST "http://localhost:8002/api/v1/invoice/download/buchhaltung/send" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"year":2026,"month":6,"datev_link":"https://datev.example.com","inventur_net_eur":"300,75","confirmed":true}'
  • Buchhaltung attachments ZIP (curl):
curl -o buchhaltung.zip "http://localhost:8002/api/v1/invoice/download/buchhaltung/attachments/zip?year=2026&month=6" \
  -H "Authorization: Bearer $TOKEN"

Frontend (DownloadSubTab.jsx)

Invoice Management → Download Management

Download ZIP Archive

  • Select year/month; optional shopping-table, platform, and month-reports filters
  • Optional Shopping-Table batching into numbered folders (configurable batch size)
  • Manual platform invoices — portal links + upload per platform
  • Review & send accounting email — locked until all manual platform invoices and bank/credit-card/Otto fee statements are uploaded

Accounting dialog

  • Warning: nothing sends until you finish in Ionos or explicitly choose server send
  • Attachment checklist with file sizes, portal links, and CSV upload for Otto/Plenty/bank statements
  • Datev link and inventur net override fields
  • Read-only German email body preview; copy subject/body buttons
  • Checkbox: confirm you reviewed recipient, subject, message, and attachments
  • Download attachments — ZIP for Ionos upload
  • Open Ionos Webmail — primary path; send manually after review
  • Send via email server… — optional; second confirm dialog, then POST /buchhaltung/send with confirmed: true