Envoyer des contrats
Dépose des contrats signés avec des fournisseurs, pour une entité : chacun devient un brouillon sur la page des contrats.
Un brouillon ne compte dans aucun chiffre. Une personne le confirme à l'écran, et les seuils de la charte s'appliquent à ce moment-là.
Un contrat est scheduled (échelonné, avec son échéancier) ou capped (un plafond, sans échéancier). L'échéancier est equal (des dates, le montant réparti à parts égales), custom (la date et le montant de chaque échéance, dont la somme fait le contrat) ou delivery (une seule date).
Tous les contrats d'un envoi sont déposés, ou aucun : un contrat refusé donne son rang. Un contrat qui attend déjà en brouillon venu de l'API (même fournisseur, même libellé, même date de début, même montant) n'est pas déposé une seconde fois.
Appel
| Repère | Valeur |
|---|---|
| Adresse | POST /api/v1/contracts/proposals |
| Par son nom | POST /api/v1/tools/propose_contracts, la réponse sous data |
| Nom de l'outil | propose_contracts |
| Droits demandés | Saisir un contrat (commitment.create) ; Lire le détail par canal, fournisseur et contrat (spendDetail.read) |
| Rôles qui ont ces droits par défaut | Propriétaire, CMO, Marketing Ops, DAF |
| Par MCP | Oui : l'envoi attend une personne. |
Paramètres
Les paramètres sont dans le corps de la requête, en JSON.
| Paramètre | Requis | Type et limites | À quoi il sert |
|---|---|---|---|
entityId | oui | texte, non vide | L'entité. list_entities donne les identifiants. |
contracts | oui | liste d'objets, 1 à 200 éléments | Les contrats à déposer. |
contracts[].supplierName | oui | texte, 1 à 120 caractères | Le fournisseur. |
contracts[].label | oui | texte, 1 à 120 caractères | L'objet du contrat. |
contracts[].type | oui | valeur au choix, scheduled, capped | scheduled pour un contrat échelonné, capped pour un plafond. |
contracts[].channel | oui | texte, 1 à 120 caractères | Le canal : une clé du catalogue ou son nom. |
contracts[].subChannelKey | non | texte, 120 caractères au plus | Le sous-canal, parmi ceux du canal. Facultatif. |
contracts[].currency | non | texte, 3 caractères | La devise du contrat, en trois lettres, quand ce n'est pas l'euro. |
contracts[].committedCents | oui | nombre entier, supérieur à 0 | Le montant du contrat hors taxes, en centimes : dans sa devise quand currency est donnée, en euros sinon. |
contracts[].startDate | oui | date, AAAA-MM-JJ | Le début du contrat. |
contracts[].endDate | non | date, AAAA-MM-JJ | Sa fin. Facultative. |
contracts[].noticeDays | non | nombre entier, de 0 à 730 | Le préavis, en jours. |
contracts[].tacitRenewal | non | vrai ou faux | Vrai si le contrat se renouvelle par tacite reconduction. |
contracts[].signedDate | non | date, AAAA-MM-JJ | La date de signature. Elle sert au délai de saisie de la charte. |
contracts[].schedule | non | objet | L'échéancier d'un contrat scheduled. |
contracts[].schedule.kind | oui | valeur au choix, equal, custom, delivery | La forme de l'échéancier. |
contracts[].schedule.dueDates | oui | liste de dates, 1 à 120 éléments, chaque élément : AAAA-MM-JJ, quand kind vaut equal | Les dates des échéances. |
contracts[].schedule.installments | oui | liste d'objets, 1 à 120 éléments, quand kind vaut custom | Les échéances, une à une. |
contracts[].schedule.installments[].dueDate | oui | date, AAAA-MM-JJ | La date de l'échéance. |
contracts[].schedule.installments[].amountCents | oui | nombre entier | Son montant, en centimes. |
contracts[].schedule.deliveryDate | oui | date, AAAA-MM-JJ, quand kind vaut delivery | La date de livraison. |
Exemple
curl -X POST "$MARVESTO_URL/api/v1/contracts/proposals" \
-H "x-api-key: $MARVESTO_API_KEY" \
-H "content-type: application/json" \
-d @corps.jsonLe fichier corps.json :
{
"entityId": "ENTITY_ID",
"contracts": [
{
"supplierName": "Agence Lumière",
"label": "Accompagnement SEO 2027",
"type": "scheduled",
"channel": "content",
"committedCents": 4800000,
"startDate": "2027-01-01",
"endDate": "2027-12-31",
"noticeDays": 90,
"schedule": {
"kind": "equal",
"dueDates": ["2027-01-15", "2027-04-15", "2027-07-15", "2027-10-15"]
}
}
]
}Réponse
created : les brouillons créés, avec leur identifiant. alreadyFiled : le nombre de contrats qui attendaient déjà.
{
"created": [
{
"commitmentId": "COMMITMENT_ID",
"supplierName": "Agence Lumière",
"label": "Accompagnement SEO 2027"
}
],
"alreadyFiled": 0
}Refus
Un refus répond { "message": "…" }, en français, avec son statut HTTP : voir Droits et erreurs.