REST API · v1
API-documentatie
Laat uw eigen software brochures versturen. Uw systeem plaatst een order; wij drukken, vouwen en versturen de brochure per post. Alles in JSON over HTTPS.
Snel starten
- Log in en ga naar Integraties → API-sleutels. Daarvoor heeft u de teampermissie Integraties nodig.
- 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.
- 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.
Authenticatie en scopes
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:
| Scope | Geeft toegang tot |
|---|---|
orders:create | Orders plaatsen. Orders plaatsen (los of in een batch) en vooraf de kosten berekenen. Verbruikt tegoed. |
orders:read | Orders inzien. Orders en hun verzendstatus opvragen. |
brochures:read | Brochures inzien. Brochures opvragen, bijvoorbeeld om het juiste brochure_id te kiezen. |
campaigns:read | Campagnes inzien. Webhook-campagnes opvragen. Webhook-URL en -token blijven verborgen. |
documents:upload | Documenten uploaden. Een PDF uploaden (met veiligheidsscan) en er een brochure of brief van maken. |
letters:read | Brieven inzien. Brieven, hun velden en een proefweergave opvragen. |
letters:write | Brieven beheren. Brieven aanmaken, wijzigen en archiveren. |
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.
Endpoints
- GET
/brochuresBrochures, nieuwste eerst. Filters: status, format, search.
Scope:
brochures:read - GET
/brochures/{id}Eén brochure.
Scope:
brochures:read - POST
/documents/upload-urlUpload van een PDF starten: geeft een upload_token en de upload_url.
Scope:
documents:upload - GET
/documents/upload-status/{token}Status van de upload en de scan. Opvragen tot passed.
Scope:
documents:upload - POST
/brochuresBrochure maken van een goedgekeurde upload.
Scope:
documents:upload - GET
/letters/settingsOf brief bijvoegen aanstaat, de prijs per vel, lettertypes en standaardvelden.
Scope:
letters:read - GET
/lettersBrieven, nieuwste eerst. Filter: status (active of archived).
Scope:
letters:read - POST
/lettersBrief maken: een tekst met velden of een eigen PDF.
Scope:
letters:write - POST
/letters/previewProef-PDF van een tekstbrief die nog niet is opgeslagen.
Scope:
letters:read - GET
/letters/{id}Eén brief, met de velden die hij gebruikt.
Scope:
letters:read - PATCH
/letters/{id}Brief wijzigen of archiveren.
Scope:
letters:write - DELETE
/letters/{id}Brief verwijderen. Geplaatste orders houden hun brief.
Scope:
letters:write - GET
/letters/{id}/pdfProef-PDF van een opgeslagen brief.
Scope:
letters:read - POST
/orders/estimateKosten berekenen zonder iets te versturen.
Scope:
orders:create - POST
/ordersEén order plaatsen (of een oplage naar één adres).
Scope:
orders:create - POST
/orders/batchDezelfde brochure naar maximaal 100 ontvangers.
Scope:
orders:create - POST
/onepagers/estimateKosten van een onepager berekenen zonder iets te versturen.
Scope:
orders:create - POST
/onepagersEen brief los versturen als onepager: één A4-vel, zonder boekje.
Scope:
orders:create - POST
/onepagers/batchDezelfde onepager naar maximaal 100 ontvangers.
Scope:
orders:create - GET
/ordersOrders, nieuwste eerst. Filters: status, source, kind, brochure_id, external_reference, date_from, date_to.
Scope:
orders:read - GET
/orders/{id}Eén order met statusgeschiedenis.
Scope:
orders:read - GET
/orders/{id}/letterDe brief-PDF zoals hij met deze order meegaat.
Scope:
orders:read - GET
/orders/savedGespaarde orders per brochure: hoeveel adressen wachten en wanneer de eerste uiterlijk vertrekt.
Scope:
orders:read - POST
/orders/{id}/send-nowGespaarde order nu versturen, zonder batchkorting.
Scope:
orders:create - POST
/orders/{id}/cancel-savedGespaarde order annuleren; het tegoed komt terug.
Scope:
orders:create - GET
/campaignsWebhook-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).
Orders plaatsen en volgen
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.
Haalt een batch voor dezelfde brochure genoeg verschillende adressen, dan geldt batchkorting op elke verzending, alleen op de porto. Drempel en percentage staan in batch_discount van GET /pricing; POST /orders/estimate laat zien of de korting geldt. Wilt u verzendingen laten wachten tot de batch vol is, stuur dan save_for_batch: true mee, eventueel met send_by (JJJJ-MM-DD) als uiterste verzenddatum. De order krijgt status saved: u betaalt nu de normale prijs, en zodra de batch vol is gaat alles naar de drukker en komt de korting terug als tegoed. Is de batch op de uiterste datum nog niet vol, dan gaat de order zonder korting weg. Gespaarde orders vallen niet onder de leverbelofte van 2 werkdagen; die geldt vanaf het vertrek.
curl https://slimfolderen.nl/api/v1/orders/0b8f3f9e-2c4d-4e1a-8f57-6a9d2e1c7b40 \
-H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
-H "Accept: application/json"| Status | Betekenis |
|---|---|
saved | Gespaard tot een batch: wacht op batchkorting, uiterlijk tot de gekozen verzenddatum. |
queued | Ingepland, wacht op de drukker. |
printing | Wordt gedrukt. |
printed | Gedrukt en gevouwen. |
ready_to_ship | Klaar voor verzending. |
shipped | Verzonden. |
delivered | Bezorgd. |
failed | Mislukt. Neem contact met ons op. |
cancelled | Geannuleerd. |
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);Veilig opnieuw proberen
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-Afterbetekent dat het eerste verzoek is afgebroken. Kijk in beide gevallen metexternal_referencewat 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"Documenten uploaden
Een eigen PDF, voor een brochure of een brief, uploadt u in drie stappen. De sleutel heeft daarvoor de scope documents:upload nodig en de collega van de sleutel de teampermissie Upload.
- Start een upload met
POST /documents/upload-url. U krijgt eenupload_token, eenupload_urlen eenmodeterug. De uploadsessie is 15 minuten geldig. - Stuur de PDF naar de
upload_url. Bijmode: presignedis dat een PUT met de PDF-bytes enContent-Type: application/pdf, zonder Authorization-header: deupload_urlis een tijdelijke opslag-URL. Bijmode: directis het een POST alsmultipart/form-datamet het veldpdf, en dan wél met uw sleutel als bearer-token. - Vraag elke 2 seconden
GET /documents/upload-status/{token}op tot de statuspassedis. Dan staat het aantal pagina’s inpage_count. Bijfailedkrijgt u een 422 met de reden infailure_reason; start dan een nieuwe upload.
curl -X POST https://slimfolderen.nl/api/v1/documents/upload-url \
-H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
-H "Accept: application/json"{
"upload_token": "3f2a9c1e-5b7d-4e8f-a1c2-9d0e7b6a5f43",
"mode": "presigned",
"upload_url": "https://…",
"expires_at": "2026-11-04T09:45:00+00:00"
}# mode "presigned": PUT naar de opslag-URL, zonder Authorization-header
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: application/pdf" \
--data-binary @brochure.pdf
# mode "direct": POST als multipart/form-data, met uw API-sleutel
curl -X POST "$UPLOAD_URL" \
-H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
-H "Accept: application/json" \
-F "pdf=@brochure.pdf"curl https://slimfolderen.nl/api/v1/documents/upload-status/3f2a9c1e-5b7d-4e8f-a1c2-9d0e7b6a5f43 \
-H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
-H "Accept: application/json"{
"upload_token": "3f2a9c1e-5b7d-4e8f-a1c2-9d0e7b6a5f43",
"status": "passed",
"page_count": 8,
"suggested_format": "A4",
"detected": true,
"failure_reason": null,
"expires_at": "2026-11-04T09:45:00+00:00"
}Elke PDF wordt gescand voordat u hem kunt gebruiken. Alleen A4 tot 100 MB komt erdoor, zonder scripts of ingesloten bestanden. Een brief-PDF heeft daarnaast maximaal 2 pagina’s.
Met het upload_token maakt u daarna een brochure, of een brief (zie Brieven bijvoegen). Een token is één keer te gebruiken, binnen de 15 minuten van de uploadsessie en alleen met een sleutel van dezelfde collega.
curl -X POST https://slimfolderen.nl/api/v1/brochures \
-H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"title": "Productbrochure 2026",
"upload_token": "3f2a9c1e-5b7d-4e8f-a1c2-9d0e7b6a5f43",
"format": "A4",
"pages": 8,
"paper_tier": "standard"
}'Een brochure vraagt title, format: A4 en pages. Daarbij moet pages gelijk zijn aan page_count van de upload: 2, 4 of een veelvoud van 4 tot en met 80. Optioneel zijn description, visibility en paper_tier (budget, standard of premium; standaard standard). U krijgt een 201 met de brochure terug. Die heeft meteen status active en kan dus direct worden verstuurd.
Brieven bijvoegen
Bij een brochure kan een brief mee: A4, niet gevouwen, enkel- of dubbelzijdig, bij het boekje in de envelop. Een brief is een eigen PDF (kind: pdf) of een tekst met velden (kind: text) die we per ontvanger opmaken, met logo, afzender, adresblok, plaats en datum, betreft en de tekst.
Brief bijvoegen wordt gefaseerd aangezet. Kijk in enabled van GET /letters/settings of het voor u aanstaat. Zolang dat false is, geeft een order met letter_id een 422. Brieven aanmaken en de proefweergave werken wel al. Hetzelfde endpoint geeft ook de prijs per vel (credits_per_sheet), de lettertypes, de lettergroottes en de standaardvelden.
Een brief maken
Maak een tekstbrief met POST /letters (scope letters:write). Verplicht zijn title, kind: text en body, de tekst van maximaal 8000 tekens. Een lege regel begint een nieuwe alinea; **vet** en *cursief* werken. Daarnaast kunt u meegeven:
subject: de betreft-regel.typography:zakelijk(standaard),klassiek,modern,elegant,vriendelijkofeenvoudig.font_size:klein(10 pt),normaal(11 pt, standaard) ofgroot(12 pt).duplex: dubbelzijdig drukken (standaardfalse).logo_id: het id van een envelop-logo, dat dan bovenaan de brief komt.show_sender_blockenshow_address_block: afzender en adresblok tonen (standaardtrue).
Beslaat de tekst meer dan 2 pagina’s, of gebruikt hij een onbekend veld, dan krijgt u een 422 op body. Voor een eigen PDF stuurt u kind: pdf, een title en het upload_token van een goedgekeurde upload (zie Documenten uploaden), eventueel met duplex.
curl -X POST https://slimfolderen.nl/api/v1/letters \
-H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"title": "Opvolging beurs",
"kind": "text",
"subject": "Ons gesprek op de beurs",
"body": "{{ontvanger.aanhef}},\n\nBedankt voor uw bezoek aan {{veld.stand|onze stand}}. Uw accountmanager {{veld.accountmanager}} belt u volgende week.\n\nMet vriendelijke groet,\n{{afzender.naam}}",
"typography": "zakelijk",
"font_size": "normaal"
}'HTTP/1.1 201 Created
{
"message": "Brief opgeslagen.",
"letter": {
"id": "5a7e2c14-8b3d-4f6a-9e21-7c0d4b8a3f56",
"title": "Opvolging beurs",
"kind": "text",
"status": "active",
"format": "A4",
"duplex": false,
"pages": 1,
"sheets": 1,
"estimated_credits": 5,
"fields": {
"standard": ["ontvanger.aanhef", "afzender.naam"],
"custom": ["stand", "accountmanager"]
}
}
}Velden
Velden staan tussen dubbele accolades, zoals {{ontvanger.voornaam}}. Na een pipe volgt een terugvaltekst voor als het veld leeg is: {{veld.stand|onze stand}}. Deze standaardvelden vullen we zelf in:
| Veld | Waarde |
|---|---|
{{ontvanger.aanhef}} | “Beste <voornaam>”; zonder naam “Geachte heer/mevrouw”. |
{{ontvanger.naam}} | Naam van de ontvanger. |
{{ontvanger.voornaam}} | Het eerste woord van de naam. |
{{ontvanger.achternaam}} | De rest van de naam. |
{{ontvanger.bedrijf}} | Bedrijf van de ontvanger. |
{{ontvanger.adres}} | Straat en huisnummer. |
{{ontvanger.postcode}} | Postcode. |
{{ontvanger.plaats}} | Plaats. |
{{afzender.naam}} | Naam van de collega van de sleutel. |
{{afzender.email}} | Diens e-mailadres. |
{{afzender.telefoon}} | Diens telefoonnummer, anders dat van uw bedrijf. |
{{afzender.bedrijf}} | Naam van uw bedrijf. |
{{afzender.adres}} | Adres van uw bedrijf. Afzender- en adresblok volgen de afzender- en ontvangervelden, dus een waarde in letter_fields verandert ook die. |
{{afzender.postcode}} | Postcode van uw bedrijf. |
{{afzender.plaats}} | Plaats van uw bedrijf, ook bij de datum. |
{{datum}} | De datum waarop de order wordt geplaatst, bijvoorbeeld 4 november 2026. |
Een eigen veld schrijft u als {{veld.<naam>}}. De waarde geeft u per order mee in letter_fields. Ontbreekt de waarde van een eigen veld zonder terugvaltekst, dan geeft de order een 422 op letter_fields. Welke eigen velden een brief gebruikt, staat in fields.custom van de brief.
Proefweergave
Met GET /letters/{id}/pdf haalt u een proef-PDF op. Een tekstbrief is dan gevuld met voorbeeldgegevens; overschrijf ze in de query met letter_fields[naam]=… en recipient[recipient_name]=…. Een pdf-brief geeft het bestand zelf. Een veld zonder waarde en zonder terugvaltekst staat in de proef tussen haken, zoals [veld.accountmanager].
POST /letters/preview maakt een proef van een tekstbrief die nog niet is opgeslagen: dezelfde velden als bij aanmaken, plus optioneel letter_fields en recipient. Het antwoord is de PDF; de headers X-Letter-Pages en X-Letter-Sheets geven het aantal pagina’s en vellen.
curl -G https://slimfolderen.nl/api/v1/letters/5a7e2c14-8b3d-4f6a-9e21-7c0d4b8a3f56/pdf \
-H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
-H "Accept: application/json" \
--data-urlencode "letter_fields[accountmanager]=Piet" \
--data-urlencode "recipient[recipient_name]=Jan Jansen" \
-o proef.pdfBijvoegen bij een order
Geef bij POST /orders een letter_id mee en, voor een tekstbrief, letter_fields met de waarden. Een sleutel zonder voorvoegsel is een eigen veld: {"accountmanager": "Piet"} vult {{veld.accountmanager}}. Een standaardveld overschrijft de berekende waarde, zoals {"ontvanger.aanhef": "Geachte heer Jansen"}. Geneste objecten mogen ook: {"ontvanger": {"aanhef": "…"}}.
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: 8c4d1e2f-3a5b-4c6d-9e7f-0a1b2c3d4e5f" \
-d '{
"brochure_id": "9d3c4a52-7f1e-4b8a-9c61-2f0e8b7a1d34",
"recipient_name": "Jan Jansen",
"recipient_address": "Keizersgracht 1",
"recipient_postal_code": "1015 CJ",
"recipient_city": "Amsterdam",
"letter_id": "5a7e2c14-8b3d-4f6a-9e21-7c0d4b8a3f56",
"letter_fields": {
"accountmanager": "Piet",
"ontvanger.aanhef": "Geachte heer Jansen"
}
}'HTTP/1.1 201 Created
{
"message": "Brochure succesvol ingepland voor verzending!",
"order": {
"id": "7e1b9c3a-4d2f-4a8e-b6c5-1f0d9e8a7b62",
"status": "queued",
"total_credits": 27,
"recipient_name": "Jan Jansen",
"brochure": "Productbrochure 2026",
"letter": { "id": "5a7e2c14-8b3d-4f6a-9e21-7c0d4b8a3f56", "title": "Opvolging beurs", "pages": 1, "sheets": 1, "credits": 5 },
"created_at": "2026-11-04T10:02:11.000000Z"
},
"credit_balance": 951
}Bij POST /orders/batch gelden letter_id en letter_fields voor alle ontvangers; recipients[].letter_fields vult ze per ontvanger aan of overschrijft ze. Mist een ontvanger een veld, dan komt hij in failed en is het antwoord een 207. Met letter_id in POST /orders/estimate staan de kosten van de brief in letter_credits, gerekend met de pagina’s van de brief zelf.
Een brief kost credits_per_sheet × het aantal vellen. Enkelzijdig is elke pagina een vel; dubbelzijdig passen er twee pagina’s op een vel, naar boven afgerond. Er gaat één brief mee per order. Bij een oplage (quantity groter dan 1) is dat één brief per zending. De batchkorting geldt niet op de brief, alleen op de porto. Een tekstbrief wordt per ontvanger opgemaakt, en de order rekent met de pagina’s van die opgemaakte brief.
Een brief die niet kan worden bijgevoegd geeft een 422 op letter_id, met “Brief bijvoegen is nog niet beschikbaar.” of “Deze brief bestaat niet of is gearchiveerd.” Ook een tekstbrief die voor deze ontvanger meer dan 2 pagina’s beslaat, geeft daar een fout.
GET /orders/{id} toont letter_id, letter_fields, letter_pages, letter_sheets, letter_credits, letter en letter_pdf_available. Met GET /orders/{id}/letter haalt u de brief-PDF op zoals hij voor deze ontvanger is opgemaakt.
Wijzigen en verwijderen
Met PATCH /letters/{id} wijzigt u title, status (active of archived), duplex en bij een tekstbrief de tekstvelden. Bij een pdf-brief vervangt een nieuw upload_token de PDF. DELETE /letters/{id} verwijdert en archiveert de brief. Alleen actieve brieven kunnen worden bijgevoegd; orders die al geplaatst zijn houden hun brief. Voor aanmaken heeft de collega van de sleutel de teampermissie Upload nodig, voor wijzigen en verwijderen de teampermissie Bewerken.
Onepagers versturen
Een onepager is een brief die los de deur uit gaat, zonder boekje: één A4-vel op 210 g, enkel- of dubbelzijdig, plat in de envelop. U gebruikt dezelfde brieven als bij brieven bijvoegen: een tekst met velden of een eigen PDF. Hij moet op één vel passen: één pagina enkelzijdig of twee dubbelzijdig.
Onepagers worden gefaseerd aangezet. Kijk in onepager.enabled van GET /letters/settings of het voor u aanstaat. Daar staan ook het papiergewicht (gsm), de drukkosten per vel en het verzendtarief per land.
curl -X POST https://slimfolderen.nl/api/v1/onepagers \
-H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 3f9a1c7e-2b4d-4e6f-8a0c-5d7e9f1b3c2a" \
-d '{
"letter_id": "5a7e2c14-8b3d-4f6a-9e21-7c0d4b8a3f56",
"letter_fields": { "accountmanager": "Piet" },
"recipient_name": "Jan Jansen",
"recipient_address": "Keizersgracht 1",
"recipient_postal_code": "1015 CJ",
"recipient_city": "Amsterdam"
}'HTTP/1.1 201 Created
{
"message": "Onepager succesvol ingepland voor verzending!",
"order": {
"id": "8f2c0d4b-5e3a-4b9f-c7d6-2a1e0f9b8c73",
"kind": "onepager",
"status": "queued",
"total_credits": 24,
"letter_credits": 5,
"shipping_credits": 19,
"recipient_name": "Jan Jansen",
"letter": { "id": "5a7e2c14-8b3d-4f6a-9e21-7c0d4b8a3f56", "title": "Opvolging beurs", "pages": 2, "sheets": 1, "credits": 5 },
"paper": { "format": "A4", "gsm": 210, "duplex": true, "sheets": 1, "folded": false },
"created_at": "2026-11-04T10:02:11.000000Z"
},
"credit_balance": 927
}Een onepager kost de drukkosten van het vel (onepager.credits_per_sheet) plus een eigen verzendtarief, lager dan dat van een boekje: binnen Nederland 19 credits, België 29, Duitsland 39 en elders 59. Geen oplage, sparen of batchkorting.
POST /onepagers/batch verstuurt dezelfde onepager naar maximaal 100 ontvangers, met gedeelde letter_fields en per ontvanger recipients[].letter_fields. Meerdere ontvangers op hetzelfde adres gaan samen in één envelop; de verzending telt dan één keer. POST /onepagers/estimate berekent de kosten vooraf, met recipient_country of een lijst recipients.
Een onepager is een gewone order met kind onepager en zonder brochure_id. U volgt hem met GET /orders/{id}; GET /orders?kind=onepager toont alleen onepagers. Een brief die langer is dan één vel geeft een 422 op letter_id, net als een tekstbrief die voor een ontvanger op een tweede vel uitkomt.
Fouten
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, een brief die niet kan worden bijgevoegd (errors.letter_id of errors.letter_fields), 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"]
}Rate limits
Elke sleutel mag 60 verzoeken per minuut doen. Daarnaast plaatst één gebruiker maximaal 60 orders en 20 batches per minuut, start hij maximaal 10 uploads en maakt hij maximaal 10 brochures per minuut. Brieven aanmaken, wijzigen en proef-PDF’s opvragen kan maximaal 30 keer per minuut. Het opvragen van de uploadstatus telt mee voor de 60 verzoeken per sleutel. 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.
OpenAPI-specificatie
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.
