API-documentatie

1. Log in en ga naar Integraties → API-sleutels. Daarvoor heeft u de teampermissie Integraties nodig.
2. Maak een sleutel met een naam, de scopes die uw koppeling nodig heeft en een looptijd. Kopieer de sleutel meteen: u ziet hem maar één keer.
3. Zet de sleutel in een omgevingsvariabele en vraag uw brochures op:

curl https://slimfolderen.nl/api/v1/brochures?status=active \
  -H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
  -H "Accept: application/json"

Basis-URL: https://slimfolderen.nl/api/v1. Stuur bij elk verzoek Accept: application/json mee, dan krijgt u ook fouten als JSON terug.

Stuur de sleutel mee als bearer-token: Authorization: Bearer 12|Xh3k…. Een sleutel werkt namens de collega die hem aanmaakte. Orders komen op diens naam en volgen diens rechten. Een sleutel van een beheerder ziet alle orders van het bedrijf, andere rollen alleen hun eigen orders.

Een sleutel kan alleen de endpoints aanroepen waarvoor hij een scope heeft:

Uw tegoed, team, instellingen, andere API-sleutels en betalingen zijn nooit bereikbaar met een API-sleutel, ook niet met alle scopes. Kies per sleutel een looptijd van 30 dagen tot een jaar, of laat hem niet verlopen. Trek een sleutel in zodra u hem niet meer gebruikt; in het portaal ziet u wanneer elke sleutel voor het laatst is gebruikt.

• GET/brochures

  Brochures, nieuwste eerst. Filters: status, format, search.

  Scope: brochures:read

• GET/brochures/{id}

  Eén brochure.

  Scope: brochures:read

• POST/orders/estimate

  Kosten berekenen zonder iets te versturen.

  Scope: orders:create

• POST/orders

  Eén order plaatsen (of een oplage naar één adres).

  Scope: orders:create

• POST/orders/batch

  Dezelfde brochure naar maximaal 100 ontvangers.

  Scope: orders:create

• GET/orders

  Orders, nieuwste eerst. Filters: status, source, brochure_id, external_reference, date_from, date_to.

  Scope: orders:read

• GET/orders/{id}

  Eén order met statusgeschiedenis.

  Scope: orders:read

• GET/campaigns

  Webhook-campagnes. Filter: active.

  Scope: campaigns:read

• GET/campaigns/{id}

  Eén campagne.

  Scope: campaigns:read

Lijsten zijn gepagineerd: de items staan in data, met current_page, last_page en total ernaast. Gebruik page en per_page (maximaal 100).

Een order kost credits uit uw wallet: drukkosten per pagina plus verzendkosten per adres. Bereken de kosten eerst als u ze wilt tonen of controleren:

curl -X POST https://slimfolderen.nl/api/v1/orders/estimate \
  -H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"brochure_id": "9d3c4a52-7f1e-4b8a-9c61-2f0e8b7a1d34", "recipient_country": "NL"}'

{
  "print_credits": 10,
  "shipping_credits": 12,
  "total_credits": 22,
  "paper": { "key": "normal", "label": "Standaard", "cover_gsm": 120, "inner_gsm": 100, "credits_per_page": 5 },
  "estimated_euro": 4.4
}

Plaats daarna de order. Alleen brochures met status active kunnen worden verstuurd. Het land is standaard NL.

curl -X POST https://slimfolderen.nl/api/v1/orders \
  -H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2b8e-1d4a-4f0e-9b3a-2c7d5e8f9a10" \
  -d '{
    "brochure_id": "9d3c4a52-7f1e-4b8a-9c61-2f0e8b7a1d34",
    "recipient_name": "Jan Jansen",
    "recipient_company": "Jansen Installatietechniek B.V.",
    "recipient_address": "Keizersgracht 1",
    "recipient_postal_code": "1015 CJ",
    "recipient_city": "Amsterdam",
    "recipient_country": "NL",
    "external_reference": "crm-4711"
  }'

HTTP/1.1 201 Created

{
  "message": "Brochure succesvol ingepland voor verzending!",
  "order": {
    "id": "0b8f3f9e-2c4d-4e1a-8f57-6a9d2e1c7b40",
    "status": "queued",
    "quantity": 1,
    "total_credits": 22,
    "recipient_name": "Jan Jansen",
    "external_reference": "crm-4711",
    "brochure": "Productbrochure 2026",
    "created_at": "2026-10-27T09:15:02.000000Z"
  },
  "credit_balance": 978
}

Met external_reference (maximaal 100 tekens) geeft u de order uw eigen kenmerk mee, bijvoorbeeld een CRM- of ordernummer. Het komt terug in elk antwoord en u zoekt er orders mee op. De Idempotency-Key maakt het veilig om het verzoek na een time-out opnieuw te sturen; zie Veilig opnieuw proberen.

Voor meerdere ontvangers gebruikt u POST /orders/batch met een lijst recipients, elk met een eigen external_reference als u wilt. Ontvangers op hetzelfde adres gaan samen in één envelop. Het antwoord is 201 als alles gelukt is en 207 als een deel mislukte; die ontvangers staan in failed, met hun index en external_reference.

curl https://slimfolderen.nl/api/v1/orders/0b8f3f9e-2c4d-4e1a-8f57-6a9d2e1c7b40 \
  -H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
  -H "Accept: application/json"

import { randomUUID } from 'node:crypto';

// Eén sleutel per order. Bewaar hem en gebruik dezelfde bij elke nieuwe poging.
const idempotencyKey = randomUUID();

const response = await fetch('https://slimfolderen.nl/api/v1/orders', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SLIMFOLDEREN_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': idempotencyKey,
  },
  body: JSON.stringify({
    brochure_id: '9d3c4a52-7f1e-4b8a-9c61-2f0e8b7a1d34',
    recipient_name: 'Jan Jansen',
    recipient_address: 'Keizersgracht 1',
    recipient_postal_code: '1015 CJ',
    recipient_city: 'Amsterdam',
    external_reference: 'crm-4711',
  }),
});

const data = await response.json();
if (!response.ok) {
  // 422: data.errors per veld, bijvoorbeeld data.errors.credits bij te weinig tegoed
  throw new Error(data.message);
}
console.log(data.order.id, data.order.status);

Een geplaatste order wordt gedrukt en kost tegoed. Krijgt u geen antwoord, bijvoorbeeld door een time-out, dan weet u niet of de order er al staat. Stuur daarom bij POST /orders en POST /orders/batch een Idempotency-Key mee: een eigen, unieke waarde per order of batch, bijvoorbeeld een UUID. Probeer het daarna gerust opnieuw met dezelfde sleutel en dezelfde body.

• Dezelfde sleutel en dezelfde body geven 24 uur lang het eerste antwoord terug: dezelfde status en body, met de header Idempotent-Replayed: true. Er komt geen tweede order en er wordt niets extra afgeschreven. Bij een batch met een 207 worden de gelukte ontvangers dus niet opnieuw verstuurd.
• De sleutel geldt per API-sleutel. Dezelfde sleutel met een andere body of op een ander endpoint geeft een 422.
• Loopt het eerste verzoek nog, dan krijgt u een 409 met Retry-After. Wacht dat aantal seconden en probeer het opnieuw.
• Een 4xx wordt niet bewaard, want dan is er niets aangemaakt. Na bijvoorbeeld opwaarderen of het verbeteren van een veld gebruikt u dezelfde sleutel opnieuw.
• Een 5xx wordt wel bewaard, want een batch kan dan al deels verstuurd zijn. Een 409 zonder Retry-After betekent dat het eerste verzoek is afgebroken. Kijk in beide gevallen met external_reference wat er staat en verstuur de rest met een nieuwe sleutel.

HTTP/1.1 201 Created
Idempotent-Replayed: true

{ ...hetzelfde antwoord als de eerste keer... }

curl "https://slimfolderen.nl/api/v1/orders?external_reference=crm-4711" \
  -H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
  -H "Accept: application/json"

Fouten komen terug als JSON met een message. Bij een 422 staat per veld in errors wat er mis is.

• 401Geen, een ongeldige, verlopen of ingetrokken sleutel.
• 403De sleutel mist de scope (zie required_scopes), het endpoint is niet bereikbaar voor API-sleutels, of de eigenaar van de sleutel heeft er geen recht op.
• 404Bestaat niet of hoort niet bij uw bedrijf.
• 409Een verzoek met dezelfde Idempotency-Key wordt nog verwerkt of is afgebroken.
• 422Ongeldige invoer, een brochure die niet verstuurd kan worden, onvoldoende tegoed (errors.credits) of een Idempotency-Key die al voor een ander verzoek is gebruikt (errors.idempotency_key).
• 429Rate limit bereikt. Wacht het aantal seconden uit de Retry-After-header.

HTTP/1.1 403 Forbidden

{
  "message": "Deze API-sleutel mist de benodigde scope.",
  "required_scopes": ["orders:create"]
}

Elke sleutel mag 60 verzoeken per minuut doen. Daarnaast plaatst één gebruiker maximaal 60 orders en 20 batches per minuut. Elk antwoord bevat X-RateLimit-Limit en X-RateLimit-Remaining. Bij een 429 staat in Retry-After na hoeveel seconden u het opnieuw kunt proberen.

Alle endpoints, velden en antwoorden staan in de OpenAPI 3.1-specificatie. Importeer hem in Postman, Insomnia of een codegenerator.

Liever zonder code? Met webhooks koppelt u uw CRM of Zapier en Make zonder te programmeren.