API BEVERITRAX

Créez des dossiers, déposez des pièces, enregistrez des événements métier et recevez chaque étape franchie dans vos systèmes. Le contrat complet est publié au format OpenAPI 3.1.

openapi.json État du service

Authentification

Clé d’API créée par l’administrateur de l’espace (menu Développeurs). En-tête Authorization: Bearer bvx_live_… — bvx_test_… pour un espace bac à sable.

Garde-fous

Une clé agit comme un compte de service aux droits limités. Elle ne prend aucune décision réservée au second facteur : approbation, levée d’engagement, revue de pièce, archive de preuve.

Fiabilité

Idempotency-Key sur les créations, erreurs typées { code, message, details }, refus nommé quand une condition d’étape manque, montants en unités mineures ISO 4217.

Exemple

curl -X POST $BVX/v1/cases \
  -H "Authorization: Bearer $BEVERITRAX_API_KEY" \
  -H "Idempotency-Key: sap-4500001" -H "Content-Type: application/json" \
  -d '{"title":"Commande 4500001","templateId":"…","attributes":{"poNumber":"4500001","deliveryDate":"2026-12-20","qualityRequirement":"EN10204_3_1","criticality":"B"},"parties":[{"counterpartyId":"…","role":"SUPPLIER"}]}'

Client TypeScript sans dépendance : @beveritrax/sdk (fourni avec le code source).

Points d’entrée

Webhooks

Chaque envoi porte BVX-Signature: t=<unix>,v1=<HMAC-SHA256(secret, t + "." + corps)>. Refusez un message de plus de 5 minutes, traitez chaque id une seule fois. Reprise automatique jusqu’à 8 essais (1 min à 4 h).

import { verifyWebhook } from '@beveritrax/sdk';

app.post('/webhooks/beveritrax', express.raw({ type: 'application/json' }), (req, res) => {
  const event = verifyWebhook(process.env.BEVERITRAX_WEBHOOK_SECRET, req.get('bvx-signature'), req.body.toString('utf8'));
  // event.type : 'case.state_changed', 'document.sealed', …  — traitez de façon idempotente (event.id)
  res.sendStatus(204);
});