# API Mast : guide d'intégration

L'API de Mast permet à vos propres systèmes de travailler avec la comptabilité de votre société dans
Mast. Votre back-office crée vos clients, vos produits et vos factures, et tient vos fournisseurs à
jour ; vos outils d'analyse lisent
vos factures, vos encaissements, vos écritures et vos mouvements bancaires. Ce guide suit les deux
usages les plus courants, pas à pas. Le détail de chaque appel, champ par champ, est dans la
[référence](https://mastfinance.io/developers/reference.md) (en anglais), et le même contrat existe pour les machines au format OpenAPI
([`openapi.v1.json`](https://mastfinance.io/developers/openapi.v1.json)).

| | |
|---|---|
| Adresse | `https://api.mastfinance.io/api/v1` |
| Format | JSON sur HTTPS |
| Authentification | Une clé API de votre société : `Authorization: Bearer mast_sk_…` |
| Hébergement | En Suisse (Zurich), comme le reste de Mast |

## 1. Obtenir une clé

L'API s'ouvre compte par compte. Une fois ouverte pour le vôtre :

1. Un propriétaire ou un administrateur du compte ouvre **Paramètres › Clés API** dans Mast et choisit
   **Créer une clé**. Mast lui demande d'avoir d'abord activé la validation en deux étapes (une
   application d'authentification).
2. Il nomme la clé (« Back-office »), choisit le **rôle** dont elle aura les droits, et son expiration.
   Il ne peut lui donner qu'un rôle dont il détient lui-même les droits. La page propose une expiration
   « Dans un an », et offre aussi 30 jours, 90 jours ou « Jamais » : Mast ne fixe aucune expiration de
   lui-même, et une clé créée avec « Jamais » n'en a pas (`expiresAt` vaut `null`).
3. Mast affiche la clé **une seule fois**. Rangez-la là où votre système garde ses secrets : Mast n'en
   conserve qu'une empreinte et ne peut plus la montrer.

Une clé appartient à **une société** et n'agit que dans celle-ci. Elle peut ce que peut son rôle, rien
de plus : la clé d'un outil d'analyse prend un rôle qui ne fait que consulter. Une société peut avoir
jusqu'à 20 clés actives : donnez-en une à chaque système, pour pouvoir en révoquer une sans arrêter
les autres. Une clé révoquée dans les paramètres s'arrête à l'instant : chaque appel relit la clé. La
page montre la dernière utilisation de chacune, à cinq minutes près.

Mast ouvre l'API pour tout le compte, et peut la refermer. Une fois fermée, chaque clé du compte est
refusée (`403 PUBLIC_API_NOT_ENABLED`) dans la minute, car chaque serveur de Mast relit ce réglage
toutes les 60 secondes ; les clés sont conservées, et fonctionnent de nouveau si l'API est rouverte.

Les rôles et leurs droits se règlent dans **Paramètres › Utilisateurs & permissions**. Ce guide nomme
chaque droit comme cette page le nomme : la fonctionnalité (« Factures clients »), puis la colonne
(« Consulter », « Créer », « Modifier », « Comptabiliser », « Supprimer »).

Vérifiez une nouvelle clé avec le seul appel qui ne demande aucun droit :

```bash
curl -s https://api.mastfinance.io/api/v1/ext/me -H "Authorization: Bearer $MAST_API_KEY"
```

```json
{
  "key": { "id": "…", "name": "Back-office", "displayPrefix": "mast_sk_a1B2c3", "roleName": "Facturation", "expiresAt": "2027-11-19T00:00:00.000Z" },
  "company": { "id": "…", "name": "Muster Handel AG" }
}
```

La réponse nomme la clé, son rôle et la société dans laquelle elle agit.

## 2. Créer vos factures depuis votre back-office

Votre back-office connaît vos clients, leurs conditions, vos produits et ce que vous avez vendu. Il
envoie tout cela à Mast, qui en fait des factures conformes, les numérote, les comptabilise et les
envoie. Le parcours tient en six appels :

| Étape | Appel | Droit du rôle de la clé |
|---|---|---|
| Tenir vos clients à jour | `PUT /ext/customers/{externalRef}` | Clients : Créer et Modifier |
| Tenir vos produits à jour | `PUT /ext/products/{externalRef}` | Produits : Créer et Modifier |
| Préparer un brouillon de facture | `POST /ext/invoices` | Factures clients : Créer |
| Le corriger, ou l'abandonner | `PATCH` ou `DELETE /ext/invoices/{externalRef}` | Factures clients : Modifier, Supprimer |
| L'émettre | `POST /ext/invoices/{externalRef}/validate` | Factures clients : Comptabiliser |
| L'envoyer au client par e-mail | `POST /ext/invoices/{externalRef}/send` | Factures clients : Comptabiliser |

Pour relire ce qu'elle a créé, la clé a aussi besoin de « Consulter » sur ces trois fonctionnalités.
Pour suivre les paiements (`GET /ext/payments`), il lui faut « Consulter » sur « Affectation de
trésorerie », celle de la section **Ventes et facturation** : consulter les factures ne le donne pas,
et l'« Affectation de trésorerie » de la section **Achats et factures** est une autre fonctionnalité.

Partout, `{externalRef}` est **votre** identifiant : celui que votre back-office donne déjà à ce
client, à ce produit, à cette facture. Vous n'avez aucun identifiant de Mast à stocker.

Les exemples ci-dessous forment un seul scénario. Leurs chiffres sont ceux que Mast répond
réellement : un test automatique rejoue ce scénario à chaque version.

### 2.1 Vos clients, avec leurs conditions

Un seul appel crée le client s'il n'existe pas encore sous votre identifiant, et le met à jour sinon.
Votre synchronisation n'a donc pas à savoir si Mast le connaît déjà.

Mast contient déjà des clients ou des produits, créés par une personne ou importés ? Lisez d'abord
2.2 : ils ne portent pas encore votre identifiant, et cet appel ne les retrouverait pas.

```bash
curl -s -X PUT https://api.mastfinance.io/api/v1/ext/customers/crm-1042 \
  -H "Authorization: Bearer $MAST_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "type": "business",
    "companyName": "Muster Handel AG",
    "email": "compta@muster-handel.example",
    "address": { "street": "Bahnhofstrasse 1", "postalCode": "8001", "city": "Zürich" },
    "language": "fr",
    "defaultDiscountPercent": 10,
    "paymentTermsDays": 20
  }'
```

Mast répond `201` la première fois (le client est créé), `200` ensuite (il est modifié), avec le
client tel qu'il le tient :

```json
{
  "id": "cmwnsw2nz00a16muqe2qwffsl",
  "externalRef": "crm-1042",
  "number": "CUST-00046",
  "type": "business",
  "name": "Muster Handel AG",
  "email": "compta@muster-handel.example",
  "address": { "street": "Bahnhofstrasse 1", "postalCode": "8001", "city": "Zürich", "country": "Switzerland", "countryCode": "CH" },
  "language": "fr",
  "defaultDiscountPercent": 10,
  "paymentTermsDays": 20,
  "…": "…"
}
```

- **Ses conditions.** `defaultDiscountPercent` est la remise que Mast garde pour ce client, et
  `paymentTermsDays` son délai de paiement en jours. Une facture qui ne nomme pas de délai prend
  celui du client. Sa remise, elle, n'est appliquée que si la facture le demande (voir 2.4).
- **Une entreprise ou une personne.** `type` vaut `business` (nommée par `companyName`) ou
  `individual` (nommée par `firstName` et `lastName`).
- **Sa langue** (`de`, `fr`, `it`, `en`) est celle de ses factures et de ses rappels.
- **Créer demande le tout, modifier seulement ce qui change.** Pour un client nouveau, l'appel donne
  son type, son nom, son e-mail et son adresse. Ensuite, il peut n'envoyer que ce qui change :
  `{ "paymentTermsDays": 30 }` change le délai et laisse le reste. Un champ qui peut être vide (le
  téléphone, le numéro de TVA, le numéro au registre du commerce) est effacé quand il est envoyé à
  `null` ; la référence dit, champ par champ, lesquels acceptent `null`.
- **Un champ que Mast ne connaît pas est ignoré**, sans un mot : `{ "paymentTermDays": 30 }`, mal
  orthographié, ne change rien et répond tout de même `200`. Comparez la réponse à ce que vous avez
  envoyé (section 4).
- Le pays, s'il est omis, est celui de votre société. `number` est le numéro de client de Mast.

### 2.2 Vous avez déjà des clients ou des produits dans Mast

Un client ou un produit créé dans Mast par une personne, ou importé, n'a que l'identifiant de Mast :
son `externalRef` vaut `null`. Tant qu'il ne porte pas le vôtre, votre `PUT` ne le retrouve pas. Avant
votre première synchronisation, rattachez donc ce que Mast contient déjà à vos propres
enregistrements. Si votre compte est neuf, passez à 2.3.

**Lisez ce que Mast contient.** La liste sert tous les clients de la société, les vôtres comme ceux
créés dans Mast, chacun avec ses deux identifiants :

```bash
curl -s https://api.mastfinance.io/api/v1/ext/customers -H "Authorization: Bearer $MAST_API_KEY"
```

```json
{
  "data": [
    {
      "id": "cmwo41w8100a3xtuqh7n7fnpc",
      "externalRef": null,
      "number": "CUST-00010",
      "type": "business",
      "name": "Beispiel Technik GmbH",
      "email": "info@beispiel-technik.example",
      "address": { "street": "Lagerstrasse 12", "postalCode": "4051", "city": "Basel", "country": "Switzerland", "countryCode": "CH" },
      "vatNumber": "CHE-123.456.789 MWST",
      "registrationNumber": null,
      "…": "…"
    }
  ],
  "nextCursor": null
}
```

**Faites la correspondance de votre côté.** Pour reconnaître un client, chaque ligne donne son numéro
dans Mast (`number`), son nom (`name`, avec `companyName` ou `firstName` et `lastName` selon son
`type`), son numéro de TVA (`vatNumber`), son numéro au registre du commerce (`registrationNumber`),
son e-mail (`email`), son téléphone (`phone`) et son adresse (`address`). Pour un produit
(`GET /ext/products`) : son numéro (`number`), son nom (`name`), son code (`code`), son prix
(`unitPrice`, `currency`) et son unité (`unit`). C'est votre système qui décide que deux
enregistrements sont le même : Mast ne rapproche jamais deux clients ou deux produits d'après leur
nom.

**Donnez votre identifiant à chacun**, en le désignant par l'identifiant de Mast :

```bash
curl -s -X PATCH https://api.mastfinance.io/api/v1/ext/customers/by-id/cmwo41w8100a3xtuqh7n7fnpc \
  -H "Authorization: Bearer $MAST_API_KEY" -H "Content-Type: application/json" \
  -d '{ "externalRef": "crm-0318" }'
```

Mast répond `200` avec le client, qui porte désormais votre identifiant :

```json
{
  "id": "cmwo41w8100a3xtuqh7n7fnpc",
  "externalRef": "crm-0318",
  "number": "CUST-00010",
  "type": "business",
  "name": "Beispiel Technik GmbH",
  "…": "…"
}
```

Rien d'autre ne change dans le client. À partir de là, `PUT /ext/customers/crm-0318` le met à jour
(2.1) et vos factures le nomment par `customerExternalRef` (2.4). Un produit se rattache de la même
façon, par `PATCH /ext/products/by-id/{id}` ; une ligne de facture le nomme ensuite par
`productExternalRef`.

- **Répéter l'appel ne fait rien de plus.** Renvoyer l'identifiant que l'enregistrement porte déjà
  répond `200` sans rien écrire.
- **Un identifiant ne désigne qu'un enregistrement.** S'il est déjà porté par un autre client de la
  société, l'appel répond `409 EXT_CUSTOMER_EXISTS` (`EXT_PRODUCT_EXISTS` pour un produit). S'il est
  porté par un client supprimé dans Mast, où il reste archivé, l'appel répond
  `409 EXT_CUSTOMER_ARCHIVED` : restaurez ce client dans Mast, ou prenez un autre identifiant.
- **Un rattachement erroné se défait.** Envoyez `{ "externalRef": null }` : l'enregistrement n'a de
  nouveau que l'identifiant de Mast, et le vôtre est libre pour le bon. Envoyer un autre identifiant
  remplace directement l'ancien.
- **La liste revient sur ce que vous rattachez.** Un enregistrement rattaché vient de changer : si
  vous lisez la liste page par page en même temps, il revient plus loin, cette fois avec votre
  identifiant.
- **Droits de la clé.** « Consulter » pour lire la liste, « Modifier » pour rattacher.

**Si vous sautez cette étape**, votre premier `PUT` ne trouve rien sous votre identifiant et veut
créer l'enregistrement. Pour un client, Mast refuse (`409 CUSTOMER_NAME_EXISTS`) quand un client de
la société porte à la fois le même nom, la même adresse de facturation et le même e-mail ; dès que
l'un des trois diffère, il crée un second client à côté du premier. Un produit est toujours créé une
seconde fois. Pour réparer un doublon, retirez-lui d'abord votre identifiant
(`{ "externalRef": null }`), donnez-le au bon enregistrement, puis supprimez le doublon dans Mast.
Dans cet ordre : un enregistrement supprimé dans Mast y reste archivé, et garde l'identifiant qu'il
portait.

**Vérifier que les deux côtés disent la même chose.** Une liste lue avec `updatedSince` rend tout ce
qui a changé dans Mast depuis un instant, que le changement vienne de votre back-office ou d'une
personne dans Mast. Une comparaison nocturne tient donc en un appel par liste :

```bash
curl -s "https://api.mastfinance.io/api/v1/ext/customers?updatedSince=2026-11-18T22:00:00Z" \
  -H "Authorization: Bearer $MAST_API_KEY"
```

Chaque ligne porte ses deux identifiants, tous ses champs et `updatedAt`, l'instant de son dernier
changement : comparez-les aux vôtres. Une ligne dont `externalRef` vaut `null` est un client que vous
n'avez pas encore rattaché, et qu'une personne vient de créer ou de modifier dans Mast. La section 3
décrit la lecture page par page.

Un `PUT` avance `updatedAt` même quand il ne change rien : une synchronisation qui renvoie chaque
nuit tous vos clients les voit tous revenir à sa lecture suivante par `updatedSince`, et une
modification faite par une personne dans Mast s'y perd. N'envoyez que ce qui a changé de votre côté,
ou comparez avec ce que Mast contient avant d'envoyer.

Une suppression ne s'y lit pas : un client supprimé dans Mast sort de la liste. Sa lecture par votre
identifiant répond alors `404 EXT_CUSTOMER_NOT_FOUND`, et un `PUT` qui le renvoie en entier
`409 EXT_CUSTOMER_ARCHIVED`.

### 2.3 Vos produits

Même principe que pour vos clients (2.1), un appel par produit :

```bash
curl -s -X PUT https://api.mastfinance.io/api/v1/ext/products/sku-conseil \
  -H "Authorization: Bearer $MAST_API_KEY" -H "Content-Type: application/json" \
  -d '{ "type": "service", "name": "Conseil", "code": "CONSEIL", "unitPrice": 180, "unit": "h", "vatRateCode": "CH_STD" }'

curl -s -X PUT https://api.mastfinance.io/api/v1/ext/products/sku-manuel \
  -H "Authorization: Bearer $MAST_API_KEY" -H "Content-Type: application/json" \
  -d '{ "type": "good", "name": "Manuel", "code": "MANUEL", "unitPrice": 19.90, "unit": "pcs", "vatRateCode": "CH_RED" }'
```

- `unitPrice` est le prix de vente hors TVA. C'est un prix par défaut : une ligne de facture peut
  toujours donner le sien.
- `vatRateCode` est l'un des codes TVA de votre société, tels que **Paramètres › TVA** les liste. Dans
  une société suisse, `CH_STD` est le taux normal (8,1 %) et `CH_RED` le taux réduit (2,6 %). Mast
  répond le taux à côté du code (`vatRatePercent`).
- `accountCode`, facultatif, est le compte de produits de votre plan comptable sur lequel ce produit
  est comptabilisé. Sans lui, Mast prend le compte de ventes par défaut de la société.

### 2.4 Un brouillon de facture

```bash
curl -s -X POST https://api.mastfinance.io/api/v1/ext/invoices \
  -H "Authorization: Bearer $MAST_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "externalRef": "bo-2026-0457",
    "customerExternalRef": "crm-1042",
    "issueDate": "2026-11-19",
    "reference": "PO-7781",
    "applyCustomerDefaultDiscount": true,
    "lines": [
      { "productExternalRef": "sku-conseil", "quantity": 12.5 },
      { "productExternalRef": "sku-manuel", "quantity": 3, "discountPercent": 20 },
      { "description": "Frais de déplacement", "quantity": 1, "unitPrice": 85, "vatRateCode": "CH_STD" }
    ]
  }'
```

Mast répond `201` avec le brouillon, ses lignes et ses totaux calculés :

```json
{
  "id": "cmwnsw2sf00a76muqm4kto1cu",
  "externalRef": "bo-2026-0457",
  "documentNumber": "Draft-INV-2026-00043",
  "status": "draft",
  "customerExternalRef": "crm-1042",
  "issueDate": "2026-11-19",
  "dueDate": "2026-12-09",
  "currency": "CHF",
  "subtotal": 2382.76,
  "discountPercent": 10,
  "discountAmount": 238.28,
  "netAmount": 2144.48,
  "vatAmount": 171.34,
  "total": 2315.82,
  "amountDue": 2315.82,
  "vatRows": [
    { "ratePercent": 8.1, "netAmount": 2101.5, "vatAmount": 170.22 },
    { "ratePercent": 2.6, "netAmount": 42.98, "vatAmount": 1.12 }
  ],
  "lines": [
    { "position": 1, "description": "Conseil", "quantity": 12.5, "unit": "h", "unitPrice": 180, "discountPercent": null, "netAmount": 2250, "vatRatePercent": 8.1, "…": "…" },
    { "position": 2, "description": "Manuel", "quantity": 3, "unit": "pcs", "unitPrice": 19.9, "discountPercent": 20, "netAmount": 47.76, "vatRatePercent": 2.6, "…": "…" },
    { "position": 3, "description": "Frais de déplacement", "quantity": 1, "unit": "pcs", "unitPrice": 85, "discountPercent": null, "netAmount": 85, "vatRatePercent": 8.1, "…": "…" }
  ],
  "…": "…"
}
```

**Une ligne** nomme un produit (`productExternalRef`) et prend alors son nom, son prix, son unité et
son taux de TVA, sauf ceux qu'elle donne elle-même. Ou elle est libre, avec sa description, son prix
et son taux. Un prix convenu avec ce client est simplement le `unitPrice` envoyé sur la ligne. Le prix
d'un produit est repris tel quel, dans la devise de la facture : un produit à 100 EUR donne une ligne
de 100.00 sur une facture en CHF. Mast ne convertit rien et ne refuse rien ici : sur une facture dans
une autre devise que celle du produit, donnez à la ligne son propre `unitPrice`.

**Les remises.** Mast n'applique aucune remise que l'appel ne demande pas. Il y en a trois, qui se
cumulent dans cet ordre :

| Remise | Champ | Dans l'exemple |
|---|---|---|
| Sur une ligne | `discountPercent` de la ligne | 20 % sur les manuels : 59.70 devient 47.76 |
| Sur toute la facture | `discountPercent` ou `discountAmount` de la facture, jamais les deux | (non utilisée) |
| La remise du client | `applyCustomerDefaultDiscount: true`, si l'appel ne nomme pas de remise sur la facture | 10 % de 2'382.76, soit 238.28 |

Un `discountAmount` supérieur à ce que font les lignes n'est pas refusé : Mast le prend comme le tout
des lignes, la facture vaut 0.00, et elle peut être émise ainsi. Vérifiez le `total` que Mast répond.

**Les totaux.** `subtotal` est la somme des lignes après leurs propres remises. `netAmount` est ce que
la facture demande hors TVA, `vatAmount` sa TVA et `total` son montant TTC. `vatRows` donne la TVA
par taux, telle que le PDF l'imprime : ses lignes s'additionnent exactement à `vatAmount`. Reprenez
ces chiffres plutôt que de les recalculer. Une facture dont le total passerait sous zéro est refusée
(`400 INVOICE_TOTAL_NEGATIVE`) : une facture réclame un montant ; pour en rendre un à votre client,
établissez un avoir dans Mast.

**Le reste.** Sans `issueDate`, la facture est datée d'aujourd'hui. Sans `dueDate` ni
`paymentTermsDays`, l'échéance vient du délai du client (ici 20 jours). `reference` est la référence
de votre client (un numéro de commande), imprimée sur la facture. `title`, `introText`, `notes` et
`footerText` sont les textes libres du document. `priceIncludesVat: true` dit que vos prix sont TTC.
`currency` et `language`, omis, sont ceux de la société et du client.

Un brouillon n'a **ni numéro officiel ni écriture comptable**. Vous pouvez le lire, le montrer, le
corriger. Rien n'est encore dû.

### 2.5 Corriger ou abandonner un brouillon

Tant que la facture est un brouillon, corrigez-le : les champs envoyés remplacent ceux du brouillon,
et `lines` remplace toutes les lignes.

```bash
curl -s -X PATCH https://api.mastfinance.io/api/v1/ext/invoices/bo-2026-0457 \
  -H "Authorization: Bearer $MAST_API_KEY" -H "Content-Type: application/json" \
  -d '{ "lines": [
        { "productExternalRef": "sku-conseil", "quantity": 14 },
        { "productExternalRef": "sku-manuel", "quantity": 3, "discountPercent": 20 },
        { "description": "Frais de déplacement", "quantity": 1, "unitPrice": 85, "vatRateCode": "CH_STD" }
      ] }'
```

Avec 14 heures au lieu de 12,5, le brouillon passe à 2'387.48 hors TVA et 2'578.50 TTC : la remise du
client reste appliquée. Un changement de remise ou de `priceIncludesVat` recalcule toute la facture,
il vient donc avec les lignes. Une modification est acceptée quel que soit le total qui en résulte :
un brouillon passé sous zéro est refusé au moment de son émission (`400 INVOICE_TOTAL_NEGATIVE`), et
reste un brouillon.

Ou bien, à la place, abandonnez le brouillon : il disparaît, et son identifiant redevient libre. Ne
lancez pas cet appel si vous suivez le scénario, qui émet ensuite le brouillon.

```bash
curl -s -X DELETE https://api.mastfinance.io/api/v1/ext/invoices/bo-2026-0457 \
  -H "Authorization: Bearer $MAST_API_KEY"
```

Une facture **émise** ne se modifie plus et ne se supprime plus (`409 EXT_INVOICE_NOT_DRAFT`) : elle se
corrige par un avoir, établi dans Mast.

### 2.6 Émettre la facture

```bash
curl -s -X POST https://api.mastfinance.io/api/v1/ext/invoices/bo-2026-0457/validate \
  -H "Authorization: Bearer $MAST_API_KEY" \
  -H "Idempotency-Key: emettre-bo-2026-0457"
```

La facture prend son **numéro officiel** dans la série de votre société (`INV-2026-00014`) et son
**écriture comptable**, au nom de la clé. Son `status` passe de `draft` à `open`, et elle compte
désormais dans ce que vous avez facturé (`invoicedNetAmount`).

- **C'est définitif.** L'API n'annule pas une facture émise ; un avoir la corrige, dans Mast.
- **Émettre deux fois ne fait rien de plus.** Répéter l'appel répond la même facture : un seul numéro,
  une seule écriture. Envoyez tout de même une `Idempotency-Key` (voir la section 4) : après une
  coupure réseau, la répétition reçoit exactement la réponse du premier appel.
- **Votre comptabilité peut refuser.** Une période clôturée, par exemple, refuse l'émission avec le
  code que l'application elle-même affiche. La facture reste alors un brouillon.

### 2.7 L'envoyer au client

```bash
curl -s -X POST https://api.mastfinance.io/api/v1/ext/invoices/bo-2026-0457/send \
  -H "Authorization: Bearer $MAST_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: envoyer-bo-2026-0457" \
  -d '{}'
```

Mast envoie la facture en PDF **par l'expéditeur que votre société a choisi** dans **Paramètres ›
Configuration email** : sa propre boîte Microsoft 365 ou, si Mast le propose à votre compte, Mast
lui-même au nom de votre société. Elle part à l'adresse du client, avec le texte de votre modèle
« facture envoyée » dans la langue du client. Un brouillon est émis au passage : l'envoi peut donc
être votre seul appel après la création.

- Pour écrire à une autre adresse, donnez `recipient` (et `ccRecipient` pour une copie). Pour vos
  propres mots, donnez `subject` et `message` : chacun remplace celui du modèle, et avec les deux,
  aucun modèle n'est nécessaire. Ils vont dans un corps envoyé en JSON : envoyé autrement, l'appel
  est refusé (`415 EXT_JSON_BODY_REQUIRED`) et rien n'est envoyé.
- La réponse contient la facture telle qu'elle est après l'envoi, le destinataire, et
  `deduplicated` : `true` si un envoi aux mêmes adresses (`recipient` et `ccRecipient`) est parti
  moins d'une minute plus tôt, auquel cas aucun second e-mail n'est envoyé. Un envoi fait pendant
  qu'un autre envoi de la même facture tourne encore est refusé (`409 INVOICE_SEND_IN_FLIGHT`).
  Passée cette minute, le même appel envoie de nouveau l'e-mail : envoyez une `Idempotency-Key`
  (section 4), pour qu'une répétition reçoive la réponse du premier appel et que votre client ne
  reçoive qu'un e-mail.
- **À mettre en place une fois dans Mast :** connecter la boîte Microsoft 365 de la société, ou
  choisir « Par Mast, au nom de votre société » là où c'est proposé (**Paramètres › Configuration
  email**), et vérifier le modèle d'e-mail (**Paramètres › Modèles & rappels**). Sans boîte, et sans
  autre expéditeur proposé, l'appel répond `503 EMAIL_NO_ACCOUNT_CONNECTED` ; sans modèle ni texte,
  `422 EXT_INVOICE_EMAIL_TEMPLATE_MISSING` ; si l'envoi des factures par e-mail est désactivé dans les
  paramètres de la société, `403 INVOICE_EMAIL_SENDING_DISABLED_YOUR_ORGANIZATION_SETTINGS`. Une
  facture annulée n'est jamais envoyée (`400 INVOICE_CANCELLED_CANNOT_BE_SENT`). Tout ce qui peut
  refuser l'envoi est vérifié avant d'émettre : un envoi refusé laisse le brouillon intact. La
  référence liste chaque refus de l'appel, y compris ceux de l'envoi par Mast en votre nom.
- Si la boîte n'accepte pas ensuite l'e-mail, l'appel répond `502 EXT_INVOICE_SEND_FAILED` : la
  facture est alors émise, et l'e-mail n'est pas parti. La réponse ne dit pas ce que la boîte a
  répondu ; l'appel peut être refait.
- Vous préférez envoyer vous-même ? Émettez (2.6), récupérez le PDF (2.8) et joignez-le à votre
  propre e-mail.

### 2.8 Récupérer le PDF

```bash
curl -s https://api.mastfinance.io/api/v1/ext/invoices/bo-2026-0457/pdf \
  -H "Authorization: Bearer $MAST_API_KEY" -o facture-bo-2026-0457.pdf
```

C'est le document que reçoit votre client, avec sa QR-facture pour une société suisse. Une clé
obtient un PDF à la fois : un appel fait pendant qu'un autre PDF qu'elle a demandé est encore en
préparation reçoit `429 RATE_LIMITED` avec `Retry-After` ; demandez-les donc l'un après l'autre. Un
tel appel compte tout de même dans la limite de la minute (« Limites de débit »).

### 2.9 Suivre le paiement

```bash
curl -s https://api.mastfinance.io/api/v1/ext/invoices/bo-2026-0457 -H "Authorization: Bearer $MAST_API_KEY"
```

`status` dit où en est la facture, `amountPaid` ce qui est encaissé et `amountDue` ce qui reste dû :

| `status` | Ce que cela veut dire |
|---|---|
| `draft` | Brouillon : pas de numéro officiel, pas d'écriture |
| `open` | Émise, rien reçu, pas encore échue |
| `overdue` | Émise, rien reçu, échéance dépassée |
| `partially_paid` | Un paiement reçu, un solde encore dû |
| `paid` | Soldée |
| `cancelled` | Annulée : son écriture est extournée, rien n'est dû |

Trois autres valeurs (`paid_in_provider`, `refunded_in_provider`, `paid_outside_provider`) ne
concernent que les factures émises par un prestataire de paiement relié à Mast.

Les paiements se constatent dans Mast, en général par le rapprochement de vos relevés bancaires.
L'API vous les rend, à une clé dont le rôle consulte « Affectation de trésorerie » (section **Ventes
et facturation**) :

```bash
# Les paiements d'une facture
curl -s "https://api.mastfinance.io/api/v1/ext/payments?invoiceExternalRef=bo-2026-0457" \
  -H "Authorization: Bearer $MAST_API_KEY"

# Tout ce qui a bougé depuis votre dernière lecture, pour mettre votre back-office à jour
curl -s "https://api.mastfinance.io/api/v1/ext/invoices?updatedSince=2026-11-19T06:00:00Z" \
  -H "Authorization: Bearer $MAST_API_KEY"
```

La seconde lecture, relancée régulièrement, suffit à tenir l'état de vos factures à jour dans votre
back-office (la section 3 décrit la méthode). Une précision : une facture qui devient `overdue` ne
change pas en base, elle n'est donc pas resservie pour cela. `overdue` se juge le jour de la lecture,
à partir de `dueDate`.

### 2.10 Ce qui se fait dans Mast, et pas par l'API

- **Les avoirs.** L'API les lit (`GET /ext/credit-notes`), avec la facture que chacun corrige. Ils
  s'établissent dans Mast.
- **L'enregistrement des paiements**, par le rapprochement bancaire.
- **Les rappels de paiement**, que Mast envoie selon les réglages de votre société.
- **Là où un fournisseur est payé.** L'API crée et modifie vos fournisseurs (2.11), jamais leur
  compte bancaire : une personne le saisit dans Mast, sur la fiche du fournisseur.
- **Les notifications.** L'API ne vous appelle pas quand quelque chose change : lisez les listes par
  `updatedSince`, à votre rythme.

### 2.11 Vos fournisseurs

Votre back-office, ou l'outil d'achat par lequel votre société commande, tient vos fournisseurs à
jour dans Mast comme vos clients : un appel par fournisseur, sous votre propre identifiant, qui le
crée la première fois et le modifie ensuite. Les fournisseurs ne font pas partie du parcours vers une
facture ; une clé qui les tient n'a besoin que des droits sur « Fournisseurs ».

| Pour | Appel | Droit du rôle de la clé |
|---|---|---|
| Tenir un fournisseur à jour | `PUT /ext/suppliers/{externalRef}` | Fournisseurs : Créer et Modifier |
| En lire un par votre identifiant | `GET /ext/suppliers/{externalRef}` | Fournisseurs : Consulter |
| Les lire tous, ou ce qui a changé | `GET /ext/suppliers` | Fournisseurs : Consulter |
| Donner votre identifiant à un fournisseur créé dans Mast | `PATCH /ext/suppliers/by-id/{id}` | Fournisseurs : Modifier |

```bash
curl -s -X PUT https://api.mastfinance.io/api/v1/ext/suppliers/erp-7001 \
  -H "Authorization: Bearer $MAST_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Muster Bureau AG",
    "email": "compta@muster-bureau.example",
    "address": { "street": "Musterweg 3", "postalCode": "3000", "city": "Bern" },
    "vatStatus": "registered",
    "vatNumber": "CHE-123.456.788 MWST",
    "paymentTermsDays": 30
  }'
```

Mast répond `201` la première fois (le fournisseur est créé), `200` ensuite (il est modifié), avec le
fournisseur tel qu'il le tient :

```json
{
  "id": "cmwp2k7rx00b4suqf0a9c3lzd",
  "externalRef": "erp-7001",
  "number": "SUPP-00012",
  "name": "Muster Bureau AG",
  "businessType": "corporation_company",
  "email": "compta@muster-bureau.example",
  "address": { "street": "Musterweg 3", "postalCode": "3000", "city": "Bern", "country": "Switzerland" },
  "vatStatus": "registered",
  "vatNumber": "CHE123456788",
  "currency": "CHF",
  "paymentTermsDays": 30,
  "…": "…"
}
```

- **Créer demande son nom et son statut TVA.** `vatStatus` vaut `registered` pour un fournisseur
  immatriculé à la TVA du pays de votre société, `foreign_registered` pour un fournisseur étranger
  qui y est immatriculé, chacun avec son numéro dans `vatNumber` ; `not_registered` ou
  `foreign_not_registered` pour un fournisseur qui ne l'est pas, sans numéro. Mast vérifie le numéro
  comme le pays de votre société l'écrit, le garde compact et le répond ainsi. Une lecture peut
  répondre `unknown` pour un fournisseur enregistré avant que Mast ne demande le statut ; un appel ne
  l'écrit jamais. Ensuite, un appel n'envoie que ce qui change, et `null` efface un champ qui peut
  être vide.
- **Omis, ceux de la société.** Le pays d'une adresse qui n'en nomme pas est celui de votre société,
  la devise de ses factures la devise de base de votre société, son délai de paiement 30 jours et sa
  forme juridique (`businessType`) `corporation_company`.
- **Son téléphone** s'écrit sous sa forme internationale, `+` et l'indicatif du pays en premier
  (`+41 44 000 00 00`) : Mast ne devine pas le pays d'un numéro national, et le refuse
  (`422 VALIDATION_FAILED`). Il garde et répond le numéro sans espaces (`+41440000000`).
- **Un fournisseur par nom.** Comme dans Mast, deux fournisseurs actifs d'une société ne partagent
  jamais un nom, une adresse e-mail ou un numéro de téléphone : l'appel répond
  `409 SUPPLIER_NAME_EXISTS`, `SUPPLIER_EMAIL_EXISTS` ou `SUPPLIER_PHONE_EXISTS`. Un fournisseur
  qu'une personne a déjà créé ou importé dans Mast se rattache d'abord, comme un client (2.2) :
  trouvez-le dans `GET /ext/suppliers`, où son `externalRef` vaut `null`, donnez-lui votre
  identifiant par `PATCH /ext/suppliers/by-id/{id}` et `{ "externalRef": "erp-0042" }`, et votre
  `PUT` le modifie ensuite. `null` lui retire de nouveau l'identifiant.
- **Les règles de Mast sur le statut TVA** répondent `400` avec leurs propres codes : un fournisseur
  immatriculé sans numéro (`SUPPLIER_CH_VAT_NUMBER_REQUIRED`), un numéro que son pays n'écrit pas
  ainsi (`SUPPLIER_CH_VAT_NUMBER_FORMAT`, `SUPPLIER_CH_VAT_NUMBER_CHECKSUM`), un numéro à côté d'un
  statut qui n'en prend pas (`SUPPLIER_CH_VAT_NUMBER_FORBIDDEN` : envoyez `"vatNumber": null` avec le
  nouveau statut). Ce sont les codes que rencontre la fiche du fournisseur dans Mast.
- **Jamais son compte bancaire.** L'API n'écrit pas là où un fournisseur est payé : ni son IBAN, ni
  sa banque, ni le titulaire du compte, et pas davantage ses paramètres comptables par défaut, ses
  catégories ou sa mise sur liste noire. Un champ qui en nomme un est ignoré, comme tout champ que
  Mast ne connaît pas, et ce que le fournisseur tenait reste tel quel. Une clé qui pourrait changer
  là où un fournisseur est payé pourrait détourner un paiement : une personne saisit donc le compte
  bancaire dans Mast. L'API ne le sert pas non plus.

## 3. Sortir vos données pour vos analyses

Ce que Mast tient pour votre société se lit par l'API, pour alimenter votre outil de tableaux de
bord ou votre entrepôt de données. Donnez à cette clé un rôle qui ne fait que consulter.

Chaque lecture demande le droit « Consulter » sur la fonctionnalité correspondante, telle que
**Paramètres › Utilisateurs & permissions** la nomme :

| Ce que vous lisez | Appel | Fonctionnalité à consulter |
|---|---|---|
| La société, sa devise de base, ses exercices | `GET /ext/company` | Profil de l'entreprise |
| Les clients | `GET /ext/customers` | Clients |
| Les produits | `GET /ext/products` | Produits |
| Les factures, avec leurs lignes | `GET /ext/invoices?include=lines` | Factures clients |
| Les avoirs, avec leurs lignes | `GET /ext/credit-notes?include=lines` | Avoirs clients |
| Les encaissements | `GET /ext/payments` | Affectation de trésorerie, section Ventes et facturation |
| Le plan comptable | `GET /ext/accounts` | Plan comptable |
| Les écritures, avec leurs lignes | `GET /ext/journal-entries` | Écritures comptables |
| La balance entre deux jours | `GET /ext/trial-balance?from=…&to=…` | États financiers |
| Les comptes bancaires et leurs soldes | `GET /ext/bank-accounts` | Comptes bancaires |
| Les mouvements bancaires | `GET /ext/bank-transactions` | Relevés bancaires |
| Les fournisseurs | `GET /ext/suppliers` | Fournisseurs |
| Les factures fournisseurs, avec leurs lignes | `GET /ext/bills` | Factures fournisseurs |

### Lire ce qui a changé

Toutes les listes prennent les trois mêmes paramètres et répondent la même forme :

| Paramètre | Ce qu'il fait |
|---|---|
| `updatedSince` | Seulement ce qui a changé à partir de cet instant, écrit avec son décalage (`2026-11-18T22:00:00Z`). Omis : tout |
| `limit` | Lignes par page, de 1 à 100, 50 par défaut |
| `cursor` | Le `nextCursor` de la page précédente, pour lire la suivante |

Écrivez `updatedSince` en UTC, avec `Z`. Un décalage comme `+01:00` doit s'envoyer `%2B01:00` : dans
une chaîne de requête, un `+` non encodé se lit comme une espace, et l'appel est refusé
(`422 VALIDATION_FAILED`).

```json
{ "data": [ … ], "nextCursor": "…" }
```

Les lignes arrivent **du changement le plus ancien au plus récent**. `nextCursor` vaut `null` quand il
n'y a plus rien pour l'instant.

Un curseur est opaque et appartient à la liste qui l'a donné : renvoyez-le tel que vous l'avez reçu, à
cette liste. Une valeur qui n'est pas un curseur, et le curseur d'une autre liste, sont refusés
(`400 EXT_CURSOR_INVALID`) plutôt que de repartir du début sans le dire. Un curseur n'est pas signé :
un curseur modifié à la main ne se distingue pas de ceux de Mast, et la liste reprend alors là où il
pointe.

Pour garder une copie à jour, par exemple chaque nuit :

1. La première fois, lisez toute la liste : sans `updatedSince`, puis suivez `nextCursor` jusqu'au bout.
2. Retenez le `updatedAt` le plus récent que vous avez reçu.
3. La fois suivante, passez-le comme `updatedSince`, **quelques minutes plus tôt**, et suivez de
   nouveau `nextCursor`.
4. Rangez chaque ligne sous son `id` : une ligne qui change pendant votre lecture revient plus loin
   dans la liste. Une synchronisation livre « au moins une fois », jamais « au plus une fois ».

```bash
curl -s "https://api.mastfinance.io/api/v1/ext/invoices?include=lines&updatedSince=2026-11-18T22:00:00Z&limit=100" \
  -H "Authorization: Bearer $MAST_API_KEY"
```

### Des chiffres qui tombent juste

- **Ce qui a été facturé sur une période.** Additionnez `invoicedNetAmount` sur les factures et les
  avoirs dont `issueDate` tombe dans la période. Un brouillon et un document annulé valent `null` :
  ils ne comptent pas. Les montants d'un avoir sont négatifs, donc la somme est déjà nette. Pour
  additionner des documents de devises différentes, prenez `baseInvoicedNetAmount`, dans la devise de
  base de la société ; il vaut `null` pour un document en devise étrangère sans taux enregistré, que
  Mast ne convertit jamais à 1 pour 1.
- **Par client ou par produit.** Faites la même somme sur les lignes : chaque ligne porte son
  `invoicedNetAmount`, sa part de ce pour quoi son document a été émis, remise du document comprise.
  Les lignes d'un document s'additionnent donc exactement à ce qui a été facturé.
- **Ce que vos clients vous doivent.** Les factures dont `amountDue` est supérieur à zéro. `status`
  dit où chacune en est (`open`, `overdue`, `partially_paid`), `dueDate` son échéance.
- **Ce qui est rentré.** Les encaissements (`GET /ext/payments`), chacun avec son jour (`paidOn`), son
  montant et sa facture.
- **Le résultat et le bilan.** La balance entre deux jours donne, par compte, le solde d'ouverture,
  les débits et crédits de la période et le solde de clôture, dans la devise de base. Ce sont les
  chiffres de la balance de Mast pour les mêmes jours. Chaque montant est signé débit moins crédit :
  un compte de produit, de passif ou de fonds propres se lit donc normalement en négatif.
- **La trésorerie.** Les comptes bancaires portent le solde du dernier relevé et le solde calculé sur
  tous les mouvements que Mast détient ; les mouvements donnent le détail. Lorsque votre compte exige
  la validation en deux étapes de chaque personne qui s'y connecte (c'est le cas dès qu'une banque
  est connectée à Mast), ces deux appels répondent `403 EXT_BANK_DATA_TWO_FACTOR_ACCOUNT` à une clé,
  qui se connecte sans seconde étape ; tous les autres appels répondent comme d'habitude.
- **Vos achats.** Les factures fournisseurs portent leur statut tel que Mast le tient, leurs montants
  et ce qui reste à payer. La liste ne prend pas de filtre `status` et sert aussi les brouillons et les
  factures encore à traiter : gardez de votre côté les statuts que vous comptez. Une facture
  comptabilisée porte son `journalEntryId`. Un avoir de fournisseur (`type: credit_note`) a des
  montants positifs, et se soustrait.
- **Par centre de coûts.** Chaque ligne d'écriture porte ses parts par centre de coûts
  (`costCenterShares`), dont les montants s'additionnent exactement à la ligne.

Commencez par `GET /ext/company` : il donne la devise de base, dans laquelle tous les chiffres
comptables sont exprimés, et les premiers et derniers jours de chaque exercice.

## 4. Les règles communes à tous les appels

### Formats

- Les **noms** de champs sont en camelCase. Un jour s'écrit `AAAA-MM-JJ` ; un instant est en ISO 8601,
  en UTC (`2026-11-19T08:30:00.000Z`).
- Les **montants** sont des nombres décimaux à deux décimales, toujours à côté de leur devise
  (`currency`, ISO 4217). Un montant dans la devise de base de la société le dit dans son nom.
- Les **mots** qui nomment un état ou un genre (`status`, `type`, `direction`) sont en minuscules. De
  nouvelles valeurs peuvent apparaître avec le temps : traitez une valeur inconnue comme « autre », ne
  bloquez pas dessus.
- **Un champ sans valeur vaut `null`**, il n'est jamais omis. De nouveaux champs peuvent apparaître
  dans une réponse : ignorez ceux que vous n'utilisez pas.
- **Deux identifiants.** Tout a l'identifiant de Mast, `id`. Ce que votre système crée porte aussi
  **votre** identifiant, `externalRef`, unique dans la société, et s'adresse par lui
  (`/ext/invoices/{externalRef}`) : vous n'avez jamais à stocker l'identifiant de Mast pour retrouver
  votre facture. Ce qu'une personne a créé dans Mast a `externalRef: null`, et se lit par
  l'identifiant de Mast : `/ext/invoices/by-id/{id}`. Un client, un produit ou un fournisseur dans
  ce cas reçoit votre identifiant par le même chemin (2.2, 2.11).
- **Aucune donnée personnelle dans un `externalRef`.** Votre identifiant voyage dans l'adresse de
  chaque appel, et les adresses sont gardées dans des journaux : les vôtres, ceux de Mast et ceux de
  chaque intermédiaire. Prenez un numéro ou un code (`crm-1042`), jamais le nom ou l'e-mail d'une
  personne.
- **Un corps est du JSON, envoyé avec `Content-Type: application/json`**
  (`application/json; charset=utf-8` aussi). Un corps envoyé sous un autre type, ou sans type, est
  refusé `415 EXT_JSON_BODY_REQUIRED`, et rien n'est fait : `curl -d` sans l'en-tête envoie
  `application/x-www-form-urlencoded`, par exemple. Un appel qui ne prend pas de corps (une lecture,
  l'émission d'une facture, une suppression) s'envoie sans corps, et n'est alors jamais refusé pour
  son type.
- **Un champ que Mast ne connaît pas est ignoré**, sans erreur : un nom de champ mal orthographié
  n'est pas refusé, il ne change rien. Relisez ce que vous avez écrit (chaque écriture répond
  l'enregistrement tel que Mast le tient) et comparez-le à ce que vous avez envoyé. Un appel est
  strict : donner votre identifiant par celui de Mast (`PATCH /ext/…/by-id/{id}`) refuse tout autre
  champ que `externalRef`.
- **Un paramètre de requête que l'appel ne connaît pas est ignoré** de la même façon :
  `GET /ext/invoices?statut=paid`, mal orthographié, répond toutes les factures, comme si aucun filtre
  n'avait été donné. La référence liste les paramètres de chaque appel.
- **Le texte est lu sans ce qu'il ne peut pas vouloir dire.** Mast retire tout caractère NUL (U+0000)
  du texte d'un corps avant de le lire, et écrit une moitié isolée d'une paire de substitution UTF-16
  comme `�` (U+FFFD). Ensuite, chaque champ texte d'un corps (un `externalRef`, un code, un nom) et
  chaque référence ou identifiant d'un chemin est lu sans les espaces qui l'entourent : `"crm-1042 "`
  est enregistré, et retrouvé, comme `crm-1042`. Un NUL dans un chemin ou une chaîne de requête est
  refusé (`422 VALIDATION_FAILED`).

### Quand un appel est refusé

Un appel refusé répond son statut HTTP et un objet JSON :

```json
{
  "statusCode": 409,
  "error": "ConflictException",
  "message": "An invoice with this externalRef already exists in the company.",
  "code": "EXT_INVOICE_EXISTS",
  "timestamp": "2026-11-19T08:30:00.000Z",
  "path": "/api/v1/ext/invoices"
}
```

Décidez sur le **`code`**, qui est stable. Le `message` est en anglais, pour un développeur, et peut
être reformulé. `details`, quand il y en a un, en dit plus (les champs qu'une validation a refusés).
Les codes propres à chaque appel sont dans la référence, chacun avec un exemple de la réponse entière
dans `openapi.v1.json` ; ceux-ci peuvent venir de n'importe quel appel :

| Statut | Code | Que faire |
|---|---|---|
| 422 | `VALIDATION_FAILED` | La requête n'a pas la forme attendue. `details.fieldErrors` nomme chaque champ (`lines.0.quantity`) et pourquoi. Corrigez et renvoyez |
| 400 | aucun | Le corps de la requête n'est pas du JSON valide. Cette réponse ne porte ni `code` ni `x-request-id` (ci-dessous) |
| 413 | `FILE_TOO_LARGE` | Le corps dépasse 1 Mo (« request entity too large »), ou ses listes comptent plus de 20'000 éléments en tout. Mast n'en a rien lu et n'a rien fait : envoyez moins en un appel |
| 415 | `EXT_JSON_BODY_REQUIRED` | Le corps n'a pas été envoyé en JSON : un autre `Content-Type`, ou aucun. Rien n'a été fait. Renvoyez-le avec `Content-Type: application/json` |
| 415 | `BAD_REQUEST` | Mast n'a pas pu lire le corps : son `charset` n'est pas un UTF (« unsupported charset "LATIN1" »), ou il est arrivé compressé (`Content-Encoding`), ce que le pare-feu de Mast refuse avant que Mast ne le voie (ci-dessous). Rien n'a été fait. Envoyez-le non compressé, en UTF-8 |
| 400 | `IDEMPOTENCY_KEY_INVALID` | Sur un appel qui écrit : l'`Idempotency-Key` n'est pas faite de 1 à 255 caractères ASCII visibles, ou elle a été envoyée deux fois. Rien n'a été fait |
| 401 | `API_KEY_REQUIRED`, `API_KEY_INVALID` | Pas de clé, ou pas une clé de Mast : vérifiez l'en-tête |
| 401 | `API_KEY_REVOKED`, `API_KEY_EXPIRED` | Créez une nouvelle clé dans les paramètres |
| 403 | `API_KEY_COMPANY_MISMATCH` | La requête nomme, dans un en-tête `x-company-id`, une autre société que celle de la clé. Une clé agit dans sa propre société et n'a besoin d'aucun en-tête de ce genre : retirez-le |
| 403 | `API_KEY_ROUTE_NOT_ALLOWED` | Une clé a été envoyée à une adresse hors de l'API (`/api/v1/ext`) : une clé n'atteint que l'API |
| 403 | `PUBLIC_API_NOT_ENABLED` | L'API n'est pas ouverte pour ce compte, ou ne l'est plus |
| 403 | `ACCESS_DENIED_ROLE_REQUIRED` | Le rôle de la clé n'a pas le droit que demande cet appel. Donnez un autre rôle à la clé, ou ce droit au rôle |
| 403 | `SUBSCRIPTION_CANCELED_READ_ONLY`, `YOUR_FREE_TRIAL_EXPIRED`, `SUBSCRIPTION_REQUIRED`, `ORGANIZATION_PENDING_DELETION_READ_ONLY` et leurs semblables | Votre compte Mast est pour l'instant en lecture seule : un appel qui écrit est refusé, une lecture répond. Le propriétaire du compte règle cela dans Mast |
| 429 | `RATE_LIMITED` | Trop d'appels de ce genre en une minute. Attendez les secondes indiquées par `Retry-After` |
| 5xx | `INTERNAL_ERROR` ou aucun | Mast a échoué. Réessayez plus tard avec la même `Idempotency-Key` ; si cela dure, écrivez-nous avec le `x-request-id` de la réponse. Un `503` qui porte un code propre nomme ce qui n'est pas mis en place dans Mast, et aucun nouvel essai ne le règle : `EMAIL_NO_ACCOUNT_CONNECTED`, par exemple, dit que la société n'a pas de boîte depuis laquelle envoyer ses e-mails (2.7) |

Un `RATE_LIMITED` a une seconde cause, avec d'autres mots : une adresse qui présente des clés que
Mast n'accepte pas. Chaque appel d'une même adresse avec une clé bien formée (`mast_sk_…`, comme Mast
les crée) mais inconnue, révoquée ou expirée est compté ; une valeur qui n'a pas la forme d'une clé
est refusée `401 API_KEY_INVALID` et n'est pas comptée. Les 31 premiers appels de ce genre d'une
minute reçoivent `401` comme d'habitude ; dès le suivant, chaque appel de cette adresse avec une clé
bien formée reçoit `429 RATE_LIMITED`, avec `Retry-After`, jusqu'à la fin de la minute, quelle que
soit la clé. Une clé qui a appelé avec succès dans les dix dernières minutes passe en général tout de
même. Vérifiez qu'aucun système oublié n'envoie encore une ancienne clé.

Un refus des règles propres de Mast sur un client, un produit, un fournisseur ou une facture
(`EXT_CUSTOMER_INVALID`, `EXT_PRODUCT_INVALID`, `EXT_SUPPLIER_INVALID`, `EXT_INVOICE_INVALID`) ne
nomme aujourd'hui aucun champ : comparez ce que vous avez envoyé à la référence.

### Les en-têtes d'une réponse

`openapi.v1.json` déclare chacun de ces en-têtes (`components.headers`) sur les réponses qui le
portent toujours : un client généré à partir de lui peut compter sur chaque en-tête qu'il y trouve.

| En-tête | Sur quelles réponses |
|---|---|
| `x-request-id` | Chaque réponse de l'application, refus compris, sauf le refus d'un corps que Mast n'a pas pu lire (le `400` ci-dessus, le `413`, le `415 BAD_REQUEST`) et les réponses du pare-feu (ci-dessous). Citez-le quand vous nous écrivez au sujet d'un appel : il le retrouve dans nos journaux. Vous pouvez envoyer le vôtre, en lettres, chiffres et `.` `_` `:` `-`, jusqu'à 128 caractères : Mast répond avec lui |
| `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` | Chaque réponse d'un appel que la limite a compté : dès que la clé et le droit de son rôle sont acceptés, quoi qu'il arrive ensuite (un succès, un `404`, un `409`, un `422`, le `429` d'un PDF demandé pendant qu'un autre est en préparation). Pas sur une réponse donnée avant : le refus d'un corps que Mast n'a pas pu lire, un `401`, les `403` `API_KEY_COMPANY_MISMATCH`, `PUBLIC_API_NOT_ENABLED`, `ACCESS_DENIED_ROLE_REQUIRED` et `EXT_BANK_DATA_TWO_FACTOR_ACCOUNT`, le `415` `EXT_JSON_BODY_REQUIRED` ; ni sur le `429` de la limite elle-même, ou d'une adresse refusée pour les clés qu'elle présente |
| `Retry-After` | Un `429` d'une limite sur les appels (la limite de débit, un PDF à la fois, une adresse refusée pour ses clés, le pare-feu) : les secondes à attendre. Pas le `429 EMAIL_MAST_SENDER_DAILY_LIMIT` d'un envoi, quand Mast a envoyé en votre nom les e-mails de la journée de la société : l'envoi reprend le lendemain |
| `idempotent-replayed: true` | Une répétition à laquelle Mast rend la réponse gardée sous son `Idempotency-Key` |
| `x-idempotency-keys` | Chaque réponse d'un appel qui a passé les vérifications de sa clé, de son rôle et de la limite : `accepted` tant que Mast honore `Idempotency-Key`, `unavailable` dans le rare moment où il ne le peut pas (une répétition est alors exécutée de nouveau : votre `externalRef` l'empêche tout de même de créer un second enregistrement) |

### Le pare-feu de Mast

Devant l'API, un pare-feu répond lui-même à certaines requêtes, avant que Mast ne les voie. Ses
réponses ne portent ni `x-request-id`, ni en-tête `X-RateLimit`, ni `message` :

| Statut | Corps | Quand | Que faire |
|---|---|---|---|
| 429 | `{"statusCode":429,"source":"waf-per-ip-rate-limit"}`, avec `Retry-After: 60` | Plus de 8'000 requêtes d'une même adresse IP en 5 minutes, quelle que soit la clé | Attendez les secondes indiquées par `Retry-After`. Plusieurs systèmes derrière une même adresse partagent ce compte |
| 403 | `{"statusCode":403,"code":"REQUEST_BLOCKED","source":"waf-blocked-request"}` | Une requête sans en-tête `User-Agent` ; un corps ou une chaîne de requête dont le texte se lit comme du SQL, comme un chemin vers les fichiers du serveur (`../`) ou comme une URL contenant une adresse IP ; un script dans la chaîne de requête ou le chemin ; une chaîne de requête de plus de 8 Ko ; une adresse sur les listes d'attaquants connus d'Amazon | Envoyez un `User-Agent` qui nomme votre système (`MonBackOffice/2.1`) : la plupart des bibliothèques HTTP en envoient un, mais pas toutes. Si une requête légitime est refusée, écrivez à Mast avec l'heure, l'appel et le corps |
| 415 | `{"statusCode":415,"source":"waf-compressed-request-body"}` | Une requête avec un en-tête `Content-Encoding` : Mast ne prend que des corps non compressés | Envoyez le corps sans le compresser, et sans l'en-tête |

### Ne faire une chose qu'une fois

Une coupure réseau peut vous laisser sans savoir si un appel est arrivé. Deux mécanismes rendent un
nouvel essai sûr.

- **Votre identifiant décide.** Un client, un produit, un fournisseur ou une facture est créé sous
  votre `externalRef`, et la base de données refuse elle-même un second sous le même identifiant
  (`409 …_EXISTS`). Une création rejouée ne fait jamais de doublon.
- **`Idempotency-Key`.** Tout appel qui écrit peut porter cet en-tête, une valeur à vous (1 à 255
  caractères), unique par acte. Pendant 24 heures, une répétition avec la même clé et la même requête
  reçoit exactement la réponse de la première, avec l'en-tête `idempotent-replayed: true`, et rien
  n'est fait deux fois. La même clé avec une autre requête est refusée
  (`422 IDEMPOTENCY_KEY_REUSED`) ; une répétition qui arrive pendant que la première tourne encore
  est priée d'attendre (`409 IDEMPOTENCY_REQUEST_IN_PROGRESS`). Utilisez-la pour les appels qui
  agissent : émettre une facture, l'envoyer.

### Limites de débit

Les limites se comptent par clé et par appel, sur une minute :

| Genre d'appel | Par minute |
|---|---|
| Lecture (listes, un enregistrement) | 300 |
| États calculés et fichiers (la balance, un PDF) | 60 |
| Écriture (créer, modifier, émettre, envoyer) | 60 |

Une réponse que la limite a comptée dit où vous en êtes : `X-RateLimit-Limit`,
`X-RateLimit-Remaining` et `X-RateLimit-Reset` (les secondes jusqu'à la fin de la minute) ; « Les
en-têtes d'une réponse », ci-dessus, dit quelles réponses les portent. Au-delà, la réponse est
`429 RATE_LIMITED` avec `Retry-After` (secondes), et sans en-tête `X-RateLimit`. Un PDF demandé
pendant qu'un autre PDF de la clé est encore en préparation (2.8) reçoit lui aussi
`429 RATE_LIMITED` avec `Retry-After`, mais ce n'est pas la réponse de la limite : la limite a laissé
passer cet appel et l'a compté, il porte donc les en-têtes `X-RateLimit` et prend un appel des 60 de
la minute. Devant l'API, le
pare-feu de Mast compte aussi toutes les requêtes d'une même adresse IP : au-delà de 8'000 en
5 minutes, il répond lui-même `429` (« Le pare-feu de Mast »). Ces limites protègent contre une
boucle, ce ne sont pas des quotas : une synchronisation nocturne ou quelques centaines de factures par
jour restent très en dessous. Si votre volume est d'un autre ordre, dites-le-nous avant de commencer.

### Versions et stabilité

L'adresse porte la version : `/api/v1`. À l'intérieur, **seuls des ajouts sont faits** : un nouvel
appel, un nouveau champ facultatif dans une requête, un nouveau champ ou une nouvelle valeur dans une
réponse. Aucun appel, aucun champ et aucune valeur acceptée ne disparaît, ne change de type ou ne
devient obligatoire. Un changement qui casserait votre code viendrait sous une nouvelle adresse
(`/api/v2`), annoncée à l'avance, les deux étant servies côte à côte. Mast le vérifie par machine :
le contrat est imprimé depuis le code qui répond, et un changement qui casserait un client est refusé
avant d'être publié.

## 5. Brancher votre propre assistant IA (MCP)

Mast expose aussi son API par le protocole MCP (Model Context Protocol), le protocole ouvert par
lequel un assistant IA utilise les fonctions d'un service comme des outils. Un assistant à vous
(Claude, ou tout client qui parle MCP) peut ainsi lire vos clients, vos factures et votre
comptabilité dans Mast, et préparer des brouillons de factures, avec une clé API de votre société.

C'est la même API sous une autre forme : chaque outil est un appel de l'API, tenu aux mêmes droits,
aux mêmes limites et aux mêmes règles.

| | |
|---|---|
| Adresse | `https://api.mastfinance.io/api/v1/ext/mcp` |
| Transport | Streamable HTTP (`POST`), réponses en JSON |
| Authentification | L'en-tête `Authorization: Bearer mast_sk_…` |

**Ce que l'assistant peut faire, et ne peut pas faire**

- Il agit dans une seule société, avec les droits du rôle de la clé. Pour un assistant qui répond à
  des questions, donnez à la clé un rôle qui ne fait que consulter.
- Il lit ce que lit l'API : la société, les clients, les produits, les factures, les avoirs, les
  encaissements, le plan comptable, les écritures, la balance, les comptes et mouvements bancaires,
  les fournisseurs et leurs factures.
- **Il prépare, il n'émet jamais.** Il peut créer et corriger des clients, des produits, des
  fournisseurs et des **brouillons** de factures. Un brouillon n'a pas de numéro officiel ni
  d'écriture comptable, et rien n'est envoyé à votre client. Émettre une facture et l'envoyer par
  e-mail ne font pas partie des outils : une personne le fait dans Mast, ou votre propre système par
  l'API. C'est voulu. Aucun outil n'écrit le compte bancaire d'un fournisseur : là où un fournisseur
  est payé se saisit dans Mast, par une personne.
- **Les outils ne sont une barrière que dans la mesure du rôle de la clé.** C'est la clé que Mast
  écoute, par ces outils comme par l'API. Une clé dont le rôle a « Comptabiliser » sur les factures
  clients peut émettre et envoyer par l'API, et un assistant capable de lancer ses propres commandes
  pourrait être amené à l'appeler. Donnez donc à la clé d'un assistant un rôle **sans
  « Comptabiliser »** : Mast lui refuse alors d'émettre et d'envoyer, quoi qu'on lui demande.
- Ce qu'il écrit apparaît dans Mast sous le nom de la clé : ce qu'a écrit une clé nommée « Assistant »
  se lit « Assistant (API) » partout où Mast indique qui a fait quoi.

**Les outils**

Chaque outil demande au rôle de la clé le droit que demande son appel, nommé comme **Paramètres ›
Utilisateurs & permissions** le nomme : la fonctionnalité, puis la colonne.

| Pour demander | Outil | Effet | Droit du rôle de la clé |
|---|---|---|---|
| Quelle clé suis-je, dans quelle société ? | `mast_whoami` | lit | aucun |
| La société, sa devise de base, ses exercices | `mast_get_company` | lit | Profil de l'entreprise : Consulter |
| Les clients | `mast_list_customers` | lit | Clients : Consulter |
| Un client, par votre identifiant | `mast_get_customer` | lit | Clients : Consulter |
| Créer ou modifier un client | `mast_save_customer` | écrit | Clients : Créer et Modifier |
| Les produits | `mast_list_products` | lit | Produits : Consulter |
| Un produit, par votre identifiant | `mast_get_product` | lit | Produits : Consulter |
| Créer ou modifier un produit | `mast_save_product` | écrit | Produits : Créer et Modifier |
| Les factures, par état, avec leurs lignes | `mast_list_invoices` | lit | Factures clients : Consulter |
| Une facture, par votre identifiant | `mast_get_invoice` | lit | Factures clients : Consulter |
| Une facture, par l'identifiant de Mast | `mast_get_invoice_by_id` | lit | Factures clients : Consulter |
| Préparer un **brouillon** de facture | `mast_create_invoice_draft` | écrit | Factures clients : Créer |
| Corriger un brouillon | `mast_update_invoice_draft` | écrit | Factures clients : Modifier |
| Abandonner un brouillon | `mast_delete_invoice_draft` | écrit | Factures clients : Supprimer |
| Les avoirs | `mast_list_credit_notes` | lit | Avoirs clients : Consulter |
| Un avoir, par l'identifiant de Mast | `mast_get_credit_note_by_id` | lit | Avoirs clients : Consulter |
| Les encaissements | `mast_list_payments` | lit | Affectation de trésorerie (Ventes et facturation) : Consulter |
| Le plan comptable | `mast_list_accounts` | lit | Plan comptable : Consulter |
| Les écritures | `mast_list_journal_entries` | lit | Écritures comptables : Consulter |
| La balance | `mast_get_trial_balance` | lit | États financiers : Consulter |
| Les comptes bancaires | `mast_list_bank_accounts` | lit | Comptes bancaires : Consulter |
| Les mouvements bancaires | `mast_list_bank_transactions` | lit | Relevés bancaires : Consulter |
| Les fournisseurs | `mast_list_suppliers` | lit | Fournisseurs : Consulter |
| Un fournisseur, par votre identifiant | `mast_get_supplier` | lit | Fournisseurs : Consulter |
| Créer ou modifier un fournisseur | `mast_save_supplier` | écrit | Fournisseurs : Créer et Modifier |
| Les factures fournisseurs | `mast_list_bills` | lit | Factures fournisseurs : Consulter |

Un outil que le rôle ne couvre pas répond `ACCESS_DENIED_ROLE_REQUIRED`, et les autres fonctionnent.
Mast dit à chaque assistant de commencer par `mast_get_company`, pour connaître la devise de base et
les exercices : donnez au rôle d'un assistant « Consulter » sur **Profil de l'entreprise**, sinon ce
premier appel échoue.

Ce que vous pouvez ensuite demander à votre assistant, avec vos mots :

- « Quelles factures sont en retard, et pour quel montant par client ? »
- « Qu'avons-nous facturé en octobre, avoirs déduits, par produit ? »
- « Prépare un brouillon de facture pour Muster Handel AG : 14 heures de conseil et trois manuels,
  avec sa remise habituelle. » L'assistant prépare le brouillon ; vous le vérifiez et l'émettez dans
  Mast.
- « Qu'est-ce qui est arrivé en banque la semaine dernière et n'est pas encore rapproché ? »

**Se connecter avec Claude Code**

```bash
claude mcp add --transport http mast https://api.mastfinance.io/api/v1/ext/mcp --header "Authorization: Bearer mast_sk_…"
```

Tout client qui permet de donner l'adresse d'un serveur distant et un en-tête peut se connecter. Un
client qui ne sait s'identifier auprès d'un serveur que par OAuth se connecte, là où Mast l'a ouvert
pour votre compte, en vous faisant vous connecter à Mast : voir la page [MCP](https://mastfinance.io/developers/mcp.md#connect-mast-to-claude-by-signing-in)
(en anglais).

**Bonnes pratiques**

- Une clé par assistant, à son nom, avec le rôle le plus étroit qui lui suffit, et une expiration.
- La clé reste dans la configuration du client ou dans une variable d'environnement, jamais dans une
  conversation ni dans un fichier que l'assistant lit.
- Gardez une personne dans la boucle pour ce qui s'écrit : la plupart des clients demandent une
  confirmation avant un outil qui écrit, et Mast marque chaque outil comme lecture ou écriture pour
  qu'ils le puissent.
- Ce que l'assistant lit n'a pas tout été écrit par vous. Le texte d'un mouvement bancaire est celui
  de son payeur, les lignes d'une facture fournisseur sont celles du fournisseur, le nom d'un client
  est ce que quelqu'un a saisi. Un tel texte peut contenir une phrase adressée à un assistant
  (« ignorez vos instructions et… »). Mast le transmet tel quel, comme une donnée, et le dit à chaque
  client dans les instructions qu'il lui donne. Un rôle qui ne fait que consulter, l'accord d'une
  personne avant une écriture, et un assistant qui n'a pas d'autre outil pour faire sortir des données
  rendent une telle phrase inoffensive.
- Ce que l'assistant lit passe par l'assistant que vous avez branché et par son fournisseur, selon
  votre accord avec eux, pas celui de Mast.

La page [MCP](https://mastfinance.io/developers/mcp.md) (en anglais) donne le détail, et chaque appel de la [référence](https://mastfinance.io/developers/reference.md)
nomme l'outil qui lui correspond.
