Une API prévisible, des webhooks fiables

Conventions

• Base : https://api.braxads.com/v1. JSON en entrée et en sortie, UTF-8.
• Champs en camel case, collections au pluriel.
• Versionnage par segment d'URL ; une version majeure est maintenue au moins douze mois après l'annonce de son retrait.
• Horodatages ISO 8601 en temps universel (suffixe Z).
• Identifiants préfixés par type : org_, cnx_, msg_, tpl_, cmp_.
• Pagination par curseur exclusivement.
• Limitation de débit : en-têtes X-RateLimit-Limit / Remaining / Reset sur chaque réponse ; l'envoi de messages est mis en file plutôt que rejeté.

Authentification

Jeton porteur dans l'en-tête Authorization. Une clé est générée avec un préfixe explicite — bx_live_ en production, bx_test_ en test — et n'est affichée qu'une seule fois. Le secret est stocké haché. Une clé peut être globale à l'organisation ou restreinte à une entreprise connectée, et révoquée immédiatement.

Démarrage rapide

1. Créez une clé d'API de test depuis l'interface (section Développeurs).
2. Envoyez un message : POST /v1/messages avec connectionId, to et exactement un champ de contenu (template, text, image…).
3. Recevez le statut de livraison par webhook (message.status.updated), pas par sondage.

L'état de la fenêtre de service de 24 heures est évalué localement : un envoi libre hors fenêtre est rejeté en 409 avant tout appel au transport. Le quota de l'abonnement est vérifié avant émission.

Webhooks sortants

Chaque livraison est signée par condensé HMAC-SHA256 sur le corps brut, avec horodatage (en-tête X-Brax-Signature). Les réessais suivent une progression exponentielle sur au moins 24 heures ; un endpoint en échec durable est désactivé avec notification. Chaque événement porte un identifiant unique pour la déduplication, et chaque livraison est rejouable depuis l'interface.

• message.received, message.status.updated
• conversation.opened / assigned / resolved
• template.status.updated, campaign.completed
• contact.unsubscribed, connection.quality.changed
• conversion.recorded, subscription.past_due

Documentation complète

La référence exhaustive des points de terminaison, le guide des webhooks avec exemples dans deux langages et l'environnement de test isolé sont en cours de préparation. Écrivez-nous pour un accès anticipé.