Bjet24 API: vanuit uw CRM een postzending opstarten in enkele regels code

Wanneer postverzending vanuit uw applicatie moet vertrekken

Veel papieren zendingen zijn de gevolgen van een business-event: een ondertekend contract, een factuur 30 dagen vervallen, een wettelijke opzegging, een gewijzigde verzekerde. Vragen aan een mens om zich « te herinneren » om na elk event een brief op te stellen, is de deur openzetten voor vergetelheid en vertraging.

De Bjet24 API dient precies daarvoor: uw applicatie triggert de verzending, Bjet24 drukt, steekt in envelop en geeft af aan bpost, met bewijzen bij de retour. Bekijk de tariefpagina voor een overzicht van de kosten per zendtype.

Overzicht van de flow

De levenscyclus van een zending via de API telt vier stappen:

1. U maakt een job aan met de PDF, de ontvanger en het verzendtype.
2. De job doorloopt de statussen draft → paid → queued → printed → posted → delivered.
3. U ontvangt een webhook bij elke majeure statuswijziging (betaling, bpost-afgifte, bewijs van afgifte).
4. U kunt op elk moment de job opvragen om de PDF-bewijzen op te halen (bewijs van afgifte, ontvangstbewijs, enz.).

Klassiek asynchroon mechanisme — uw aanroepende app blijft niet wachten op de uitreiking.

Authenticatie

De API gebruikt een API-sleutel in de header Authorization: Bearer <key>. Sleutels worden in uw Bjet24-account aangemaakt, gescoped op een omgeving (sandbox of productie) en individueel intrekbaar.

Goede reflex: één sleutel per integratie (CRM, ERP, intern tool). Bij een incident herroept u één sleutel zonder de andere te breken. Controleer ook de best practices voor Belgische postadresverificatie om terugzendingen te vermijden.

Een zending aanmaken in TypeScript

Typisch verzoek voor een gewone brief. De PDF wordt aangeduid met een bestand-id dat u vooraf hebt geüpload via een upload-endpoint:

const res = await fetch("https://api.bjet24.com/v1/mail-jobs", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.BJET24_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "standard",            // of "registered" voor aangetekend
    priority: "prior",           // of "non-prior"
    documentId: "doc_abc123",    // PDF vooraf geüpload
    recipient: {
      name: "Dupont BV",
      street: "Wetstraat",
      number: "12",
      box: "3",
      zip: "1000",
      city: "Brussel",
      country: "BE",
    },
  }),
})

const job = await res.json()
console.log("job created:", job.id, job.status)

Typische respons:

{
  "id": "job_01HE...",
  "status": "draft",
  "type": "standard",
  "priority": "prior",
  "amount": { "value": 195, "currency": "EUR" },
  "createdAt": "2026-03-20T10:14:22.000Z"
}

In dit stadium staat de job op draft. Om hem te bevestigen betaalt u via uw vooraf geladen portefeuille of via Stripe, waarna hij naar paid → queued schuift.

Events via webhooks ontvangen

In plaats van de API voortdurend te bevragen (polling) abonneert u een endpoint op de events. Typische payload:

{
  "id": "evt_...",
  "type": "mail_job.posted",
  "createdAt": "2026-03-21T08:02:11.000Z",
  "data": {
    "id": "job_01HE...",
    "status": "posted",
    "bpostTrackingId": "EE...BE",
    "proofs": {
      "deposit": "https://api.bjet24.com/v1/proofs/.../deposit.pdf"
    }
  }
}

De events die u moet kennen:

• mail_job.paid — betaling geïnd,
• mail_job.printed — stuk afgedrukt,
• mail_job.posted — afgegeven aan bpost (bewijs van afgifte beschikbaar),
• mail_job.delivered — uitgereikt (enkel aangetekend, bewijs van afgifte beschikbaar),
• mail_job.failed — retour of weigering (ongeldig adres, weigering).

Vergeet niet de HMAC-handtekening in de header X-Bjet24-Signature te valideren. Dat is de bescherming tegen vervalste webhooks. Raadpleeg de Bjet24 webhooks-tutorial voor real-time statusopvolging voor een gedetailleerde implementatiegids.

Drie nuttige integratiepatronen

1) Automatische herinnering D+30 (CRM/facturatie). Een geplande taak loopt uw onbetaalde facturen met vervaldag > 30 dagen door en maakt een registered job met ontvangstbewijs aan, vooringevuld vanuit uw PDF-sjabloon. Voor grotere volumes is ook professioneel bulk-mailen voor Belgische kmo's een interessante optie.

2) Onboardingbevestiging (verzekering, bank). Bij elektronische ondertekening van een contract roept de webhook van uw e-signtool de Bjet24 API aan om de papieren kopie naar de klant te sturen — door sommige toezichthouders verplicht.

3) Reglementaire kennisgeving (HR, vastgoed). Bij elk business-event dat een termijn opent (opzegging, betwisting) maakt u meteen een job aan, archiveert u het jobId in uw database en bewaart u het bewijs van afgifte als bewijsstuk.

Sandbox, idempotency en limieten

Enkele best practices om niet vast te lopen:

• Sandbox: gebruik de testsleutel voor alle ontwikkeling. Jobs doorlopen dezelfde cyclus maar worden niet effectief afgedrukt.
• Idempotency-Key: stuur een Idempotency-Key header eigen aan uw business-event mee. Als uw worker opnieuw probeert, maakt u geen dubbele zending aan.
• Rate limits: de publieke API kent een redelijk quotum (zie documentatie). Voor grote volumes gebruikt u het bulk-endpoint dat een CSV in één aanroep verwerkt.

Samengevat

De Bjet24 API transformeert elk triggerend business-event in een traceerbare postzending, zonder manuele tussenkomst. Voor een CRM- of ERP-integratie rekent u op een tot twee dagen ontwikkeling voor de eerste versie (job + webhook). De ROI komt vooral uit betrouwbaarheid: geen vergeten brieven meer, geen post die op een bureau ligt te wachten en alle bewijzen netjes gearchiveerd.