🩺

Valider son intégration avec le diagnostic complet

Apprenez à utiliser les deux endpoints de diagnostic de l'API Coffrify pour vérifier la santé de votre intégration en temps réel et suivre la progression de votre configuration.

Télécharger en PDF

L'API Coffrify expose deux endpoints de diagnostic complémentaires. Le premier, GET /v1/diagnostics/setup-checklist, retourne un score de maturité (0-100) calculé en fonction des éléments de configuration de votre workspace : branding, MFA, domaines vérifiés, webhooks actifs, etc. Le second, POST /v1/diagnostics/full-stack-test, exécute un test bout-en-bout qui sonde successivement la couche d'authentification, la base de données, la configuration des plans tarifaires, le journal d'audit et le sous-système de webhooks, puis rend un verdict global ok ou degraded. Ensemble, ces deux appels constituent le point de départ recommandé pour valider une intégration avant de passer en production.

GET/v1/diagnostics/setup-checklistRetourne un score de maturité (0-100) et la liste des étapes d'onboarding avec leur statut done/not-done et leur niveau d'impact (low, medium, high).POST/v1/diagnostics/full-stack-testLance un smoke-test bout-en-bout sur 5 couches (auth, db_read, config_fetch, audit_write, webhook_subsystem) et retourne un verdict global ok ou degraded.

Authentification

GET /v1/diagnostics/setup-checklist ne requiert aucun scope particulier : tout porteur d'une clé API valide (cof_live_…, cof_test_… ou cof_sandbox_…) pour le workspace cible peut appeler cet endpoint. En revanche, POST /v1/diagnostics/full-stack-test exige le scope workspace:manage car il effectue une écriture dans le journal d'audit (coffrify.diagnostics.full_stack_test). Transmettez votre clé dans l'en-tête Authorization: Bearer <votre_clé>.

Appeler les endpoints

Les exemples ci-dessous récupèrent d'abord la checklist d'onboarding, puis lancent le smoke-test bout-en-bout. Choisissez votre langage.

# 1. Score de configuration
curl -s https://api.coffrify.com/v1/diagnostics/setup-checklist \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx"
 
# 2. Smoke-test bout-en-bout (scope workspace:manage requis)
curl -s -X POST https://api.coffrify.com/v1/diagnostics/full-stack-test \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Réponse : setup-checklist

La réponse renvoie un score global (0-100) et le détail de chaque étape (items) avec son statut et son impact. Concentrez-vous d'abord sur les étapes high non faites.

{
  "score": 72,
  "items": [
    {
      "key": "workspace_named",
      "label": "Workspace nommé",
      "done": true,
      "impact": "low",
      "action_url": "/workspace/settings/workspace"
    },
    {
      "key": "branding_logo",
      "label": "Logo de marque téléchargé",
      "done": true,
      "impact": "medium",
      "action_url": "/workspace/settings/branding"
    },
    {
      "key": "branding_color",
      "label": "Couleur primaire personnalisée",
      "done": false,
      "impact": "low",
      "action_url": "/workspace/settings/branding"
    },
    {
      "key": "mfa_enabled",
      "label": "MFA activé sur le owner",
      "done": true,
      "impact": "high",
      "action_url": "/workspace/settings/security"
    },
    {
      "key": "first_transfer",
      "label": "Premier transfert créé",
      "done": true,
      "impact": "high",
      "action_url": "/transfers"
    },
    {
      "key": "first_webhook",
      "label": "Au moins 1 webhook actif",
      "done": true,
      "impact": "medium",
      "action_url": "/workspace/webhooks/new"
    },
    {
      "key": "custom_domain",
      "label": "Domaine personnalisé vérifié (Ultra)",
      "done": false,
      "impact": "medium",
      "action_url": "/workspace/settings/domains"
    },
    {
      "key": "team_member",
      "label": "Au moins 2 membres dans le workspace",
      "done": false,
      "impact": "low",
      "action_url": "/workspace/workspace/members"
    },
    {
      "key": "api_key",
      "label": "Au moins 1 clé API créée",
      "done": true,
      "impact": "medium",
      "action_url": "/workspace/api-keys/new"
    }
  ]
}

Réponse : full-stack-test

Le smoke-test renvoie un tableau checks, une ligne par couche testée (auth, base, configuration, audit, webhooks), avec son statut et sa latence. Un seul status en échec suffit à invalider l'intégration.

{
  "checks": [
    {
      "step": "auth",
      "status": "ok",
      "ms": 0,
      "detail": "workspace=a1b2c3d4…"
    },
    {
      "step": "db_read",
      "status": "ok",
      "ms": 12,
      "detail": null
    },
    {
      "step": "config_fetch",
      "status": "ok",
      "ms": 8,
      "detail": "pricing config readable"
    },
    {
      "step": "audit_write",
      "status": "ok",
      "ms": 21,
      "detail": null
    },
    {
      "step": "webhook_subsystem",
      "status": "ok",
      "ms": 9,
      "detail": "2 active webhooks"
    }
  ],
  "verdict": "ok"
}

Erreurs possibles

Les erreurs portent surtout sur l'authentification. Le tableau ci-dessous indique la résolution pour chaque cas.

Code HTTP	Code erreur	Quand	Résolution
401	`missing_api_key`	En-tête Authorization absent	Ajoutez `Authorization: Bearer cof_live_…` à votre requête.
401	`invalid_api_key`	Clé mal formée ou inconnue	Vérifiez le préfixe (`cof_live_`, `cof_test_`, `cof_sandbox_`) et régénérez la clé si nécessaire.
401	`expired_api_key`	Clé arrivée à expiration	Créez une nouvelle clé depuis `/workspace/api-keys/new`.
401	`revoked_api_key`	Clé révoquée manuellement	Créez une nouvelle clé depuis `/workspace/api-keys/new`.
403	`scope_missing`	Appel de `POST /full-stack-test` avec une clé sans scope `workspace:manage`	Éditez la clé et cochez le scope `workspace:manage`.
403	`ip_not_allowed`	IP de la requête hors de la liste blanche de la clé	Ajoutez votre IP dans les paramètres de la clé ou désactivez la restriction.
429	`rate_limited`	Quota par minute dépassé pour le workspace	Attendez la durée indiquée dans `Retry-After`, puis relancez la requête.
500	`internal_error`	Erreur interne (base de données, RPC)	Consultez le `request_id` dans la réponse pour le support.

Interpréter le score

Le score retourné par setup-checklist est calculé selon une pondération par impact : chaque élément high vaut 3 points, medium 2 points et low 1 point. Le score final est le rapport entre les points obtenus et le total possible, exprimé en pourcentage entier. Un score de 100 signifie que tous les éléments sont complétés. Les éléments non complétés (done: false) contiennent un action_url qui pointe directement vers la page console concernée.

Voir aussi

Authentification et clés API
Comprendre les scopes et permissions
Configurer votre premier webhook
Référence : GET /v1/diagnostics/setup-checklist
Référence : POST /v1/diagnostics/full-stack-test
Gestion des erreurs et codes de retour

Continuer

Autres tutoriels à suivre

📥Recevoir des fichiers en 5 min (no-code)→🚀Construire un agent qui crée et livre des transferts automatiquement→✅Implémenter un workflow d'approbation de transfert→