> 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 à tous les outils MCP d'Abby.

## Montants en centimes

Tous les montants monétaires sont exprimés en **centimes d'euros** (euros × 100).

| Montant réel | Valeur dans l'API |
| ------------ | ----------------- |
| 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

## Codes TVA

Les lignes de facturation utilisent des codes TVA simplifiés :

| 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 DOM                           |
| `fr_0`              | 0%   | Exonéré (franchise en base de TVA) |
| `fr_not_applicable` | 0%   | TVA non applicable                 |

## Scopes (permissions)

Chaque outil MCP nécessite un scope spécifique. Les scopes sont accordés lors du flux OAuth.

| 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 et modification de produits  |
| `client:read`       | Lecture des contacts et organisations |
| `client:write`      | Création et modification de clients   |
| `declaration:read`  | Lecture des estimations URSSAF        |
| `declaration:write` | Soumission de déclarations URSSAF     |

## Format de réponse

Toutes les réponses suivent un format uniforme :

### Succès

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

### Erreur

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

## Gestion des erreurs

Les erreurs courantes que vous pouvez rencontrer :

| Code                            | Description                                          |
| ------------------------------- | ---------------------------------------------------- |
| `UNAUTHORIZED`                  | Token invalide ou expiré — relancez le flux OAuth    |
| `FORBIDDEN`                     | Scope insuffisant pour cette action                  |
| `NOT_FOUND`                     | Ressource introuvable (vérifiez l'identifiant)       |
| `VALIDATION_ERROR`              | Paramètres invalides (vérifiez les types et valeurs) |
| `BILLING_ALREADY_FINALIZED`     | Le document est déjà finalisé                        |
| `DECLARATION_ALREADY_SUBMITTED` | La déclaration a déjà été soumise pour cette période |

## Pagination

Les outils retournant des listes utilisent la pagination :

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

Utilisez le paramètre `page` pour naviguer entre les pages.


---

# 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 dynamically by asking a question.

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

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.