Module ChatGPT Checkout PrestaShop (ACP): volledige gids

Deze module verandert uw PrestaShop-winkel in een agentic-commerce-backend conform het Agentic Commerce Protocol (ACP), de open standaard gedragen door OpenAI en Stripe. Een AI-agent (ChatGPT, Claude, Perplexity) kan uw producten ontdekken via een geauthenticeerde feed, een betaalsessie aanmaken en de aankoop afronden — wat een echte PrestaShop-bestelling in uw winkel aanmaakt.

Vereisten

• PrestaShop 8.0 tot 9.x (compatibel met multistore).
• Winkel geserveerd via HTTPS (het protocol vereist het, de endpoints forceren SSL).
• Vriendelijke URL’s ingeschakeld (SEO & URL’s → URL-herschrijving): de REST-paden hangen ervan af.
• Een Stripe-account als u de gedelegeerde betaling wilt activeren (optioneel).

Installatie

1. Back-office → Modules → Een module uploaden, en selecteer het archief dfaiagent.zip.
2. Schakel de vriendelijke URL’s in als dat nog niet is gebeurd.
3. Open de configuratie van de module: kopieer de basis-URL en de API-sleutel voor de onboarding van het agentische platform.

Configuratie

API-sleutel (Bearer)

Bij de installatie wordt een API-sleutel gegenereerd. De agents authenticeren zich met de header Authorization: Bearer UW_API_SLEUTEL. U kunt de sleutel op elk moment vanuit het paneel regenereren; de oude werkt dan onmiddellijk niet meer.

Slug van de basis-URL

Padsegment van de endpoints (standaard acp). De basis-URL ziet er dan uit als https://uw-winkel.com/acp.

Handtekeningverificatie

Indien ingeschakeld verifieert de module de header Signature: een HMAC-SHA256 van de ruwe body van het verzoek, base64-gecodeerd, berekend met het gedeelde geheim dat het agentische platform levert.

Bestelwebhooks

Vul de webhook-URL van het platform en een handtekeninggeheim in. Bij het aanmaken van een bestelling wordt een event order_created gepusht, ondertekend via de header DataFirefly-Signature.

Gedelegeerde Stripe-betaling (optioneel)

Als “Innen via Stripe” is ingeschakeld en een geheime Stripe-sleutel is ingevuld, wordt het bij de afronding ontvangen shared payment token geïnd via een bevestigde Stripe PaymentIntent, vóór het aanmaken van de bestelling.

Bestelstatussen

Kies de beginstatus (bestelling aangemaakt zonder inning door de module) en de status “betaald” (Stripe-inning geslaagd).

Endpoints

Met de standaardslug acp:

• POST /acp/checkout_sessions — een sessie aanmaken
• POST /acp/checkout_sessions/{id} — bijwerken (artikelen, adres, verzendoptie)
• GET /acp/checkout_sessions/{id} — de huidige status raadplegen
• POST /acp/checkout_sessions/{id}/complete — afronden en de bestelling aanmaken
• POST /acp/checkout_sessions/{id}/cancel — annuleren
• GET /acp/feed?page=1&limit=200 — catalogusfeed

Een sessie aanmaken

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

Het antwoord geeft de volledige status van de winkelwagen terug: line_items, totals, fulfillment_options, currency en status. De bedragen zijn in kleinste eenheden (centen).

Bijwerken (adres, verzending)

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

Afronden

curl -X POST "https://uw-winkel.com/acp/checkout_sessions/cs_XXXX/complete" -H "Authorization: Bearer UW_API_SLEUTEL" -H "Content-Type: application/json" -d '{ "buyer": { "name": "Marie Martin", "email": "marie@voorbeeld.nl" }, "payment_data": { "token": "spt_123", "provider": "stripe" } }'

Bij succes wordt een PrestaShop-bestelling aangemaakt en bevat het antwoord een object order (id + permanente link).

Authenticatie en handtekening

Elk verzoek moet de header Authorization: Bearer met de API-sleutel dragen. Is de handtekeningverificatie ingeschakeld, dan herberekent de module de HMAC-SHA256 van de body en vergelijkt ze die met de header Signature via een vergelijking in constante tijd. De headers Idempotency-Key en Request-Id worden in het antwoord teruggegeven.

Codering van de artikel-identifiers

De ACP-item.id volgt het formaat {product_id} of {product_id}-{variant_id}. Voorbeeld: 42 voor een eenvoudig product, 42-7 voor variant 7 van product 42. Dezelfde codering wordt in de catalogusfeed gebruikt.

Catalogusfeed

Het endpoint GET /acp/feed (geauthenticeerd) toont uw actieve producten en hun varianten, met price, availability, inventory_quantity en enable_checkout. Gebruik page en limit voor de paginering.

Gedelegeerde Stripe-betaling

Bestelwebhooks

Bij het aanmaken van een bestelling verstuurt de module een event order_created naar de geconfigureerde URL, met een ACP-status afgeleid van de PrestaShop-bestelstatus (created, confirmed, shipped, fulfilled, canceled). De payload wordt ondertekend via HMAC.

Een agentisch platform aansluiten

Geef aan het platform (bijvoorbeeld de onboarding van ChatGPT Instant Checkout) door: de basis-URL, de API-sleutel, en zo nodig het handtekeninggeheim en de webhook-URL/het webhookgeheim. De module blijft de referentieverkoper: u houdt de controle over de voorraad, de prijzen, de belastingen en de betaling.

Probleemoplossing

De endpoints geven een 404-pagina / HTML terug

Schakel de vriendelijke URL’s in en leeg de PrestaShop-cache. Controleer of de basisslug overeenkomt met de aan het platform doorgegeven URL.

401-antwoord

De API-sleutel ontbreekt of is fout in de header Authorization, of de handtekening komt niet overeen met het geconfigureerde geheim.

De bestelling wordt niet aangemaakt

Controleer of een geldig leveringsadres en een verzendoptie zijn aangeleverd, of de voorraad toereikend is, en — als de Stripe-inning is ingeschakeld — of de geheime Stripe-sleutel correct is.