# Clients

Les outils clients permettent de gérer vos contacts (particuliers) et organisations (entreprises). Ces clients sont ensuite utilisables dans la facturation.

Abby distingue deux types de clients :

* **Contacts** — clients particuliers (personnes physiques)
* **Organisations** — clients professionnels (entreprises, associations, etc.)

Les organisations peuvent avoir plusieurs contacts associés.

## Lecture

### `get-contacts`

Récupère les contacts avec pagination et recherche.

**Paramètres**

| Paramètre  | Type    | Requis | Description                               |
| ---------- | ------- | ------ | ----------------------------------------- |
| `page`     | number  | Non    | Numéro de page (défaut : 1)               |
| `limit`    | number  | Non    | Résultats par page, max 100 (défaut : 50) |
| `search`   | string  | Non    | Recherche par prénom ou nom               |
| `archived` | boolean | Non    | Filtrer par statut d'archivage            |

**Réponse**

```json
{
  "success": true,
  "total": 15,
  "page": 1,
  "contacts": [
    {
      "id": "string",
      "firstname": "Jean",
      "lastname": "Dupont",
      "emails": ["jean.dupont@email.com"],
      "phone": "+33612345678",
      "jobTitle": "Directeur technique",
      "organizationId": "string",
      "organizationName": "Dupont SARL",
      "notes": "",
      "addresses": [...],
      "archivedAt": null,
      "hasBillings": true,
      "createdAt": "2025-01-15T00:00:00.000Z"
    }
  ]
}
```

***

### `get-contact-by-id`

Récupère un contact par son identifiant. Retourne les détails incluant nom, email, téléphone, poste, organisation et adresses.

**Paramètres**

| Paramètre   | Type   | Requis | Description            |
| ----------- | ------ | ------ | ---------------------- |
| `contactId` | string | Oui    | Identifiant du contact |

***

### `get-organizations`

Récupère les organisations avec pagination et recherche.

**Paramètres**

| Paramètre  | Type    | Requis | Description                               |
| ---------- | ------- | ------ | ----------------------------------------- |
| `page`     | number  | Non    | Numéro de page (défaut : 1)               |
| `limit`    | number  | Non    | Résultats par page, max 100 (défaut : 50) |
| `search`   | string  | Non    | Recherche par nom                         |
| `archived` | boolean | Non    | Filtrer par statut d'archivage            |

**Réponse**

```json
{
  "success": true,
  "total": 8,
  "organizations": [
    {
      "id": "string",
      "name": "Dupont SARL",
      "commercialName": "Dupont & Fils",
      "emails": ["contact@dupont.fr"],
      "siret": "12345678901234",
      "vatNumber": "FR12345678901",
      "countContacts": 3,
      "notes": "",
      "addresses": [...],
      "archivedAt": null,
      "hasBillings": true,
      "createdAt": "2025-01-15T00:00:00.000Z"
    }
  ]
}
```

***

### `get-organization-by-id`

Récupère une organisation par son identifiant. Retourne les détails incluant nom, SIRET, TVA, nombre de contacts et adresses.

**Paramètres**

| Paramètre        | Type   | Requis | Description                   |
| ---------------- | ------ | ------ | ----------------------------- |
| `organizationId` | string | Oui    | Identifiant de l'organisation |

***

### `get-organization-contacts`

Récupère tous les contacts associés à une organisation.

**Paramètres**

| Paramètre        | Type   | Requis | Description                   |
| ---------------- | ------ | ------ | ----------------------------- |
| `organizationId` | string | Oui    | Identifiant de l'organisation |

**Réponse**

```json
{
  "success": true,
  "total": 3,
  "organizationId": "string",
  "contacts": [
    {
      "id": "string",
      "firstname": "Marie",
      "lastname": "Martin",
      "emails": ["m.martin@dupont.fr"],
      "jobTitle": "Comptable",
      "defaultContact": true
    }
  ]
}
```

***

## Création

### `create-contact`

Crée un nouveau contact (client particulier). Nécessite au minimum un prénom et un nom.

**Paramètres**

| Paramètre                   | Type      | Requis | Description                              |
| --------------------------- | --------- | ------ | ---------------------------------------- |
| `firstname`                 | string    | Oui    | Prénom                                   |
| `lastname`                  | string    | Oui    | Nom de famille                           |
| `emails`                    | string\[] | Non    | Adresses email                           |
| `phone`                     | string    | Non    | Numéro de téléphone                      |
| `jobTitle`                  | string    | Non    | Poste / fonction                         |
| `notes`                     | string    | Non    | Notes libres                             |
| `billingAddress`            | object    | Non    | Adresse de facturation                   |
| `billingAddress.address`    | string    | Oui    | Rue                                      |
| `billingAddress.complement` | string    | Non    | Complément (bâtiment, étage, etc.)       |
| `billingAddress.city`       | string    | Oui    | Ville                                    |
| `billingAddress.zipCode`    | string    | Oui    | Code postal                              |
| `billingAddress.country`    | string    | Oui    | Code pays ISO 3166-1 alpha-2 (ex : `FR`) |
| `deliveryAddress`           | object    | Non    | Adresse de livraison (même structure)    |

***

### `create-organization`

Crée une nouvelle organisation (client professionnel). Nécessite au minimum un nom.

**Paramètres**

| Paramètre         | Type      | Requis | Description                                                  |
| ----------------- | --------- | ------ | ------------------------------------------------------------ |
| `name`            | string    | Oui    | Raison sociale                                               |
| `commercialName`  | string    | Non    | Nom commercial                                               |
| `emails`          | string\[] | Non    | Adresses email                                               |
| `siret`           | string    | Non    | Numéro SIRET                                                 |
| `vatNumber`       | string    | Non    | Numéro de TVA intracommunautaire                             |
| `notes`           | string    | Non    | Notes libres                                                 |
| `billingAddress`  | object    | Non    | Adresse de facturation (même structure que `create-contact`) |
| `deliveryAddress` | object    | Non    | Adresse de livraison (même structure)                        |

***

## Modification

### `update-contact`

Met à jour un contact existant. Charge les données existantes avant la mise à jour pour préserver les informations non exposées (coordonnées bancaires, préférences).

**Paramètres**

| Paramètre         | Type      | Requis | Description            |
| ----------------- | --------- | ------ | ---------------------- |
| `contactId`       | string    | Oui    | Identifiant du contact |
| `firstname`       | string    | Non    | Prénom                 |
| `lastname`        | string    | Non    | Nom de famille         |
| `emails`          | string\[] | Non    | Adresses email         |
| `phone`           | string    | Non    | Numéro de téléphone    |
| `jobTitle`        | string    | Non    | Poste / fonction       |
| `billingAddress`  | object    | Non    | Adresse de facturation |
| `deliveryAddress` | object    | Non    | Adresse de livraison   |

{% hint style="info" %}
Les notes sont gérées séparément via `update-contact-notes` pour éviter tout écrasement accidentel.
{% endhint %}

***

### `update-organization`

Met à jour une organisation existante. Préserve les coordonnées bancaires et préférences existantes.

**Paramètres**

| Paramètre         | Type      | Requis | Description                   |
| ----------------- | --------- | ------ | ----------------------------- |
| `organizationId`  | string    | Oui    | Identifiant de l'organisation |
| `name`            | string    | Non    | Raison sociale                |
| `commercialName`  | string    | Non    | Nom commercial                |
| `emails`          | string\[] | Non    | Adresses email                |
| `siret`           | string    | Non    | Numéro SIRET                  |
| `vatNumber`       | string    | Non    | Numéro de TVA                 |
| `billingAddress`  | object    | Non    | Adresse de facturation        |
| `deliveryAddress` | object    | Non    | Adresse de livraison          |

***

### `update-contact-notes`

Met à jour les notes d'un contact via un use case dédié.

**Paramètres**

| Paramètre   | Type   | Requis | Description            |
| ----------- | ------ | ------ | ---------------------- |
| `contactId` | string | Oui    | Identifiant du contact |
| `notes`     | string | Oui    | Nouvelles notes        |

***

### `update-organization-notes`

Met à jour les notes d'une organisation via un use case dédié.

**Paramètres**

| Paramètre        | Type   | Requis | Description                   |
| ---------------- | ------ | ------ | ----------------------------- |
| `organizationId` | string | Oui    | Identifiant de l'organisation |
| `notes`          | string | Oui    | Nouvelles notes               |

***

## Suppression et archivage

### `delete-contact`

Supprime définitivement un contact. **Échoue si le contact a des documents de facturation** — utilisez `archive-contact` dans ce cas.

**Paramètres**

| Paramètre   | Type   | Requis | Description            |
| ----------- | ------ | ------ | ---------------------- |
| `contactId` | string | Oui    | Identifiant du contact |

***

### `delete-organization`

Supprime définitivement une organisation. **Échoue si l'organisation a des contacts ou des documents de facturation** — utilisez `archive-organization` dans ce cas.

**Paramètres**

| Paramètre        | Type   | Requis | Description                   |
| ---------------- | ------ | ------ | ----------------------------- |
| `organizationId` | string | Oui    | Identifiant de l'organisation |

***

### `archive-contact`

Archive un contact (suppression douce). Le contact n'apparaît plus dans les listes actives mais ses données sont conservées. **Préférez l'archivage à la suppression** quand le contact a des documents de facturation.

**Paramètres**

| Paramètre   | Type   | Requis | Description            |
| ----------- | ------ | ------ | ---------------------- |
| `contactId` | string | Oui    | Identifiant du contact |

***

### `archive-organization`

Archive une organisation. L'organisation n'apparaît plus dans les listes actives mais ses données sont conservées.

**Paramètres**

| Paramètre        | Type   | Requis | Description                   |
| ---------------- | ------ | ------ | ----------------------------- |
| `organizationId` | string | Oui    | Identifiant de l'organisation |

***

## Scopes requis

| Outil                                                                                                                                                                                                                     | Scope          |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `get-contacts`, `get-contact-by-id`, `get-organizations`, `get-organization-by-id`, `get-organization-contacts`                                                                                                           | `client:read`  |
| `create-contact`, `create-organization`, `update-contact`, `update-organization`, `update-contact-notes`, `update-organization-notes`, `delete-contact`, `delete-organization`, `archive-contact`, `archive-organization` | `client:write` |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.abby.fr/mcp/clients.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.