API Bjet24 : déclencher un envoi postal depuis votre CRM en quelques lignes

Quand l'envoi postal doit être déclenché par votre application

Beaucoup d'envois papier sont la conséquence d'un événement métier : un contrat signé, une facture impayée à J+30, un préavis légal, un changement d'assuré. Demander à un humain de « se souvenir » de générer le courrier après chaque événement, c'est ouvrir la porte aux oublis et aux retards.

L'API Bjet24 sert exactement à cela : votre application déclenche l'envoi, Bjet24 imprime, met sous pli et remet à bpost, avec les preuves au retour. Pour connaître le détail des tarifs par type d'envoi, consultez la page de tarification.

Vue d'ensemble du flux

Le cycle de vie d'un envoi via l'API tient en quatre étapes :

1. Vous créez un job d'envoi avec le PDF, le destinataire et le type d'envoi.
2. Le job passe par les statuts draft → paid → queued → printed → posted → delivered.
3. Vous recevez un webhook à chaque changement de statut majeur (paiement, dépôt bpost, preuve de remise).
4. À tout moment, vous pouvez consulter le job pour récupérer les preuves PDF (preuve de dépôt, accusé de réception, etc.).

C'est un mécanisme asynchrone classique — l'application appelante ne reste pas bloquée en attendant la distribution.

Authentification

L'API utilise une clé d'API à passer en en-tête Authorization: Bearer <key>. Les clés sont créées dans votre espace Bjet24, scopées à un environnement (sandbox ou production), et révocables individuellement.

Bon réflexe : créer une clé par intégration (CRM, ERP, outil interne). En cas d'incident, on révoque sans casser les autres. Avant de pousser en production, pensez également à vérifier la conformité de vos adresses postales belges pour éviter les retours.

Créer un envoi en TypeScript

Voici un appel type pour envoyer une lettre simple. Le PDF est référencé par un identifiant de fichier que vous avez préalablement téléversé via un endpoint d'upload :

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",            // ou "registered" pour un recommandé
    priority: "prior",           // ou "non-prior"
    documentId: "doc_abc123",    // PDF téléversé au préalable
    recipient: {
      name: "Société Dupont SRL",
      street: "Rue de la Loi",
      number: "12",
      box: "3",
      zip: "1000",
      city: "Bruxelles",
      country: "BE",
    },
  }),
})

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

Réponse type :

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

À ce stade, le job est en draft. Pour le confirmer, vous le payez via votre portefeuille pré-chargé ou Stripe, ce qui le fait passer en paid → queued.

Recevoir les événements via webhooks

Plutôt que de scruter l'API en boucle (polling), vous abonnez un endpoint à recevoir les événements. La payload typique est :

{
  "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"
    }
  }
}

Les événements à connaître :

• mail_job.paid — paiement encaissé,
• mail_job.printed — pli imprimé,
• mail_job.posted — remis à bpost (preuve de dépôt disponible),
• mail_job.delivered — distribué (recommandé uniquement, preuve de remise disponible),
• mail_job.failed — retour ou rejet (adresse invalide, refus).

Pensez à valider la signature HMAC transmise dans l'en-tête X-Bjet24-Signature. C'est la barrière contre les webhooks falsifiés. Pour un guide complet sur la mise en place des webhooks, consultez le tutoriel webhooks Bjet24 pour le suivi en temps réel.

Trois patterns d'intégration utiles

1) Relance automatique J+30 (CRM/facturation). Une tâche planifiée parcourt vos factures impayées dont la date d'échéance dépasse 30 jours et crée un job registered avec accusé de réception, pré-rempli depuis votre modèle PDF. Les entreprises qui expédient plusieurs dizaines de courriers par mois peuvent également s'intéresser aux envois en lot pour PME belges.

2) Confirmation d'un onboarding (assurance, banque). À la signature électronique d'un contrat, le webhook de votre outil de signature appelle l'API Bjet24 pour envoyer la copie papier au client — exigée par certains régulateurs.

3) Notification réglementaire (RH, immobilier). À chaque événement métier qui ouvre un délai (préavis, contestation), vous créez un job dans la foulée, archivez le jobId dans votre base, et stockez la preuve de dépôt comme pièce justificative.

Sandbox, idempotence et limites

Quelques bonnes pratiques pour ne pas se faire piéger :

• Sandbox : utilisez la clé de test pour tout développement. Les jobs y suivent le même cycle mais ne sont pas réellement imprimés.
• Idempotency-Key : passez un en-tête Idempotency-Key propre à votre événement métier. Si le retry de votre worker rejoue, vous ne créez pas deux envois.
• Rate limits : l'API publique est limitée à un quota raisonnable (consulter la documentation). Pour les volumes pro, utilisez l'endpoint bulk qui accepte un CSV en un appel.

En résumé

L'API Bjet24 permet de transformer chaque événement métier déclencheur en envoi postal traçable, sans aucune intervention manuelle. Pour une intégration CRM ou ERP, comptez une à deux journées de développement pour la première version (création de job + webhook). Le retour sur investissement vient surtout de la fiabilité : plus d'oubli, plus de courrier qui dort sur un bureau, et toutes les preuves archivées au bon endroit.