ChatGPT-Checkout-Modul für PrestaShop (ACP) — Installation & Konfiguration

Dieses Modul verwandelt Ihren PrestaShop-Shop in ein Backend für agentischen Handel, das dem Agentic Commerce Protocol (ACP) entspricht – dem von OpenAI und Stripe gepflegten offenen Standard. Ein KI-Agent (ChatGPT, Claude, Perplexity) kann Ihre Produkte über einen authentifizierten Feed entdecken, eine Checkout-Sitzung erstellen und den Kauf abschließen – wodurch eine echte PrestaShop-Bestellung in Ihrem Shop erstellt wird.

Voraussetzungen

• PrestaShop 8.0 bis 9.x (multishop-fähig).
• Shop über HTTPS ausgeliefert (das Protokoll erfordert es; die Endpoints erzwingen SSL).
• Sprechende URLs aktiviert (SEO & URLs → URL-Rewriting): die REST-Pfade hängen davon ab.
• Ein Stripe-Konto, wenn Sie die delegierte Zahlung aktivieren möchten (optional).

Installation

1. Back-Office → Module → Modul hochladen, dann das Archiv dfaiagent.zip auswählen.
2. Aktivieren Sie die sprechenden URLs, falls noch nicht geschehen.
3. Öffnen Sie die Modulkonfiguration: Kopieren Sie die Basis-URL und den API-Schlüssel für das Onboarding der Agenten-Plattform.

Konfiguration

API-Schlüssel (Bearer)

Bei der Installation wird ein API-Schlüssel erzeugt. Agenten authentifizieren sich mit dem Header Authorization: Bearer IHR_API_SCHLUESSEL. Sie können den Schlüssel jederzeit im Panel neu erzeugen; der alte funktioniert sofort nicht mehr.

Basis-URL-Slug

Pfadsegment der Endpoints (Standard acp). Die Basis-URL sieht dann so aus: https://ihr-shop.com/acp.

Signaturprüfung

Wenn aktiviert, prüft das Modul den Signature-Header: ein base64-codierter HMAC-SHA256 des rohen Anfrage-Bodys, berechnet mit dem von der Agenten-Plattform bereitgestellten gemeinsamen Geheimnis.

Bestell-Webhooks

Tragen Sie die Webhook-URL der Plattform und ein Signaturgeheimnis ein. Bei der Bestellerstellung wird ein order_created-Ereignis gesendet, signiert über den Header DataFirefly-Signature.

Delegierte Stripe-Zahlung (optional)

Wenn „Über Stripe belasten“ aktiviert ist und ein Stripe-Secret-Key hinterlegt wurde, wird der beim Abschluss empfangene Shared Payment Token über einen bestätigten Stripe-PaymentIntent belastet, bevor die Bestellung erstellt wird.

Bestellstatus

Wählen Sie den Anfangsstatus (Bestellung ohne Belastung durch das Modul erstellt) und den „bezahlt“-Status (erfolgreiche Stripe-Belastung).

Endpoints

Mit dem Standard-Slug acp:

• POST /acp/checkout_sessions — eine Sitzung erstellen
• POST /acp/checkout_sessions/{id} — aktualisieren (Artikel, Adresse, Versandoption)
• GET /acp/checkout_sessions/{id} — aktuellen Zustand abrufen
• POST /acp/checkout_sessions/{id}/complete — abschließen und Bestellung erstellen
• POST /acp/checkout_sessions/{id}/cancel — stornieren
• GET /acp/feed?page=1&limit=200 — Produkt-Feed

Sitzung erstellen

curl -X POST "https://ihr-shop.com/acp/checkout_sessions" -H "Authorization: Bearer IHR_API_SCHLUESSEL" -H "Content-Type: application/json" -d '{ "items": [ { "id": "42", "quantity": 1 } ] }'

Die Antwort liefert den vollständigen Warenkorbzustand: line_items, totals, fulfillment_options, currency und status. Beträge sind in kleinsten Einheiten (Cent).

Aktualisieren (Adresse, Versand)

curl -X POST "https://ihr-shop.com/acp/checkout_sessions/cs_XXXX" -H "Authorization: Bearer IHR_API_SCHLUESSEL" -H "Content-Type: application/json" -d '{ "fulfillment_option_id": "ship_2" }'

Abschließen

curl -X POST "https://ihr-shop.com/acp/checkout_sessions/cs_XXXX/complete" -H "Authorization: Bearer IHR_API_SCHLUESSEL" -H "Content-Type: application/json" -d '{ "buyer": { "name": "Anna Müller", "email": "anna@beispiel.de" }, "payment_data": { "token": "spt_123", "provider": "stripe" } }'

Bei Erfolg wird eine PrestaShop-Bestellung erstellt und die Antwort enthält ein order-Objekt (id + Permalink).

Authentifizierung und Signatur

Jede Anfrage muss den Header Authorization: Bearer mit dem API-Schlüssel tragen. Wenn die Signaturprüfung aktiviert ist, berechnet das Modul den HMAC-SHA256 des Bodys neu und vergleicht ihn über einen zeitkonstanten Vergleich mit dem Signature-Header. Die Header Idempotency-Key und Request-Id werden in der Antwort zurückgegeben.

Kodierung der Artikel-IDs

Die ACP-item.id folgt dem Format {produkt_id} oder {produkt_id}-{kombination_id}. Beispiel: 42 für ein einfaches Produkt, 42-7 für Kombination 7 des Produkts 42. Dieselbe Kodierung wird im Produkt-Feed verwendet.

Produkt-Feed

Der Endpoint GET /acp/feed (authentifiziert) stellt Ihre aktiven Produkte und deren Kombinationen bereit, mit price, availability, inventory_quantity und enable_checkout. Verwenden Sie page und limit für die Paginierung.

Delegierte Stripe-Zahlung

Bestell-Webhooks

Bei der Bestellerstellung sendet das Modul ein order_created-Ereignis an die konfigurierte URL, mit einem aus dem PrestaShop-Bestellstatus abgeleiteten ACP-Status (created, confirmed, shipped, fulfilled, canceled). Die Nutzlast ist HMAC-signiert.

Eine Agenten-Plattform verbinden

Geben Sie der Plattform (z. B. dem ChatGPT-Instant-Checkout-Onboarding): die Basis-URL, den API-Schlüssel und bei Bedarf das Signaturgeheimnis sowie die Webhook-URL/das Webhook-Geheimnis. Da das Modul der Merchant of Record bleibt, behalten Sie die Kontrolle über Bestand, Preise, Steuern und Zahlung.

Fehlerbehebung

Endpoints liefern eine 404-/HTML-Seite

Aktivieren Sie die sprechenden URLs und leeren Sie den PrestaShop-Cache. Prüfen Sie, ob der Basis-Slug der an die Plattform übergebenen URL entspricht.

401-Antwort

Der API-Schlüssel fehlt oder ist im Authorization-Header falsch, oder die Signatur stimmt nicht mit dem konfigurierten Geheimnis überein.

Die Bestellung wird nicht erstellt

Stellen Sie sicher, dass eine gültige Versandadresse und eine Versandoption vorhanden sind, dass der Bestand ausreicht und — wenn die Stripe-Belastung aktiviert ist — dass der Stripe-Secret-Key korrekt ist.