Zakelijk · Automatiseren

Post-API: brieven versturen vanuit je eigen software

Stuur ons een PDF en een adres; wij printen, frankeren en bieden de brief aan bij de post. Gewoon of aangetekend, naar Nederland en ruim tweehonderd andere landen. Elke brief gaat van je vooraf opgewaardeerde tegoed af, tegen dezelfde prijs als op de site.

API-sleutel aanvragen Liever zonder code? Zapier, Make of n8n

Aan de slag

Log in op je zakelijke account met een link per e-mail.
Waardeer tegoed op onder Tegoed (iDEAL of kaart; factuur op je btw-nummer).
Maak onder API en automatisering een sleutel. Je ziet hem één keer; bewaar hem als een wachtwoord.
Stuur elk verzoek met de header Authorization: Bearer bv_live_… naar https://www.briefverzenden.nl/api/v1. Gebruik altijd www..

Een brief versturen

curl https://www.briefverzenden.nl/api/v1/brieven \
  -H "Authorization: Bearer bv_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: factuur-2026-114" \
  -d '{
    "ontvanger": {
      "naam": "Jansen BV",
      "tav": "Afdeling crediteuren",
      "adres": "Dorpsstraat 1",
      "postcode": "1234 AB",
      "woonplaats": "Utrecht",
      "land": "NL"
    },
    "aangetekend": true,
    "referentie": "factuur-2026-114",
    "pdfUrl": "https://voorbeeld.nl/factuur-2026-114.pdf"
  }'

HTTP/1.1 201 Created

{
  "id": "brf_3f1c0a9e5b7d2c4a6e8f0b1d",
  "status": "ingediend",
  "aangemaakt": "2026-11-09T10:00:00.000Z",
  "prijs": 11.95,
  "valuta": "EUR",
  "paginas": 2,
  "ontvanger": { "naam": "Jansen BV", "tav": "Afdeling crediteuren", … },
  "opties": { "kleur": false, "dubbelzijdig": true, "aangetekend": true },
  "referentie": "factuur-2026-114",
  "volgnummer": null,
  "volgUrl": null,
  "fout": null,
  "tegoed": { "saldo": 38.05, "valuta": "EUR" }
}

Of in JavaScript (Node 18+):

const antwoord = await fetch('https://www.briefverzenden.nl/api/v1/brieven', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BRIEFVERZENDEN_SLEUTEL}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': `factuur-${factuur.nummer}`,
  },
  body: JSON.stringify({
    naam: factuur.klant, adres: factuur.straat, postcode: factuur.postcode,
    woonplaats: factuur.plaats, land: 'NL',
    pdfBase64: pdf.toString('base64'),
    referentie: factuur.nummer,
  }),
})
const brief = await antwoord.json()
if (!antwoord.ok) throw new Error(brief.error)

Endpoints

POST/brieven

Verstuurt een brief en boekt de prijs af van je tegoed. JSON of multipart/form-data (bestand in het veld pdf, overige velden als tekst). Antwoord 201 met de brief.

Veld	Verplicht	Toelichting
ontvanger.naam	ja	Naam of bedrijfsnaam op de envelop, max. 120 tekens.
ontvanger.tav	nee	T.a.v.-regel.
ontvanger.adres	ja	Straat en huisnummer.
ontvanger.postcode	ja
ontvanger.woonplaats	ja
ontvanger.land	nee	ISO-code (NL, DE, BE …) of Nederlandse landnaam. Standaard NL.
kleur	nee	true of false, standaard false.
dubbelzijdig	nee	Standaard true.
aangetekend	nee	Standaard false. Niet in elk land; zie /landen.
snelheid	nee	traag, standaard, snel of plus; per land verschillend (zie /landen).
afzender	nee	Eén regel afzendertekst op het adresblad.
referentie	nee	Je eigen kenmerk, komt ongewijzigd terug. Max. 100 tekens.
pdfBase64	of pdfUrl	De PDF als base64. Tot ongeveer 3 MB (een verzoek mag max. 4,5 MB zijn).
pdfUrl	of pdfBase64	Een https-link naar de PDF; wij halen hem op. Max. 10 MB.

De ontvangervelden mogen ook plat op het hoogste niveau staan (naam, adres, …). Het adres hoeft niet in de PDF: wij zetten er een adresblad voor dat in het venster van de envelop valt en niet als pagina meetelt. Maximaal 60 pagina’s, A4.

GET/brieven/{id}

Eén brief met de actuele status bij de vervoerder: ingediend, verzonden, bezorgd, of een eindstatus onbestelbaar, geannuleerd of mislukt (bedrag teruggeboekt). Zodra er een volgnummer is, staan volgnummer en volgUrl erbij. Gewone post zonder volgnummer meldt niet altijd “bezorgd”.

GET/brieven?limit=25&status=verzonden

De nieuwste brieven (max. 100), nieuwste eerst, met een optioneel filter op status.

POST/prijs

Wat een brief kost, zonder iets te versturen. Dezelfde velden als bij versturen; zonder PDF geef je paginas mee. Je ziet ook of je tegoed genoeg is.

GET/me

Test je sleutel: account, bedrijfsnaam en je huidige tegoed.

GET/landen

Alle bestemmingen met ISO-code, en per land of aangetekend kan en welke snelheden er zijn. Geen sleutel nodig.

Nooit dubbel versturen

Fysieke post kun je niet terughalen. Stuur daarom bij elke brief een header Idempotency-Key mee met iets unieks, zoals je factuurnummer (8 tot 200 tekens). Komt hetzelfde verzoek nog eens binnen, bijvoorbeeld na een time-out, dan krijg je de eerste brief terug (HTTP 200 met Idempotent-Replayed: true) en gaat er niets opnieuw op de post.

Fouten

Altijd JSON in de vorm { "error": "…", "code": "…" }, met een leesbare uitleg in het Nederlands.

400 · Ongeldige invoer: veld ontbreekt, land onbekend, PDF niet leesbaar, aangetekend niet mogelijk.
401 · Geen of een ongeldige API-sleutel.
402 · Onvoldoende tegoed (code onvoldoende_tegoed). Er is niets verstuurd.
404 · Brief bestaat niet bij dit account.
429 · Te veel verzoeken; wacht het aantal seconden uit de header Retry-After.
502 · De vervoerder weigerde of was onbereikbaar (code indienen_mislukt). Het bedrag is teruggeboekt.

Goed om te weten

Tot ongeveer twee verzoeken per seconde, met ruimte voor pieken. Daarboven krijg je 429.
Brieven die op een werkdag binnenkomen, gaan binnen 24 uur geprint de deur uit.
Zakt je tegoed onder € 10, dan krijg je één mail. Opwaarderen kan altijd in het portaal.
Een sleutel intrekken werkt direct. Maak per koppeling een eigen sleutel, dan hoef je bij een lek maar één te vervangen.
Liever een AI-assistent laten versturen? Zie onze MCP-server.