Aller au contenu
Démarrer

Démarrer

Créer une clé, faire un premier appel, lire ce que l'API répond.

Ce que fait l'API

  • Lire les chiffres que vos écrans affichent : pilotage, funnel, pipeline, rendement par canal, vue CEO. Avec les droits du membre de la clé, et rien de plus.
  • Envoyer des deals, des contacts, des factures, de la dépense, des contrats, l'objectif de l'exercice. Ce qui est envoyé attend une personne : rien n'est compté avant sa validation à l'écran.

Aucune intégration n'est obligatoire. Chaque donnée se saisit aussi à la main, ou s'importe par fichier.

Créer une clé

  1. Ouvrez les réglages de l'organisation, puis « Clés API ».
  2. Cliquez « Créer une clé » et nommez-la.
  3. Copiez la clé : elle n'est affichée qu'une fois.

Le propriétaire et Marketing Ops créent des clés. Une clé agit avec les droits de la personne qui l'a créée, jamais plus. Elle cesse de fonctionner si cette personne quitte l'organisation.

Premier appel

L'API est à l'adresse de votre espace, sous /api/v1. Dans les exemples, MARVESTO_URL est cette adresse (celle de votre navigateur, sans le chemin) et MARVESTO_API_KEY votre clé.

export MARVESTO_URL="https://…"
export MARVESTO_API_KEY="nsk_…"

curl "$MARVESTO_URL/api/v1/organization" \
  -H "x-api-key: $MARVESTO_API_KEY"
{
  "organization": {
    "id": "ORGANIZATION_ID",
    "name": "Lumen Analytics",
    "slug": "lumen-analytics"
  }
}

La clé passe dans l'en-tête x-api-key, ou dans Authorization: Bearer.

Deux façons d'appeler

Chaque appel a un nom : get_pipeline, propose_deals… Vous l'appelez par son adresse, ou par son nom.

FaçonAppelRéponse
Par son adresseGET /api/v1/pipeline, les paramètres après ?Le résultat, tel quel.
Par son nomPOST /api/v1/tools/get_pipeline, les paramètres dans le corps, en JSONLe résultat, sous data.

Quelques lectures n'ont que leur nom. Chaque page de la référence donne l'adresse à utiliser et un exemple.

Découvrir les appels

GET /api/v1/tools liste les appels que votre clé peut faire, chacun avec le schéma JSON de ses paramètres. GET /api/v1/tools/<nom> en donne un seul.

La liste dépend des droits du membre de la clé : un appel que vous ne voyez pas est un appel que ce membre ne peut pas faire. Les descriptions y sont en anglais, parce qu'elles servent aussi aux applications connectées par MCP.

Lire une valeur

Un chiffre n'arrive jamais seul. Il arrive avec ce qu'il vaut comme preuve :

{
  "value": 18450000,
  "status": "provisional",
  "kind": "amount",
  "evidence": "observed"
}
  • value : le chiffre. null quand il n'est pas disponible, jamais 0.
  • status : signed (validé par le DAF), reconciled (rapproché), provisional (provisoire), estimate (estimation) ou not_computable (non calculable).
  • kind : ce que le chiffre est (un montant, un taux, un ratio sur une période…).
  • evidence : ce sur quoi il repose, quand l'écran le dit.
  • sample : le nombre d'observations, pour un taux. low et high : sa fourchette, pour une prévision.

Trois règles valent partout :

  • Les montants sont en centimes, en nombres entiers, hors taxes. 18450000 vaut 184 500 €.
  • Les dates s'écrivent AAAA-MM-JJ, les mois AAAA-MM.
  • Les lectures « à date » s'arrêtent au dernier mois arrêté par le CMO. Le mois en cours n'est jamais un chiffre final.

Ce qu'un écran masque à un membre, l'API le masque à sa clé, et dit pourquoi.

Limites

LimiteValeur
Requêtes1 000 par heure et par clé
Corps d'une requête4 Mo
Tableau envoyé5 000 lignes (20 000 pour les contacts), 120 colonnes

Les autres listes ont leur propre limite, dite sur la page de chaque appel.