Développer les objets - Chataigne Docs

De nombreuses ressources Chataigne font référence à d’autres ressources par leur id. Par exemple, une organization contient un tableau location_ids d’identifiants loc_…, et non les objets d’établissement complets. Pour éviter un second aller-retour, vous pouvez demander à l’API de développer ces références et d’inclure les objets associés dans la réponse.

Fonctionnement

Transmettez un ou plusieurs paramètres de requête expand[] en indiquant les champs à inclure. Chaque champ développable possède une cible documentée : pour une organization, le champ développable est locations.

curl https://server.chataigne.ai/v1/organizations/org_8f3kd92mxq?expand[]=locations \
  -H "x-api-key: ch_org_live_xxx"

const res = await fetch(
  "https://server.chataigne.ai/v1/organizations/org_8f3kd92mxq?" +
    new URLSearchParams({ "expand[]": "locations" }),
  { headers: { "x-api-key": "ch_org_live_xxx" } },
);
const organization = await res.json();

Sans développement

Par défaut, l’organisation renvoie uniquement les identifiants. Il faudrait effectuer une requête supplémentaire pour chaque établissement afin de récupérer les objets complets.

Réponse par défaut

{
  "id": "org_8f3kd92mxq",
  "object": "organization",
  "name": "Trattoria Group",
  "location_ids": ["loc_2a7wq1", "loc_5h9zt4"],
  "active_location_ids": ["loc_2a7wq1"],
  "created_at": "2026-01-12T09:30:00Z",
  "updated_at": "2026-04-02T14:05:00Z"
}

Avec développement

Lorsque vous développez locations, la réponse ajoute un champ locations contenant les objets location complets. Les champs d’identifiants d’origine sont conservés.

Réponse développée

{
  "id": "org_8f3kd92mxq",
  "object": "organization",
  "name": "Trattoria Group",
  "location_ids": ["loc_2a7wq1", "loc_5h9zt4"],
  "active_location_ids": ["loc_2a7wq1"],
  "locations": [
    {
      "id": "loc_2a7wq1",
      "object": "location",
      "organization_id": "org_8f3kd92mxq",
      "name": "Trattoria Bellevue",
      "currency": "CHF",
      "country": "CH",
      "timezone": "Europe/Zurich",
      "default_language": "fr",
      "address": {
        "line1": "Rue du Marché 12",
        "line2": null,
        "postal_code": "1204",
        "city": "Genève",
        "country": "CH",
        "latitude": 46.2044,
        "longitude": 6.1432
      },
      "created_at": "2026-01-12T09:31:00Z",
      "updated_at": "2026-03-18T08:22:00Z"
    }
  ],
  "created_at": "2026-01-12T09:30:00Z",
  "updated_at": "2026-04-02T14:05:00Z"
}

Le développement est additif. Le tableau location_ids reste présent aux côtés du champ locations développé : les intégrations existantes qui lisent les identifiants continuent donc de fonctionner.

Identifiants et champs développables

Les champs qui contiennent une référence portent le suffixe _id ou _ids et renvoient des identifiants opaques préfixés. Chacun correspond à un champ développable que vous pouvez demander avec expand[].

Ressource	Champ d’identifiant	Contenu	Champ développable	Résultat du développement
`organization`	`location_ids`	Identifiants `loc_…`	`locations`	Tableau de `location`
`location`	`organization_id`	Identifiant `org_…`	—	Non développable

Seuls les champs documentés comme développables peuvent être transmis à expand[]. Le champ organization_id d’une location est un identifiant de référence, mais il n’est actuellement pas développable.

Développement prudent des listes

Le développement est aussi disponible sur les endpoints de liste, mais il est appliqué avec prudence : le paramètre expand[] résout les références de chaque élément du tableau data, et seuls les champs développables documentés sont pris en compte. Associez-le à la pagination pour limiter la taille des réponses.

curl "https://server.chataigne.ai/v1/organizations?limit=5&expand[]=locations" \
  -H "x-api-key: ch_org_live_xxx"

const params = new URLSearchParams({ limit: "5" });
params.append("expand[]", "locations");
const res = await fetch(
  `https://server.chataigne.ai/v1/organizations?${params}`,
  { headers: { "x-api-key": "ch_org_live_xxx" } },
);
const page = await res.json();

Réponse de liste (tronquée)

{
  "object": "list",
  "data": [
    {
      "id": "org_8f3kd92mxq",
      "object": "organization",
      "name": "Trattoria Group",
      "location_ids": ["loc_2a7wq1", "loc_5h9zt4"],
      "active_location_ids": ["loc_2a7wq1"],
      "locations": [
        { "id": "loc_2a7wq1", "object": "location", "name": "Trattoria Bellevue" }
      ],
      "created_at": "2026-01-12T09:30:00Z",
      "updated_at": "2026-04-02T14:05:00Z"
    }
  ],
  "has_more": true,
  "url": "/v1/organizations"
}

Développer une liste multiplie le nombre d’objets contenus dans la réponse : une page de 10 organisations comprenant chacune de nombreux établissements peut devenir volumineuse. Conservez une valeur limit faible et parcourez les résultats page par page plutôt que de demander une grande page avec des développements profonds.

Paramètres

string[]

Répétable. Chaque valeur désigne un champ développable documenté sur la ressource, ou sur chaque élément dans le cas d’une liste. Les noms de champs inconnus sont ignorés au lieu d’être développés.

Champs de réponse

string[]

Toujours présent sur une organization. Contient les identifiants loc_… de ses établissements, que locations soit développé ou non.

location[]

Présent uniquement lorsque expand[]=locations est demandé. Contient les objets location complets référencés par location_ids.

Ressource associée

Pagination

Parcourez les endpoints de liste avec limit, starting_after et ending_before, puis associez cette pagination par curseur à un développement prudent des listes.

​Fonctionnement

​Sans développement

​Avec développement

​Identifiants et champs développables

​Développement prudent des listes

​Paramètres

​Champs de réponse

​Ressource associée

Pagination

Fonctionnement

Sans développement

Avec développement

Identifiants et champs développables

Développement prudent des listes

Paramètres

Champs de réponse

Ressource associée