---
name: s29-cartes-actives-solde
description: Liste les cartes actives (status=ACT) avec leur solde disponible et résout les noms des propriétaires via list_cards + get_users
tags: [cartes, list_cards, solde, availableBalance, get_users]
when_to_use: Quand on veut voir les cartes virtuelles actives avec leur solde disponible — pour vérifier la trésorerie des cartes, identifier des soldes non utilisés, ou préparer un rapport de flottes de cartes actives
---

# Instructions

## Use case

Lister les cartes actives avec leur solde disponible et identifier le propriétaire pour chaque carte.

## Appel de base

```json
{
  "companyId": "<COMPANY_ID>",
  "status": "ACT",
  "pageSize": 50
}
```

Note : contrairement à `get_purchase_orders.status` qui prend un **tableau**, `list_cards.status` prend une **string simple** (un seul statut à la fois).

## Lifecycle des cartes

```
PRE (pre-active) → ACT (active)
ACT → BLO (blocked)
BLO → REA (reactivated) → ACT
```

États terminaux (ne peuvent pas revenir actifs) : `LOS`, `STO`, `DAM`, `EXP`, `CAN`, `CMD`

Pour lister les cartes actives au sens large, cibler `ACT` et `REA` :
- `status: "ACT"` — actives
- `status: "REA"` — réactivées (après blocage)

## Piège critique — availableBalance.amount est un DÉCIMAL, pas un coefficient

**Toutes les autres réponses Spendesk** retournent `amount` comme un coefficient entier :
`{ amount: 9138, precision: 2 }` → 91.38 EUR

**`list_cards.availableBalance.amount` retourne la valeur DÉCIMALE directement :**
`{ amount: 91.38, currency: "EUR", precision: 2 }` → 91.38 EUR (pas 9138 !)

→ Ne jamais appliquer `amount / 10^precision` sur `availableBalance.amount` de `list_cards` — le résultat serait 100× trop petit.

```javascript
// CORRECT pour list_cards.availableBalance
const balance = card.availableBalance.amount  // 91.38 EUR directement

// CORRECT pour tous les autres tools (get_payables, etc.)
const amount = payable.amount.amount / Math.pow(10, payable.amount.precision)
```

## Structure de réponse

```json
{
  "id": "lfyzcn76rvd200",
  "type": "subscription",          // single_purchase | subscription | physical | multi_use
  "status": "ACT",
  "lastFourDigits": "7071",        // 4 derniers chiffres du PAN — le PAN complet n'est jamais retourné
  "expiryDate": "2030-04-30T23:59:59.000Z",
  "ownerId": "lywtbkp615b21t",     // userId du propriétaire
  "currency": "EUR",
  "availableBalance": { "amount": 91.38, "currency": "EUR", "precision": 2 },
  "spendingLimit": null            // null sur les cartes subscription
}
```

## Piège — spendingLimit null sur les cartes subscription

`spendingLimit` est `null` pour les cartes `subscription` (confirmé S29 et S16). Le solde disponible se lit via `availableBalance` uniquement. Pour les cartes `single_purchase` et `multi_use`, `spendingLimit` contient le plafond.

## Résoudre ownerId → nom de l'employé

`list_cards` retourne `ownerId` (userId) mais pas le nom. Pour afficher le nom :

```json
// get_users avec filtre par ID
{
  "companyId": "<COMPANY_ID>",
  "ids": ["lywtbkp615b21t", "autre_user_id"]
}
```

→ Retourne `{ firstName, lastName, email }` pour chaque userId. Construire un map userId → nom pour enrichir les cartes.

## Filtres disponibles

| Paramètre | Type | Description |
|-----------|------|-------------|
| `status` | string | Un seul statut (PRE/ACT/BLO/REA/EXP/CAN/LOS/STO/DAM/CMD/CBL) |
| `type` | enum | single_purchase / subscription / physical / multi_use |
| `userId` | string | Filtrer par propriétaire |
| `createdAfter` | YYYY-MM-DD | Cartes créées après cette date |
| `createdBefore` | YYYY-MM-DD | Cartes créées avant cette date |

## Exemples de prompts utilisateurs

- "Quelles cartes virtuelles sont actives en ce moment avec leur solde disponible ?"
- "Y a-t-il des cartes avec un solde résiduel non utilisé ?"
- "Montre-moi les cartes actives de l'équipe Marketing"