Ajouter des lignes à une note de crédit
add_credit_note_linesDescription
Ajoute des lignes à une note de crédit en brouillon, dans l'ordre donné : titres, sous-titres, lignes libres à prix saisi, articles et ouvrages du catalogue. Prix, marges, unités et TVA des articles viennent du catalogue (search_items) et du client, sauf valeur fournie. Une ligne sans parentLineId se place en fin de document, sous le titre qui précède. 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 ajoute de nouvelles lignes. Seul un brouillon (sans numéro, à éditer) change : le numéro d'une facture est légal et définitif. Oxygenius recalcule les prix, les sous-totaux, la TVA et les totaux comme l'écran du document. Rien n'est envoyé au client.
Accès requis
- Permission :
credit-note.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 |
|---|---|---|---|
creditNoteId | integer | obligatoire | Note de crédit (champ id de search_credit_notes). |
lines | object[] | obligatoire | Lignes à ajouter, 50 au plus. |
lines[].kind | string | obligatoire | title (titre), subtitle (sous-titre), free (ligne libre à prix saisi), item (article du catalogue) ou job (ouvrage du catalogue, avec ses articles). |
lines[].name | string | facultatif | Libellé : obligatoire pour title, subtitle et free ; celui du catalogue pour item et job. |
lines[].description | string | facultatif | Description ; celle du catalogue par défaut pour item et job. |
lines[].quantity | number | facultatif | Quantité (1 par défaut) ; celle d'un ouvrage multiplie les quantités de ses articles. |
lines[].unitPrice | number | facultatif | Prix unitaire hors TVA : celui d'une ligne libre, ou un prix imposé à un article à la place de celui du catalogue. |
lines[].itemId | integer | facultatif | Article ou ouvrage du catalogue (champ id de search_items : kind job pour un ouvrage, item pour les autres), pour item et job. |
lines[].unit | string | facultatif | Unité, par son nom (ex. m², h, pièce) ; celle de l'article par défaut. |
lines[].vatRate | number | facultatif | Taux de TVA en pourcents (ex. 21, 6) ; celui du client par défaut. |
lines[].parentLineId | integer | facultatif | Titre ou sous-titre (champ id des lignes du document) sous lequel placer la ligne ; sinon en fin de document, rattachée au titre qui précède. |
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 |
|---|---|---|---|
addedLineIds | integer[] | Identifiant de chaque ligne ajoutée, dans l'ordre de la demande (le sous-titre pour un ouvrage). | |
creditNote | object | La note de crédit à jour, montants recalculés. | |
creditNote.customerVatNumber | string | peut être null | Numéro de TVA du client imprimé sur la note de crédit. |
creditNote.customerAddress | string | peut être null | Adresse du client imprimée sur la note de crédit. |
creditNote.dossierIndication | string | peut être null | Intitulé court du dossier. |
creditNote.structuredCommunication | string | peut être null | Communication structurée. |
creditNote.discountPercentage | number | peut être null | Remise globale en pourcents. |
creditNote.discountAmount | number | peut être null | Montant de la remise globale (hors TVA). |
creditNote.vatBreakdown | object[] | Montant de TVA par taux. | |
creditNote.vatBreakdown[].rate | string | peut être null | Code du taux de TVA (ex. 21, 6, CO pour cocontractant). |
creditNote.vatBreakdown[].percentage | number | peut être null | Pourcentage de TVA. |
creditNote.vatBreakdown[].amount | number | peut être null | Montant de TVA à ce taux. |
creditNote.lines | object | Lignes de la note de crédit. | |
creditNote.lines.totalCount | integer | Nombre total de lignes du document. | |
creditNote.lines.isTruncated | boolean | Vrai si le document compte plus de lignes que celles renvoyées. | |
creditNote.lines.items | object[] | Lignes dans l'ordre du document. | |
creditNote.lines.items[].id | integer | Identifiant de la ligne (lineId ou parentLineId des outils de modification d'un devis). | |
creditNote.lines.items[].number | string | peut être null | Numéro de la ligne tel qu'imprimé (ex. 1.2). |
creditNote.lines.items[].type | string | supertitle, title, subtitle, item (article) ou other. | |
creditNote.lines.items[].isOption | boolean | Vrai pour une ligne en option (variante), non comprise dans les totaux. | |
creditNote.lines.items[].name | string | peut être null | Libellé de la ligne. |
creditNote.lines.items[].description | string | peut être null | Description détaillée. |
creditNote.lines.items[].quantity | number | peut être null | Quantité (articles). |
creditNote.lines.items[].unit | string | peut être null | Unité (articles). |
creditNote.lines.items[].unitPrice | number | peut être null | Prix unitaire hors TVA (articles). |
creditNote.lines.items[].vatRate | number | peut être null | Taux de TVA en pourcents (articles). |
creditNote.lines.items[].discountAmount | number | peut être null | Remise accordée sur la ligne (articles). |
creditNote.lines.items[].amountExcludingVat | number | peut être null | Montant hors TVA, net de la remise de la ligne (articles). |
creditNote.lines.items[].remark | string | peut être null | Remarque imprimée sous la ligne (devis). |
creditNote.lines.items[].depositInvoiceId | integer | peut être null | Facture d'acompte déduite par cette ligne (à passer à get_invoice). |
creditNote.invoiceId | integer | peut être null | Identifiant de la facture créditée (à passer à get_invoice), si la note en crédite une. |
creditNote.invoiceReference | string | peut être null | Numéro de la facture créditée. |
creditNote.id | integer | Identifiant du document (à passer à l'outil de détail). | |
creditNote.reference | string | peut être null | Numéro du document (vide pour un brouillon de facture ou de note de crédit). |
creditNote.status | string | peut être null | Statut du document. |
creditNote.date | string (date) | peut être null | Date du document. |
creditNote.customer | string | peut être null | Client tel qu'imprimé sur le document. |
creditNote.tiersId | integer | Identifiant du tiers client (à passer à get_tiers). | |
creditNote.dossierId | integer | Identifiant du dossier (à passer à get_dossier). | |
creditNote.dossierReference | string | peut être null | Référence du dossier. |
creditNote.amountExcludingVat | number | peut être null | Total hors TVA, net de la remise globale. |
creditNote.vatAmount | number | peut être null | Montant de TVA. |
creditNote.amountIncludingVat | number | peut être null | Total TVA comprise. |
Annotations MCP
| Annotation | Valeur | Signification |
|---|---|---|
title | Ajouter des lignes à une note de crédit | 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": "add_credit_note_lines",
"title": "Ajouter des lignes à une note de crédit",
"description": "Ajoute des lignes à une note de crédit en brouillon, dans l'ordre donné : titres, sous-titres, lignes libres à prix saisi, articles et ouvrages du catalogue. Prix, marges, unités et TVA des articles viennent du catalogue (search_items) et du client, sauf valeur fournie. Une ligne sans parentLineId se place en fin de document, sous le titre qui précède. 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 ajoute de nouvelles lignes. Seul un brouillon (sans numéro, à éditer) change : le numéro d'une facture est légal et définitif. Oxygenius recalcule les prix, les sous-totaux, la TVA et les totaux comme l'écran du document. Rien n'est envoyé au client.",
"inputSchema": {
"type": "object",
"properties": {
"creditNoteId": {
"description": "Note de crédit (champ id de search_credit_notes).",
"type": "integer"
},
"lines": {
"description": "Lignes à ajouter, 50 au plus.",
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"description": "title (titre), subtitle (sous-titre), free (ligne libre à prix saisi), item (article du catalogue) ou job (ouvrage du catalogue, avec ses articles).",
"type": "string"
},
"name": {
"description": "Libellé : obligatoire pour title, subtitle et free ; celui du catalogue pour item et job.",
"type": [
"string",
"null"
]
},
"description": {
"description": "Description ; celle du catalogue par défaut pour item et job.",
"type": [
"string",
"null"
]
},
"quantity": {
"description": "Quantité (1 par défaut) ; celle d'un ouvrage multiplie les quantités de ses articles.",
"type": [
"number",
"null"
]
},
"unitPrice": {
"description": "Prix unitaire hors TVA : celui d'une ligne libre, ou un prix imposé à un article à la place de celui du catalogue.",
"type": [
"number",
"null"
]
},
"itemId": {
"description": "Article ou ouvrage du catalogue (champ id de search_items : kind job pour un ouvrage, item pour les autres), pour item et job.",
"type": [
"integer",
"null"
]
},
"unit": {
"description": "Unité, par son nom (ex. m², h, pièce) ; celle de l'article par défaut.",
"type": [
"string",
"null"
]
},
"vatRate": {
"description": "Taux de TVA en pourcents (ex. 21, 6) ; celui du client par défaut.",
"type": [
"number",
"null"
]
},
"parentLineId": {
"description": "Titre ou sous-titre (champ id des lignes du document) sous lequel placer la ligne ; sinon en fin de document, rattachée au titre qui précède.",
"type": [
"integer",
"null"
]
}
},
"required": [
"kind"
]
}
}
},
"required": [
"creditNoteId",
"lines"
]
},
"outputSchema": {
"type": "object",
"properties": {
"addedLineIds": {
"description": "Identifiant de chaque ligne ajoutée, dans l'ordre de la demande (le sous-titre pour un ouvrage).",
"type": "array",
"items": {
"type": "integer"
}
},
"creditNote": {
"description": "La note de crédit à jour, montants recalculés.",
"type": "object",
"properties": {
"customerVatNumber": {
"description": "Numéro de TVA du client imprimé sur la note de crédit.",
"type": [
"string",
"null"
]
},
"customerAddress": {
"description": "Adresse du client imprimée sur la note de crédit.",
"type": [
"string",
"null"
]
},
"dossierIndication": {
"description": "Intitulé court du dossier.",
"type": [
"string",
"null"
]
},
"structuredCommunication": {
"description": "Communication structurée.",
"type": [
"string",
"null"
]
},
"discountPercentage": {
"description": "Remise globale en pourcents.",
"type": [
"number",
"null"
]
},
"discountAmount": {
"description": "Montant de la remise globale (hors TVA).",
"type": [
"number",
"null"
]
},
"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 note de crédit.",
"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"
]
},
"invoiceId": {
"description": "Identifiant de la facture créditée (à passer à get_invoice), si la note en crédite une.",
"type": [
"integer",
"null"
]
},
"invoiceReference": {
"description": "Numéro de la facture créditée.",
"type": [
"string",
"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"
]
}
},
"required": [
"addedLineIds",
"creditNote"
]
},
"annotations": {
"title": "Ajouter des lignes à une note de crédit",
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": false,
"readOnlyHint": false
}
}