Clés d'intégration — Statistiques avancées & intégrations pour IPBX

Créez, listez, consultez, modifiez et supprimez les clés d'intégration CRM d'un compte client.

Une clé d'intégration contient les identifiants qu'utilise CX-Engine pour connecter un compte client à un système tiers (Salesforce, HubSpot, Dynamics, ConnectWise, un webhook…).

Tous les endpoints de cette section sont scopés au workspace, requièrent le scope OAuth client et agissent sur un seul compte client, sélectionné avec le paramètre de requête customer_account (voir Choix du compte client).

En-têtes : Authorization: Bearer {token-workspace}

Les identifiants ne sont jamais renvoyés. Les secrets sont stockés chiffrés et ne figurent dans aucune réponse de l'API. L'attribut has_keys indique seulement si des identifiants sont enregistrés.

#Permissions

Endpoint	Permission requise
`GET /api/integration-keys`	`customer-integration.view`
`GET /api/integration-keys/{id}`	`customer-integration.view`
`POST /api/integration-keys`	`customer-integration.create`
`PUT /api/integration-keys/{id}`	`customer-integration.edit`
`DELETE /api/integration-keys/{id}`	`customer-integration.delete`

L'utilisateur authentifié doit également avoir accès au compte client sélectionné.

#L'objet clé d'intégration

{
  "id": 7,
  "uid": "70c7ee70-3e75-4dd3-a728-f435af607db4",
  "integration_id": null,
  "outsource_provider": "salesforce",
  "customer_id": 12,
  "keyable_type": "customer",
  "keyable_id": 12,
  "enabled": true,
  "requires_action": false,
  "name": "Salesforce production",
  "type": "oauth",
  "created_at": "2025-02-10T10:12:00.000000Z",
  "updated_at": "2025-02-10T10:15:31.000000Z",
  "has_keys": true
}

Champ	Description
`outsource_provider`	Système connecté : `active_campaign`, `atera`, `bluerocktel`, `connectwise`, `dynamics`, `glpi`, `hubspot`, `neoteem`, `salesforce`, `sellsy`, `webhook`
`type`	Type d'authentification : `none`, `token`, `app_token`, `oauth`, `oauth_pat`, `oauth_client_credentials`, `oauth_azure`, `password`, `basic`, `connectwise`, `oauth_password`, `header_token`
`uid`	Identifiant du flux OAuth, pour les clés OAuth
`requires_action`	`true` tant que l'autorisation OAuth n'a pas été finalisée
`enabled`	Clé utilisée ou non
`has_keys`	Des identifiants sont enregistrés pour cette clé
`integration_id`	Ancien identifiant d'intégration, peut valoir `null`

#GET /api/integration-keys

Retourne toutes les clés d'intégration du client sélectionné sous forme de tableau JSON simple (non paginé).

Paramètres de requête

Paramètre	Type	Requis	Description
`customer_account`	string	oui	Code de compte client

Réponse 200 : tableau d'objets clé d'intégration

#GET /api/integration-keys/{id}

Retourne une clé d'intégration.

Paramètres de requête

Paramètre	Type	Requis	Description
`customer_account`	string	oui	Code de compte client

Réponse 200 : objet clé d'intégration

Réponse 404 : la clé n'appartient pas au client sélectionné

#POST /api/integration-keys

Connecte une nouvelle clé d'intégration au client sélectionné. Le corps doit être un objet JSON. La clé est toujours rattachée au client sélectionné avec customer_account : customer_id, keyable_id, keyable_type et integration_id sont ignorés s'ils sont envoyés.

Paramètres de requête

Paramètre	Type	Requis	Description
`customer_account`	string	oui	Code de compte client

Corps de la requête

Champ	Type	Requis	Description
`outsource_provider`	string	oui	Système connecté (voir le tableau ci-dessous)
`type`	string	oui	Type d'authentification, parmi les types autorisés pour le fournisseur
`name`	string	oui	Nom affiché (2 à 255 caractères)
`enabled`	boolean	non	`true` par défaut
`keys`	object	selon `type`	Identifiants (voir ci-dessous)

type autorisés par fournisseur

`outsource_provider`	`type` autorisés
`active_campaign`	`header_token`
`atera`	`token`
`bluerocktel`	`password`
`connectwise`	`connectwise`
`dynamics`	`oauth_azure`, `oauth_client_credentials`
`glpi`	`app_token`
`hubspot`	`oauth`, `token`
`neoteem`	`basic`
`salesforce`	`oauth`
`sellsy`	`oauth_pat`
`webhook`	`none`, `basic`, `token`, `password`, `oauth_client_credentials`, `oauth_password`

Champs de keys par type

`type`	Champs requis	Champs optionnels
`none`	—	`api_url`
`token`	—	`api_url`, `access_token`, `refresh_token`, `key_placement` (`header` ou `request_parameter`), `header_name` (requis quand `key_placement` vaut `request_parameter`), `header_prefix`
`header_token`	`api_url`, `access_token`	—
`app_token`	`api_url`, `client_id`, `client_secret`	—
`password`, `basic`	`user_login`, `user_password`	`api_url`
`connectwise`	`api_url`, `tenant_id`, `client_id`, `user_login`, `user_password`	—
`oauth_client_credentials`	`api_url`, `client_id`, `client_secret`	`tenant_id`, `scope`
`oauth_password`	`api_url`, `client_id`, `client_secret`, `user_login`, `user_password`	—
`oauth_pat`	`client_id`, `client_secret`	`expires_in`, `expires_at`
`oauth_azure`	`api_url`	—
`oauth`	—	—

Exemple

{
  "outsource_provider": "atera",
  "type": "token",
  "name": "Atera production",
  "keys": {
    "api_url": "https://app.atera.com/api/v3",
    "access_token": "votre-cle-api-atera"
  }
}

Réponse 201

{
  "entity": { "id": 8, "outsource_provider": "atera", "type": "token", "name": "Atera production", "enabled": true, "requires_action": false, "has_keys": true, "...": "..." },
  "action": null
}

Pour les types OAuth (oauth, oauth_azure), la clé est créée avec requires_action: true et action décrit l'autorisation à finaliser : ouvrez action.redirect_url dans un navigateur pour accorder l'accès.

{
  "entity": { "id": 9, "outsource_provider": "salesforce", "type": "oauth", "requires_action": true, "...": "..." },
  "action": {
    "type": "oauth",
    "provider": "salesforce",
    "uid": "70c7ee70-3e75-4dd3-a728-f435af607db4",
    "requires_action": true,
    "redirect_url": "https://login.salesforce.com/services/oauth2/authorize?..."
  }
}

Réponse 400 : échec de validation : outsource_provider manquant ou inconnu, type non autorisé pour le fournisseur, name manquant ou keys invalides pour le type

{
  "response": "bad request: please check body parameters.",
  "hint": ["The selected type is invalid."]
}

#PUT /api/integration-keys/{id}

Renomme, active ou désactive une clé d'intégration, ou remplace ses identifiants. Le corps doit être un objet JSON.

Paramètres de requête

Paramètre	Type	Requis	Description
`customer_account`	string	oui	Code de compte client

Corps de la requête

Champ	Type	Requis	Description
`name`	string	non	Nom affiché (2 à 255 caractères)
`enabled`	boolean	non	Active ou désactive la clé
`keys`	object	non	Nouveaux identifiants, validés selon le `type` actuel de la clé (mêmes champs qu'à la création). Ils remplacent les identifiants enregistrés. Non acceptés pour les clés OAuth (`oauth`, `oauth_azure`) : supprimez puis recréez la clé

Le propriétaire, le fournisseur et le type d'une clé ne peuvent pas être modifiés : envoyer customer_id, keyable_id, keyable_type, integration_id, outsource_provider, type, uid ou requires_action renvoie une 400.

Réponse 201 : l'objet clé d'intégration modifié

Réponse 400 : échec de validation (champ interdit, keys invalides pour le type de la clé)

Réponse 422 : keys envoyés pour une clé OAuth

Réponse 404 : la clé n'appartient pas au client sélectionné

#DELETE /api/integration-keys/{id}

Supprime une clé d'intégration.

Paramètres de requête

Paramètre	Type	Requis	Description
`customer_account`	string	oui	Code de compte client

Réponse 200

{ "response": "element deleted" }

Réponse 404 : la clé n'appartient pas au client sélectionné