Ajouter des lignes à un devis

Tool nameadd_estimate_lines
Write

Adds titles, subtitles, free lines and catalogue items or assemblies to an estimate; Oxygenius recalculates all amounts.

Description

Exact text sent to the model by tools/list (French, the language of the data):

Ajoute des lignes à un devis, dans l'ordre donné : titres, sous-titres, lignes libres à prix saisi, articles du catalogue et ouvrages (un ouvrage ajoute un sous-titre et ses articles). 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 devis, 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. Oxygenius recalcule les prix, les sous-totaux, la TVA et les totaux comme l'écran du devis ; un devis accepté, refusé ou annulé, ou en attente de signature électronique, ne change plus (proposer create_estimate_version). Rien n'est envoyé au client. Renvoie le devis à jour.

Required access

Parameters

NameTypePresenceDescription
estimateIdintegerrequiredDevis (champ id de search_estimates).
linesobject[]requiredLignes à ajouter, 50 au plus.
lines[].kindstringrequiredtitle (titre), subtitle (sous-titre), free (ligne libre à prix saisi), item (article du catalogue) ou job (ouvrage du catalogue, avec ses articles).
lines[].namestringoptionalLibellé : obligatoire pour title, subtitle et free ; celui du catalogue pour item et job.
lines[].descriptionstringoptionalDescription ; celle du catalogue par défaut pour item et job.
lines[].quantitynumberoptionalQuantité (1 par défaut) ; celle d'un ouvrage multiplie les quantités de ses articles.
lines[].unitPricenumberoptionalPrix unitaire hors TVA : celui d'une ligne libre, ou un prix imposé à un article à la place de celui du catalogue.
lines[].itemIdintegeroptionalArticle ou ouvrage du catalogue (champ id de search_items), pour item et job.
lines[].unitstringoptionalUnité, par son nom (ex. m², h, pièce) ; celle de l'article par défaut.
lines[].categorystringoptionalPour free : material (matériel), workforce (main-d'œuvre, quantité en heures) ou free (par défaut).
lines[].vatRatenumberoptionalTaux de TVA en pourcents (ex. 21, 6) ; celui du client par défaut.
lines[].parentLineIdintegeroptionalTitre ou sous-titre (champ id des lignes de get_estimate) sous lequel placer la ligne ; sinon en fin de devis, rattachée au titre qui précède.

Result

The result is returned as structured content (structuredContent) matching the output schema below, and as JSON text for clients that do not read structured content. An error comes back with isError: true and a French message that explains what to fix.

Result fields
NameTypePresenceDescription
addedLineIdsinteger[]Identifiant de chaque ligne ajoutée, dans l'ordre de la demande (le sous-titre pour un ouvrage).
estimateobjectLe devis à jour, montants recalculés.
estimate.customerVatNumberstringnullableNuméro de TVA du client imprimé sur le devis.
estimate.customerAddressstringnullableAdresse du client imprimée sur le devis.
estimate.dossierIndicationstringnullableIntitulé court du dossier.
estimate.discountPercentagenumbernullableRemise globale en pourcents.
estimate.discountAmountnumbernullableMontant de la remise globale (hors TVA).
estimate.remarkstringnullableRemarque imprimée sur le devis.
estimate.vatBreakdownobject[]Montant de TVA par taux.
estimate.vatBreakdown[].ratestringnullableCode du taux de TVA (ex. 21, 6, CO pour cocontractant).
estimate.vatBreakdown[].percentagenumbernullablePourcentage de TVA.
estimate.vatBreakdown[].amountnumbernullableMontant de TVA à ce taux.
estimate.linesobjectLignes du devis.
estimate.lines.totalCountintegerNombre total de lignes du document.
estimate.lines.isTruncatedbooleanVrai si le document compte plus de lignes que celles renvoyées.
estimate.lines.itemsobject[]Lignes dans l'ordre du document.
estimate.lines.items[].idintegerIdentifiant de la ligne (lineId ou parentLineId des outils de modification d'un devis).
estimate.lines.items[].numberstringnullableNuméro de la ligne tel qu'imprimé (ex. 1.2).
estimate.lines.items[].typestringsupertitle, title, subtitle, item (article) ou other.
estimate.lines.items[].isOptionbooleanVrai pour une ligne en option (variante), non comprise dans les totaux.
estimate.lines.items[].namestringnullableLibellé de la ligne.
estimate.lines.items[].descriptionstringnullableDescription détaillée.
estimate.lines.items[].quantitynumbernullableQuantité (articles).
estimate.lines.items[].unitstringnullableUnité (articles).
estimate.lines.items[].unitPricenumbernullablePrix unitaire hors TVA (articles).
estimate.lines.items[].vatRatenumbernullableTaux de TVA en pourcents (articles).
estimate.lines.items[].discountAmountnumbernullableRemise accordée sur la ligne (articles).
estimate.lines.items[].amountExcludingVatnumbernullableMontant hors TVA, net de la remise de la ligne (articles).
estimate.lines.items[].remarkstringnullableRemarque imprimée sous la ligne (devis).
estimate.lines.items[].depositInvoiceIdintegernullableFacture d'acompte déduite par cette ligne (à passer à get_invoice).
estimate.amendmentsobject[]Avenants de ce devis.
estimate.amendments[].idintegerIdentifiant du document lié.
estimate.amendments[].referencestringnullableNuméro du document lié.
estimate.amendments[].typestringnullableType de facture (acompte, finale, avancement…).
estimate.amendments[].statusstringnullableStatut du document lié.
estimate.amendments[].datestring (date)nullableDate du document lié.
estimate.amendments[].amountIncludingVatnumbernullableTotal TVA comprise.
estimate.invoicesobject[]Factures émises pour ce devis et ses avenants (vide sans accès aux factures).
Same structure as estimate.amendments[]
estimate.creditNotesobject[]Notes de crédit liées à ce devis (vide sans accès aux notes de crédit).
Same structure as estimate.amendments[]
estimate.billingBalanceobjectnullableAvancement de la facturation d'un devis accepté (absent sinon, ou sans accès aux factures).
estimate.billingBalance.acceptedAmountExcludingVatnumbernullableMontant accepté : devis principal et avenants acceptés, hors TVA.
estimate.billingBalance.invoicedAmountExcludingVatnumbernullableMontant déjà facturé (factures non annulées), hors TVA.
estimate.billingBalance.creditedAmountExcludingVatnumbernullableMontant des notes de crédit, hors TVA.
estimate.billingBalance.remainingAmountExcludingVatnumbernullableReste à facturer, hors TVA.
estimate.titlestringnullableIntitulé du devis.
estimate.typestringnullableType : devis ou contrat.
estimate.validUntilstring (date)nullableDate de fin de validité de l'offre.
estimate.isAmendmentbooleanVrai pour un avenant (travaux complémentaires d'un devis).
estimate.parentEstimateIdintegernullablePour un avenant : identifiant du devis principal.
estimate.idintegerIdentifiant du document (à passer à l'outil de détail).
estimate.referencestringnullableNuméro du document (vide pour un brouillon de facture ou de note de crédit).
estimate.statusstringnullableStatut du document.
estimate.datestring (date)nullableDate du document.
estimate.customerstringnullableClient tel qu'imprimé sur le document.
estimate.tiersIdintegerIdentifiant du tiers client (à passer à get_tiers).
estimate.dossierIdintegerIdentifiant du dossier (à passer à get_dossier).
estimate.dossierReferencestringnullableRéférence du dossier.
estimate.amountExcludingVatnumbernullableTotal hors TVA, net de la remise globale.
estimate.vatAmountnumbernullableMontant de TVA.
estimate.amountIncludingVatnumbernullableTotal TVA comprise.

MCP annotations

AnnotationValueMeaning
titleAjouter des lignes à un devisHuman-readable name shown by the MCP client.
readOnlyHintnoThe tool changes nothing.
destructiveHintnoThe tool may change or delete existing data, or trigger an irreversible action.
idempotentHintnoCalling it again with the same arguments has no further effect.
openWorldHintnoThe tool reads e-mails or document content, or reaches an external service.

JSON definition

Exact tools/list entry
{
  "name": "add_estimate_lines",
  "title": "Ajouter des lignes à un devis",
  "description": "Ajoute des lignes à un devis, dans l'ordre donné : titres, sous-titres, lignes libres à prix saisi, articles du catalogue et ouvrages (un ouvrage ajoute un sous-titre et ses articles). 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 devis, 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. Oxygenius recalcule les prix, les sous-totaux, la TVA et les totaux comme l'écran du devis ; un devis accepté, refusé ou annulé, ou en attente de signature électronique, ne change plus (proposer create_estimate_version). Rien n'est envoyé au client. Renvoie le devis à jour.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "estimateId": {
        "description": "Devis (champ id de search_estimates).",
        "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), 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"
              ]
            },
            "category": {
              "description": "Pour free : material (matériel), workforce (main-d'œuvre, quantité en heures) ou free (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 de get_estimate) sous lequel placer la ligne ; sinon en fin de devis, rattachée au titre qui précède.",
              "type": [
                "integer",
                "null"
              ]
            }
          },
          "required": [
            "kind"
          ]
        }
      }
    },
    "required": [
      "estimateId",
      "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"
        }
      },
      "estimate": {
        "description": "Le devis à jour, montants recalculés.",
        "type": "object",
        "properties": {
          "customerVatNumber": {
            "description": "Numéro de TVA du client imprimé sur le devis.",
            "type": [
              "string",
              "null"
            ]
          },
          "customerAddress": {
            "description": "Adresse du client imprimée sur le devis.",
            "type": [
              "string",
              "null"
            ]
          },
          "dossierIndication": {
            "description": "Intitulé court du dossier.",
            "type": [
              "string",
              "null"
            ]
          },
          "discountPercentage": {
            "description": "Remise globale en pourcents.",
            "type": [
              "number",
              "null"
            ]
          },
          "discountAmount": {
            "description": "Montant de la remise globale (hors TVA).",
            "type": [
              "number",
              "null"
            ]
          },
          "remark": {
            "description": "Remarque imprimée sur le devis.",
            "type": [
              "string",
              "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 du devis.",
            "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"
            ]
          },
          "amendments": {
            "description": "Avenants de ce devis.",
            "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"
              ]
            }
          },
          "invoices": {
            "description": "Factures émises pour ce devis et ses avenants (vide sans accès aux factures).",
            "type": "array",
            "items": {
              "$ref": "#/properties/estimate/properties/amendments/items"
            }
          },
          "creditNotes": {
            "description": "Notes de crédit liées à ce devis (vide sans accès aux notes de crédit).",
            "type": "array",
            "items": {
              "$ref": "#/properties/estimate/properties/amendments/items"
            }
          },
          "billingBalance": {
            "description": "Avancement de la facturation d'un devis accepté (absent sinon, ou sans accès aux factures).",
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "acceptedAmountExcludingVat": {
                "description": "Montant accepté : devis principal et avenants acceptés, hors TVA.",
                "type": [
                  "number",
                  "null"
                ]
              },
              "invoicedAmountExcludingVat": {
                "description": "Montant déjà facturé (factures non annulées), hors TVA.",
                "type": [
                  "number",
                  "null"
                ]
              },
              "creditedAmountExcludingVat": {
                "description": "Montant des notes de crédit, hors TVA.",
                "type": [
                  "number",
                  "null"
                ]
              },
              "remainingAmountExcludingVat": {
                "description": "Reste à facturer, hors TVA.",
                "type": [
                  "number",
                  "null"
                ]
              }
            }
          },
          "title": {
            "description": "Intitulé du devis.",
            "type": [
              "string",
              "null"
            ]
          },
          "type": {
            "description": "Type : devis ou contrat.",
            "type": [
              "string",
              "null"
            ]
          },
          "validUntil": {
            "description": "Date de fin de validité de l'offre.",
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "isAmendment": {
            "description": "Vrai pour un avenant (travaux complémentaires d'un devis).",
            "type": "boolean"
          },
          "parentEstimateId": {
            "description": "Pour un avenant : identifiant du devis principal.",
            "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"
        ]
      }
    },
    "required": [
      "addedLineIds",
      "estimate"
    ]
  },
  "annotations": {
    "title": "Ajouter des lignes à un devis",
    "destructiveHint": false,
    "idempotentHint": false,
    "openWorldHint": false,
    "readOnlyHint": false
  }
}