🔌 Unified Contract API

Die zentrale API für alle Instances

---

🎯 Konzept

Alle Instances (FLO, MORELO, Bavaria, etc.) kommunizieren über eine einheitliche Contract API:

┌────────────────────────────────────────────────────────┐
│            ContractPlattformWhiteLabel API             │
│                 (Cloudflare Workers)                   │
└────────────────────────────────────────────────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        │                 │                 │
        ▼                 ▼                 ▼
   FLO Instance    MORELO Instance   Future Instances

---

📊 Contract Types

Universal Contract Interface

interface UnifiedContract {
  // Identifiers
  id: string;
  instance_id: string;        // 'flo', 'morelo', 'bavaria'
  external_id?: string;       // Optional: Instance-specific ID

  // Type & Status
  type: ContractType;
  status: ContractStatus;

  // Parties
  party_a: ContractParty;     // Verkäufer/Vermieter/Provider
  party_b: ContractParty;     // Käufer/Mieter/Kunde

  // Asset (Polymorphic)
  asset: Asset;

  // Financials
  financials: ContractFinancials;

  // Documents
  documents: ContractDocument[];

  // Metadata
  metadata: Record<string, unknown>;

  // Timestamps
  created_at: Date;
  updated_at: Date;
  signed_at?: Date;
  expires_at?: Date;
}

Contract Types

type ContractType = 
  // FLO
  | 'membership'           // GYM Membership
  | 'service_contract'     // Personal Training, etc.
  | 'mietvertrag_immo'     // Immobilien Miete
  | 'kaufvertrag_immo'     // Immobilien Kauf

  // MORELO
  | 'kfz_kaufvertrag'      // Fahrzeugkauf
  | 'kfz_leasing'          // Fahrzeug Leasing
  | 'probefahrt'           // Test Drive Agreement

  // Future: Bavaria
  | 'yacht_kaufvertrag'
  | 'yacht_charter'
  | 'sea_trial'

  // Future: Generic
  | 'generic_contract'
  ;

type ContractStatus = 
  | 'draft'
  | 'pending_signature'
  | 'signed'
  | 'active'
  | 'terminated'
  | 'expired'
  ;

Asset Types

type Asset = 
  | GymMembership
  | Immobilie
  | Fahrzeug
  | Yacht
  | ServicePackage
  ;

interface Fahrzeug {
  category: 'wohnmobil' | 'yacht' | 'hypercar' | 'motorcycle';
  manufacturer: string;        // 'MORELO', 'Bavaria', 'Porsche'
  model: string;               // 'PALACE 90 LMF', 'R40 FLY'
  vin?: string;                // Vehicle Identification Number
  configuration?: {
    chassis: string;
    engine: string;
    options: string[];
  };
  nft_token_id?: string;       // Blockchain NFT Reference
  price: number;
}

interface Immobilie {
  type: 'wohnung' | 'haus' | 'gewerbe';
  address: {
    street: string;
    city: string;
    zip: string;
    country: string;
  };
  size_sqm: number;
  rooms: number;
  monthly_rent?: number;       // For Mietvertrag
  purchase_price?: number;     // For Kaufvertrag
}

interface GymMembership {
  type: 'monthly' | 'yearly' | 'trial';
  start_date: Date;
  end_date?: Date;
  monthly_fee: number;
  features: string[];
}

---

🔐 Authentication

API Keys

Jede Instance erhält einen API Key:

Authorization: Bearer inst_morelo_sk_live_abc123...

Scopes

Scope	Description
contracts:read	Read contracts
contracts:write	Create/Update contracts
contracts:sign	Sign contracts
documents:generate	Generate PDFs
payments:process	Process payments

---

📡 Endpoints

1. Create Contract

POST /api/v1/contracts
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "instance_id": "morelo",
  "type": "kfz_kaufvertrag",
  "party_a": {
    "type": "organization",
    "name": "MORELO Reisemobile GmbH",
    "address": "...",
    "tax_id": "DE123456789"
  },
  "party_b": {
    "type": "person",
    "first_name": "Max",
    "last_name": "Mustermann",
    "email": "max@example.com",
    "address": "..."
  },
  "asset": {
    "type": "fahrzeug",
    "category": "wohnmobil",
    "manufacturer": "MORELO",
    "model": "PALACE 90 LMF",
    "vin": "WMK12345678901234",
    "configuration": {
      "chassis": "IVECO Daily",
      "engine": "3.0L Diesel",
      "options": ["Solaranlage", "Lithium Batterie"]
    },
    "price": 289000
  },
  "financials": {
    "total_amount": 289000,
    "currency": "EUR",
    "payment_method": "leasing",
    "payment_terms": {
      "down_payment": 50000,
      "monthly_rate": 1200,
      "duration_months": 60
    }
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "ctr_abc123",
    "instance_id": "morelo",
    "type": "kfz_kaufvertrag",
    "status": "draft",
    "created_at": "2026-01-15T10:00:00Z",
    "pdf_url": null,
    "signature_url": "https://api.contractplattform.dev/sign/ctr_abc123"
  }
}

---

2. Get Contract

GET /api/v1/contracts/{contract_id}
Authorization: Bearer {api_key}

Response:

{
  "success": true,
  "data": {
    "id": "ctr_abc123",
    "instance_id": "morelo",
    "type": "kfz_kaufvertrag",
    "status": "signed",
    "party_a": { ... },
    "party_b": { ... },
    "asset": { ... },
    "financials": { ... },
    "documents": [
      {
        "type": "contract_pdf",
        "url": "https://cdn.contractplattform.dev/ctr_abc123.pdf",
        "created_at": "2026-01-15T10:05:00Z"
      }
    ],
    "signed_at": "2026-01-15T14:30:00Z"
  }
}

---

3. List Contracts

GET /api/v1/contracts?instance_id=morelo&status=active&limit=10
Authorization: Bearer {api_key}

Query Parameters:

Parameter	Type	Description
instance_id	string	Filter by instance
type	ContractType	Filter by type
status	ContractStatus	Filter by status
party_b_email	string	Filter by customer email
limit	number	Max results (default: 20)
offset	number	Pagination offset

---

4. Update Contract

PATCH /api/v1/contracts/{contract_id}
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "status": "pending_signature",
  "metadata": {
    "sales_person": "John Doe",
    "dealer_id": "dealer_123"
  }
}

---

5. Sign Contract

POST /api/v1/contracts/{contract_id}/sign
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "party": "party_b",
  "signature": {
    "type": "electronic",
    "ip_address": "192.168.1.1",
    "user_agent": "Mozilla/5.0...",
    "timestamp": "2026-01-15T14:30:00Z"
  }
}

---

6. Generate Document

POST /api/v1/contracts/{contract_id}/documents
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "template": "kfz_kaufvertrag_de",
  "format": "pdf"
}

Response:

{
  "success": true,
  "data": {
    "document_id": "doc_xyz789",
    "type": "contract_pdf",
    "url": "https://cdn.contractplattform.dev/ctr_abc123_signed.pdf",
    "size_bytes": 245678,
    "created_at": "2026-01-15T14:35:00Z"
  }
}

---

🔄 Webhooks

Instances können Webhooks registrieren für Events:

POST /api/v1/webhooks
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "url": "https://morelo.example.com/webhooks/contracts",
  "events": [
    "contract.signed",
    "contract.expired",
    "payment.succeeded"
  ]
}

Webhook Payload:

{
  "event": "contract.signed",
  "contract_id": "ctr_abc123",
  "instance_id": "morelo",
  "timestamp": "2026-01-15T14:30:00Z",
  "data": {
    "contract": { ... }
  }
}

---

🌐 i18n Support

Die API unterstützt mehrsprachige Contracts:

POST /api/v1/contracts
Content-Language: de-DE

{
  "type": "kfz_kaufvertrag",
  "locale": "de-DE",
  ...
}

Supported Locales:

• de-DE - Deutsch
• en-US - English
• fr-FR - Français

---

📊 Rate Limits

Tier	Requests/Minute	Contracts/Day
Free	10	10
Pro	100	1000
Enterprise	Unlimited	Unlimited

---

🛠️ SDKs

TypeScript/JavaScript

import { ContractClient } from '@contractplattform/client';

const client = new ContractClient({
  apiKey: 'inst_morelo_sk_live_...',
  instanceId: 'morelo',
});

const contract = await client.contracts.create({
  type: 'kfz_kaufvertrag',
  party_a: { ... },
  party_b: { ... },
  asset: { ... },
  financials: { ... },
});

console.log(contract.id); // ctr_abc123

Python

from contractplattform import ContractClient

client = ContractClient(
    api_key='inst_morelo_sk_live_...',
    instance_id='morelo'
)

contract = client.contracts.create(
    type='kfz_kaufvertrag',
    party_a={ ... },
    party_b={ ... },
    asset={ ... },
    financials={ ... }
)

print(contract.id)  # ctr_abc123

---

🔗 OpenAPI Specification

Full API Spec: openapi.yaml

Interactive Docs: Swagger UI

---

Next: Architecture →