Premier appel API
Obtenir un jeton et lire les sociétés avec une app connectée.
Prérequis#
Un administrateur crée une app connectée avec le scope companies:read. Récupérez son Client ID et son secret lors de leur présentation. Les exemples utilisent un domaine fictif : remplacez-le par l'adresse de votre instance. Exécutez ces commandes sur votre poste ou serveur, jamais dans le JavaScript public d'une page.
export CERCLA_URL='https://crm.exemple.fr'
export CERCLA_CLIENT_ID='votre-client-id'
# Fournissez CERCLA_CLIENT_SECRET depuis votre gestionnaire de secrets.Obtenir un jeton#
L'endpoint attend un formulaire URL-encodé. --data-urlencode préserve les caractères spéciaux du secret.
TOKEN=$(curl --fail-with-body --silent --show-error "$CERCLA_URL/api/v1/oauth/token" --data-urlencode 'grant_type=client_credentials' --data-urlencode "client_id=$CERCLA_CLIENT_ID" --data-urlencode "client_secret=$CERCLA_CLIENT_SECRET" | jq -er '.access_token')La réponse porte access_token, token_type, expires_in et scope. Le jeton opaque d'app, préfixé sat_, expire par défaut après une heure. Le flux client credentials n'émet pas de refresh token : redemandez un jeton avec les identifiants de l'app. Ne journalisez pas le secret ni le jeton.
Vérifier la connexion#
curl --fail-with-body --silent --show-error "$CERCLA_URL/api/v1/ping" -H "Authorization: Bearer $TOKEN" | jqUn 401 indique notamment un jeton absent, invalide, expiré ou révoqué. Un 403 sur une opération indique souvent un scope ou une action non autorisés. Consultez les erreurs et droits.
Lire une première page#
curl --fail-with-body --silent --show-error "$CERCLA_URL/api/v1/companies?limit=20" -H "Authorization: Bearer $TOKEN" | jqLa réponse paginée contient data et nextCursor. Continuez avec ce curseur jusqu'à null. Ne déduisez pas le nombre total de fiches de la taille d'une page.
Passer à l'écriture#
Ajoutez seulement les scopes nécessaires, par exemple companies:write et referentials:read. Lisez les utilisateurs autorisés pour obtenir un ownerId, puis suivez le corps de création dans la référence REST.
Testez sur des données de recette. Une société naît selon ses règles métier ; son statut client est calculé et ne se force pas dans le corps de création. Les écritures sont attribuées à l'utilisateur d'intégration de l'app.
Télécharger le contrat#
curl --fail-with-body --silent --show-error "$CERCLA_URL/api/v1/openapi.json" -o cercla-openapi.jsonLe document de votre instance est la référence de la version installée. Le contrat téléchargeable dans cette documentation correspond à la version utilisée pour sa construction.