Connecter l’API bexio à WordPress

Une demande du formulaire du site doit arriver comme contact dans bexio, une commande comme facture, un client de la boutique comme adresse. Pour cela, WordPress doit parler à l’API bexio. Ce guide montre le chemin de l’app dans le Developer Portal jusqu’au premier contact créé, les pièges en route, et quand un plugin prêt à l’emploi vaut mieux que du code maison.

Qu’est-ce que l’API bexio

L’API bexio est une interface REST en JSON. Tous les endpoints se trouvent sous https://api.bexio.com, les chemins commencent selon le domaine par /2.0/, /3.0/ ou plus récent, par exemple /2.0/contact pour les contacts et /3.0/users/me pour l’utilisateur connecté. La référence se trouve sur docs.bexio.com. Selon sa propre documentation, bexio ne propose pas de description OpenAPI ; un client s’écrit donc à la main.

Chaque accès demande un access token dans l’en-tête Authorization: Bearer …. La manière dont WordPress obtient ce token constitue le vrai travail.

Étape 1 : créer une app dans le Developer Portal

1. Se connecter au Developer Portal avec le compte bexio.
2. Lire et accepter les conditions d’utilisation, en particulier le chiffre 4.4 sur l’usage commercial (voir les pièges).
3. Créer une nouvelle app et saisir l’URL de redirection vers laquelle bexio renvoie après la connexion, par exemple la page de réglages du plugin dans l’administration WordPress. Jusqu’à dix adresses sont possibles, par exemple pour le test et la production.
4. Relever le Client ID et le Client Secret sous « App Details ».

Le Client Secret reste sur le serveur, jamais dans du JavaScript côté navigateur.

Étape 2 : se connecter avec OAuth 2

bexio connecte via OpenID Connect sur auth.bexio.com, avec l’« Authorization Code Flow ». WordPress envoie pour cela l’utilisateur sur la page de connexion de bexio :

https://auth.bexio.com/realms/bexio/protocol/openid-connect/auth
  ?client_id=<Client ID>
  &redirect_uri=<URL de redirection enregistrée>
  &response_type=code
  &scope=openid offline_access contact_edit note_edit
  &state=<valeur aléatoire>

L’utilisateur se connecte et confirme les droits. bexio renvoie avec un code, que WordPress échange, avec le Client ID et le Secret, auprès de l’endpoint de token /realms/bexio/protocol/openid-connect/token contre un access token et un refresh token.

À propos des scopes : un droit d’écriture inclut le droit de lecture, contact_edit suffit donc aussi pour chercher. offline_access est nécessaire pour le refresh token. Et l’API travaille toujours avec les droits de l’utilisateur qui a établi la connexion : s’il ne voit pas les contacts dans bexio, l’app ne les voit pas non plus.

Étape 3 : enregistrer et renouveler les tokens

L’access token expire vite. Avant cela, WordPress en obtient un nouveau avec le refresh token et grant_type=refresh_token, toutes les valeurs dans le corps de la requête, pas dans l’URL. À retenir :

• Toujours enregistrer le nouveau refresh token renvoyé lors du renouvellement.
• Si une connexion reste un an sans renouvellement, bexio ferme la session ; quelqu’un doit alors se reconnecter.
• Stocker les tokens dans des options WordPress sans autoload, pour qu’ils ne soient pas chargés à chaque affichage de page.

Pour vos propres scripts, il existe aussi les jetons d’accès personnels (PAT). Ils ont un accès complet à toutes les données de l’entreprise et sont valables 60 jours. Pratiques pour un usage personnel, ils ne conviennent pas à un plugin installé sur le site d’un client.

Étape 4 : créer un contact et une note

Un déroulement typique pour une demande de formulaire demande quatre appels :

1. GET /3.0/users/me renvoie l’ID de l’utilisateur. Il est obligatoire à la création, comme user_id et owner_id.
2. POST /2.0/contact/search cherche par l’adresse e-mail si le contact existe déjà.
3. Sinon : POST /2.0/contact le crée, contact_type_id 1 pour les entreprises, 2 pour les personnes.
4. POST /2.0/note ajoute le texte du formulaire comme note au contact.

L’appel pour créer une entreprise ressemble à ceci :

{
  "contact_type_id": 1,
  "name_1": "Exemple SA",
  "street_name": "Rue du Lac",
  "house_number": "1",
  "postcode": "1003",
  "city": "Lausanne",
  "mail": "info@exemple.ch",
  "user_id": 1,
  "owner_id": 1
}

Pièges habituels

• URL de redirection : elle doit figurer exactement ainsi dans le Developer Portal, sinon la connexion s’interrompt avec un message d’erreur.
• Nouveaux scopes : les droits d’une connexion ne changent pas au renouvellement. Si l’app a besoin de plus, l’utilisateur doit se reconnecter.
• Champs d’adresse : le champ address est obsolète à la création. Rue et numéro vont dans street_name et house_number.
• Retours à la ligne dans les notes : bexio affiche le texte d’une note sans retours à la ligne. Pour des paragraphes, mettre <br> et échapper les valeurs en HTML.
• Limite de requêtes : trop de requêtes par minute, et l’API répond avec le statut 429. Les en-têtes RateLimit-Remaining et RateLimit-Reset indiquent combien de temps attendre.
• Formulaires lents : appeler bexio au moment de l’envoi fait attendre le visiteur et perd la demande si bexio ne répond pas. Mieux vaut transmettre en arrière-plan et réessayer en cas d’erreur.
• Usage commercial : selon le chiffre 4.4 des conditions, bexio doit être informé par quiconque exploite sur l’API un modèle d’affaires propre auquel au moins cinq comptes bexio sont connectés.

Trois approches comparées

Make et Zapier proposent bexio comme app à part entière. Le plugin de formulaire envoie la demande par webhook, et une action bexio crée le contact.

Solutions prêtes à l’emploi

Pour les deux cas les plus fréquents, il existe mes connexions :

• Connecteur de formulaires bexio : plugin WordPress, les demandes du formulaire du site deviennent des contacts avec note dans bexio, les doublons sont reconnus à l’e-mail. Chaque exploitant connecte son bexio via sa propre app, les données vont directement du site à bexio.
• bexio ↔ HubSpot : un deal gagné dans HubSpot devient offre ou facture dans bexio, l’état du paiement revient dans le deal.

Tous les guides