> 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/adpage-feed-je-eigen-api/technical-specification.md).

# Technische specificatie

Het contract achter AdPage Feed v1: endpoints, velden, de vier regels waaraan een feed moet voldoen, en hoe je die test. Voor de ontwikkelaar die de feed bouwt.

Versie 1.0 · stabiel · vragen: <support@adpage.io>

Dit is het contract waaraan een feed moet voldoen om zonder maatwerk aan beide kanten op AdPage aan te sluiten. Het is geschreven voor de ontwikkelaar die de eindpunten bouwt. Waar de feed voor is, en hoe je hem aansluit zodra hij werkt, staat op [AdPage-feed (je eigen API)](https://docs.adpage.io/data-and-insights/data-and-insights-nl/marketingintegraties/adpage-feed-je-eigen-api.md).

AdPage haalt de gegevens op; jij stuurt nooit iets. De wekelijkse omzet wordt de *doel* van het Marketing Mix Model: de reeks die je advertentiebudget moet verklaren. Daarom is het meetniveau een ISO-week in plaats van een dag of een order, en daarom zijn totalen genoeg.

{% hint style="info" %}
AdPage vraagt nooit om persoonsgegevens, orders, orderregels of schrijfrechten. Drie GET-eindpunten, één sleutel, wekelijkse totalen.
{% endhint %}

## Transport en authenticatie

| Onderwerp       | Vereiste                                                                                                                                                   |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Protocol        | Alleen HTTPS. Redirects worden niet gevolgd, dus de basis-URL moet direct antwoorden.                                                                      |
| Methode         | `GET`                                                                                                                                                      |
| Authenticatie   | Eén statisch geheim in een HTTP-header, bij elk verzoek                                                                                                    |
| Headernaam      | Naar keuze. `Authorization: Bearer <token>` wordt aanbevolen; een eigen naam, zoals `Ocp-Apim-Subscription-Key` in Azure API Management werkt net zo goed. |
| Sleutels        | Geef er twee uit, een primaire en een secundaire, beide tegelijk geldig. Zo wordt rotatie mogelijk zonder onderbreking.                                    |
| Intrekken       | Een sleutel moet binnen enkele minuten kunnen worden ingetrokken.                                                                                          |
| Snelheidslimiet | Minstens 60 verzoeken per minuut.                                                                                                                          |
| Responstijd     | Binnen 60 seconden per verzoek. Zie [Responstijd](#response-time).                                                                                         |
| CORS            | Niet nodig. Elk verzoek is server-to-server.                                                                                                               |

AdPage roept de feed één keer per week aan, op dinsdag om 05:00 UTC, en vraagt elke keer opnieuw om de laatste twee jaar, in blokken van 13 weken: ongeveer 16 verzoeken per run. Direct na het koppelen wordt de historie op dezelfde manier opgehaald.

## Eindpunten

De basis-URL is van jou, bijvoorbeeld `https://api.yourcompany.com`. De onderstaande paden zijn de standaardwaarden; tijdens het koppelen kunnen andere paden worden ingesteld.

### `GET /livez` — bereikbaarheidstest

Geen authenticatie. Antwoordt `200` met:

```json
{ "status": "ok" }
```

Optioneel, maar sterk aanbevolen: zonder dit kan AdPage een storing niet onderscheiden van een sleutelprobleem.

### `GET /adpage/v1/weekly-revenue` — omzet per week per kanaal

| Parameter   | Vereist | Formaat      | Betekenis            |
| ----------- | ------- | ------------ | -------------------- |
| `date_from` | ja      | `YYYY-MM-DD` | Begin van het bereik |
| `date_to`   | ja      | `YYYY-MM-DD` | Einde van het bereik |

```bash
curl -s "https://api.yourcompany.com/adpage/v1/weekly-revenue?date_from=2026-01-01&date_to=2026-03-31" \
  -H "Authorization: Bearer $TOKEN"
```

Respons `200` is een JSON-array met één object per week × kanaal:

```json
[
  {
    "iso_year": 2026,
    "iso_week": 1,
    "week_start": "2025-12-29",
    "week": "2026-W01",
    "channel": "store",
    "revenue_excl_vat": "815883.62",
    "vat": "171257.26",
    "revenue_incl_vat": "987140.88",
    "cnt_receipts": 4590,
    "modified_at": "2026-08-17T02:44:13.885131"
  }
]
```

| Veld               | Type                      | Vereist | Beschrijving                                                                          |
| ------------------ | ------------------------- | ------- | ------------------------------------------------------------------------------------- |
| `iso_year`         | geheel getal              | ja      | ISO-jaar. Kan afwijken van het kalenderjaar van `week_start`.                         |
| `iso_week`         | geheel getal              | ja      | ISO-weeknummer, 1–53                                                                  |
| `week_start`       | datum                     | ja      | De maandag van de ISO-week, `YYYY-MM-DD`                                              |
| `week`             | tekenreeks                | ja      | Bijvoorbeeld `"2026-W01"`                                                             |
| `channel`          | tekenreeks                | ja      | Zie [Kanalen](#channels)                                                              |
| `revenue_excl_vat` | getal of numerieke string | ja¹     | Netto-omzet exclusief btw                                                             |
| `vat`              | getal of numerieke string | nee     | Btw-bedrag                                                                            |
| `revenue_incl_vat` | getal of numerieke string | ja¹     | Netto-omzet inclusief btw                                                             |
| `cnt_receipts`     | geheel getal              | nee     | Aantal bonnen of bestellingen                                                         |
| `currency`         | tekenreeks                | nee     | ISO 4217, standaard `EUR`                                                             |
| `location`         | tekenreeks                | nee     | Winkel- of shoplabel, wanneer er meerdere zijn                                        |
| `postal_area`      | string of `null`          | nee     | Postcodegebied van de **klant**. Zie [Postcode-splitsing](#postcode-split)            |
| `country`          | tekenreeks                | nee     | Land van de **klant**, ISO 3166 alfa-2 (`NL`, `DE`). Leeg betekent `NL`.              |
| `modified_at`      | datumtijd                 | ja      | Wanneer de rij voor het laatst is samengesteld. Zie [de vier regels](#the-four-rules) |

¹ Minstens één van de twee. Beide aanleveren is het beste. Als je alleen het bedrag inclusief btw aanlevert, rekent AdPage het om tegen 21%; laat support weten als een ander tarief geldt.

Bedragen mogen een getal zijn of een numerieke string met een punt als decimaalscheidingsteken (`"815883.62"`). Een lege array (`[]`) is een geldig antwoord en betekent dat er geen gegevens in het bereik zijn.

#### Postcode-splitsing

`postal_area` is optioneel, en het verandert het meetniveau: één rij per week × kanaal × postcodegebied in plaats van week × kanaal. Dit gebruikt AdPage voor regionale analyses en geo-experimenten, en voor een retailer met winkels is dit de enige manier om winkelomzet per regio te zien.

1. **Het is de postcode van de klant, niet van de winkel.** Vier cijfers in Nederland (PC4). Een winkelnaam hoort in `location`.
2. **`null` is een geldige waarde** en betekent dat het niet te herleiden is: een anonieme bon, een gastbestelling, een ongeldige postcode. Die rij telt nog steeds volledig mee voor het wekelijkse totaal. Houd hem; laat hem niet weg.
3. **De gebieden tellen op tot het wekelijkse totaal.** Wijs elke bon vóór het tellen aan precies één gebied toe, zodat omzet en `cnt_receipts` per week en kanaal optellen tot hetzelfde bedrag als zonder de splitsing.
4. **Deduplicatie omvat het gebied**: `(week_start, channel, country, postal_area)`.

Klanten buiten Nederland hebben `country` ook nodig:

| `country`      | `postal_area`                                   | Regionaal niveau                                        |
| -------------- | ----------------------------------------------- | ------------------------------------------------------- |
| `NL` of leeg   | PC4, vier cijfers (`5384`; `5384 AB` werkt ook) | 12 provincies                                           |
| `DE`           | PLZ, vijf cijfers (`52062`)                     | 16 deelstaten                                           |
| elk ander land | niet gelezen                                    | geen — het telt nog steeds mee in het wekelijkse totaal |

Een waarde die niet op een postcode van dat land lijkt, krijgt geen regio. Vijf cijfers zonder `country` zijn daarom **niet** gelezen als een Nederlandse postcode — dat zou stilletjes een Duitse klant in een Nederlandse provincie plaatsen — en de synchronisatie meldt op hoeveel rijen dat van invloed was.

### `GET /adpage/v1/weekly-returns` — retouren per week per kanaal

Zelfde parameters, zelfde weekregels. Dit eindpunt is optioneel: als het antwoordt `404`, schakelt AdPage retouren uit voor deze koppeling en blijft omzet doorlopen.

| Veld                                                    | Type                      | Vereist | Beschrijving                                                                                 |
| ------------------------------------------------------- | ------------------------- | ------- | -------------------------------------------------------------------------------------------- |
| `iso_year`, `iso_week`, `week_start`, `week`, `channel` |                           | ja      | Net als bij omzet                                                                            |
| `return_value_excl_vat`                                 | getal of numerieke string | ja¹     | Retourwaarde exclusief btw, als een **positief** bedrag                                      |
| `return_value_incl_vat`                                 | getal of numerieke string | ja¹     | Retourwaarde inclusief btw, **positief**                                                     |
| `return_items`                                          | geheel getal              | nee     | Aantal geretourneerde items                                                                  |
| `date_basis`                                            | tekenreeks                | **ja**  | `verwerkingsweek` of `bestelweek`. Zie [Retouren en datumgrondslag](#returns-and-date-basis) |
| `currency`, `location`                                  |                           | nee     | Net als bij omzet                                                                            |
| `modified_at`                                           | datumtijd                 | ja      | Net als bij omzet                                                                            |

De Nederlandse waarden `verwerkingsweek` en `besteldatum` worden geaccepteerd voor `date_basis` ook.

## Kanalen

| Waarde        | Betekenis                   | Wat AdPage ermee doet                                                                                            |
| ------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `webshop`     | Online verkopen             | **Vervangt** het wekelijkse cijfer dat AdPage zelf meet via tracking. Het zijn dezelfde verkopen, beter gemeten. |
| `winkel`      | Fysieke winkel, kassa       | **Voegt** toe aan het doel: een andere kant van het bedrijf.                                                     |
| `marketplace` | Bol, Amazon en dergelijke   | **Genegeerd** standaard; kan per klant worden ingeschakeld.                                                      |
| `b2b`         | Zakelijke of dealerverkopen | **Genegeerd** standaard.                                                                                         |

`online` en `e-commerce` worden gelezen als `webshop`; `retail` en `winkel` als `winkel`. Elke andere waarde blijft buiten het doel totdat support het toewijst, en de verbindingstest vermeldt welke kanalen het heeft weggelaten. Schrijf een kanaal elke keer op dezelfde manier, in beide eindpunten.

## De vier regels

Bijna alles wat misgaat met een koppeling als deze gaat mis bij een van deze vier.

### 1. Geef hele ISO-weken terug

Elke ISO-week die het bereik **raakt** komt terug **volledig**. Een week wordt nooit doormidden geknipt.

`date_from=2026-01-01&date_to=2026-03-31` geeft dus 14 weken terug: `2026-W01`, die begint op maandag 29 december 2025, tot en met `2026-W14`, die eindigt op zondag 5 april 2026. Dat is iets meer dan een kalenderkwartaal, en dat is de bedoeling.

Waarom: in een model lijkt een halve week op een week waarin de vraag instortte terwijl het advertentiebudget gelijk bleef, en het model neemt dat volledig serieus. Een grensweek te veel is onschuldig; een halve week niet.

### 2. Dezelfde week levert altijd hetzelfde cijfer op

Aangrenzende bereiken delen hun grensweek: Q1 en Q2 bevatten beide `2026-W14`. AdPage dedupliceert op week en kanaal, plus `location`, `country` en `postal_area` wanneer je ze verstuurt. Niet alleen op de week: dan `winkel` en `webshop` zouden ze elkaar overschrijven.

Voor jou betekent dat: geef een week terug met dezelfde bedragen, ongeacht welk bereik erom vroeg. Een week mag alleen veranderen wanneer de gegevens eronder veranderen, en dan geldt regel 3.

### 3. `modified_at` loopt op wanneer een rij wordt herzien

Wanneer iets verandert in een oude week — een late betaling, een correctie, een herboeking — zet `modified_at` opnieuw. Wanneer niets verandert, laat het met rust.

AdPage vraagt elke week om de laatste twee jaar, dus een correctie komt door. Wanneer dezelfde week twee keer terugkomt met verschillende bedragen, wint de rij met de hogere `modified_at` en de synchronisatie meldt het conflict. Zonder `modified_at`, kan AdPage een correctie niet onderscheiden van een feed die afwijkt.

### 4. Zeg wat in het bedrag zit

De specificatie schrijft geen zakelijke definitie van omzet voor. Er wordt gevraagd om een definitie die consistent en vastgelegd is. Spreek die af voordat je begint:

* Zijn diensten, verzendkosten en cadeaukaarten inbegrepen?
* Zijn kortingen al verrekend?
* Zijn retouren al van de omzet afgetrokken, of verschijnen ze alleen in het retouren-eindpunt?
* Welke btw-grondslag, en welk tarief?

Een voorbeeld van een duidelijk antwoord: alleen artikelregels — geen diensten, geen cadeaubonnen, geen retourkosten of de bijbehorende kortingsregels; retouren alleen in het retouren-eindpunt.

De definitie hoeft niet elegant te zijn; ze moet jaar na jaar hetzelfde blijven. Een definitie die halverwege verandert is voor een model een gebeurtenis die het zal proberen te verklaren.

## Retouren en datumgrondslag

| Waarde            | Betekenis                                                  |
| ----------------- | ---------------------------------------------------------- |
| `verwerkingsweek` | Gegroepeerd per week waarin de retour werd **geboekt**     |
| `bestelweek`      | Gegroepeerd per week van de **oorspronkelijke bestelling** |

Het veld is verplicht omdat het verschil groot en van buitenaf onzichtbaar is. Met `verwerkingsweek`, landt een retour op een order uit week 3 in week 8, dus wekelijkse omzet minus wekelijkse retouren is niet de netto-omzet van die week. Daarom trekt AdPage **niet** retouren standaard van het doel af. Het aftrekken ervan is een bewuste keuze per koppeling.

## Foutafhandeling

| Status                     | Betekenis                                        | Wat AdPage doet                                                                                        |
| -------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `200`                      | OK                                               | Verwerkt de rijen                                                                                      |
| `401`                      | Sleutel ontbreekt of ongeldig                    | Niet opnieuw geprobeerd. De koppeling wordt als mislukt gemarkeerd en de fout verschijnt op de tegel.  |
| `403`                      | Abonnement opgeschort of geblokkeerd door beleid | Hetzelfde                                                                                              |
| `404` op `/weekly-returns` | Eindpunt niet geïmplementeerd                    | Retouren uitgeschakeld; omzet blijft doorlopen                                                         |
| `400`, `422`               | Ongeldige parameters                             | Niet opnieuw geprobeerd                                                                                |
| `429`                      | Snelheidslimiet                                  | Wacht zolang als `Retry-After` zegt (stuur het alstublieft mee), en probeert het daarna opnieuw        |
| `5xx`                      | Storing                                          | Exponentiële backoff, maximaal vier pogingen; daarna wordt het blok opnieuw opgevraagd in twee helften |
| `3xx`                      | Doorverwijzing                                   | Wordt als fout behandeld. Vul de definitieve URL in.                                                   |

### Responstijd

AdPage vraagt telkens om 13 weken. Als een blok niet binnen 60 seconden terugkomt, wordt het niet ongewijzigd opnieuw geprobeerd, maar opnieuw opgevraagd in twee helften, tot aan één enkele week. Dat werkt, maar het is trager. Met de postcode-splitsing kan een respons honderden keren groter zijn, dus daar is dit vooral iets om in de gaten te houden: een API die een kwartaal binnen een halve minuut teruggeeft, wordt in één keer opgehaald.

## Test het zelf

```bash
export TOKEN="your-key"
export BASE="https://api.yourcompany.com"

# 1. Bereikbaar?
curl -s "$BASE/livez"

# 2. Omzet over een kwartaal
curl -s "$BASE/adpage/v1/weekly-revenue?date_from=2026-01-01&date_to=2026-03-31" \
  -H "Authorization: Bearer $TOKEN" | jq 'length, .[0]'

# 3. Grensweken: begint de eerste week VOOR date_from?
curl -s "$BASE/adpage/v1/weekly-revenue?date_from=2026-01-01&date_to=2026-03-31" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.[0].week, .[0].week_start'
# verwacht, bijvoorbeeld: "2026-W01" en "2025-12-29"

# 4. Stabiliteit: dezelfde week uit twee bereiken, hetzelfde bedrag?
for R in "2026-01-01 2026-03-31" "2026-04-01 2026-06-30"; do
  set -- $R
  curl -s "$BASE/adpage/v1/weekly-revenue?date_from=$1&date_to=$2" \
    -H "Authorization: Bearer $TOKEN" \
    | jq -r '.[] | select(.week=="2026-W14") | "\(.week) \(.channel) \(.revenue_incl_vat)"'
done
# beide blokken moeten identiek zijn

# 5. Zonder sleutel hoor je 401 te krijgen
curl -s -o /dev/null -w '%{http_code}\n' "$BASE/adpage/v1/weekly-revenue?date_from=2026-01-01&date_to=2026-01-31"
```

Als je een eigen headernaam gebruikt, vervang `Authorization: Bearer $TOKEN` door die header.

## Checklist

* [ ] Alleen HTTPS, `GET` alleen, geen redirects
* [ ] Sleutel in een header; een primaire en een secundaire sleutel, beide geldig
* [ ] `/livez` zonder authenticatie
* [ ] `/adpage/v1/weekly-revenue` met `date_from` en `date_to`
* [ ] Volledige ISO-weken, grensweken volledig
* [ ] Eén rij per week × kanaal (× `location`) (× `postal_area`)
* [ ] Met `postal_area`: de segmenten tellen op tot het weektotaal, en `null` telt nog steeds mee
* [ ] Klanten buiten Nederland: `country` verstuurd (`DE` met een vijfcijferige postcode)
* [ ] Dezelfde week levert altijd dezelfde bedragen op
* [ ] `modified_at` op elke rij, verhoogd bij revisie
* [ ] `revenue_excl_vat` en/of `revenue_incl_vat`
* [ ] `channel` uit een vaste, consistente set
* [ ] Optioneel: `/adpage/v1/weekly-returns` met de vereiste `date_basis`
* [ ] `Retry-After` op `429`
* [ ] De vastgelegde bedrijfsdefinitie van omzet

Een feed die aan deze lijst voldoet, koppelt zonder maatwerk aan AdPage. Voor een review van je implementatie of een testsleutel van onze kant, neem contact op <support@adpage.io>.


---

# 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/adpage-feed-je-eigen-api/technical-specification.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.
