# 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: 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/conventions.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.