PS PrestaShop Gemiddeld

Module ChatGPT Checkout PrestaShop (ACP): volledige gids

Installeer en configureer dfaiagent 2.0.0: Agentic Commerce Protocol-endpoint (ACP) voor de platforms voor AI-winkelagenten die u als verkoper hebben toegelaten.

Bijgewerkt Moduleversie 2.0.0

dfaiagent opent in uw winkel een toegangspunt volgens het Agentic Commerce Protocol (ACP), het open protocol van OpenAI en Stripe. Een platform voor AI-winkelagenten dat u als verkoper heeft toegelaten, kan er een betaalsessie aanmaken, adres en levering kiezen en de aankoop afronden: er ontstaat een echte PrestaShop-bestelling met de prijzen, btw, voorraad en vervoerders van uw winkel.

Lees dit vóór elk project. De module schrijft u bij geen enkel platform in en garandeert geen verkoop: toegang hangt ervan af of elk platform uw winkel toelaat. Op 20 november 2026 vermeldt de pagina van OpenAI voor verkopers dat ChatGPT afstapt van een zelfstandige Instant Checkout-ervaring en vooral productfeeds opent, met een wachtlijst. We vonden geen officiële bron die zegt dat Claude of Perplexity ACP-endpoints van verkopers aanroepen. Controleer de voorwaarden van het gekozen platform voordat u het endpoint activeert.

Nieuw in 2.0.0

  • Volledig herschreven. Versie 1.0.0 verwerkte geen enkel verzoek (fatale fout bij het laden van de klassen): updaten wordt sterk aanbevolen.
  • ACP-protocol 2026-04-17 (huidige versie) en 2026-01-30, naast 2025-09-29 (formaat van 1.0.0).
  • Prijzen, btw en voorraad onder vergrendeling herberekend door PrestaShop; voor elke bestelling wordt een gastklant aangemaakt, nooit gekoppeld aan een bestaand account via het e-mailadres.
  • Gecorrigeerde, idempotente betaling met gedeeld Stripe-token, met automatische terugbetaling als de bestelling mislukt.
  • Volledige back-office: dashboard, installatieassistent, catalogus, regels, betaling, webhooks, sessies, logboek, diagnose, beveiliging en een blok op de bestelpagina.
  • Compatibel met PrestaShop 1.7.8; interface in 8 talen (FR, EN, ES, DE, IT, PL, NL, PT).

Vereisten

  • PrestaShop 1.7.8 tot 9.x. Getest op 1.7.8.11 (PHP 7.4), 8.2.1 (PHP 8.1) en 9.1.5 (PHP 8.5), ook in multistore.
  • Winkel via HTTPS: zonder HTTPS antwoordt de API met een JSON-fout, nooit met een doorverwijzing.
  • Vriendelijke URL’s ingeschakeld (Winkelparameters → Verkeer & SEO).
  • Gepubliceerde juridische pagina’s: voorwaarden, privacy, retouren en contact. Ze worden vóór de betaling naar de agent gestuurd.
  • Optioneel: een Stripe-account om het gedeelde token af te schrijven. Begin in testmodus.

Installatie

  1. Back-office → Modules → Een module uploaden, kies dan dfaiagent-2.0.0.zip.
  2. Het menu Bestellingen → AI-agenten (ACP) verschijnt. Het endpoint blijft uit zolang u het niet in de assistent activeert (antwoord 503).

Update vanaf 1.0.0

Upload de zip van 2.0.0 over 1.0.0 heen. Uw integratie blijft werken: de API-sleutel blijft geldig, maar alleen de hash wordt bewaard (de leesbare waarde wordt uit de database gewist); het ondertekeningsgeheim wordt versleuteld; het formaat van 1.0.0 blijft behouden (versie 2025-09-29 als de header ontbreekt, optionele Idempotency-Key, base64-handtekening). Sessies en bestellingen van 1.0.0 verschijnen in de module. De diagnose raadt daarna aan de sleutel te vernieuwen en de 1.0.0-compatibiliteit uit te schakelen.

Installatieassistent

Installatieassistent: URL, API-sleutel, handtekening, betaling, webhook en test met de ingebouwde testagent

De assistent begeleidt u in 7 stappen:

  1. Basis-URL: pad van de endpoints (standaard acp, dus https://uw-winkel.nl/acp) en controle van de vriendelijke URL’s.
  2. API-sleutel: maak per platform een sleutel aan, met een label. Hij begint met dfak_ en wordt maar één keer getoond: geef hem meteen via een veilig kanaal door aan het platform.
  3. Handtekening van verzoeken: genereer een geheim of plak het geheim van het platform. De handtekening is standaard verplicht.
  4. Betaling: gedeeld Stripe-token of bestellingen die „wachten op betaling”.
  5. Bestelwebhook (optioneel): HTTPS-URL van het platform en geheim.
  6. Verbindingstest: de ingebouwde testagent maakt een sessie aan, voegt een adres toe, berekent verzending en btw, leest de sessie en annuleert ze. Er wordt geen betaling of bestelling aangemaakt. Deze stap controleert ook of de publieke URL bereikbaar is.
  7. Activering: open het endpoint. U kunt het op elk moment uitschakelen.

Dashboard

Dashboard van de AI-winkelagenten: gemeten bestellingen, omzet, sessies en API-aanroepen, controlepunten

Het dashboard toont alleen cijfers die in uw winkel gemeten zijn: bestellingen en omzet van agenten, geopende en afgeronde sessies, API-aanroepen en fouten, en de controlepunten die de diagnose meldt.

Getoonde catalogus

Catalogus voor agenten: categorieën, uitgesloten producten, klantengroep en automatische uitsluitingen

Kies de getoonde categorieën, sluit producten uit en stel de klantengroep voor de prijzen in (standaard de groep Gast, gebruikt voor zowel de offerte als de bestelling). Altijd uitgesloten: inactieve, onzichtbare of niet-bestelbare producten, producten zonder getoonde prijs, voorbehouden aan een andere groep of met verplichte personalisatie. Dezelfde regels gelden voor de feed en de betaling: een product dat niet in de feed staat, kan niet gekocht worden.

Landen, vervoerders en limieten

Leveringslanden, vervoerders en levertijden, bestellimieten en juridische pagina’s vóór de betaling

Beperk de leveringslanden en aangeboden vervoerders, geef de levertijd van elke vervoerder op en stel een maximumbedrag per bestelling en een maximumaantal bestellingen per uur in. Kies ook de CMS-pagina’s die als voorwaarden, privacy, retouren en contact naar de agent gaan.

Betaling

Betaling met het gedeelde Stripe-token: idempotente afschrijving, inning, automatische terugbetaling bij fouten

Met Stripe (gedeeld token)

Vul uw geheime Stripe-sleutel in (die wordt versleuteld). Bij het afronden schrijft de module het Shared Payment Token van de agent af, met een idempotentiesleutel die gekoppeld is aan de sessie, het token, het bedrag en de valuta:

  • één afschrijving, ook als het verzoek herhaald wordt of in een time-out loopt;
  • kaart geweigerd: payment_declined, de sessie kan met een ander middel betaald worden;
  • 3-D Secure vereist: de betaalintentie wordt geannuleerd en de agent krijgt requires_3ds;
  • totaal anders dan getoond aan de koper: er wordt niets afgeschreven (price_change);
  • afschrijving gelukt, bestelling mislukt: automatische terugbetaling (of annulering van de autorisatie), gastklant verwijderd, waarschuwing in het logboek en, als u dat inschakelt, per e-mail.

Standaard directe inning. Uitgestelde inning is beschikbaar als optie, maar Stripe documenteert handmatige inning voor gedeelde tokens niet expliciet: overleg met Stripe voordat u ze inschakelt.

De module is getest tegen een gesimuleerde Stripe, niet tegen de echte Stripe. De veldnamen volgen de Stripe-documentatie over gedeelde tokens (API-versie „preview”). Valideer het volledige verloop in de testmodus van Stripe voordat u live gaat.

Zonder Stripe

De bestelling krijgt de status „Wacht op betaling (AI-agent)”, zonder factuur, en er wordt niets afgeschreven. U int daarna met uw eigen betaalmiddel.

Bestelwebhooks

Ondertekende bestelwebhooks, nieuwe pogingen met oplopende wachttijd en verzendgeschiedenis

De module stuurt order_create bij het aanmaken van de bestelling en daarna order_update bij elke statuswijziging of terugbetaling. De body bevat de volledige bestelling (regels, aanpassingen, terugbetaald totaal), zonder persoonsgegevens. Hij wordt ondertekend in de header Merchant-Signature: t=<tijdstempel>,v1=<HMAC-SHA256 hex van "t.body">.

Bij een fout volgen nieuwe pogingen na 1 min, 5 min, 30 min, 2 u, 6 u en 24 u, daarna „niet afgeleverd” met een waarschuwing. Alleen publieke HTTPS-URL’s worden aanvaard: privé- en lokale adressen, cloudmetadata, inloggegevens in de URL en gevoelige poorten worden geweigerd, en doorverwijzingen worden niet gevolgd.

Sessies en logboek

Door agenten geopende betaalsessies: status, protocolversie, getoond totaal en bestelling

De sessielijst toont voor elke door een agent geopende sessie de status, de protocolversie, het getoonde totaal en de aangemaakte bestelling. Sessiegegevens worden versleuteld en 24 u na afloop gewist.

Logboek van verzoeken en gebeurtenissen met gemaskeerde persoonsgegevens

Het logboek registreert verzoeken en gebeurtenissen (betalingen, terugbetalingen, webhooks, waarschuwingen) met gemaskeerde persoonsgegevens. Sleutels staan er nooit in: alleen hun prefix wordt genoteerd.

Bestellingen geplaatst door een agent

Bestelpagina: herkomst AI-agent, betaling, Stripe-terugbetaling en annulering met melding aan het platform

De bestelling krijgt het privébericht „bestelling geplaatst door een AI-winkelagent” en een blok op haar pagina: Stripe-betaling, volledige of gedeeltelijke terugbetaling, annulering. Het aanmaken van een PrestaShop-creditnota start ook de Stripe-terugbetaling. Elke actie stuurt order_update naar het platform. De koper ontvangt de standaard-e-mails van PrestaShop.

Beveiliging

Beveiliging: noodstop, gehashte API-sleutels met rotatie zonder onderbreking, handtekening en beschermingen
  • API-sleutels van 256 bits, gehasht opgeslagen, in constante tijd vergeleken. Rotatie zonder onderbreking: de oude sleutel blijft naar keuze 0 u tot 7 dagen geldig. Onmiddellijke intrekking.
  • Geheimen (handtekening, webhook, Stripe) versleuteld met AES-256-GCM.
  • Verplichte handtekening, venster van 5 minuten, rotatie van het geheim met overgangsperiode.
  • Limieten: verzoeken per sleutel, bescherming tegen brute force per IP (429 + Retry-After), body van maximaal 64 KB en JSON van maximaal 32 niveaus.
  • Geen CORS, geen cookies, headers nosniff en no-store.
  • Noodstop: schakelt het endpoint met één klik uit (503 voor agenten).
  • Rechten van de back-office worden gerespecteerd (bekijken / bewerken); in multistore zijn instellingen, sleutels, sessies en cijfers per winkel gescheiden.

Diagnose

Diagnose: vriendelijke URL’s, HTTPS, sleutels, handtekening, betaling, webhooks, catalogus en juridische pagina’s

De diagnose controleert vriendelijke URL’s, HTTPS, sleutels (oude sleutels die nog actief zijn, 1.0.0-compatibiliteit), handtekening, betaling, mislukte webhooks, de getoonde catalogus en de juridische pagina’s.

API-referentie

Met het standaardpad acp:

  • POST /acp/checkout_sessions: een sessie aanmaken
  • GET /acp/checkout_sessions/{id}: opvragen
  • POST /acp/checkout_sessions/{id}: bijwerken (artikelen, adres, leveringsoptie, koper)
  • POST /acp/checkout_sessions/{id}/complete: afronden en de bestelling aanmaken
  • POST /acp/checkout_sessions/{id}/cancel: annuleren
  • GET /acp/feed?limit=200&after=…: productfeed (gepagineerde JSON); /acp/feed.jsonl in JSON Lines; ?format=legacy&page=1 voor het formaat van 1.0.0

Headers

  • Authorization: Bearer UW_API_SLEUTEL (verplicht).
  • API-Version: 2026-04-17 (of 2026-01-30, 2025-09-29). Ontbrekend of onbekend: 400 met de lijst supported_versions.
  • Idempotency-Key: verplicht bij elke POST. Zelfde sleutel en zelfde body: herhaald antwoord (Idempotent-Replayed: true); andere body: 422 idempotency_conflict (409 in 2025-09-29 en 2026-01-30); lopend verzoek: 409 met Retry-After.
  • Signature: t=<unix-tijdstempel>,v1=<HMAC-SHA256 hex van "t.ruwe body">. De ACP-specificatie definieert geen handtekening voor checkoutverzoeken: de module past de handtekening toe die ze voor webhooks definieert.
  • Accept-Language: taal van de berichten die naar de koper gaan.

Voorbeeld: een sessie aanmaken

curl -X POST "https://uw-winkel.nl/acp/checkout_sessions" -H "Authorization: Bearer UW_API_SLEUTEL" -H "API-Version: 2026-04-17" -H "Idempotency-Key: 6f1c2a90-create-1" -H "Signature: t=1795000000,v1=…" -H "Content-Type: application/json" -d '{"currency":"eur","line_items":[{"id":"42-7","quantity":1}],"fulfillment_details":{"name":"Alex de Vries","address":{"name":"Alex de Vries","line_one":"Kerkstraat 12","city":"Utrecht","postal_code":"3511 LX","country":"NL"}}}'

Het antwoord bevat de volledige sessie: line_items, fulfillment_options, totals (in de kleinste munteenheid), messages, links (juridische pagina’s) en status. De agent kiest daarna een optie met selected_fulfillment_options en roept complete aan met buyer en payment_data (gedeeld token in instrument.credential). Bij succes bevat het antwoord een order-object.

Artikel-ID’s

42 voor een eenvoudig product, 42-7 voor combinatie 7 van product 42. De feed gebruikt dezelfde codering in item_id.

Productfeed

De feed gebruikt de veldnamen van de productfeed van OpenAI (item_id, title, description, url, brand, image_url, availability, price in het formaat „12.50 EUR”, gtin, mpn, sale_price, juridische pagina’s…). Hij toont alleen producten die de agent ook kan kopen. Met de header ETag volgt een 304-antwoord als er niets veranderd is.

Bekende beperkingen

  • Gedelegeerde 3-D Secure wordt niet ondersteund (de agent krijgt requires_3ds).
  • Kortingscodes van de agent worden niet toegepast (waarschuwing discount_code_invalid).
  • Gesplitste leveringen over meerdere vervoerders worden niet aangeboden.
  • De tussenliggende ACP-versies 2025-12-12 en 2026-01-16 worden expliciet geweigerd.

Probleemoplossing

503 service_unavailable

Het endpoint is niet geactiveerd of de noodstop staat aan. Rond de assistent af of activeer het endpoint opnieuw onder Beveiliging.

404 of HTML-pagina

Schakel vriendelijke URL’s in, leeg de PrestaShop-cache en controleer of het pad overeenkomt met de URL die aan het platform is gegeven.

401

Sleutel ontbreekt, is fout, ingetrokken of verlopen na rotatie, of de handtekening is ongeldig (geheim, tijdstempel buiten het venster van 5 minuten, gewijzigde body). Het logboek vermeldt de reden.

400 missing_api_version

De agent stuurt de header API-Version niet mee. Gaat het om een 1.0.0-integratie, laat de 1.0.0-compatibiliteit dan aan tijdens de migratie.

Product geweigerd of niet in de feed

Controleer of het actief, zichtbaar, bestelbaar en op voorraad is, in een getoonde categorie staat, toegankelijk is voor de gekozen groep en geleverd kan worden in het land van de koper.

De verbindingstest meldt „niet bereikbaar”

De server kan zijn eigen publieke URL niet bereiken (firewall, interne DNS, lokale omgeving). De tests van de ingebouwde agent blijven geldig; controleer de toegang van buitenaf.

Was deze pagina nuttig?

Loopt u nog vast? Neem contact op met support