01.05.API Features

01.05. API Features

This document outlines the core features and functionalities of the bnc-cpt-api project.

Core Backend Features

FastAPI Framework: High-performance asynchronous API implementation.
JWT Authentication: Secure user authentication using JSON Web Tokens with support for both OAuth2 form and JSON variants.
Role-Based Access Control: Secure dependencies for managing authenticated vs. optional user access.
Rate Limiting: Protects endpoints (Payments, Webhooks, PDF generation, Tesla OAuth/API) from abuse.
Health Monitoring: Dedicated endpoints for service health checks.
Redis Session Storage: (New) Persistent session management via GCP Memorystore, enabling horizontal scalability and session durability across deployments.

Payment Integration

Strategy Pattern Architecture: Pluggable provider system (Stripe, PayPal currently implemented).
Payment Lifecycle Management: Creation of payment intents, verification of status, and webhook handling.
Automated Receipting: Generation of receipt PDFs upon successful payment using WeasyPrint.
Server-Side Plan Validation: Secure validation of payment plans (Basic, Pro, Bulk).

Tesla Fleet API Integration

OAuth 2.0 Flow: Full implementation of Tesla's 3-legged OAuth flow, including browser-based callback handling.
API Proxy Layer: Secure proxying of requests to Tesla Fleet API for:
Vehicle listing and detailed vehicle data.
Service history and status.
Recent alerts and diagnostic information.
Charging history and invoice downloads.
Warranty details.
Tesla Public Key Endpoint: Hosts the required public key for Tesla Fleet API integration.

Charging Invoice Downloads

Per-Vehicle Invoice ZIP: GET /session/{id}/vehicles/{vin}/charging-invoices.zip streams a ZIP of invoice PDFs for one vehicle.
Session-Level Invoice ZIP: GET /session/{id}/charging-invoices.zip aggregates invoices from ALL vehicles in a session into a single ZIP, organized in per-vehicle subfolders.
Individual Invoice PDF: GET /session/{id}/vehicles/{vin}/charging-invoices/{invoice_id} downloads a single invoice PDF.
Charging History CSV: GET /session/{id}/vehicles/{vin}/charging-history.csv exports charging session data as CSV.
Invoice Metadata: GET /session/{id}/vehicles/{vin}/charging-invoices returns invoice metadata with session details, monthly totals, and currency breakdowns.

PDF Generation & Reporting

Asynchronous PDF Pipeline

The PDF generation uses a non-blocking async pipeline so the user's browser is freed immediately:

Trigger — Frontend sends POST /api/v1/tesla/vehicle-report/pdf/async with the report data and locale. The API returns { task_id, status: "queued" } within milliseconds.
Background Worker — A FastAPI BackgroundTask renders the PDF outside the main request loop using WeasyPrint + Jinja2 templates (vehicle_report.html). This prevents the site from becoming sluggish for other users while one report is generating.
Cloud Storage — The generated PDF bytes are uploaded to a private GCS bucket (reports/{vin}-{lang}-{timestamp}.pdf). No direct public access is possible.
Signed URL — The API generates a time-limited (1 hour) cryptographically signed download link.
Polling & Progress — The frontend polls GET /api/v1/tesla/reports/status/{task_id} every ~2 seconds. Redis tracks progress stages: queued (0%) → processing (10%) → uploading (70%) → complete (100%). On complete, the frontend opens the signed download_url and the user gets the PDF instantly.

Concurrent Multi-Language Support

Each PDF request gets a unique task_id, so a single user can request reports in multiple languages (en, fi, sv, no, da, de, fr, es, it) simultaneously. All tasks run concurrently in the background.

Core Capabilities

Template-Based Generation: Uses Jinja2 templates for consistent document layout.
WeasyPrint Integration: High-quality HTML-to-PDF conversion.
Vehicle Reports: Comprehensive vehicle status reports as downloadable PDFs.
Multilingual PDF Support: Fully localized reports in 9 languages (en, fi, sv, no, da, de, fr, es, it), including all metadata, summaries, and glossary terms.
Storage Management: GCS for production (scalable across instances), local disk as fallback.

Configuration & Environments

Environment-Specific Config: Pydantic-based settings for managing API keys, URLs, and secrets across dev, tst, and prd.
Tesla Mock Integration: Seamless switching between real Tesla API and local mock server for development.
Uniform URL Pattern: (New) Standardized access via {env}.api.carpulsetracker.com across all environments.

Vehicle Picture Upload

Image Upload API: Accepts up to 10 user-uploaded vehicle images per report session (JPEG, PNG).
GCS Storage: Uploaded images are stored in the environment-specific GCS reports bucket alongside the generated PDFs.
Report Embedding: The PDF generation pipeline retrieves uploaded images and appends them as a "Vehicle Photos" section at the bottom of both the HTML and PDF reports.
Lifecycle Management: Uploaded images are tied to the report session and follow the same retention policy as generated reports.