---
name: analytical-fields-values
description: Lister les champs analytiques custom et leurs valeurs avec get_analytical_fields + get_analytical_field_values
tags: [get_analytical_fields, get_analytical_field_values, analyticalCodes, spendesk_analyze_spend]
when_to_use: Quand on veut connaître les dimensions analytiques custom d'une entreprise et les valeurs valides pour filtrer spendesk_analyze_spend
---

# Champs analytiques custom et leurs valeurs

## Contexte

Les champs analytiques sont des dimensions personnalisées définies par chaque entreprise (ex: projet, BU, code événement) — distincts des cost centers natifs Spendesk. Ils permettent de taguer les payables avec des valeurs personnalisées.

Ces valeurs sont utilisées comme filtre dans `spendesk_analyze_spend(analyticalCodes=[id])`.

## Workflow en 2 étapes

### Étape 1 — Lister les champs analytiques

```json
{
  "tool": "get_analytical_fields",
  "params": {
    "companyId": "<companyId>"
  }
}
```

Pour chaque champ, noter :
- `id` : identifiant à passer à `get_analytical_field_values(fieldId)`
- `name` : libellé du champ (ex: "Analytic codes", "Projects", "Clients")
- `type` : `"list"` (valeurs énumérées) ou `"boolean"` (case à cocher)
- `isArchived` : si true, le champ est décommissionné
- `isSplittable` : si true, un payable peut avoir plusieurs valeurs de ce champ
- `availableForEntities` : types de payables concernés (`["expense","request","payment","subscription"]`)

### Étape 2 — Obtenir les valeurs d'un champ

```json
{
  "tool": "get_analytical_field_values",
  "params": {
    "companyId": "<companyId>",
    "fieldId": "<id du champ>"
  }
}
```

Retourne la liste des valeurs valides : `{ id, value, isArchived }`.

## Piège : includeArchived par défaut = false, mais retourne quand même les archivés

Sur ce compte, `get_analytical_fields()` sans paramètre retourne **21 champs dont 16 avec `isArchived: true`**, malgré `includeArchived` par défaut = false. Le comportement documenté ("archived fields are excluded by default") ne correspond pas à l'implémentation réelle.

→ Toujours filtrer côté client sur `isArchived: false` pour n'obtenir que les champs actifs.

Sur ce compte : 5 champs actifs sur 21 :

| ID | Nom | Type | Splittable |
|----|-----|------|-----------|
| `S1zHTdxe-` | Analytic codes | list | ✅ oui |
| `kdpholncfz8sdw` | Analytic codes 2021 | list | non |
| `ol-yyb9yal5frj` | B. Start Date (invoice) | list | non |
| `k9__lhhu9gki64` | C. End Date (invoice) | list | non |
| `e3ty_iz-69hgq9` | D. Schedule | list | non |

## Découverte critique : les valeurs analytiques = les expense categories

Les IDs des valeurs retournées par `get_analytical_field_values(fieldId="S1zHTdxe-")` sont **identiques** aux IDs retournés par `get_expense_categories`.

Exemple :
- `get_expense_categories` → "ABM" : `id = r96xprmx87jiso`
- `get_analytical_field_values("S1zHTdxe-")` → "ABM" : `id = r96xprmx87jiso` (idem)

→ Le champ "Analytic codes" et `get_expense_categories` exposent **le même référentiel**. Les IDs de `get_expense_categories` peuvent être directement utilisés dans `spendesk_analyze_spend(analyticalCodes=[...])` sans passer par `get_analytical_field_values`.

## Utilisation dans spendesk_analyze_spend

```json
{
  "tool": "spendesk_analyze_spend",
  "params": {
    "companyId": "<companyId>",
    "dateRange": { "startDate": "2026-01-01", "endDate": "2026-06-30" },
    "groupBy": ["analyticalCode"],
    "analyticalCodes": ["r96xprmx87jiso", "lq0vse74ak0q_n"]
  }
}
```

Les IDs à passer = IDs des valeurs retournées par `get_analytical_field_values`.

## Champs `boolean` — pas de values à fetch

Les champs `type: "boolean"` (ex: "Approved", "Hardware") n'ont pas de valeurs listables. Ils ne sont pas utilisables comme filtre dans `spendesk_analyze_spend`. `get_analytical_field_values` retournerait un tableau vide pour ces champs.

## Exemples de prompts utilisateur

- "Quels sont les codes analytiques disponibles pour filtrer les dépenses ?"
- "Donne-moi toutes les valeurs du champ analytique 'Analytic codes'"
- "Analyse les dépenses par code analytique sur H1 2026"