> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chataigne.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Trouver vos ressources

> Découvrez l’organisation commerciale et les établissements disponibles pour votre clé API.

Commencez une intégration en demandant à l’API quelles ressources sont accessibles à votre clé. Conservez les identifiants renvoyés et utilisez-les dans les requêtes suivantes.

## Lister les établissements accessibles

`GET /v1/locations` est la meilleure requête de découverte pour tous les types de clés. Elle nécessite `location.read`.

```bash theme={null}
curl https://server.chataigne.ai/v1/locations \
  -H "x-api-key: $CHATAIGNE_API_KEY"
```

* Avec une clé limitée à une organisation commerciale, la réponse contient les établissements enfants accessibles.
* Avec une clé limitée à un établissement, la réponse contient cet établissement unique.

L’endpoint renvoie une liste paginée. Consultez `has_more` et utilisez `starting_after` pour récupérer la page suivante.

## Récupérer un établissement

Utilisez un identifiant issu de la liste avec `GET /v1/locations/{location_id}`. Cette requête nécessite également `location.read`.

```bash theme={null}
curl https://server.chataigne.ai/v1/locations/loc_r8v4n2c6tz \
  -H "x-api-key: $CHATAIGNE_API_KEY"
```

La requête renvoie `404` si l’identifiant n’existe pas ou se trouve en dehors du périmètre de la clé.

## Lister les organisations accessibles

`GET /v1/organizations` nécessite `businessOrganization.read` et renvoie une liste paginée contenant zéro ou une organisation :

```bash theme={null}
curl https://server.chataigne.ai/v1/organizations \
  -H "x-api-key: $CHATAIGNE_API_KEY"
```

| Périmètre de la clé      | Résultat                                                                         |
| ------------------------ | -------------------------------------------------------------------------------- |
| Organisation commerciale | L’organisation comprise dans le périmètre.                                       |
| Établissement            | Une liste vide. L’accès à un établissement ne remonte pas vers son organisation. |

Une liste d’organisations vide est donc valide et ne signifie pas que la liste des établissements sera également vide.

## Récupérer une organisation

Utilisez l’identifiant renvoyé avec `GET /v1/organizations/{organization_id}`. Cette requête nécessite `businessOrganization.read`.

```bash theme={null}
curl https://server.chataigne.ai/v1/organizations/busorg_k3m9x2p7qw \
  -H "x-api-key: $CHATAIGNE_API_KEY"
```

Ajoutez `expand[]=locations` pour inclure les objets établissement complets avec les identifiants des établissements de l’organisation :

```bash theme={null}
curl "https://server.chataigne.ai/v1/organizations/busorg_k3m9x2p7qw?expand[]=locations" \
  -H "x-api-key: $CHATAIGNE_API_KEY"
```

## Lister les établissements d’une organisation

Lorsque vous connaissez déjà l’identifiant de l’organisation, appelez `GET /v1/organizations/{organization_id}/locations`. Cette requête nécessite `location.read`.

```bash theme={null}
curl https://server.chataigne.ai/v1/organizations/busorg_k3m9x2p7qw/locations \
  -H "x-api-key: $CHATAIGNE_API_KEY"
```

Vous obtenez ainsi une liste d’établissements limitée à l’organisation présente dans l’URL. Utilisez `GET /v1/locations` lorsque vous souhaitez simplement récupérer tous les établissements accessibles à votre clé.

## Choisir la bonne requête de découverte

| Objectif                                     | Endpoint                                            | Permission                  |
| -------------------------------------------- | --------------------------------------------------- | --------------------------- |
| Trouver tous les établissements accessibles  | `GET /v1/locations`                                 | `location.read`             |
| Récupérer un établissement                   | `GET /v1/locations/{location_id}`                   | `location.read`             |
| Trouver l’organisation du périmètre          | `GET /v1/organizations`                             | `businessOrganization.read` |
| Récupérer une organisation                   | `GET /v1/organizations/{organization_id}`           | `businessOrganization.read` |
| Lister les établissements d’une organisation | `GET /v1/organizations/{organization_id}/locations` | `location.read`             |

Consultez [Pagination](/fr/concepts/pagination) pour toutes les options de curseur et [Développement des objets](/fr/concepts/expanding-objects) pour le fonctionnement de `expand[]`.

<Card title="Gérer un établissement" icon="store" href="/fr/location-organization-management/overview">
  Utilisez les identifiants découverts pour mettre à jour les profils et paramètres opérationnels.
</Card>