API-documentatie

Integreer Qualibox met uw tools en automatiseer het beheer van uw klantbeoordelingen.

Documentation API

Guide complet pour intégrer Qualibox avec votre CRM ou application externe

Introduction

L'API Qualibox permet de synchroniser vos données entre votre CRM et Qualibox.

L'API REST Qualibox vous permet d'automatiser la synchronisation de vos entreprises, utilisateurs, avis et enquêtes avec votre système d'information.

Synchronisation bidirectionnelle des entreprises
Import automatique des avis clients
Génération de liens d'auto-login pour vos utilisateurs
Gestion des enquêtes de satisfaction
Suivi des abonnements et factures

Tip: La documentation interactive Swagger est accessible à l'adresse /api/docs pour tester les endpoints en direct.

Authentification

Toutes les requêtes API nécessitent une clé API transmise via le header X-Api-Key.

Créer une clé API

1Connectez-vous à votre espace Qualibox
2Allez dans Réglages → API
3Cliquez sur « Créer une clé API »
4Copiez la clé affichée (elle ne sera plus visible ensuite)

Let op: Conservez votre clé API en lieu sûr. Elle ne pourra pas être récupérée ultérieurement.

Format de la clé

Voorbeeld: X-Api-Key: qb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Les clés ont le format qb_ suivi de 48 caractères hexadécimaux.

Scopes

Scope	Accès
Entreprise	Uniquement les données de votre entreprise
Réseau	Toutes les entreprises du réseau

Vereist abonnement:Business

La création de clés API nécessite un abonnement Business ou supérieur.

Entreprises

Endpoints pour gérer les entreprises.

Récupérer mon entreprise

Voorbeeld: GET /api/platform/companies/me

Retourne les détails de l'entreprise liée à la clé API. Disponible uniquement pour les clés de scope « entreprise ».

Créer ou mettre à jour une entreprise

Voorbeeld: POST /api/platform/companies/upsert

Endpoint idempotent pour synchroniser une entreprise. Le rapprochement se fait par externalCrmId ou SIRET.

Champ	Type	Description
name	string	Raison sociale (requis)
externalCrmId	string	ID dans votre CRM
siret	string	SIRET (14 chiffres)
address	string	Adresse
postalCode	string	Code postal
city	string	Ville
email	string	Email de contact
phone	string	Téléphone

Lister les entreprises

Voorbeeld: GET /api/platform/companies?externalCrmId=crm_123

Retourne la liste des entreprises du périmètre. Filtrable par externalCrmId ou slug.

Utilisateurs

Endpoints pour gérer les utilisateurs et l'auto-login.

Créer ou mettre à jour un utilisateur

Voorbeeld: POST /api/platform/users/upsert

Champ	Type	Description
email	string	Email (requis)
firstName	string	Prénom (requis)
lastName	string	Nom (requis)
companyDeviboxId	integer	ID Devibox de l'entreprise

Générer un lien d'auto-login

Voorbeeld: POST /api/platform/auth/login-url

Génère une URL permettant de connecter automatiquement un utilisateur à Qualibox. Utile pour intégrer Qualibox directement dans votre interface.

Champ	Type	Description
userEmail	string	Email de l'utilisateur (requis)
redirect	string	Chemin de redirection après login
locale	string	Langue (fr, en, es...)

Tip: L'URL générée contient un token temporaire et expire après quelques minutes.

Enquêtes

Endpoints pour gérer les enquêtes de satisfaction.

Auto-login vers une enquête

Voorbeeld: POST /api/platform/auth/survey-login-url

Génère une URL d'auto-login redirigeant directement vers une enquête spécifique.

Champ	Type	Description
userEmail	string	Email de l'utilisateur (requis)
surveyId	uuid	UUID de l'enquête
externalId	string	ID externe de l'enquête (alternative)
action	string	dashboard, edit, respondants, alertes, send

Webhooks

Recevez des notifications en temps réel lorsque des événements se produisent sur votre compte.

Vereist abonnement:Business

Les webhooks sont réservés au plan Business. Ils permettent d'automatiser vos processus en recevant des notifications instantanées.

Configurer un webhook

1Allez dans Réglages → API & Intégrations
2Cliquez sur l'onglet Webhooks
3Cliquez sur Ajouter un webhook
4Entrez l'URL de votre endpoint (HTTPS requis en production)
5Sélectionnez les événements à recevoir
6Copiez le secret généré pour vérifier les signatures

Événements disponibles

Événement	Déclencheur
review.created	Un avis est déposé par un client
review.approved	Un avis est approuvé et publié
review.rejected	Un avis est rejeté par la modération
devis.created	Une demande de devis est reçue
devis.updated	Une demande de devis est mise à jour
survey.response	Une réponse d'enquête est soumise

Format du payload

Chaque webhook envoie une requête POST avec un body JSON contenant les données de l'événement. Le format varie selon le type d'événement.

Header	Description
Content-Type	application/json
X-Webhook-Event	Nom de l'événement (ex: review.created)
X-Webhook-Signature	Signature HMAC-SHA256 du body

Vérifier la signature

Pour garantir l'authenticité des webhooks, vérifiez la signature envoyée dans le header X-Webhook-Signature. Calculez le HMAC-SHA256 du body avec votre secret et comparez-le à la signature reçue.

Voorbeeld: signature = HMAC-SHA256(secret, request_body)

Let op: Répondez avec un code HTTP 2xx dans les 30 secondes. Tout autre code ou timeout sera considéré comme un échec.

Tip: En cas d'échec, Qualibox réessaie jusqu'à 3 fois avec un délai exponentiel. Après 3 échecs consécutifs, le webhook est automatiquement désactivé.

Abonnements

Endpoints pour gérer les abonnements premium.

Lister les plans

Voorbeeld: GET /api/platform/plans

Lister les abonnements

Voorbeeld: GET /api/platform/subscriptions

Créer un abonnement

Voorbeeld: POST /api/platform/subscriptions

Champ	Type	Description
planSlug	string	Slug du plan (requis)
companyId	uuid	Entreprise concernée
billingPeriod	string	monthly ou yearly

Factures

Endpoints pour récupérer les factures.

Lister les factures

Voorbeeld: GET /api/platform/invoices

Télécharger un PDF

Voorbeeld: GET /api/platform/invoices/{id}/pdf

Rate Limiting

Limites d'utilisation de l'API.

L'API applique une limite de 100 requêtes par minute par clé API.

Let op: En cas de dépassement, vous recevrez une réponse 429 Too Many Requests. Attendez le délai indiqué dans le header Retry-After avant de réessayer.

Codes d'erreur

Liste des codes d'erreur HTTP retournés par l'API.

Code	Signification
400	Requête mal formée ou champs requis manquants
401	Clé API invalide ou absente
403	Accès refusé (hors périmètre)
404	Ressource non trouvée
409	Conflit (doublon, contrainte d'unicité)
429	Rate limit dépassé
500	Erreur serveur

Tip: Les erreurs sont retournées au format JSON : {"error": "Message d'erreur"}

Documentation interactive

Testez l'API directement dans Swagger UI.

Ouvrir Swagger

Une documentation interactive Swagger est disponible pour tester les endpoints en direct.

URL	Description
/api/docs	Swagger UI - tous les endpoints
/api/docs.json	Spec OpenAPI JSON (pour Postman)
/api/platform/docs	Swagger API Platform (CRUD)

Importer dans Postman

1Ouvrez Postman et cliquez sur « Import »
2Collez l'URL : https://api.quali-box.com/api/docs.json
3Cliquez sur « Import »
4Configurez la variable d'environnement X-Api-Key

Woordenlijst

API Key: Clé d'authentification au format qb_... permettant d'accéder à l'API.
Scope: Périmètre d'accès de la clé API : « entreprise » (une seule) ou « réseau » (toutes les filiales).
Upsert: Opération idempotente qui crée une ressource si elle n'existe pas, ou la met à jour sinon.
externalCrmId: Identifiant de la ressource dans votre CRM, utilisé pour le rapprochement.
Auto-login: Mécanisme permettant de connecter automatiquement un utilisateur via une URL contenant un token temporaire.
Rate limiting: Limitation du nombre de requêtes API autorisées par minute (100 req/min).
UUID: Identifiant unique universel au format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Klaar om Qualibox te integreren?

Maak uw gratis account aan en ontvang uw API-sleutels binnen enkele minuten.