presseportale/resources/views/web/api.blade.php

@extends('web.layouts.web-master')

@section('title', 'API-Dokumentation')
@section('meta_description', 'REST-API v1: Pressemitteilungen programmatisch erstellen, mit Bildern versehen und zur Prüfung einreichen — Token-basiert, JSON, versioniert.')

@php
    // Die API läuft zentral über den Publisher-Hub (pressekonto).
    $apiBase = rtrim((string) config('domains.domain_portal_url', config('app.url')), '/').'/api/v1';

    $host = request()->getHost();
    $apiBrandKey = str_contains($host, 'pressekonto')
        ? 'pressekonto'
        : (str_contains($host, 'presseecho') ? 'presseecho' : 'businessportal24');
    $apiContactEmail = config('domains.domains.'.$apiBrandKey.'.brand.contact_email') ?? 'info@businessportal24.com';

    $endpoints = [
        [
            'group' => 'Pressemitteilungen',
            'items' => [
                ['method' => 'GET', 'path' => '/press-releases', 'desc' => 'Eigene Mitteilungen auflisten (paginiert, filterbar über ?status= und ?per_page=, max. 100).', 'ability' => 'press-releases:read'],
                ['method' => 'POST', 'path' => '/press-releases', 'desc' => 'Neue Mitteilung anlegen — immer als Entwurf (Status draft).', 'ability' => 'press-releases:write'],
                ['method' => 'GET', 'path' => '/press-releases/{id}', 'desc' => 'Eine Mitteilung inkl. Firma, Rubrik und Bildern abrufen.', 'ability' => 'press-releases:read'],
                ['method' => 'PATCH', 'path' => '/press-releases/{id}', 'desc' => 'Mitteilung ändern — nur im Status draft oder rejected.', 'ability' => 'press-releases:write'],
                ['method' => 'POST', 'path' => '/press-releases/{id}/submit', 'desc' => 'Zur Inhaltsprüfung einreichen — der einzige Weg Richtung Veröffentlichung.', 'ability' => 'press-releases:write'],
                ['method' => 'DELETE', 'path' => '/press-releases/{id}', 'desc' => 'Mitteilung löschen — veröffentlichte Mitteilungen sind ausgenommen.', 'ability' => 'press-releases:write'],
            ],
        ],
        [
            'group' => 'Bilder',
            'items' => [
                ['method' => 'GET', 'path' => '/press-releases/{id}/images', 'desc' => 'Bilder einer Mitteilung auflisten.', 'ability' => 'press-releases:read'],
                ['method' => 'POST', 'path' => '/press-releases/{id}/images', 'desc' => 'Bild hochladen (multipart/form-data) — nur bei draft/rejected.', 'ability' => 'press-release-images:write'],
                ['method' => 'DELETE', 'path' => '/press-release-images/{imageId}', 'desc' => 'Bild entfernen — nur bei draft/rejected.', 'ability' => 'press-release-images:write'],
            ],
        ],
        [
            'group' => 'Stammdaten',
            'items' => [
                ['method' => 'GET', 'path' => '/companies', 'desc' => 'Eigene Firmenprofile (Newsrooms) auflisten.', 'ability' => 'companies:read'],
                ['method' => 'GET', 'path' => '/companies/{id}', 'desc' => 'Ein Firmenprofil abrufen.', 'ability' => 'companies:read'],
                ['method' => 'GET', 'path' => '/categories', 'desc' => 'Aktive Rubriken inkl. Übersetzungen — liefert die category_id für neue Mitteilungen.', 'ability' => 'press-releases:read'],
            ],
        ],
    ];

    $pressReleaseFields = [
        ['name' => 'company_id', 'type' => 'integer', 'required' => true, 'desc' => 'ID eines eigenen Firmenprofils — bestimmt Newsroom und Portal.'],
        ['name' => 'category_id', 'type' => 'integer', 'required' => true, 'desc' => 'Rubrik (siehe GET /categories).'],
        ['name' => 'language', 'type' => 'string', 'required' => true, 'desc' => 'Sprachcode, zwei Zeichen: de oder en.'],
        ['name' => 'title', 'type' => 'string', 'required' => true, 'desc' => 'Überschrift, max. 255 Zeichen.'],
        ['name' => 'text', 'type' => 'string', 'required' => true, 'desc' => 'Inhalt. Erlaubtes HTML: p, br, h2, h3, strong, em, ul, ol, li, blockquote, a — alles andere wird entfernt.'],
        ['name' => 'backlink_url', 'type' => 'string', 'required' => false, 'desc' => 'Link zur Quelle/Website, max. 255 Zeichen.'],
        ['name' => 'keywords', 'type' => 'string', 'required' => false, 'desc' => 'Schlagworte, kommagetrennt, max. 255 Zeichen.'],
        ['name' => 'teaser_begin / teaser_end', 'type' => 'integer', 'required' => false, 'desc' => 'Zeichen-Offsets für den Teaser-Ausschnitt.'],
        ['name' => 'no_export', 'type' => 'boolean', 'required' => false, 'desc' => 'Mitteilung von Feeds/Exporten ausnehmen.'],
    ];

    $imageFields = [
        ['name' => 'image', 'type' => 'file', 'required' => true, 'desc' => 'JPG, PNG oder WebP, max. 8 MB.'],
        ['name' => 'title', 'type' => 'string', 'required' => false, 'desc' => 'Bildtitel, max. 120 Zeichen.'],
        ['name' => 'description', 'type' => 'string', 'required' => false, 'desc' => 'Beschreibung, max. 500 Zeichen.'],
        ['name' => 'copyright', 'type' => 'string', 'required' => false, 'desc' => 'Urheberangabe, max. 255 Zeichen.'],
        ['name' => 'is_preview', 'type' => 'boolean', 'required' => false, 'desc' => 'Als Vorschaubild setzen (ersetzt ein vorhandenes).'],
    ];

    $statusCodes = [
        ['code' => '200 / 201 / 204', 'desc' => 'Erfolg — Abruf, Ressource erstellt bzw. gelöscht.'],
        ['code' => '401', 'desc' => 'Kein oder ungültiger API-Token.'],
        ['code' => '402', 'desc' => 'Einreichen erfordert eine aktive Buchung (Tarif oder Einzel-PM).'],
        ['code' => '403', 'desc' => 'Token-Berechtigung fehlt oder die Ressource gehört nicht zu Ihrem Konto.'],
        ['code' => '409', 'desc' => 'Statuskonflikt — z. B. Bearbeiten einer bereits veröffentlichten Mitteilung.'],
        ['code' => '422', 'desc' => 'Validierungsfehler oder Kontingent-/Richtlinienverstoß (Details im Body).'],
        ['code' => '429', 'desc' => 'Rate-Limit erreicht: 60 Anfragen pro Minute je Token (Header X-RateLimit-*).'],
    ];

    $methodColors = [
        'GET' => 'text-[#1F6B3F] bg-[#E7F2EA]',
        'POST' => 'text-[#8A4B12] bg-[#F7EBDD]',
        'PATCH' => 'text-[#6B4FA1] bg-[#EEE9F7]',
        'DELETE' => 'text-[#A13030] bg-[#F7E5E5]',
    ];
@endphp

@section('content')
    <x-web.static-page
        eyebrow="Entwickler"
        title="API-Dokumentation"
        lead="Pressemitteilungen programmatisch erstellen, mit Bildern versehen und zur Prüfung einreichen — über die versionierte REST-API des Publisher-Hubs."
        breadcrumb="API"
    >
        {{-- Überblick + Authentifizierung --}}
        <div class="pm-body max-w-[760px]">
            <h2>Grundlagen</h2>
            <p>
                Die API v1 ist ein RESTful Web Service mit JSON-Responses. Basis-URL:
                <strong>{{ $apiBase }}</strong>. Eine über die API angelegte Mitteilung ist immer ein
                Entwurf; veröffentlicht wird sie erst nach dem Einreichen über die Submit-Route und der
                anschließenden Inhaltsprüfung — sie erscheint dann wie jede andere Mitteilung auf beiden Portalen.
            </p>
            <h3>Authentifizierung</h3>
            <p>
                Alle Anfragen benötigen einen persönlichen API-Token als Bearer-Header:
                <code>Authorization: Bearer &lt;token&gt;</code>. Jeder Token trägt Berechtigungen
                (z.&nbsp;B. <code>press-releases:write</code>), die den Zugriff auf die jeweiligen Endpunkte steuern.
                Tokens erstellen und widerrufen Sie selbst in Ihrem Publisher-Konto unter „API-Tokens" —
                Voraussetzung ist eine aktive Buchung (Tarif oder Einzel-Pressemitteilung).
                <strong>Bestandskunden der Altportale:</strong> Ihre bisherigen API-Schlüssel wurden
                übernommen und funktionieren weiter — sowohl als Bearer-Token als auch in der alten
                Form (<code>X-ApiKey</code>-Header) und auf den dokumentierten
                <code>/service/…</code>-Pfaden. Für neue Integrationen empfehlen wir die aktuellen
                <code>/api/v1/…</code>-Endpunkte mit Bearer-Token.
            </p>
        </div>

        {{-- Endpunkte --}}
        <h2 class="font-serif text-[26px] font-semibold tracking-[-0.4px] text-ink m-0 mt-14 mb-4">Endpunkte</h2>
        <div class="max-w-[900px] space-y-8">
            @foreach ($endpoints as $group)
                <div>
                    <h3 class="text-[14px] font-semibold text-ink m-0 mb-3">{{ $group['group'] }}</h3>
                    <div class="border border-bg-rule divide-y divide-bg-rule">
                        @foreach ($group['items'] as $endpoint)
                            <div class="px-5 py-3.5 grid gap-x-4 gap-y-1 sm:grid-cols-[64px_1fr] items-baseline">
                                <span class="inline-flex justify-center px-1.5 py-0.5 text-[11px] font-bold tracking-wide rounded-[2px] {{ $methodColors[$endpoint['method']] ?? 'text-ink bg-bg-elev' }}">{{ $endpoint['method'] }}</span>
                                <div>
                                    <code class="font-mono text-[13px] text-ink">{{ $endpoint['path'] }}</code>
                                    <p class="text-[12.5px] leading-[1.55] text-ink-2 mt-1 mb-0">
                                        {{ $endpoint['desc'] }}
                                        <span class="text-ink-4">· Berechtigung: <code class="font-mono text-[11.5px]">{{ $endpoint['ability'] }}</code></span>
                                    </p>
                                </div>
                            </div>
                        @endforeach
                    </div>
                </div>
            @endforeach
        </div>

        {{-- Felder --}}
        <h2 class="font-serif text-[26px] font-semibold tracking-[-0.4px] text-ink m-0 mt-14 mb-4">Felder einer Pressemitteilung</h2>
        <div class="max-w-[900px] border border-bg-rule overflow-x-auto">
            <table class="w-full text-[13px] border-collapse">
                <thead>
                    <tr class="text-left text-ink-3 bg-bg-elev border-b border-bg-rule">
                        <th class="font-medium px-4 py-2.5">Feld</th>
                        <th class="font-medium px-4 py-2.5">Typ</th>
                        <th class="font-medium px-4 py-2.5">Pflicht</th>
                        <th class="font-medium px-4 py-2.5">Beschreibung</th>
                    </tr>
                </thead>
                <tbody class="divide-y divide-bg-rule">
                    @foreach ($pressReleaseFields as $field)
                        <tr>
                            <td class="px-4 py-2.5 font-mono text-[12.5px] text-ink whitespace-nowrap">{{ $field['name'] }}</td>
                            <td class="px-4 py-2.5 text-ink-3">{{ $field['type'] }}</td>
                            <td class="px-4 py-2.5 text-ink-3">{{ $field['required'] ? 'ja' : '—' }}</td>
                            <td class="px-4 py-2.5 text-ink-2">{{ $field['desc'] }}</td>
                        </tr>
                    @endforeach
                </tbody>
            </table>
        </div>

        <h2 class="font-serif text-[26px] font-semibold tracking-[-0.4px] text-ink m-0 mt-12 mb-4">Felder eines Bild-Uploads</h2>
        <div class="max-w-[900px] border border-bg-rule overflow-x-auto">
            <table class="w-full text-[13px] border-collapse">
                <thead>
                    <tr class="text-left text-ink-3 bg-bg-elev border-b border-bg-rule">
                        <th class="font-medium px-4 py-2.5">Feld</th>
                        <th class="font-medium px-4 py-2.5">Typ</th>
                        <th class="font-medium px-4 py-2.5">Pflicht</th>
                        <th class="font-medium px-4 py-2.5">Beschreibung</th>
                    </tr>
                </thead>
                <tbody class="divide-y divide-bg-rule">
                    @foreach ($imageFields as $field)
                        <tr>
                            <td class="px-4 py-2.5 font-mono text-[12.5px] text-ink whitespace-nowrap">{{ $field['name'] }}</td>
                            <td class="px-4 py-2.5 text-ink-3">{{ $field['type'] }}</td>
                            <td class="px-4 py-2.5 text-ink-3">{{ $field['required'] ? 'ja' : '—' }}</td>
                            <td class="px-4 py-2.5 text-ink-2">{{ $field['desc'] }}</td>
                        </tr>
                    @endforeach
                </tbody>
            </table>
        </div>

        {{-- Workflow-Beispiel --}}
        <h2 class="font-serif text-[26px] font-semibold tracking-[-0.4px] text-ink m-0 mt-14 mb-4">Schneller Einstieg</h2>
        <p class="text-[13px] text-ink-2 m-0 mb-4 max-w-[640px]">Der typische Ablauf: Entwurf anlegen, Bild hochladen, zur Prüfung einreichen.</p>
        <div class="max-w-[900px] bg-[#16140f] border border-bg-rule-strong rounded-[3px] p-5 overflow-x-auto">
            <pre class="text-[12.5px] leading-[1.6] font-mono text-[#9ad1a5] m-0"><code># 1. Entwurf anlegen
curl -X POST {{ $apiBase }}/press-releases \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": 1,
    "category_id": 2,
    "language": "de",
    "title": "Neue Produktankündigung",
    "text": "&lt;p&gt;Unser neues Produkt …&lt;/p&gt;"
  }'

# 2. Bild hochladen (multipart)
curl -X POST {{ $apiBase }}/press-releases/123/images \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "image=@pressefoto.jpg" \
  -F "copyright=Mustermann GmbH" \
  -F "is_preview=1"

# 3. Zur Inhaltsprüfung einreichen
curl -X POST {{ $apiBase }}/press-releases/123/submit \
  -H "Authorization: Bearer YOUR_API_TOKEN"</code></pre>
        </div>
        <p class="text-[12px] text-ink-3 m-0 mt-3">
            Maschinenlesbare Referenz: <a href="{{ route('docs.api.v1') }}" class="text-brand hover:underline">OpenAPI-Spezifikation (YAML)</a>.
        </p>

        {{-- Statuscodes --}}
        <h2 class="font-serif text-[26px] font-semibold tracking-[-0.4px] text-ink m-0 mt-14 mb-4">HTTP-Statuscodes</h2>
        <div class="max-w-[900px] border border-bg-rule overflow-x-auto">
            <table class="w-full text-[13px] border-collapse">
                <thead>
                    <tr class="text-left text-ink-3 bg-bg-elev border-b border-bg-rule">
                        <th class="font-medium px-4 py-2.5">Code</th>
                        <th class="font-medium px-4 py-2.5">Bedeutung</th>
                    </tr>
                </thead>
                <tbody class="divide-y divide-bg-rule">
                    @foreach ($statusCodes as $status)
                        <tr>
                            <td class="px-4 py-2.5 font-mono text-[12.5px] text-ink whitespace-nowrap">{{ $status['code'] }}</td>
                            <td class="px-4 py-2.5 text-ink-2">{{ $status['desc'] }}</td>
                        </tr>
                    @endforeach
                </tbody>
            </table>
        </div>

        {{-- CTA --}}
        <div class="mt-14 border border-bg-rule bg-bg-elev p-6 sm:p-8 flex flex-col sm:flex-row sm:items-center sm:justify-between gap-5 max-w-[900px]">
            <div>
                <h2 class="font-serif text-[20px] font-semibold tracking-[-0.3px] text-ink m-0">API-Token erstellen</h2>
                <p class="text-[13px] text-ink-2 mt-1.5 mb-0">Tokens verwalten Sie selbst im Publisher-Konto. Bei Fragen zur Anbindung hilft der Support: <a href="mailto:{{ $apiContactEmail }}" class="text-brand hover:underline">{{ $apiContactEmail }}</a></p>
            </div>
            <div class="flex flex-wrap gap-3 flex-shrink-0">
                <a href="{{ rtrim((string) config('domains.domain_portal_url', config('app.url')), '/') }}/login"
                    class="inline-flex items-center justify-center gap-1.5 px-5 py-2.5 text-[12.5px] font-semibold text-white bg-brand hover:bg-brand-deep rounded-[2px] transition-colors">
                    Zum Publisher-Konto
                </a>
                <a href="{{ route('preise') }}"
                    class="inline-flex items-center justify-center gap-1.5 px-5 py-2.5 text-[12.5px] font-semibold text-ink border border-bg-rule-strong hover:bg-bg transition-colors rounded-[2px]">
                    Preise ansehen
                </a>
            </div>
        </div>
    </x-web.static-page>
@endsection