> 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/declarations-urssaf.md).

# Déclarations URSSAF

Les outils de déclaration permettent d'estimer et de déclarer votre chiffre d'affaires à l'URSSAF, et de payer les cotisations sociales directement depuis un assistant IA.

{% hint style="warning" %}
Ces outils effectuent de **vraies actions** auprès de l'URSSAF. L'utilisateur doit avoir un mandat URSSAF actif autorisant Abby à déclarer en son nom. Sans mandat, `complete-urssaf-declaration` répond `success: false`.
{% endhint %}

{% hint style="info" %}
Ces deux outils n'ont pas d'équivalent dans la référence de l'API REST : la spécification OpenAPI publique ne contient aucune route de déclaration. Les règles communes à tous les outils sont dans [Conventions](https://docs.abby.fr/mcp/conventions.md).
{% endhint %}

## `get-turnover-estimations`

Récupère le chiffre d'affaires et une estimation des cotisations pour la période de déclaration en cours, tels qu'Abby les estime. La période (mensuelle ou trimestrielle) est celle que l'URSSAF a enregistrée pour l'entreprise : elle ne se choisit pas.

**Paramètres** : aucun.

**Réponse**

```json
{
  "period": {
    "type": "quarterly",
    "label": "…",
    "from": "YYYY-MM-DD",
    "to": "YYYY-MM-DD",
    "periode": { "annee": 2025, "trimestre": 1 }
  },
  "dueDate": "YYYY-MM-DD",
  "dueDateFormatted": "…",
  "turnover": {
    "merchandise": 0,
    "rental": 0,
    "servicePrestations": 0,
    "otherPrestations": 0,
    "cipav": 0,
    "total": 0
  },
  "contributions": {
    "montantVente": 0,
    "montantLocation": 0,
    "montantPrestationService": 0,
    "montantPrestationAutres": 0,
    "montantFormationProfessionnelle": 0,
    "montantCipav": 0,
    "taxeCCIVente": 0,
    "taxeCCIService": 0,
    "total": 0
  },
  "hasUrssafMandat": true,
  "hasAcre": false
}
```

Les zéros et les `YYYY-MM-DD` ci-dessus montrent la forme de la réponse, pas un cas réel. Pour une période mensuelle, `period.type` vaut `monthly` et `periode` contient `mois` au lieu de `trimestre`.

{% hint style="warning" %}
Cet outil est une exception à la convention des centimes : ses montants (`turnover` et `contributions`) sont en **euros**. `complete-urssaf-declaration` part des mêmes estimations et les convertit en centimes dans ses réponses. Voir [Conventions](https://docs.abby.fr/mcp/conventions.md).
{% endhint %}

**Scope** : `declaration:read`

***

## `complete-urssaf-declaration`

Déclare à l'URSSAF le chiffre d'affaires de la période en cours et, si vous le demandez, paie les cotisations. Le chiffre d'affaires déclaré est celui qu'Abby estime (le même que `get-turnover-estimations`) : il n'est pas passé en paramètre.

L'outil fonctionne en deux étapes, pour qu'une déclaration ne parte jamais sans validation :

1. **Aperçu** (`execute` absent ou `false`) : l'outil ne déclare rien. Il renvoie `preview: true`, un message `CONFIRMATION REQUIRED`, la période, le chiffre d'affaires, les cotisations estimées et la date d'échéance.
2. **Exécution** (`execute: true`) : la déclaration est réellement transmise à l'URSSAF.

**Paramètres**

| Paramètre | Type    | Requis | Description                                                                                                                                   |
| --------- | ------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `execute` | boolean | Non    | `true` pour déclarer. Sans cette valeur, l'outil renvoie un aperçu                                                                            |
| `pay`     | boolean | Non    | `true` pour payer les cotisations après la déclaration. Ne s'applique qu'avec `execute: true`. Sans `pay`, seule la déclaration est transmise |
| `iban`    | string  | Non    | IBAN à débiter (utilisé seulement avec `pay: true`). Par défaut, le mandat SEPA actif                                                         |
| `rum`     | string  | Non    | Référence unique de mandat SEPA (utilisée seulement avec `pay: true`)                                                                         |

### Étape 1 : aperçu

```json
// Appel
{ "execute": false, "pay": true }

// Réponse (forme)
{
  "preview": true,
  "message": "CONFIRMATION REQUIRED: …",
  "period": { "type": "quarterly", "label": "…", "periode": { "annee": 2025, "trimestre": 1 } },
  "turnover": {
    "merchandise": 0,
    "rental": 0,
    "servicePrestations": 0,
    "otherPrestations": 0,
    "cipav": 0,
    "total": 0
  },
  "estimatedContributions": 0,
  "dueDate": "YYYY-MM-DD",
  "willPay": true,
  "hasSepaMandateForPayment": true
}
```

Les champs `turnover` et `estimatedContributions` de l'aperçu sont en centimes ; le texte de `message`, lui, cite les montants en euros. `hasSepaMandateForPayment` indique si un IBAN et un RUM sont disponibles pour le paiement.

### Étape 2 : exécution

```json
// Appel
{ "execute": true, "pay": true }
```

La réponse contient `success: true`, un message avec le numéro de certificat, un objet `declaration` (identifiant, période, chiffre d'affaires, cotisations, `certificate`, `dueDate`, `state`, `declaredAt`) et, avec `pay: true`, un objet `payment` (`amount`, `paidAt`). Les montants des objets `declaration` et `payment` sont en centimes ; le texte de `message` les cite en euros.

Si `pay: true` est demandé mais qu'aucun mandat SEPA n'est disponible, la déclaration est tout de même transmise. La réponse porte alors `success: true`, `warning: true` et `paymentFailed: true`, avec la raison. Dans ce cas, configurez un mandat dans Abby ou renvoyez `iban` et `rum`.

{% hint style="danger" %}
Avec `execute: true`, la déclaration est **réellement transmise** à l'URSSAF. Montrez l'aperçu à l'utilisateur et attendez son accord avant d'exécuter.
{% endhint %}

**Scope** : `declaration:write`

***

## Scopes requis

| Outil                         | Scope               |
| ----------------------------- | ------------------- |
| `get-turnover-estimations`    | `declaration:read`  |
| `complete-urssaf-declaration` | `declaration:write` |


---

# 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/declarations-urssaf.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.
