03.08.API Style Guide

03.08. API Style Guide

System Overview

The Car Pulse Tracker API (bnc-cpt-api) is a FastAPI backend that provides vehicle report generation, payment processing, and Tesla OAuth integration. It runs as a containerized service on Google Cloud Run across 4 environments.

Current architecture planning is split into:

doc/md/bnc-cpt-api.ARCHITECTURE.md - broad application architecture
doc/md/bnc-cpt-api.CORE-DATA-ARCHITECTURE.md - target architecture for the provider-agnostic vehicle-data acquisition and reporting core
doc/md/bnc-cpt-api.TESLA-DATA-ARCHITECTURE.md - Tesla-specific data-fetch and normalization rules

Architecture Position

                    Internet
                       │
           ┌───────────┴───────────┐
           │                       │
    {env}.carpulsetracker.com   {env}.api.carpulsetracker.com
           │                       │
     ┌─────┴─────┐          ┌─────┴─────┐
     │ GCS Bucket │          │ Cloud Run  │
     │  (WUI)     │          │  (API)     │  ◄── THIS COMPONENT
     └───────────┘          └─────┬─────┘
                                  │
                    ┌─────────────┼─────────────┐
                    │             │             │
              ┌─────┴──┐   ┌────┴────┐   ┌───┴───┐
              │ Stripe  │   │ PayPal  │   │ Tesla │
              │   API   │   │   API   │   │  API  │
              └────────┘   └─────────┘   └───────┘

Cloud Run Deployment

Service Configuration

Property	inf	dev	tst	prd
Service Name	bnc-cpt-api-inf	bnc-cpt-api-dev	bnc-cpt-api-tst	bnc-cpt-api-prd
GCP Project	bnc-cpt-inf	bnc-cpt-dev	bnc-cpt-tst	bnc-cpt-prd
Region	europe-north1	europe-north1	europe-north1	europe-north1
Memory	512Mi	1Gi	1Gi	2Gi
CPU	1	1	1	2
Min Instances	0	0	0	1
Max Instances	5	10	10	100
Concurrency	80	80	80	80
Container Port	8100	8100	8100	8100

Custom Domains

Environment	Custom Domain	CNAME Target
prd	api.carpulsetracker.com	ghs.googlehosted.com
dev	dev.api.carpulsetracker.com	ghs.googlehosted.com
tst	tst.api.carpulsetracker.com	ghs.googlehosted.com
inf	inf.api.carpulsetracker.com	ghs.googlehosted.com

DNS CNAME records managed by Terraform step 007-dns.

Docker Image

Registry: europe-north1-docker.pkg.dev/{project}/bnc-cpt-api/cpt-api
Tags: latest + commit SHA
Dockerfile: bnc-cpt-utl/src/docker/cpt-api/Dockerfile.x86_64
Base: Python 3.10 slim + Poetry
Artifact Registry cleanup: keeps 20 images (prd), 10 (dev/tst), 5 (inf)

Application Components

Endpoints

Endpoint	Method	Purpose
`/`	GET	Root info + version
`/health`	GET	Health check
`/docs`	GET	Swagger UI
`/redoc`	GET	ReDoc
`/api`	GET	API info + version
`/.well-known/appspecific/com.tesla.3p.public-key.pem`	GET	Tesla Fleet API public key
`/api/v1/auth/login/json`	POST	JWT authentication
`/api/v1/payment/create-intent`	POST	Create payment (Stripe/PayPal)
`/api/v1/payment/verify`	POST	Verify payment status
`/api/v1/payment/receipt/{id}`	GET	Get receipt data
`/api/v1/payment/receipt/{id}/pdf`	GET	Download receipt PDF
`/api/v1/payment/webhook/stripe`	POST	Stripe webhook
`/api/v1/payment/webhook/paypal`	POST	PayPal webhook
`/api/v1/payment/capture/paypal/{order_id}`	POST	Capture PayPal order
`/api/v1/tesla/oauth/initiate`	POST	Start Tesla OAuth
`/api/v1/tesla/oauth/callback`	GET	Tesla OAuth callback
`/api/v1/tesla/session/{id}/vehicles`	GET	Session vehicle inventory
`/api/v1/tesla/session/{id}/state`	GET	Session state for frontend resumption
`/api/v1/tesla/session/{id}/select`	POST	Select vehicles and package
`/api/v1/tesla/reports/generate`	POST	Generate reports for session
`/api/v1/tesla/report/{id}`	GET	Get session reports
`/api/v1/tesla/vehicle-report/pdf`	POST	Generate vehicle report PDF
`/api/v1/tesla/session/{id}/vehicles/{vin}/charging-invoices`	GET	Charging invoice metadata
`/api/v1/tesla/session/{id}/vehicles/{vin}/charging-invoices/{inv_id}`	GET	Download single charging invoice
`/api/v1/tesla/session/{id}/vehicles/{vin}/charging-invoices.zip`	GET	Download all charging invoices as ZIP
`/api/v1/tesla/session/{id}/vehicles/{vin}/charging-history.csv`	GET	Download charging history CSV
`/api/v1/pricing/catalog`	GET	CPQ pricing catalog
`/api/v1/pricing/quote`	POST	Compute price quote for session
`/api/v1/pricing/validate-voucher`	POST	Validate voucher code
`/api/v1/dev-proxy/register`	POST	Register dev tunnel for OAuth relay
`/api/v1/dev-proxy/unregister`	DELETE	Remove dev tunnel registration
`/api/v1/dev-proxy/initiate-oauth`	POST	Initiate OAuth via dev proxy
`/api/v1/dev-proxy/status`	GET	List active dev proxy registrations

Payment Processing

Payment plans (server-side validated, amounts in cents):

Plan	Price	EUR
Basic	1900	19.00
Pro	2900	29.00
Bulk	14900	149.00

Providers implemented: Stripe, PayPal. Placeholders: MobilePay, Google Pay, Apple Pay.

Finnish VAT rate: 25.5%

PDF Generation

Engine: WeasyPrint (HTML-to-PDF)
Templates: Jinja2 (app/templates/receipt.html, vehicle_report.html)
Storage: storage/receipts/receipt-{method}-{payment_id}.pdf
Generated on payment success

Authentication

JWT tokens (HS256, 30 min expiry)
Admin credentials stored in GCP Secret Manager
Password hashing: bcrypt

GCP Secrets

The API consumes these secrets from GCP Secret Manager (mounted as env vars by Cloud Run):

Environment Variable	GCP Secret ID	Purpose
STRIPE_SECRET_KEY	bnc-cpt-stripe-secret-key	Stripe API
STRIPE_PUBLISHABLE_KEY	bnc-cpt-stripe-publishable-key	Stripe client
STRIPE_WEBHOOK_SECRET	bnc-cpt-stripe-webhook-secret	Stripe webhooks
PAYPAL_CLIENT_ID	bnc-cpt-paypal-client-id	PayPal API
PAYPAL_CLIENT_SECRET	bnc-cpt-paypal-client-secret	PayPal API
PAYPAL_WEBHOOK_ID	bnc-cpt-paypal-webhook-id	PayPal webhooks
JWT_SECRET_KEY	bnc-cpt-jwt-secret-key	JWT signing
ADMIN_USERNAME	bnc-cpt-admin-username	Admin auth
ADMIN_PASSWORD_HASH	bnc-cpt-admin-password-hash	Admin auth
TESLA_CLIENT_ID	bnc-cpt-tesla-client-id	Tesla OAuth
TESLA_CLIENT_SECRET	bnc-cpt-tesla-client-secret	Tesla OAuth
TESLA_REDIRECT_URI	bnc-cpt-tesla-redirect-uri	Tesla OAuth
COMPANY_NAME	bnc-cpt-company-name	Receipts
COMPANY_ADDRESS	bnc-cpt-company-address	Receipts
COMPANY_Y_TUNNUS	bnc-cpt-company-y-tunnus	Finnish business ID
COMPANY_VAT_NUMBER	bnc-cpt-company-vat-number	Receipts
COMPANY_EMAIL	bnc-cpt-company-email	Receipts
COMPANY_WEBSITE	bnc-cpt-company-website	Receipts

Secret containers created by Terraform step 029-create-gcp-secrets. Values synced from Google Sheet via do_gcp_sync_secrets.

Environment Variables (non-secret)

Set directly in Cloud Run via CD workflow:

Variable	inf/dev	tst	prd
DEBUG	True	False	False
APP_NAME	Car Pulse Tracker API	same	same
APP_VERSION	(from git tag)	same	same
CORS_ORIGINS	https://{env}.carpulsetracker.com	same	https://carpulsetracker.com,https://www.carpulsetracker.com
JWT_ACCESS_TOKEN_EXPIRE_MINUTES	30	30	30
VAT_RATE	25.5	25.5	25.5
PAYPAL_MODE	sandbox	sandbox	live

CI/CD Pipeline

CI (`ci.yaml`)

Trigger: All pushes to any branch
Runs pytest inside Docker container
Quality gate for merge to master

Unified Workflow (`ci.yaml`)

Trigger: Push to master (paths: src/python/cpt-api/**) or workflow_dispatch
Auto-deploy: inf + dev on master push
Manual deploy: tst, prd via workflow_dispatch only

Pipeline steps: 1. Clone all team repos 2. Load config from {env}.env.json 3. Read version from git tag 4. Setup GCP credentials 5. Build Docker image (production target) 6. Push to Artifact Registry (:latest + :sha) 7. Deploy to Cloud Run with env vars + secrets 8. Map custom domain 9. Health check (Cloud Run URL + custom domain) 10. Verify Swagger UI accessible

GitHub Actions Secrets

Secret	Purpose
ALL_CSI_GITHUB_TOKEN	Clone team repos
GCP_SA_KEY_INF	GCP auth for inf
GCP_SA_KEY_DEV	GCP auth for dev
GCP_SA_KEY_TST	GCP auth for tst
GCP_SA_KEY_PRD	GCP auth for prd

Provisioned by Terraform step 120-github-general-secrets.

Versioning

Source of truth: git tags (v0.2.2)
CD workflow reads tag and passes as APP_VERSION to Cloud Run
Visible at /, /api, /health endpoints
Bumped via: TARGET_PROJ=.../bnc-cpt-api ./run -a do_version_bump (from bnc-cpt-utl)
Increment: patch 0-9 -> minor -> major

Infrastructure Dependencies

Terraform Step	What it provides
001-enable-gcp-services	`run.googleapis.com`, `secretmanager.googleapis.com`, `artifactregistry.googleapis.com`
007-dns	CNAME records for `{env}.api.carpulsetracker.com`
025-gcp-artifact-registry	Docker image repository with cleanup policies
029-create-gcp-secrets	Secret containers in GCP Secret Manager
030-gcp-cloud-run	Cloud Run service definition
120-github-general-secrets	GitHub Actions secrets for CI/CD

Tesla Fleet API Integration

Tesla Fleet API partner registration completed 2026-02-10 (EU region). Live integration via tesla_fleet.py (v2 connect-first architecture): - Real OAuth flow with code exchange and token management - Session-based workflow: OAuth → vehicle inventory → vehicle/package selection → payment → report generation - Sessions stored in Redis with 30-minute TTL - Regional endpoint fallback (EU, NA, CN) - Charging history, invoice downloads (PDF + ZIP), and CSV export

See bnc-cpt-api.TESLA.md for full integration guide including: - App registration and scopes - Partner registration steps - OAuth flow - All API endpoints and response fields - Known issues and next steps

Current Limitations

Redis for session/payment storage (no relational database yet)
MobilePay, Google Pay, Apple Pay are placeholders
Tests are placeholder/TODO