Aller au contenu
Envoyer des données/Envoyer des contrats

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èreValeur
AdressePOST /api/v1/contracts/proposals
Par son nomPOST /api/v1/tools/propose_contracts, la réponse sous data
Nom de l'outilpropose_contracts
Droits demandésSaisir un contrat (commitment.create) ; Lire le détail par canal, fournisseur et contrat (spendDetail.read)
Rôles qui ont ces droits par défautPropriétaire, CMO, Marketing Ops, DAF
Par MCPOui : l'envoi attend une personne.

Paramètres

Les paramètres sont dans le corps de la requête, en JSON.

ParamètreRequisType et limitesÀ quoi il sert
entityIdouitexte, non videL'entité. list_entities donne les identifiants.
contractsouiliste d'objets, 1 à 200 élémentsLes contrats à déposer.
contracts[].supplierNameouitexte, 1 à 120 caractèresLe fournisseur.
contracts[].labelouitexte, 1 à 120 caractèresL'objet du contrat.
contracts[].typeouivaleur au choix, scheduled, cappedscheduled pour un contrat échelonné, capped pour un plafond.
contracts[].channelouitexte, 1 à 120 caractèresLe canal : une clé du catalogue ou son nom.
contracts[].subChannelKeynontexte, 120 caractères au plusLe sous-canal, parmi ceux du canal. Facultatif.
contracts[].currencynontexte, 3 caractèresLa devise du contrat, en trois lettres, quand ce n'est pas l'euro.
contracts[].committedCentsouinombre entier, supérieur à 0Le montant du contrat hors taxes, en centimes : dans sa devise quand currency est donnée, en euros sinon.
contracts[].startDateouidate, AAAA-MM-JJLe début du contrat.
contracts[].endDatenondate, AAAA-MM-JJSa fin. Facultative.
contracts[].noticeDaysnonnombre entier, de 0 à 730Le préavis, en jours.
contracts[].tacitRenewalnonvrai ou fauxVrai si le contrat se renouvelle par tacite reconduction.
contracts[].signedDatenondate, AAAA-MM-JJLa date de signature. Elle sert au délai de saisie de la charte.
contracts[].schedulenonobjetL'échéancier d'un contrat scheduled.
contracts[].schedule.kindouivaleur au choix, equal, custom, deliveryLa forme de l'échéancier.
contracts[].schedule.dueDatesouiliste de dates, 1 à 120 éléments, chaque élément : AAAA-MM-JJ, quand kind vaut equalLes dates des échéances.
contracts[].schedule.installmentsouiliste d'objets, 1 à 120 éléments, quand kind vaut customLes échéances, une à une.
contracts[].schedule.installments[].dueDateouidate, AAAA-MM-JJLa date de l'échéance.
contracts[].schedule.installments[].amountCentsouinombre entierSon montant, en centimes.
contracts[].schedule.deliveryDateouidate, AAAA-MM-JJ, quand kind vaut deliveryLa 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.json

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