API Mast : guide d'intégration

Sur cette page

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 :

  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 :

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. 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 :

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

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" }'
  • 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

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 (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

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. 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).

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

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

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.