Capturia mesure ses publicités et la fréquentation du site avec le pixel Meta et Google Analytics. Tu peux refuser en tout temps. En savoir plus

EN

Systems

1 point d'accès

get/v1/systems

Lister les Systèmes

Retourne les Systèmes actifs du compte, le Système principal d'abord, puis les autres par nom. Un Système en brouillon ou archivé n'est pas listé.

L'id d'un Système est la clé à passer partout où l'API en nomme un : le filtre system_id de GET /v1/contacts, le system_id d'une création de contact ou d'une capture de lead, la limite system_ids d'un webhook. Chaque contact lu rend le sien (system).

Pas de pagination par curseur

Un compte a peu de Systèmes (100 au plus sont rendus) : la liste tient toujours dans une seule page. La réponse retourne pagination.next_cursor=null et has_more=false ; pagination.limit vaut toujours 100, la borne de cette page, et pagination.total_count le nombre de Systèmes rendus.

Scope

contacts:read ou webhooks:manage : l'un ou l'autre suffit. Une clé qui lit les contacts y lit la légende de leur Système ; une clé qui gère des webhooks y trouve les identifiants de system_ids. Une clé qui n'a aucun des deux reçoit 403 insufficient_scope, qui nomme contacts:read.

Ouverture compte par compte

Les Systèmes s'ouvrent à l'API compte par compte. Tant que ce n'est pas ouvert pour le compte de la clé, la réponse est 403 feature_not_available (details.feature: systems) : le refus vient du compte, pas de la clé.

Scopes requis : contacts:read ou webhooks:manage

Réponses

StatutDescription
200

Systèmes actifs du compte.

401

La clé API manque, est inconnue ou a expiré. code distingue les trois causes : missing_api_key (aucun en-tête Authorization: Bearer), invalid_api_key (clé inconnue, révoquée ou de format invalide) et expired_api_key (date d'expiration dépassée).

missing_api_key
{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Aucune clé API n'a été fournie.",
    "hint": "Ajoute un header Authorization sous la forme : Bearer cap_live_<ta_clé>",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#missing_api_key",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
invalid_api_key
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "La clé API est invalide ou a été révoquée.",
    "hint": "Vérifie la clé dans ton dashboard ou génère-en une nouvelle.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#invalid_api_key",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
expired_api_key
{
  "error": {
    "type": "authentication_error",
    "code": "expired_api_key",
    "message": "La clé API a expiré.",
    "hint": "Roule la clé depuis le dashboard pour en générer une nouvelle valide.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#expired_api_key",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
403

Refus d'autorisation. code distingue les refus que l'opération rend sous ce statut, et chaque exemple en montre un. insufficient_scope : la clé n'a ni contacts:read ni webhooks:manage ; le refus nomme contacts:read. feature_not_available : details.feature nomme ce qui manque, l'API publique au forfait du compte (public_api) ou les Systèmes, pas encore ouverts à l'API pour ce compte (systems).

browser_not_allowed
{
  "error": {
    "type": "authorization_error",
    "code": "browser_not_allowed",
    "message": "Les clés API s'utilisent depuis un serveur, jamais depuis un navigateur.",
    "hint": "La requête porte un en-tête `Origin` : appelle l'API depuis ton serveur, où la clé reste secrète.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/errors#browser_not_allowed",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
account_suspended
{
  "error": {
    "type": "authorization_error",
    "code": "account_suspended",
    "message": "L'accès à ce compte est suspendu par l'équipe Capturia.",
    "hint": "Le refus vient du compte, pas de la clé. Tant que la suspension dure, aucune requête n'est acceptée : contacte l'équipe Capturia.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#account_suspended",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
feature_not_availablepublic_api
{
  "error": {
    "type": "authorization_error",
    "code": "feature_not_available",
    "message": "Cette fonctionnalité n'est pas incluse dans ton forfait.",
    "hint": "Le refus vient du forfait du compte, pas de la clé. Contacte ton conseiller Capturia pour en parler.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#plan",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "feature": "public_api"
    }
  }
}
insufficient_scope
{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Cette clé API ne contient pas le scope requis pour ce point d'accès.",
    "hint": "Cette clé n'a pas le scope `contacts:read`. Crée une nouvelle clé avec le preset « Lecture seule » ou ajoute le scope via le dashboard.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#scopes",
    "dashboard_url": "https://capturia.io/platform/dashboard/admin/integrations/api-keys/6f1e2d3c-4b5a-4c6d-8e7f-9a0b1c2d3e4f?tab=permissions",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "required_scope": "contacts:read",
      "current_scopes": [
        "leads:capture"
      ],
      "suggested_preset": "read_only"
    }
  }
}
feature_not_availablesystems
{
  "error": {
    "type": "authorization_error",
    "code": "feature_not_available",
    "message": "Cette fonctionnalité n'est pas encore ouverte pour ce compte.",
    "hint": "Capturia l'ouvre compte par compte avant son lancement ; le refus vient du compte, pas de la clé. `details.feature` la nomme. Contacte ton conseiller Capturia pour la faire ouvrir.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#plan",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "feature": "systems"
    }
  }
}
429

Limite de débit atteinte. rate_limit_exceeded : le quota horaire de la clé est épuisé. too_many_attempts : trop de clés invalides présentées depuis cette adresse IP (protection contre la force brute). Dans les deux cas, Retry-After donne le délai en secondes.

rate_limit_exceeded
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Limite de requêtes atteinte.",
    "hint": "Réessaie après le nombre de secondes indiqué dans retry_after_seconds, et envisage d'implémenter un backoff exponentiel.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/rate-limits",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "limit": 100,
      "count": 100,
      "limit_type": "per_key",
      "retry_after_seconds": 42
    }
  }
}
too_many_attempts
{
  "error": {
    "type": "rate_limit_error",
    "code": "too_many_attempts",
    "message": "Trop de tentatives d'authentification invalides depuis cette IP.",
    "hint": "Attends la période indiquée par retry_after_seconds avant de réessayer.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/authentication#brute-force",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7",
    "details": {
      "limit_type": "brute_force",
      "retry_after_seconds": 300
    }
  }
}
500

Erreur serveur inattendue. Toujours fournir le request_id au support.

internal_error
{
  "error": {
    "type": "server_error",
    "code": "internal_error",
    "message": "Erreur serveur. L'équipe Capturia a été notifiée.",
    "hint": "Si le problème persiste, contacte le support en incluant le request_id de cette réponse.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/errors#internal_error",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
501

Les clés de test (cap_test_) ne sont pas encore servies : seules les clés cap_live_ sont acceptées.

not_implemented
{
  "error": {
    "type": "server_error",
    "code": "not_implemented",
    "message": "Cette fonctionnalité n'est pas encore implémentée.",
    "hint": "Consulte la documentation API pour les fonctionnalités disponibles et le changelog pour les prochaines versions.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/errors#not_implemented",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}
503

Un service dont la requête dépend n'a pas répondu (lecture de la clé, du compte ou du forfait). La même requête passera quand il reviendra : réessaie après le délai de Retry-After.

service_unavailable
{
  "error": {
    "type": "server_error",
    "code": "service_unavailable",
    "message": "Service temporairement indisponible.",
    "hint": "Réessaie après la période indiquée par Retry-After.",
    "doc_url": "https://capturia.io/fr/developers/api/v1/errors#service_unavailable",
    "request_id": "req_01J9X8Z3F4K2M5N7P9Q1R3S5T7"
  }
}

Exemple de requête

curl -X GET 'https://api.capturia.io/v1/systems' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'