common-api

Zentraler API-Integrations-Hub für Bluesafety-Anwendungen. Die common-api ist eine Laravel 12 Anwendung (PHP 8.2+, Laravel Sanctum), die drei externe Systeme an die interne Common-Datenbank anbindet:

System	Zweck	Auth
Grenke	Equipment-Leasing-Plattform	X.509-Zertifikat (PEM)
Weclapp	Cloud-ERP-System	API-Key (Bearer)
MFR	Mobile Field Report (Außendienst)	HTTP Basic + OData

Wofür nutze ich diese Doku?

Diese Developer-Doku richtet sich an alle, die …

• die common-api weiterentwickeln (neue Endpunkte, neue Aktionen, neue Integrationen),
• die common-api aus anderen Plattformen aufrufen wollen (Frontend, andere Laravel-Apps, externe Services),
• den Grenke-Request-Flow verstehen oder erweitern wollen,
• Weclapp-Webhooks anbinden oder Mailflows konfigurieren möchten,
• MFR-Daten synchronisieren oder OData-Queries schreiben.

Die automatisch generierte OpenAPI-Referenz (Scramble) findest du unter /api/playground bzw. live unter https://api.bluesafety.dev/scramble.

Verzeichnisstruktur (kurz)

common-api/
├── app/
│   ├── Actions/Grenke/             # Single-Operation-Klassen (execute())
│   ├── DataTransferObjects/        # readonly DTOs (fromArray/toArray)
│   │   ├── Grenke/
│   │   └── Weclapp/
│   ├── Enums/Grenke/               # State, ProductType, PaymentMethod, …
│   ├── Http/
│   │   ├── Clients/                # GuzzleClient, ODataClient
│   │   ├── Controllers/            # Grenke/, Mfr/, Weclapp/
│   │   ├── Helpers/                # ApiHelper, PdfHelper, BiMapHelper
│   │   ├── Middleware/             # Weclapp.php (IP-Whitelist)
│   │   └── Requests/               # FormRequest-Validation
│   ├── Services/
│   │   ├── Grenke/                 # ApiService, RequestFlowService, …
│   │   ├── WeclappApiService.php
│   │   ├── WeclappMailTemplateService.php
│   │   ├── WeclappTemplateRendererService.php
│   │   └── MfrApiService.php
│   ├── Jobs/MfrSyncJob.php
│   └── Mail/                       # RenderedWeclappTemplateMail, …
├── routes/
│   ├── api.php                     # /v1 + Auth + include grenke|weclapp|mfr
│   ├── grenke.php
│   ├── weclapp.php
│   └── mfr.php
└── config/
    ├── grenke.php                  # MissingInfo-Mailflow-Settings
    ├── services.php                # Credentials für alle Externals
    └── scramble.php                # OpenAPI-Generator

Routen-Konvention

Alle API-Routen leben unter dem Prefix v1/ und liegen in eigenen Route-Dateien pro Domain. Geschützt sind sie durch auth:sanctum (Bearer-Token). Ausnahme: Weclapp-Webhooks unter v1/weclapp/webhooks nutzen eine IP-Whitelist statt Sanctum.

# Auth (öffentlich)
POST   /api/v1/login

# Auth (geschützt)
POST   /api/v1/logout
GET    /api/v1/user

# Grenke
POST   /api/v1/grenke
GET    /api/v1/grenke/{financingId}
PATCH  /api/v1/grenke/{financingId}
PATCH  /api/v1/grenke/{financingId}/lessee
GET    /api/v1/grenke/{financingId}/wait-ready-to-sign
GET    /api/v1/grenke/{financingId}/e-signature/configuration
POST   /api/v1/grenke/{financingId}/e-signature
PUT    /api/v1/grenke/{financingId}/cancel-e-signature
PUT    /api/v1/grenke/{financingId}/switch-to-paper-contract
GET    /api/v1/grenke/{financingId}/contractdocument/base64
POST   /api/v1/grenke/{financingId}/contractdocument/link
POST   /api/v1/grenke/grenke/request-flow      # Orchestrator (One-Shot)

# Weclapp
GET|POST /api/v1/weclapp/webhooks               # IP-Whitelist!
GET    /api/v1/weclapp/show/{model?}/{entity?}/{value?}
GET    /api/v1/weclapp/setup/{model?}
GET    /api/v1/weclapp/get
GET    /api/v1/weclapp/update/{model?}/{entity?}/{value?}

# MFR
GET    /api/v1/mfr/show
GET    /api/v1/mfr/show/{entity?}/{attribute?}/{value?}
GET    /api/v1/mfr/sync/{entity?}
GET    /api/v1/mfr/setup/{stage?}
# + apiResource für: companies, contacts, products, documents, timeEvents,
#   stepListTemplates, itemTypes, itemUnits, users, costCenters, tags,
#   qualifications, serviceObjects, serviceRequests, items

Wo geht's weiter?

• Architektur & Patterns — verstehe Action / DTO / Service / State-Machine
• Authentication — Login, Token, Logout
• Grenke — kompletter Leasing-Flow mit E-Signature
• Weclapp — ERP-Anbindung, Webhooks, Mail-Templates
• MFR — Außendienst-Sync, OData
• Common — HTTP-Clients & Helper

Externe Doku & Tools

• Scramble (Auto-OpenAPI) — https://scramble.dedoc.co/
• Postman Team-Workspace — https://bluesafety.postman.co/
• Wiki — https://wiki.bluesafety.com/
  • Grenke: https://wiki.bluesafety.com/books/grenke
  • Weclapp: https://wiki.bluesafety.com/books/weclapp/chapter/development
  • MFR: https://wiki.bluesafety.com/books/mfr-field-service
• Live-API
  • Base: https://api.bluesafety.dev
  • OpenAPI JSON: https://api.bluesafety.dev/scramble/openapi.json
  • Scramble UI: https://api.bluesafety.dev/scramble