> For the complete documentation index, see [llms.txt](https://docs.abby.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.abby.fr/mcp/conventions.md).

# Conventions

Cette page décrit les conventions communes aux outils MCP d'Abby. Pour les conventions de l'API REST, voir [Conventions](https://docs.abby.fr/concepts/conventions.md) : les règles ne sont pas toujours les mêmes.

## Écrire les montants en centimes

Les montants que vous envoyez aux outils, et ceux qu'ils renvoient, sont exprimés en **centimes d'euros** (euros × 100).

| Montant réel | Valeur dans l'outil |
| ------------ | ------------------- |
| 100,00 €     | `10000`             |
| 75,50 €      | `7550`              |
| 0,99 €       | `99`                |
| 1 500,00 €   | `150000`            |

{% hint style="warning" %}
Ne confondez pas euros et centimes. Un prix unitaire de `7500` correspond à **75,00 €**, pas à 7 500 €.
{% endhint %}

**Formules de conversion :**

* Entrée : euros × 100 = centimes
* Affichage : centimes ÷ 100 = euros

Trois règles complètent la convention :

* Une remise en pourcentage (`discount.mode: "PERCENTAGE"`) s'écrit en pourcents : `10` pour 10 %. Une remise en montant (`"AMOUNT"`) s'écrit en centimes. Voir [Facturation](https://docs.abby.fr/mcp/facturation.md#remise).
* Un pourcentage d'acompte (`create-advance`, mode `percentage`) s'écrit en pourcents : `30` pour 30 %.
* **Exception** : `get-turnover-estimations` renvoie ses montants en euros. Voir [Déclarations URSSAF](https://docs.abby.fr/mcp/declarations-urssaf.md).

## Écrire les dates

Le format dépend de l'outil :

| Où                                                                                       | Format                                                                                                                                      |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `rangeFrom` et `rangeTo` de `get-billings`                                               | Jour au format `YYYY-MM-DD`, interprété en heure d'Europe/Paris                                                                             |
| `customDueDate`, `emittedAt`, `deliveryDate` et `expiredAt` de `update-billing-timeline` | Timestamp Unix en **secondes** (entier)                                                                                                     |
| Délais de paiement                                                                       | Valeurs nommées comme `thirty_days` ou `end_of_month` (voir [Facturation](https://docs.abby.fr/mcp/facturation.md#update-billing-timeline)) |

Ne passez pas de millisecondes : la valeur maximale acceptée est `4102444800` (1er janvier 2100), donc un timestamp en millisecondes est refusé.

## Retrouver les identifiants

Les identifiants sont des chaînes. Récupérez-les par les outils de lecture : `get-customers` pour `customerId`, `get-products` pour `productId`, `get-billings` pour `billingId`, `get-contacts` et `get-organizations` pour les clients. Un outil ne cherche un objet que dans l'entreprise liée à votre jeton.

## Choisir un code TVA

Les lignes de facturation acceptent des codes simplifiés. Omettez le code pour que le produit du catalogue ou la politique de TVA de l'entreprise décide.

| Code                | Taux  | Description                                       |
| ------------------- | ----- | ------------------------------------------------- |
| `fr_20`             | 20 %  | Taux normal                                       |
| `fr_10`             | 10 %  | Taux intermédiaire                                |
| `fr_5_5`            | 5,5 % | Taux réduit                                       |
| `fr_2_1`            | 2,1 % | Taux super-réduit                                 |
| `fr_8_5`            | 8,5 % | Taux de 8,5 %                                     |
| `fr_0`              | 0 %   | Hors taxe                                         |
| `fr_not_applicable` | 0 %   | TVA non applicable (même code interne que `fr_0`) |
| `fr_eu`             | 0 %   | Union européenne                                  |
| `fr_non_eu`         | 0 %   | Hors Union européenne                             |

Le catalogue (`create-product`, `update-product`) utilise les codes internes : `FR_210`, `FR_550`, `FR_850`, `FR_1000`, `FR_2000`, `FR_00HT`, `FR_00UE`, `FR_0HUE`. Les lignes de facturation les acceptent aussi.

## Vérifier les scopes

Chaque outil exige un seul scope, indiqué dans sa page. Les scopes sont accordés lors du flux OAuth, décrit dans [Démarrer avec le MCP](https://docs.abby.fr/mcp/demarrer.md).

| Scope               | Description                                                 |
| ------------------- | ----------------------------------------------------------- |
| `billing:read`      | Lecture des documents de facturation                        |
| `billing:write`     | Création et modification de documents                       |
| `catalog:read`      | Lecture du catalogue de produits                            |
| `catalog:write`     | Création, modification et suppression de produits           |
| `client:read`       | Lecture des contacts et organisations                       |
| `client:write`      | Création, modification, archivage et suppression de clients |
| `declaration:read`  | Lecture des estimations URSSAF                              |
| `declaration:write` | Soumission de déclarations URSSAF                           |
| `mcp:read`          | Raccourci : accorde tous les scopes `:read` ci-dessus       |
| `mcp:write`         | Raccourci : accorde tous les scopes `:write` ci-dessus      |

Aucun outil ne vérifie `mcp:read` ou `mcp:write` : à l'autorisation, Abby ajoute les scopes de données correspondants, et ce sont eux que les outils contrôlent. Une clé API n'a pas de scopes et passe tous les contrôles.

## Confirmer avant d'agir

Deux outils demandent une confirmation explicite avant d'agir :

| Outil                         | Confirmation                                                |
| ----------------------------- | ----------------------------------------------------------- |
| `finalize-billing`            | Sans `confirm: true`, renvoie un aperçu et ne finalise rien |
| `complete-urssaf-declaration` | Sans `execute: true`, renvoie un aperçu et ne déclare rien  |

Dans les deux cas, montrez l'aperçu à l'utilisateur et attendez son accord avant le second appel.

D'autres outils agissent dès le premier appel et n'ont pas d'aperçu : `cancel-invoice` (annule une facture et crée un avoir), `refuse-estimate`, `sign-estimate`, `send-invoice-by-email`, `delete-product`, `delete-contact` et `delete-organization`. Ne les appelez qu'après l'accord de l'utilisateur.

## Lire les réponses

Les outils renvoient du JSON dans un bloc de texte.

* Les outils qui modifient des données renvoient en général `success` (`true` ou `false`) et un `message`. Les outils de lecture renvoient souvent directement les données, sans `success`.
* Quand un outil échoue, il répond le plus souvent `success: false` avec un `message` qui décrit l'erreur, et parfois l'identifiant concerné. Quelques outils (`get-billings`, `create-estimate`, `update-contact`, `update-organization`, entre autres) n'ont pas cette enveloppe : leur échec remonte comme une erreur d'outil.

### Succès

```json
{
  "success": true,
  "message": "Description de l'action effectuée.",
  ...
}
```

### Erreur

```json
{
  "success": false,
  "message": "Description de l'erreur."
}
```

## Traiter les erreurs

Les erreurs que vous pouvez rencontrer :

| Situation                                                                        | Ce que vous recevez                                                                                                                        |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Jeton absent                                                                     | Réponse HTTP `401` avec l'en-tête `WWW-Authenticate: Bearer resource_metadata="…"`. Un client MCP relance le flux OAuth                    |
| Jeton invalide ou expiré                                                         | Réponse HTTP `401` avec `error="invalid_token"`. Reconnectez le client                                                                     |
| Scope insuffisant                                                                | Erreur `Insufficient scope. Required: <scope>`. Autorisez de nouveau le client avec le scope demandé                                       |
| Offre ne donnant pas accès au MCP, ou essai terminé                              | Résultat d'outil en erreur, avec un message et un lien pour souscrire. Réessayer ne change rien                                            |
| Finalisation avec TVA sans l'offre requise                                       | Résultat d'outil en erreur ; le document reste en brouillon (voir [Facturation](https://docs.abby.fr/mcp/facturation.md#finalize-billing)) |
| Objet introuvable, document dans le mauvais état, paramètres refusés par l'outil | `success: false` avec un `message`                                                                                                         |

Un paramètre qui ne respecte pas le schéma de l'outil est refusé avant l'exécution.

## Parcourir les listes paginées

Les outils qui renvoient des listes paginées (`get-billings`, `get-customers`, `get-contacts`, `get-organizations`, `get-products`) utilisent `page` (à partir de 1) et renvoient des champs de pagination à côté de la liste :

```json
{
  "total": 42,
  "page": 1,
  "limit": 10,
  "totalPages": 5,
  "hasNextPage": true,
  "hasPrevPage": false,
  "billings": [...]
}
```

Le nom du tableau dépend de l'outil : `billings`, `customers`, `contacts`, `organizations` ou `products`. `limit` est plafonné à 100 sur `get-billings`, `get-customers`, `get-contacts` et `get-organizations`. `get-products` fixe 100 résultats par page et n'accepte pas `limit`. `get-last-invoices` ne prend aucun paramètre et renvoie les 10 factures les plus récentes dans `invoices`.

Utilisez `page` pour naviguer entre les pages, jusqu'à ce que `hasNextPage` vaille `false`. Pour la pagination de l'API REST, voir [Pagination](https://docs.abby.fr/concepts/pagination.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.abby.fr/mcp/conventions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
