# 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.

```sh
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.

```sh
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

```sh
curl --fail-with-body --silent --show-error   "$CERCLA_URL/api/v1/ping"   -H "Authorization: Bearer $TOKEN" | jq
```

Un `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](/documentation/api-conventions/).

## Lire une première page

```sh
curl --fail-with-body --silent --show-error   "$CERCLA_URL/api/v1/companies?limit=20"   -H "Authorization: Bearer $TOKEN" | jq
```

La 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](/documentation/api-reference/).

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

```sh
curl --fail-with-body --silent --show-error   "$CERCLA_URL/api/v1/openapi.json" -o cercla-openapi.json
```

Le 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.