README

📋 Über diesen Adapter

Flexible Bestell-API für curenect Partner mit vollständiger Docker-Integration.

Diese API ermöglicht autorisierten Partnern die flexible Erstellung von TI-Bestellungen mit vollständiger Unterstützung für Einzel- und Multi-Standort-Szenarien.

🐳 Vollständig containerisiert - Identische Entwicklungs- und CI-Umgebung für alle.

🚀 Quick Start

Voraussetzungen

Docker (20.10+)
Docker Compose (2.0+)
Make (optional, für vereinfachte Commands)

🐳 Setup mit Docker (Empfohlen)

# Repository clonen
git clone https://gitlab.com/sl.is/adapter/php/bestell-api-adapter.git
cd bestell-api-adapter

# Entwicklungsumgebung starten
make setup

# Oder manuell:
docker-compose --profile dev up -d
docker-compose run --rm php composer install

⚡ Entwicklung

# Tests ausführen
make test

# Code-Qualität prüfen
make quality

# Integration Tests
make integration

# Alle verfügbaren Commands anzeigen
make help

🔧 Lokale Entwicklung ohne Docker

Nur falls Docker nicht verfügbar ist:

# PHP 8.2+ und Composer erforderlich
composer install
composer test
composer quality

📋 Bestellprozess

Katalogdaten abrufen: Verfügbare Berufsgruppen, Primärsysteme und Produkte
Bestellung konfigurieren: Pro Standort individuell konfigurieren
Bestellung erstellen: Alle Standorte in einem API-Call übermitteln
Status verfolgen: Bestellstatus und Fortschritt abfragen

🏢 Standort-Flexibilität

Einzelstandort

Ein Standort pro Bestellung
Vereinfachte Struktur
Kein Hauptstandort-Flag erforderlich

Multi-Standort

Mehrere Standorte pro Bestellung
Genau ein Hauptstandort erforderlich
Individuelle Konfiguration pro Standort möglich:
- Verschiedene Bestelltypen
- Verschiedene Berufsgruppen
- Verschiedene Primärsysteme
- Individuelle Produktauswahl

📋 Bestelltypen pro Standort

Erstausstattung: Neue TI-Infrastruktur
Wechsler: Migration von bestehenden Systemen
Bestellung: Standard-Nachbestellungen

Jeder Standort kann einen anderen Bestelltyp haben!

📊 Rate Limiting

Die API verwendet Rate Limiting zum Schutz vor Missbrauch:

Katalog-Endpunkte: 100 Anfragen pro Minute
Bestellungs-Endpunkte: 60 Anfragen pro Minute
Status-Endpunkte: 200 Anfragen pro Minute

Bei Überschreitung erhalten Sie HTTP 429 mit Retry-After Header.

🔒 Idempotenz

POST-Requests unterstützen Idempotenz über den X-Idempotency-Key Header:

Verhindert Doppelbestellungen bei Retry-Versuchen
Gültigkeitsdauer: 24 Stunden
Empfohlenes Format: partner-order-{datum}-{eindeutige-id}

🛠 Entwicklung

Docker-Umgebung

Die Entwicklungsumgebung läuft vollständig in Docker-Containern und stellt eine identische Umgebung zu CI/CD bereit.

Container-Services

# Entwicklungsumgebung starten
docker-compose --profile dev up -d

# Integration Tests Services
docker-compose --profile integration up -d

# Alle Services (dev + integration)
docker-compose --profile all up -d

Verfügbare Services

Service	Port	Beschreibung
`php`	-	Haupt-PHP-Container mit allen Tools
`redis`	6379	Cache für Tests
`api-mock`	4010	Prism API Mock Server
`oauth-mock`	4011	OAuth2 Mock Server
`error-simulator`	4012	HTTP Error Simulator

Make Commands

Das Makefile bietet einheitliche Commands für alle Entwicklungsaufgaben:

# Setup & Cleanup
make setup          # Projekt einrichten
make clean          # Aufräumen
make build          # Docker Image bauen

# Testing
make test           # Unit Tests
make test-all       # Alle Test-Suites
make integration    # Integration Tests
make test-coverage  # Tests mit Coverage

# Code Quality
make quality        # Alle Quality Checks
make lint           # PHP Syntax Check
make phpstan        # Static Analysis
make cs-fix         # Code Style Fix
make rector         # Code Modernization

# CI Simulation
make ci             # Komplette CI Pipeline lokal
make ci-fast-check  # Nur Fast-Check Stage
make ci-core-tests  # Nur Core-Tests Stage

# Docker
make docker-dev     # Development Container
make docker-clean   # Container aufräumen
make docker-shell   # Shell im Container

# Help
make help           # Alle verfügbaren Commands

Lokale Entwicklung

# Container-Shell öffnen
make docker-shell
# oder
docker-compose exec php bash

# Im Container arbeiten
composer install
composer test
composer phpstan
composer cs-fix

Integration Tests lokal ausführen

# Services starten
make integration-setup

# Tests ausführen
make integration

# Oder manuell
docker-compose --profile integration up -d
composer test-integration

CI/CD Pipeline lokal testen

# Komplette Pipeline simulieren
make ci

# Einzelne Stages testen
make ci-fast-check
make ci-core-tests
make ci-integration

📖 Installation & Usage

Requirements

PHP 8.1 and later.

Composer

To install the bindings via Composer, add the following to composer.json:

{
  "require": {
    "curenect/bestell-api-adapter": "^1.0"
  }
}

Then run composer install

Manual Installation

Download the files and include autoload.php:

<?php
require_once('/path/to/bestell-api-adapter/vendor/autoload.php');

Getting Started

Please follow the installation procedure and then run the following:

<?php
require_once(__DIR__ . '/vendor/autoload.php');



// Configure OAuth2 access token for authorization: OAuth2
$config = curenect\Adapter\BestellApi\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new curenect\Adapter\BestellApi\Api\BestellungenApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$bestellungErstellen = {"standorte":[{"bestelltyp":"erstausstattung","berufsgruppe_id":1,"primaersystem_id":1,"firma":"Praxis Dr. Mustermann","ik_nummer":"123456789","strasse":"Musterstraße","hausnummer":"123","plz":"12345","ort":"Musterstadt","rechtsform":"einzelunternehmen","hauptkontakt":{"vorname":"Max","nachname":"Mustermann","telefon":"+49 123 456789","email":"max.mustermann@praxis.de"},"technischer_kontakt":{"vorname":"Anna","nachname":"Tech","telefon":"+49 123 456790","email":"anna.tech@praxis.de","position":"IT-Administrator","it_kenntnisse":"fortgeschritten"},"produkte":[{"produkt_id":1,"menge":1},{"produkt_id":5,"menge":2}],"sepa_daten":{"iban":"DE89370400440532013000","kontoinhaber":"Dr. Max Mustermann"}}],"empfehlungscode":"REF-2024-001"}; // \curenect\Adapter\BestellApi\Model\BestellungErstellen | Vollständige Bestelldaten mit Standort-Konfiguration
$xRequestID = 550e8400-e29b-41d4-a716-446655440000; // string | Eindeutige Request-ID für Tracing und Fehlerbehandlung
$xIdempotencyKey = partner-order-2024-01-15-12345; // string | Idempotenz-Schlüssel für sichere Wiederholungen von POST-Requests. Verhindert Doppelbestellungen bei Retry-Versuchen. Gültigkeitsdauer: 24 Stunden

try {
    $result = $apiInstance->createBestellung($bestellungErstellen, $xRequestID, $xIdempotencyKey);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling BestellungenApi->createBestellung: ', $e->getMessage(), PHP_EOL;
}

API Endpoints

All URIs are relative to https://odoo.curenect.io/api/partner/v2

Class	Method	HTTP request	Description
BestellungenApi	createBestellung	POST /bestellungen	Neue Bestellung erstellen
BestellungenApi	getBestellung	GET /bestellungen/{bestellnummer}	Einzelne Bestellung abrufen
BestellungenApi	getBestellungen	GET /bestellungen	Eigene Bestellungen abrufen
KatalogApi	getBerufsgruppen	GET /katalog/berufsgruppen	Verfügbare Berufsgruppen abrufen
KatalogApi	getPrimaersysteme	GET /katalog/primaersysteme	Verfügbare Primärsysteme abrufen
KatalogApi	getProdukte	GET /katalog/produkte	Verfügbare Produkte abrufen
SystemApi	getAPIStatus	GET /system/status	API-Status prüfen
WebhooksApi	deleteWebhook	DELETE /webhooks/{webhook_id}	Webhook deregistrieren
WebhooksApi	getWebhooks	GET /webhooks	Registrierte Webhooks abrufen
WebhooksApi	registerWebhook	POST /webhooks	Webhook für Bestellungsstatusänderungen registrieren

Models

Authorization

Authentication schemes defined for the API:

OAuth2

Type: OAuth
Flow: application
Authorization URL: ``
Scopes:
- partner:read: Lesezugriff auf Katalogdaten und eigene Bestellungen
- partner:write: Erstellung neuer Bestellungen

Tests

To run the tests, use:

composer install
vendor/bin/phpunit

Author

partner-api@curenect.de

About this package

This PHP package is automatically generated by the OpenAPI Generator project:

API version: 2.0.0
- Generator version: 7.14.0
Build package: org.openapitools.codegen.languages.PhpClientCodegen

curenect / bestell-api-adapter

Maintainers

Details