QualyWatchQualywatchSoft launch
Essayer
Docs · v1REST stable

API Reference v1

Branchez Qualywatch à votre CRM, ERP, BI ou helpdesk. Authentification par clé, permissions par scope, rate limit par clé. Tout en JSON, tout sous HTTPS.

Demander un accèsPrésentation produit

№ 01 · Introduction

Une API REST pensée pour vos intégrations

L'API publique Qualywatch v1 est REST, versionnée, et exclusivement JSON sur HTTPS. Toutes les ressources sont scopées à votre entreprise (multi-tenant strict). Les changements rétro-incompatibles sortiront sur une nouvelle version (v2) — la v1 restera maintenue.

Base URL

https://api.qualywatch.com/api

Format

application/json — toutes les réponses suivent { success, data, message? }.

№ 02 · Authentification

Bearer token avec scopes granulaires

Générez vos clés depuis le dashboard/dashboard/api-access(plans Business et Enterprise). Format qw_…, hashé SHA-256 côté serveur, révocable à tout moment.

Authorization header
Authorization: Bearer qw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Scopes disponibles

  • read:feedbacks

    Lecture liste et détail des feedbacks.

  • write:feedbacks

    Création de feedbacks via API.

  • read:stats

    Lecture des stats globales et NPS.

  • read:employees

    Lecture de l'annuaire employés.

  • read:services

    Lecture du catalogue services.

  • read:clients

    Lecture de la base clients.

  • webhooks

    Gestion des abonnements webhooks.

Sécurité : ne committez jamais vos clés. Stockez-les dans un secret manager (Vault, AWS Secrets, GitHub Encrypted Secrets…). Une clé compromise se révoque en 1 clic depuis le dashboard.

№ 03 · Rate limits

60 ou 300 requêtes par minute, par clé

Plan Business

60 req / min

Jusqu'à 3 clés actives en parallèle.

Plan Enterprise

300 req / min

Clés illimitées.

Chaque réponse inclut les headers suivants pour vous permettre d'adapter votre cadence :

Rate limit headers
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1714402100

En cas de dépassement, l'API renvoie un 429 Too Many Requests. Implémentez un retry avec backoff exponentiel.

№ 04 · Erreurs

Codes HTTP standards

CodeStatusQuand ?
400Bad RequestPayload invalide ou paramètres manquants.
401UnauthorizedClé API absente, mal formée ou révoquée.
403ForbiddenScope insuffisant pour cette ressource.
404Not FoundRessource introuvable ou hors de votre tenant.
429Too Many RequestsQuota de rate limit dépassé.
500Server ErrorIncident côté API. Réessayez avec backoff.
Exemple · 401 Unauthorized
401
{
  "success": false,
  "message": "Invalid or revoked API key."
}

№ 05 · Endpoints

Catalogue complet de la v1

GET/v1/feedbacksread:feedbacks

Liste paginée des feedbacks de votre entreprise. Tri décroissant par date de création. Filtres par type, statut et fenêtre de dates.

Query params

  • type — positif · negatif · suggestion · nps
  • status — new · seen · in_progress · treated · resolved · archived…
  • date_from / date_to — format YYYY-MM-DD
  • page / per_page — défaut 20, max 100
curl · GET /v1/feedbacks
curl https://api.qualywatch.com/api/v1/feedbacks?type=negatif&per_page=10 \
  -H "Authorization: Bearer qw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
200 OK · réponse
200
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid-feedback-1",
        "reference": "FB-20260415-0042",
        "type": "negatif",
        "status": "new",
        "rating": 2,
        "created_at": "2026-04-29T08:14:00+00:00"
      }
    ],
    "pagination": {
      "total": 128, "per_page": 10, "current_page": 1, "last_page": 13
    }
  }
}
GET/v1/feedbacks/{id}read:feedbacks

Détail complet d'un feedback : client, employé assigné, service, sentiment, et coordonnées de contact.

curl · GET /v1/feedbacks/{id}
curl https://api.qualywatch.com/api/v1/feedbacks/uuid-feedback-1 \
  -H "Authorization: Bearer qw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
POST/v1/feedbackswrite:feedbacks

Pousse un nouveau feedback dans Qualywatch (déclenche détection de sentiment, alertes critiques, et SLA si applicable).

curl · POST /v1/feedbacks
curl -X POST https://api.qualywatch.com/api/v1/feedbacks \
  -H "Authorization: Bearer qw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"type":"negatif","title":"Caisse 4 lente","description":"15 min d'attente","rating":2,"contact_email":"client@example.com"}'
201 Created
201
{
  "success": true,
  "data": {
    "id": "uuid-feedback-2",
    "reference": "FB-20260429-0128",
    "status": "new"
  }
}
GET/v1/stats/overviewread:stats

Indicateurs agrégés de l'entreprise : volumes par type, satisfaction, ratio résolution, top services.

curl · GET /v1/stats/overview
curl https://api.qualywatch.com/api/v1/stats/overview \
  -H "Authorization: Bearer qw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
GET/v1/stats/npsread:stats

Score NPS global, breakdown promoteurs / passifs / détracteurs, et évolution mensuelle.

curl · GET /v1/stats/nps
curl https://api.qualywatch.com/api/v1/stats/nps \
  -H "Authorization: Bearer qw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
GET/v1/employeesread:employees

Annuaire des employés avec service de rattachement, position et statut actif.

curl · GET /v1/employees
curl https://api.qualywatch.com/api/v1/employees \
  -H "Authorization: Bearer qw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
GET/v1/servicesread:services

Catalogue des services / points de contact de votre entreprise.

curl · GET /v1/services
curl https://api.qualywatch.com/api/v1/services \
  -H "Authorization: Bearer qw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
GET/v1/clientsread:clients

Base clients de l'entreprise — nom, email, téléphone, total feedbacks, KaliPoints, dernière activité (200 plus récents).

curl · GET /v1/clients
curl https://api.qualywatch.com/api/v1/clients \
  -H "Authorization: Bearer qw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

№ 06 · Webhooks

Recevez les événements en push

Statut :infrastructure prête (HMAC-SHA256 signing, retry/backoff). Le dispatcher de delivery est en cours d'intégration ; la création/suppression d'abonnements renvoie temporairement 501 Not Implemented. La lecture des abonnements existants reste fonctionnelle.

GET/v1/webhookswebhooks

Liste les abonnements webhooks attachés à votre clé d'API.

POST/v1/webhookswebhooks

Crée un abonnement (dispatcher en cours d'intégration).

DELETE/v1/webhooks/{id}webhooks

Supprime un abonnement existant (dispatcher en cours d'intégration).

Événements supportés

  • feedback.created

    Nouveau feedback reçu (tous types).

  • feedback.critical

    Feedback flag critique (sentiment / mots-clés).

  • sla.breach

    SLA dépassé sur un feedback ouvert.

Vérifier la signature

Chaque livraison embarque un headerX-QW-Signature: sha256=…calculé avec le secret de votre webhook (HMAC-SHA256 du body brut).

Vérification — Node.js
const hmac = crypto.createHmac("sha256", WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");
const expected = "sha256=" + hmac;
if (header !== expected) reject();

Politique de retry

En cas d'échec (timeout, 5xx, ou status >= 400), 3 tentatives sont déclenchées avec un backoff progressif :

  • +10s · 1ère retry
  • +1min · 2e retry
  • +5min · 3e retry

Après 3 échecs consécutifs, le webhook est désactivé et une notification est envoyée à l'administrateur du compte.

Prêt à brancher Qualywatch à votre stack ?

L'accès API est inclus dans les plans Business et Enterprise.

Demander un accès