Documentation

Envoyer des événements à Pilot-Biz

Un événement, c’est un fait métier : un paiement reçu, une commande, une demande de contact, une réservation, un incident. Pilot-Biz le classe, l’affiche dans le tableau de bord, le compte dans les finances s’il porte un montant, et prévient l’équipe si nécessaire. Pas de schéma imposé : envoyez vos champs, Pilot-Biz reconnaît les usuels (montant, client, email, téléphone, message).

Authentification

Chaque business possède ses clés, créées depuis sa fiche → Connecter → Site sur mesure. Une clé ne vaut que pour ce business et se révoque en un clic.

Authorization: Bearer pb_live_…

Envoyer un événement

POST https://pilot-biz.fr/api/v1/events Content-Type: application/json

Champ	Type	Description
type	texte, requis	Identifiant du type : paiement_recu, commande, demande_devis… Libre ; Pilot-Biz apprend chaque nouveau type.
level	texte	low, medium, high ou critical (aussi : basse, moyenne, haute, urgent). Sinon déduit du type.
data	objet	Vos champs. Reconnus : montant/amount/total, devise/currency, client/nom/name, email, telephone/phone, message.
title	texte	Titre affiché (sinon le libellé du type).
id	texte	Identifiant unique côté site : un renvoi avec le même id est ignoré (pas de doublon).
amount, currency	nombre, code ISO	Montant explicite (prioritaire sur data). Devise par défaut : celle de l’espace.
occurred_at	date ISO 8601	Date réelle de l’événement (sinon : maintenant).

Réponse : 201 { "ok": true, "id": "…" }, ou 200 avec "duplicate": true si l’id a déjà été reçu.

Niveaux et catégories

low (Info) : enregistré et classé automatiquement, pas d’alerte par défaut.
medium (À suivre) : apparaît dans « À traiter ».
high (Important) et critical (Urgent) : en tête du tableau de bord et notifiés sur Telegram.

La catégorie (vente, commande, demande, message, réservation, avis, inscription, alerte) est déduite du type et réglable dans le catalogue du business, de même que le fait de compter le montant dans le chiffre d’affaires. Conseil : n’envoyez dans le CA qu’un seul type par paiement (par exemple paiement_recu), pas aussi la commande correspondante.

Exemples

PHP

<?php // À placer dans un fichier commun (ex. config/pilotbiz.php). Clé à mettre dans .env : PILOTBIZ_KEY=pb_live_… function pilotbiz_event(string $type, array $data = [], string $level = 'medium', ?string $id = null): void { $key = getenv('PILOTBIZ_KEY') ?: ($_ENV['PILOTBIZ_KEY'] ?? ''); if (!$key || !function_exists('curl_init')) return; $ch = curl_init('https://pilot-biz.fr/api/v1/events'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 4, // ne ralentit jamais votre site CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Authorization: Bearer ' . $key], CURLOPT_POSTFIELDS => json_encode(['type' => $type, 'level' => $level, 'data' => $data, 'id' => $id]), ]); @curl_exec($ch); // en cas d'échec : silencieux, votre site continue curl_close($ch); } // Exemple, juste après l'enregistrement d'une commande payée : pilotbiz_event('paiement_recu', ['montant' => 25000, 'client' => 'Awa N.', 'commande' => 'CMD-1042'], 'medium', 'CMD-1042');

Node.js

// Node.js / Next.js (fetch natif). .env : PILOTBIZ_KEY=pb_live_… export async function pilotbizEvent(type, data = {}, level = 'medium', id) { try { await fetch('https://pilot-biz.fr/api/v1/events', { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${process.env.PILOTBIZ_KEY}` }, body: JSON.stringify({ type, level, data, id }), signal: AbortSignal.timeout(4000), }); } catch {} // jamais bloquant } await pilotbizEvent('nouvelle_reservation', { client: 'Awa N.', nuits: 3, montant: 120000 });

Python

# Python (requests). Variable d'environnement : PILOTBIZ_KEY=pb_live_… import os, requests def pilotbiz_event(type, data=None, level="medium", id=None): try: requests.post("https://pilot-biz.fr/api/v1/events", timeout=4, headers={"Authorization": f"Bearer {os.environ['PILOTBIZ_KEY']}"}, json={"type": type, "level": level, "data": data or {}, "id": id}) except Exception: pass # jamais bloquant pilotbiz_event("demande_devis", {"nom": "Awa N.", "email": "awa@exemple.com", "message": "Site e-commerce"})

cURL

curl -X POST https://pilot-biz.fr/api/v1/events \ -H "Authorization: Bearer pb_live_…" \ -H "Content-Type: application/json" \ -d '{"type":"paiement_recu","level":"medium","data":{"montant":25000,"client":"Awa N."}}'

Lien webhook universel

Un lien du type https://pilot-biz.fr/api/hooks/pbh_… accepte les webhooks de Shopify, WooCommerce, Stripe, Calendly, Typeform, Tally, ainsi que tout JSON (Zapier, Make, n8n…). Le fournisseur est reconnu par ses en-têtes ; les montants Stripe sont convertis depuis les centimes. Si vous renseignez le secret de signature du fournisseur, chaque appel est vérifié (HMAC). Pour un JSON générique : type (ou event), level, data, id.

Formulaires sans code

Chaque formulaire envoyé devient une demande ; le nom vient de data-pb-name, du titre du formulaire ou de la page.
Jamais lus : mots de passe, cartes, champs cachés, jetons. Les formulaires de connexion sont ignorés. Exclure un formulaire : data-pb-ignore.
Événement manuel : window.pilotbiz.track('reservation', { nom: 'Awa', couverts: 4 }).
La clé pk_… est publique ; elle est verrouillée sur le premier domaine qui l’utilise.

Email entrant

Chaque business peut recevoir une adresse de transfert. Les emails transférés deviennent des événements « Email reçu » (expéditeur, objet, texte). Côté plateforme, la réception passe par un service d’email entrant (Cloudflare Email Routing, Postmark, Mailgun) qui poste le message sur /api/inbound/email/<clé>.

Ancien format

Les sites branchés sur la première version restent compatibles :

POST https://pilot-biz.fr/api/ingest Authorization: Bearer <token> { "business_id": "…", "type_evenement": "paiement_recu", "urgence": "haute", "donnees": { "montant": 25000 } }

Erreurs et limites

401 clé absente, invalide ou révoquée · 400 corps invalide (détail des champs renvoyé) · 413 corps > 64 Ko · 429 trop de requêtes.
Limite : 300 événements par minute et par clé (600 pour un lien webhook).
Bonnes pratiques : délai de 4 secondes maximum côté site, erreurs ignorées silencieusement, clé dans une variable d’environnement.