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

Ne confondez pas euros et centimes. Un prix unitaire de 7500 correspond à 75,00 €, pas 7 500 €.

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

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

Erreur

{
  "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 :

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

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