> For the complete documentation index, see [llms.txt](https://docs.adpage.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.adpage.io/data-and-insights/data-and-insights-nl/marketingintegraties/craft-commerce.md).

# Craft Commerce

Koppel Craft Commerce voor wekelijkse omzet en de postcodegegevens waarop het geomodel draait, via een kleine read-only feed op je eigen shop.

Koppel Craft Commerce zodat AdPage de orderomzet en de regio waarnaar een bestelling is verzonden kan lezen. Anders dan bij de andere webshopintegraties hoef je geen inloggegevens aan te maken in een beheerpagina: je shop biedt een klein alleen-lezen endpoint aan dat AdPage vervolgens uitleest.

AdPage leest alleen.

{% hint style="info" %}
Werkt met **Craft Commerce 3, 4 en 5**. Geverifieerd met Craft 5.11 en Commerce 5.7.
{% endhint %}

### Waarom deze anders werkt

Shopify, Shopware, Magento en Lightspeed leveren allemaal een API voor het lezen van bestellingen. Craft Commerce doet dat niet — bestellingen maken geen deel uit van het GraphQL-schema, en er is geen REST-equivalent. Er is niets waar je een connector op kunt richten.

In plaats van een connector is er dus een contract: één endpoint, gedefinieerd door AdPage, dat je shop aanbiedt. Je installeert een bestand dat wij leveren; er hoeft geen eigen code te worden geschreven.

Dit betekent dat er **eerst werk aan jouw kant is voordat er gegevens stromen**. Het is klein — 15 tot 30 minuten voor degene die de site beheert, inclusief een deploy — maar er is een ontwikkelaar voor nodig, niet een admin-login.

### Wat AdPage vraagt, en wat het niet vraagt

| Gevraagd om                             | Nooit gevraagd om                     |
| --------------------------------------- | ------------------------------------- |
| Besteldatum en totaalbedrag             | Bestellijnen of producten             |
| Land, postcode en plaats van de zending | Namen of adressen van klanten         |
| Het domein van de bestel-e-mail         | Volledige e-mailadressen              |
| Leesrechten via één sleutel             | Schrijfrechten van welke aard dan ook |

Het e-maildomein wordt alleen voor één ding gebruikt: het herkennen van marketplace-bestellingen, die binnenkomen via een proxyadres van bol.com of Amazon. Het domein is daarvoor genoeg, dus het adres zelf verlaat je shop nooit.

De postcode wordt wel meegestuurd, want dat **is** het geografische signaal dat het model gebruikt. Behandel de sleutel als een echt geheim en serveer het endpoint via HTTPS.

### Twee manieren om te installeren

**Element API (aanbevolen).** Een gratis Craft-plugin van de eerste partij plus één configuratiebestand. Geen eigen PHP.

**Een kleine module.** Twee bestanden in je `modules/` map. Voor shops die liever geen plugin toevoegen — en de eenvoudigere route als `allowAdminChanges` is `false` in productie, omdat het projectconfig niet aanraakt.

Beide leveren precies hetzelfde. AdPage kan het verschil niet zien.

### Ondertekende verzoeken

Naast de sleutel bevat elke oproep die AdPage doet twee extra headers:

```
X-AdPage-Timestamp: 1790000000
X-AdPage-Signature: <hex>
```

De handtekening is een HMAC-SHA256 over vier regels — methode, pad, gesorteerde querystring en de timestamp — met de feedsleutel als geheim. Je shop berekent die opnieuw en vergelijkt. Het tijdvenster van de timestamp is vijf minuten in beide richtingen, dus een oproep die van de draad is onderschept kan de volgende dag niet opnieuw worden afgespeeld.

De bestanden die wij leveren doen dit al. Ze **controleren een handtekening wanneer die aanwezig is**, maar alleen **vereisen** er één zodra je instelt:

```
ADPAGE_FEED_REQUIRE_SIGNATURE=true
```

Die volgorde is bewust: installeren, in je logs bevestigen dat ondertekende oproepen binnenkomen en worden geaccepteerd, en pas daarna inschakelen. Er is geen moment waarop beide kanten tegelijk moeten veranderen.

### Craft verbinden in AdPage

{% stepper %}
{% step %}

#### Open de tegel

Ga naar **Integraties**, selecteer de container en open de **Craft Commerce** tegel. Kies een installatiemethode.

<figure><img src="https://3085749494-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FK5kjEu8mwstNkOrvFl6S%2Fuploads%2FZxMacjTZG29rjy1wRznf%2Fintegrations-craft-commerce-tile-en.webp?alt=media" alt="Craft Commerce tile opened with the feed URL field"><figcaption><p>De Craft Commerce-tegel op de pagina Integraties.</p></figcaption></figure>
{% endstep %}

{% step %}

#### Genereer de sleutel

AdPage genereert de sleutel voor je en toont de `.env` regel om te plakken. Je verzint er geen zelf en er hoeft niets te worden overgetypt.
{% endstep %}

{% step %}

#### Geef het aan je ontwikkelaar

Als je dit niet zelf doet, genereer dan een **deellink**. Het opent een pagina met de instructies, de sleutel en de bestanden erop — alles wat nodig is, niets meer.

De link is 14 dagen geldig, kan op elk moment worden ingetrokken, en het genereren van een nieuwe link trekt de oude in. AdPage laat zien hoe vaak die is geopend.
{% endstep %}

{% step %}

#### Controleer de installatie

Vul de URL van je shop in — de root, `https://yourshop.nl`, zonder het endpointpad — en selecteer **Controleer installatie**.

AdPage roept het endpoint aan en rapporteert wat het ziet: of het antwoord geeft, of de sleutel wordt geaccepteerd, hoeveel bestellingen er in het venster zitten, welk aandeel daarvan een postcode heeft, de valuta en hoeveel geschiedenis er beschikbaar is.
{% endstep %}

{% step %}

#### Haal de geschiedenis binnen

Voer de backfill uit om twee jaar aan bestellingen op te halen in blokken van vier weken. Het draait op de achtergrond; je kunt de pagina sluiten.

Twee jaar is ongeveer 26 blokken, verspreid over enkele minuten in plaats van in één run uitgevoerd — zie *Hoe vaak AdPage je shop aanroept* hieronder.
{% endstep %}
{% endstepper %}

### Wat je krijgt

Wekelijkse orderomzet als de waarde die het **Marketing Mix Model** verklaart, en week × provincie-omzet voor het **geomodel** dat regionale advertentielift meet.

Als je shop via meerdere winkels of sites verkoopt — bijvoorbeeld een B2B-kanaal naast de consumentenwinkel — kunnen die worden gescheiden, wat belangrijk is omdat B2B-bestellingen niet worden gedreven door de advertenties in je rapporten.

### Hoe vaak AdPage je shop aanroept

Er staat nooit meer dan één verzoek tegelijk open, en het tempo is bewust laag.

|                          |                             |
| ------------------------ | --------------------------- |
| Tussen twee pagina's     | 300 ms                      |
| Tussen twee blokken      | 2 s                         |
| Blokken per run          | 6, daarna een minuut stilte |
| Time-out van het verzoek | 30 s                        |

De backfill van twee jaar spreidt zich dus over ongeveer vijf minuten met tussendoor pauzes, in plaats van als één ononderbroken run binnen te komen.

Zodra de geschiedenis binnen is, is de enige terugkerende oproep **Maandag om 02:00 UTC** — 03:00 of 04:00 in Amsterdam, afhankelijk van het seizoen. Dat tijdstip is gekozen om ruim buiten de ochtend- en einde-dagpieken te vallen die de meeste shops zien.

De wekelijkse run leest de **laatste drie weken**opnieuw in, niet alleen de laatste. Een bestelling kan achteraf worden afgerond of gecorrigeerd, en dat verandert een weektotaal met terugwerkende kracht; alleen de afgelopen week lezen zou die correcties blijvend missen. Drie weken vormen één blok van vier weken, dus slechts een handvol verzoeken, en de schrijfoperatie is idempotent.

**Wanneer je server het moeilijk heeft**

| Situatie                             | Wat AdPage doet                                                                                                 |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| Timeout, 429 of 5xx                  | Opnieuw proberen, maximaal drie pogingen, met 2 en daarna 8 seconden wachten                                    |
| `Retry-After` in de respons          | Volgt jouw wachttijd in plaats van die van ons, met een maximum van 30 s                                        |
| 4xx anders dan 429                   | Geen herhaling. Een verkeerde sleutel of een ontbrekend endpoint zal bij de derde poging niet anders antwoorden |
| Drie blokken achter elkaar mislukken | De run wordt afgebroken. De job blijft waar die is en de volgende run is een minuut later                       |

Die laatste rij is het belangrijkst: een server die net is omgevallen krijgt de rest van het venster niet direct achter elkaar over zich heen.

### De cijfers lezen

**Totalen zijn inclusief btw.** `totalPrice` in Craft is het ordertotaal inclusief btw en verzending, overeenkomstig hoe Magento, Shopware en Lightspeed rapporteren. Het model verklaart de omzet die je shop binnenhaalt, niet de productmarge.

**De postcode is het enige regionale signaal dat er is.** Craft bouwt adressen op een internationale adresbibliotheek, en het adresformaat voor Nederland heeft geen provincieveld — dat van Duitsland ook niet. Dus komt het regio-veld bij elke Nederlandse bestelling altijd leeg terug. Dat is correct gedrag, geen foutieve configuratie.

AdPage leidt de provincie daarentegen af uit de postcode. Het gevolg is belangrijk: **als verzendpostcodes ontbreken, is er geen fallback en geen geomodel.** Daarom is postcode-dekking de ene controle die moet slagen.

**Winkelwagens worden uitgesloten.** Alleen afgeronde bestellingen tellen mee. Een achtergelaten winkelmandje dat als omzet zou meetellen, zou het model een vraagpiek tonen die nooit heeft plaatsgevonden.

**Een verse Commerce-shop staat standaard op USD ingesteld.** Als je valutacontrole faalt, is die standaard waarschijnlijk nooit gewijzigd. AdPage converteert niet stilzwijgend.

**De tijdzone van de shop bepaalt de week.** Een bestelling die net na middernacht lokale tijd wordt geplaatst valt in UTC op de vorige dag, waardoor die in de vorige ISO-week kan terechtkomen. Stel de tijdzone in zodat die overeenkomt met waar je handelt.

### Problemen oplossen

**404 op het endpoint.** Bij Element API moet het bestand exact heten `config/element-api.php` — geen enkele andere naam wordt gelezen, en een verkeerde naam mislukt stilletjes. Controleer bij de module of die is geregistreerd onder `bootstrap` in `config/app.php` en dat `composer dump-autoload` is uitgevoerd.

**403.** De sleutel komt niet overeen, of `ADPAGE_FEED_KEY` is leeg op de server. De meeste deploys herladen niet `.env` zonder herstart, en dit is verreweg de meest voorkomende oorzaak.

**403 direct na het inschakelen `ADPAGE_FEED_REQUIRE_SIGNATURE`.** Controleer eerst de serverklok. Het tijdvenster van de timestamp is vijf minuten in beide richtingen, dus een host waarvan de klok verder dan dat is verlopen weigert elke oproep terwijl de sleutel prima is. De vlag terugzetten naar `false` bevestigt of dat is wat je ziet.

**500 op de hele site, niet alleen op het endpoint.** Craft laadt de Element API-configuratie terwijl plugins worden geladen, vóór het routeren — dus een fatale fout in dat bestand legt de shop plat, niet alleen de feed. Voer `php -l config/element-api.php` uit en laad één gewone pagina voordat je naar productie uitrolt.

**`plugin/install` mislukt in productie.** `allowAdminChanges` is `false`, wat de aanbevolen productie-instelling is. Installeer op een ontwikkelomgeving, commit je projectconfiguratie en laat productie die oppikken via `composer install`. Of gebruik de module, die projectconfiguratie volledig vermijdt.

**Lege data terwijl er bestellingen zijn.** Bijna altijd het datumbereik: de einddatum is exclusief. Controleer ook of de bestellingen afgerond zijn.

**Elke regio is leeg.** Verwacht — zie *De cijfers lezen* hierboven. Controleer in plaats daarvan de postcode-dekking.

**Alle bedragen zijn €0,00.** De shop heeft geen geldige prijzen, of in Commerce 5 is de `basePrice` van de variant nooit ingevuld. Commerce 5 heeft variantprijzen verplaatst: `basePrice` is het veld dat je instelt, terwijl `price` afgeleid en alleen-lezen werd — en schrijven naar het alleen-lezen veld wordt zonder melding opgeslagen maar heeft geen effect.

Nog steeds vastgelopen? Neem contact op met <support@adpage.io> met de container en de shop-URL — nooit de sleutel.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.adpage.io/data-and-insights/data-and-insights-nl/marketingintegraties/craft-commerce.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
