Créer une facture
create_invoiceDescription
Crée une facture en brouillon, sans numéro, comme l'écran du dossier : libre pour un dossier (kind free, à remplir avec add_invoice_lines), ou depuis un devis accepté : acompte (kind deposit, pourcentage d'acompte de la société), avancement (kind progress, percentage du montant signé ou amount hors TVA, dans la limite du reste à facturer) ou finale (kind final, montant signé moins ce qui est déjà facturé). Client et adresse sont ceux du tiers facturé. Avant l'appel, annoncer précisément la modification et attendre l'accord de l'utilisateur. Ne pas rappeler l'outil après un succès : chaque appel crée une facture. Rien n'est numéroté ni envoyé. Renvoie la facture créée.
Accès requis
- Permission :
dossier-detail.invoice.create - En plus :
invoice.list.view - Société ouverte aux outils d'écriture (Paramètres → Intégration IA).
- Sans ces conditions, l'outil n'apparaît pas dans
tools/listet son appel est refusé.
Paramètres
| Nom | Type | Présence | Description |
|---|---|---|---|
kind | string | obligatoire | free (facture libre d'un dossier), deposit (acompte), progress (avancement) ou final (facture finale) d'un devis accepté. |
dossierId | integer | facultatif | Dossier d'une facture libre (champ id de search_dossiers). |
estimateId | integer | facultatif | Devis accepté, pour deposit, progress et final (champ id de search_estimates ; le devis principal, pas un avenant). |
percentage | number | facultatif | Avancement : pourcentage du montant signé (devis et avenants acceptés) à facturer, 0,01 à 100. |
amount | number | facultatif | Avancement : montant hors TVA à facturer, à la place de percentage. |
Résultat
Le résultat est renvoyé en contenu structuré (structuredContent), conforme au schéma de sortie ci-dessous, et en texte JSON pour les clients qui ne lisent pas le contenu structuré. Une erreur est renvoyée avec isError: true et un message en français qui explique quoi corriger.
Champs du résultat
| Nom | Type | Présence | Description |
|---|---|---|---|
customerVatNumber | string | peut être null | Numéro de TVA du client imprimé sur la facture. |
customerAddress | string | peut être null | Adresse du client imprimée sur la facture. |
customerOrderNumber | string | peut être null | Référence de commande (bon de commande) du client. |
dossierIndication | string | peut être null | Intitulé court du dossier. |
structuredCommunication | string | peut être null | Communication structurée du virement. |
paymentTerm | string | peut être null | Condition de paiement. |
discountPercentage | number | peut être null | Remise globale en pourcents. |
discountAmount | number | peut être null | Montant de la remise globale (hors TVA). |
retentionPercentage | number | peut être null | Retenue de garantie en pourcents. |
retentionAmount | number | peut être null | Montant de la retenue de garantie. |
paidAmount | number | peut être null | Total des paiements reçus. |
creditedAmount | number | peut être null | Total des notes de crédit sur cette facture, TVA comprise. |
payments | object[] | Paiements reçus. | |
payments[].date | string (date) | Date du paiement. | |
payments[].amount | number | peut être null | Montant payé. |
payments[].method | string | peut être null | Moyen de paiement. |
vatBreakdown | object[] | Montant de TVA par taux. | |
vatBreakdown[].rate | string | peut être null | Code du taux de TVA (ex. 21, 6, CO pour cocontractant). |
vatBreakdown[].percentage | number | peut être null | Pourcentage de TVA. |
vatBreakdown[].amount | number | peut être null | Montant de TVA à ce taux. |
lines | object | Lignes de la facture. | |
lines.totalCount | integer | Nombre total de lignes du document. | |
lines.isTruncated | boolean | Vrai si le document compte plus de lignes que celles renvoyées. | |
lines.items | object[] | Lignes dans l'ordre du document. | |
lines.items[].id | integer | Identifiant de la ligne (lineId ou parentLineId des outils de modification d'un devis). | |
lines.items[].number | string | peut être null | Numéro de la ligne tel qu'imprimé (ex. 1.2). |
lines.items[].type | string | supertitle, title, subtitle, item (article) ou other. | |
lines.items[].isOption | boolean | Vrai pour une ligne en option (variante), non comprise dans les totaux. | |
lines.items[].name | string | peut être null | Libellé de la ligne. |
lines.items[].description | string | peut être null | Description détaillée. |
lines.items[].quantity | number | peut être null | Quantité (articles). |
lines.items[].unit | string | peut être null | Unité (articles). |
lines.items[].unitPrice | number | peut être null | Prix unitaire hors TVA (articles). |
lines.items[].vatRate | number | peut être null | Taux de TVA en pourcents (articles). |
lines.items[].discountAmount | number | peut être null | Remise accordée sur la ligne (articles). |
lines.items[].amountExcludingVat | number | peut être null | Montant hors TVA, net de la remise de la ligne (articles). |
lines.items[].remark | string | peut être null | Remarque imprimée sous la ligne (devis). |
lines.items[].depositInvoiceId | integer | peut être null | Facture d'acompte déduite par cette ligne (à passer à get_invoice). |
estimateId | integer | peut être null | Identifiant du devis facturé (à passer à get_estimate ; absent sans accès aux devis). |
estimateReference | string | peut être null | Numéro du devis facturé. |
creditNotes | object[] | Notes de crédit sur cette facture (vide sans accès aux notes de crédit). | |
creditNotes[].id | integer | Identifiant du document lié. | |
creditNotes[].reference | string | peut être null | Numéro du document lié. |
creditNotes[].type | string | peut être null | Type de facture (acompte, finale, avancement…). |
creditNotes[].status | string | peut être null | Statut du document lié. |
creditNotes[].date | string (date) | peut être null | Date du document lié. |
creditNotes[].amountIncludingVat | number | peut être null | Total TVA comprise. |
type | string | peut être null | Type : acompte, finale, état d'avancement, intervention, proforma… |
dueDate | string (date) | peut être null | Date d'échéance. |
amountDue | number | peut être null | Montant à payer TVA comprise : le total, diminué de la retenue de garantie éventuelle. |
outstanding | number | peut être null | Solde restant dû : montant à payer moins paiements et notes de crédit (absent pour un brouillon, une facture annulée ou proforma). |
isOverdue | boolean | Vrai si la facture est ouverte, échue et pas soldée. | |
daysOverdue | integer | peut être null | Nombre de jours depuis l'échéance, pour une facture en retard. |
id | integer | Identifiant du document (à passer à l'outil de détail). | |
reference | string | peut être null | Numéro du document (vide pour un brouillon de facture ou de note de crédit). |
status | string | peut être null | Statut du document. |
date | string (date) | peut être null | Date du document. |
customer | string | peut être null | Client tel qu'imprimé sur le document. |
tiersId | integer | Identifiant du tiers client (à passer à get_tiers). | |
dossierId | integer | Identifiant du dossier (à passer à get_dossier). | |
dossierReference | string | peut être null | Référence du dossier. |
amountExcludingVat | number | peut être null | Total hors TVA, net de la remise globale. |
vatAmount | number | peut être null | Montant de TVA. |
amountIncludingVat | number | peut être null | Total TVA comprise. |
Annotations MCP
| Annotation | Valeur | Signification |
|---|---|---|
title | Créer une facture | Nom lisible affiché par le client MCP. |
readOnlyHint | non | L'outil ne modifie rien. |
destructiveHint | non | L'outil peut modifier ou supprimer des données existantes, ou déclencher une action irréversible. |
idempotentHint | non | Rappeler l'outil avec les mêmes arguments n'a pas d'effet supplémentaire. |
openWorldHint | non | L'outil lit des courriels ou le contenu d'un document, ou contacte un service extérieur. |
Définition JSON
Entrée exacte de tools/list
{
"name": "create_invoice",
"title": "Créer une facture",
"description": "Crée une facture en brouillon, sans numéro, comme l'écran du dossier : libre pour un dossier (kind free, à remplir avec add_invoice_lines), ou depuis un devis accepté : acompte (kind deposit, pourcentage d'acompte de la société), avancement (kind progress, percentage du montant signé ou amount hors TVA, dans la limite du reste à facturer) ou finale (kind final, montant signé moins ce qui est déjà facturé). Client et adresse sont ceux du tiers facturé. Avant l'appel, annoncer précisément la modification et attendre l'accord de l'utilisateur. Ne pas rappeler l'outil après un succès : chaque appel crée une facture. Rien n'est numéroté ni envoyé. Renvoie la facture créée.",
"inputSchema": {
"type": "object",
"properties": {
"kind": {
"description": "free (facture libre d'un dossier), deposit (acompte), progress (avancement) ou final (facture finale) d'un devis accepté.",
"type": "string"
},
"dossierId": {
"description": "Dossier d'une facture libre (champ id de search_dossiers).",
"type": [
"integer",
"null"
],
"default": null
},
"estimateId": {
"description": "Devis accepté, pour deposit, progress et final (champ id de search_estimates ; le devis principal, pas un avenant).",
"type": [
"integer",
"null"
],
"default": null
},
"percentage": {
"description": "Avancement : pourcentage du montant signé (devis et avenants acceptés) à facturer, 0,01 à 100.",
"type": [
"number",
"null"
],
"default": null
},
"amount": {
"description": "Avancement : montant hors TVA à facturer, à la place de percentage.",
"type": [
"number",
"null"
],
"default": null
}
},
"required": [
"kind"
]
},
"outputSchema": {
"type": "object",
"properties": {
"customerVatNumber": {
"description": "Numéro de TVA du client imprimé sur la facture.",
"type": [
"string",
"null"
]
},
"customerAddress": {
"description": "Adresse du client imprimée sur la facture.",
"type": [
"string",
"null"
]
},
"customerOrderNumber": {
"description": "Référence de commande (bon de commande) du client.",
"type": [
"string",
"null"
]
},
"dossierIndication": {
"description": "Intitulé court du dossier.",
"type": [
"string",
"null"
]
},
"structuredCommunication": {
"description": "Communication structurée du virement.",
"type": [
"string",
"null"
]
},
"paymentTerm": {
"description": "Condition de paiement.",
"type": [
"string",
"null"
]
},
"discountPercentage": {
"description": "Remise globale en pourcents.",
"type": [
"number",
"null"
]
},
"discountAmount": {
"description": "Montant de la remise globale (hors TVA).",
"type": [
"number",
"null"
]
},
"retentionPercentage": {
"description": "Retenue de garantie en pourcents.",
"type": [
"number",
"null"
]
},
"retentionAmount": {
"description": "Montant de la retenue de garantie.",
"type": [
"number",
"null"
]
},
"paidAmount": {
"description": "Total des paiements reçus.",
"type": [
"number",
"null"
]
},
"creditedAmount": {
"description": "Total des notes de crédit sur cette facture, TVA comprise.",
"type": [
"number",
"null"
]
},
"payments": {
"description": "Paiements reçus.",
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"description": "Date du paiement.",
"type": "string",
"format": "date"
},
"amount": {
"description": "Montant payé.",
"type": [
"number",
"null"
]
},
"method": {
"description": "Moyen de paiement.",
"type": [
"string",
"null"
]
}
},
"required": [
"date"
]
}
},
"vatBreakdown": {
"description": "Montant de TVA par taux.",
"type": "array",
"items": {
"type": "object",
"properties": {
"rate": {
"description": "Code du taux de TVA (ex. 21, 6, CO pour cocontractant).",
"type": [
"string",
"null"
]
},
"percentage": {
"description": "Pourcentage de TVA.",
"type": [
"number",
"null"
]
},
"amount": {
"description": "Montant de TVA à ce taux.",
"type": [
"number",
"null"
]
}
}
}
},
"lines": {
"description": "Lignes de la facture.",
"type": "object",
"properties": {
"totalCount": {
"description": "Nombre total de lignes du document.",
"type": "integer"
},
"isTruncated": {
"description": "Vrai si le document compte plus de lignes que celles renvoyées.",
"type": "boolean"
},
"items": {
"description": "Lignes dans l'ordre du document.",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"description": "Identifiant de la ligne (lineId ou parentLineId des outils de modification d'un devis).",
"type": "integer"
},
"number": {
"description": "Numéro de la ligne tel qu'imprimé (ex. 1.2).",
"type": [
"string",
"null"
]
},
"type": {
"description": "supertitle, title, subtitle, item (article) ou other.",
"type": "string"
},
"isOption": {
"description": "Vrai pour une ligne en option (variante), non comprise dans les totaux.",
"type": "boolean"
},
"name": {
"description": "Libellé de la ligne.",
"type": [
"string",
"null"
]
},
"description": {
"description": "Description détaillée.",
"type": [
"string",
"null"
]
},
"quantity": {
"description": "Quantité (articles).",
"type": [
"number",
"null"
]
},
"unit": {
"description": "Unité (articles).",
"type": [
"string",
"null"
]
},
"unitPrice": {
"description": "Prix unitaire hors TVA (articles).",
"type": [
"number",
"null"
]
},
"vatRate": {
"description": "Taux de TVA en pourcents (articles).",
"type": [
"number",
"null"
]
},
"discountAmount": {
"description": "Remise accordée sur la ligne (articles).",
"type": [
"number",
"null"
]
},
"amountExcludingVat": {
"description": "Montant hors TVA, net de la remise de la ligne (articles).",
"type": [
"number",
"null"
]
},
"remark": {
"description": "Remarque imprimée sous la ligne (devis).",
"type": [
"string",
"null"
]
},
"depositInvoiceId": {
"description": "Facture d'acompte déduite par cette ligne (à passer à get_invoice).",
"type": [
"integer",
"null"
]
}
},
"required": [
"type"
]
}
}
},
"required": [
"totalCount",
"isTruncated",
"items"
]
},
"estimateId": {
"description": "Identifiant du devis facturé (à passer à get_estimate ; absent sans accès aux devis).",
"type": [
"integer",
"null"
]
},
"estimateReference": {
"description": "Numéro du devis facturé.",
"type": [
"string",
"null"
]
},
"creditNotes": {
"description": "Notes de crédit sur cette facture (vide sans accès aux notes de crédit).",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"description": "Identifiant du document lié.",
"type": "integer"
},
"reference": {
"description": "Numéro du document lié.",
"type": [
"string",
"null"
]
},
"type": {
"description": "Type de facture (acompte, finale, avancement…).",
"type": [
"string",
"null"
]
},
"status": {
"description": "Statut du document lié.",
"type": [
"string",
"null"
]
},
"date": {
"description": "Date du document lié.",
"type": [
"string",
"null"
],
"format": "date"
},
"amountIncludingVat": {
"description": "Total TVA comprise.",
"type": [
"number",
"null"
]
}
},
"required": [
"id"
]
}
},
"type": {
"description": "Type : acompte, finale, état d'avancement, intervention, proforma…",
"type": [
"string",
"null"
]
},
"dueDate": {
"description": "Date d'échéance.",
"type": [
"string",
"null"
],
"format": "date"
},
"amountDue": {
"description": "Montant à payer TVA comprise : le total, diminué de la retenue de garantie éventuelle.",
"type": [
"number",
"null"
]
},
"outstanding": {
"description": "Solde restant dû : montant à payer moins paiements et notes de crédit (absent pour un brouillon, une facture annulée ou proforma).",
"type": [
"number",
"null"
]
},
"isOverdue": {
"description": "Vrai si la facture est ouverte, échue et pas soldée.",
"type": "boolean"
},
"daysOverdue": {
"description": "Nombre de jours depuis l'échéance, pour une facture en retard.",
"type": [
"integer",
"null"
]
},
"id": {
"description": "Identifiant du document (à passer à l'outil de détail).",
"type": "integer"
},
"reference": {
"description": "Numéro du document (vide pour un brouillon de facture ou de note de crédit).",
"type": [
"string",
"null"
]
},
"status": {
"description": "Statut du document.",
"type": [
"string",
"null"
]
},
"date": {
"description": "Date du document.",
"type": [
"string",
"null"
],
"format": "date"
},
"customer": {
"description": "Client tel qu'imprimé sur le document.",
"type": [
"string",
"null"
]
},
"tiersId": {
"description": "Identifiant du tiers client (à passer à get_tiers).",
"type": "integer"
},
"dossierId": {
"description": "Identifiant du dossier (à passer à get_dossier).",
"type": "integer"
},
"dossierReference": {
"description": "Référence du dossier.",
"type": [
"string",
"null"
]
},
"amountExcludingVat": {
"description": "Total hors TVA, net de la remise globale.",
"type": [
"number",
"null"
]
},
"vatAmount": {
"description": "Montant de TVA.",
"type": [
"number",
"null"
]
},
"amountIncludingVat": {
"description": "Total TVA comprise.",
"type": [
"number",
"null"
]
}
},
"required": [
"lines",
"id",
"tiersId",
"dossierId"
]
},
"annotations": {
"title": "Créer une facture",
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": false,
"readOnlyHint": false
}
}