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

# Agent Bob

> Interface conversationnelle avec Bob, l'assistant IA Finkare. Pilotez le recouvrement en langage naturel.

<Info>**Tester en direct** — Essayez ces endpoints dans la [documentation interactive Scalar](https://api.finkare.io/docs).</Info>

## Vue d'ensemble

Bob est l'assistant IA de Finkare. Via l'API Agent, vous pouvez interagir avec Bob en langage naturel pour :

* Consulter l'état des dossiers de recouvrement
* Analyser les situations et obtenir des recommandations
* Déclencher des actions (pause, accélération, modification de cascade)
* Obtenir des statistiques et des synthèses

Bob dispose d'outils internes pour consulter et agir sur vos dossiers, et respecte les contraintes anti-harcèlement à chaque action.

<Note>
  Les endpoints Agent sont en **v2** (`/api/v2/agent/`).
</Note>

***

## Chat avec Bob

Envoie un message à Bob et reçoit sa réponse.

**Scope requis :** `agent:chat`

<ParamField body="message" type="string" required>
  Message en langage naturel. Exemple : `Combien de factures impayées ai-je en ce moment ?`
</ParamField>

<ParamField body="conversationId" type="string" optional>
  ID de conversation pour continuer un échange existant (UUID)
</ParamField>

<ParamField body="context" type="object" optional>
  Contexte additionnel (page courante, locale, etc.)
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.finkare.io/api/v2/agent/chat \
    -H "X-API-Key: fk_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "message": "Quelles sont les factures impayées de Dupont & Fils ?",
      "context": { "locale": "fr" }
    }'
  ```

  ```typescript SDK theme={null}
  // Utilisation directe de l'API
  const response = await fetch('https://api.finkare.io/api/v2/agent/chat', {
    method: 'POST',
    headers: {
      'X-API-Key': 'fk_live_xxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      message: 'Quelles sont les factures impayées de Dupont & Fils ?',
    }),
  });
  ```
</CodeGroup>

```json theme={null}
{
  "success": true,
  "data": {
    "text": "Dupont & Fils SARL a 2 factures impayées pour un total de 2 350,00 € :\n\n1. **FAC-2026-001** — 1 500,00 € (échue depuis le 31/03/2026, en recouvrement)\n2. **FAC-2026-015** — 850,00 € (échue depuis le 28/02/2026, relance SMS envoyée)\n\nSouhaitez-vous que je mette en pause l'une de ces factures ou que j'accélère la relance ?",
    "toolsCalled": ["invoices_lookup", "debtor_details"],
    "conversationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "requestId": "req_bob_01",
  "timestamp": "2026-04-08T10:05:00Z"
}
```

<ResponseField name="data.text" type="string">
  Réponse de Bob en langage naturel (formatée en Markdown)
</ResponseField>

<ResponseField name="data.toolsCalled" type="array">
  Outils internes utilisés par Bob pour générer la réponse
</ResponseField>

<ResponseField name="data.conversationId" type="string">
  ID de conversation à réutiliser pour poursuivre l'échange
</ResponseField>

### Exemples de messages

| Message                                         | Ce que fait Bob                                                     |
| ----------------------------------------------- | ------------------------------------------------------------------- |
| `Combien de factures impayées ai-je ?`          | Consulte le dashboard et retourne les statistiques                  |
| `Mets en pause le recouvrement de FAC-2026-001` | Déclenche une pause sur le workflow                                 |
| `Quel est le score de solvabilité de Dupont ?`  | Consulte le scoring IA                                              |
| `Envoie un SMS de rappel à Moreau Industries`   | Planifie un SMS (si les contraintes anti-harcèlement le permettent) |
| `Résumé de la semaine`                          | Synthèse des actions, paiements et événements                       |

***

## Lister les conversations

**Scope requis :** `agent:chat`

<ParamField query="limit" type="number" optional default="20">
  Nombre de résultats (max 100)
</ParamField>

<ParamField query="offset" type="number" optional default="0">
  Offset pour pagination
</ParamField>

```bash theme={null}
curl -H "X-API-Key: fk_live_xxx" \
  "https://api.finkare.io/api/v2/agent/conversations?limit=10"
```

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "lastMessage": "Dupont & Fils SARL a 2 factures impayées...",
      "messageCount": 4,
      "createdAt": "2026-04-08T10:00:00Z",
      "updatedAt": "2026-04-08T10:05:00Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 1
  }
}
```

***

## Détails d'une conversation

**Scope requis :** `agent:chat`

<ParamField path="id" type="string" required>
  ID de la conversation (UUID)
</ParamField>

```bash theme={null}
curl -H "X-API-Key: fk_live_xxx" \
  https://api.finkare.io/api/v2/agent/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

### Codes d'erreur possibles

| Code       | HTTP | Description                                 |
| ---------- | ---- | ------------------------------------------- |
| `VAL_001`  | 400  | Message manquant ou conversationId invalide |
| `AUTH_004` | 403  | Scope `agent:chat` requis                   |
| `SVC_001`  | 503  | Service IA temporairement indisponible      |
| `RATE_001` | 429  | Rate limit dépassé                          |