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 (en anglais), et le même contrat existe pour les machines au format OpenAPI
(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 :
- 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).
- 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 (
expiresAtvautnull). - 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 :
curl -s https://api.mastfinance.io/api/v1/ext/me -H "Authorization: Bearer $MAST_API_KEY"
{
"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.
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 :
{
"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.
defaultDiscountPercentest la remise que Mast garde pour ce client, etpaymentTermsDaysson 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.
typevautbusiness(nommée parcompanyName) ouindividual(nommée parfirstNameetlastName). - 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 acceptentnull. - 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ême200. Comparez la réponse à ce que vous avez envoyé (section 4). - Le pays, s'il est omis, est celui de votre société.
numberest 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 :
curl -s https://api.mastfinance.io/api/v1/ext/customers -H "Authorization: Bearer $MAST_API_KEY"
{
"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 :
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 :
{
"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
200sans 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_EXISTSpour un produit). S'il est porté par un client supprimé dans Mast, où il reste archivé, l'appel répond409 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 :
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 :
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" }'
unitPriceest le prix de vente hors TVA. C'est un prix par défaut : une ligne de facture peut toujours donner le sien.vatRateCodeest l'un des codes TVA de votre société, tels que Paramètres › TVA les liste. Dans une société suisse,CH_STDest le taux normal (8,1 %) etCH_REDle 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
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 :
{
"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.
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.
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
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
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(etccRecipientpour une copie). Pour vos propres mots, donnezsubjectetmessage: 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:truesi un envoi aux mêmes adresses (recipientetccRecipient) 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 uneIdempotency-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
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
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) :
# 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 |
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 :
{
"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.
vatStatusvautregisteredpour un fournisseur immatriculé à la TVA du pays de votre société,foreign_registeredpour un fournisseur étranger qui y est immatriculé, chacun avec son numéro dansvatNumber;not_registeredouforeign_not_registeredpour 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épondreunknownpour 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, etnullefface 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_EXISTSouSUPPLIER_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 dansGET /ext/suppliers, où sonexternalRefvautnull, donnez-lui votre identifiant parPATCH /ext/suppliers/by-id/{id}et{ "externalRef": "erp-0042" }, et votrePUTle modifie ensuite.nulllui retire de nouveau l'identifiant. - Les règles de Mast sur le statut TVA répondent
400avec 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": nullavec 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).
{ "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 :
- La première fois, lisez toute la liste : sans
updatedSince, puis suiveznextCursorjusqu'au bout. - Retenez le
updatedAtle plus récent que vous avez reçu. - La fois suivante, passez-le comme
updatedSince, quelques minutes plus tôt, et suivez de nouveaunextCursor. - 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 ».
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
invoicedNetAmountsur les factures et les avoirs dontissueDatetombe dans la période. Un brouillon et un document annulé valentnull: 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, prenezbaseInvoicedNetAmount, dans la devise de base de la société ; il vautnullpour 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
amountDueest supérieur à zéro.statusdit où chacune en est (open,overdue,partially_paid),dueDateson é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
statuset sert aussi les brouillons et les factures encore à traiter : gardez de votre côté les statuts que vous comptez. Une facture comptabilisée porte sonjournalEntryId. 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 aexternalRef: 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-8aussi). Un corps envoyé sous un autre type, ou sans type, est refusé415 EXT_JSON_BODY_REQUIRED, et rien n'est fait :curl -dsans l'en-tête envoieapplication/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 queexternalRef. - 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 (unexternalRef, 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é, commecrm-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 :
{
"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êteidempotent-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
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 (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 (en anglais) donne le détail, et chaque appel de la référence nomme l'outil qui lui correspond.