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

1. Katalogdaten abrufen: Verfügbare Berufsgruppen, Primärsysteme und Produkte
2. Bestellung konfigurieren: Pro Standort individuell konfigurieren
3. Bestellung erstellen: Alle Standorte in einem API-Call übermitteln
4. 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

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

Models

• APIFehler
• APIFehlerFehler
• Adresse
• AnschlusstypEnum
• Berufsgruppe
• BerufsgruppenListe
• BestellstatusEnum
• BestelltypEnum
• Bestellung
• BestellungBestellpositionenInner
• BestellungErstellen
• BestellungListe
• BestellungPosition
• BestellungPositionProdukt
• BestellungStandort
• BestellungStandortBerufsgruppe
• BestellungStandortPrimaersystem
• BestellungVerwandteBestellungenInner
• CreateBestellung201Response
• GetAPIStatus200Response
• GetAPIStatus503Response
• GetWebhooks200Response
• GetWebhooks200ResponseWebhooksInner
• KonnektorherstellerEnum
• Kontakt
• Primaersystem
• PrimaersystemListe
• Produkt
• ProduktBestellbarFuer
• ProduktListe
• RechtsformEnum
• RegisterWebhook201Response
• RegisterWebhookRequest
• SEPADaten
• Standort
• StandortProdukt
• TechnischerKontakt
• ValidationError
• ValidationErrorFehler
• ValidationErrorFehlerValidierungsfehlerInner
• WebhookEvent
• WebhookSignatur
• WechslerDaten

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