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é
- Ouvrez les réglages de l'organisation, puis « Clés API ».
- Cliquez « Créer une clé » et nommez-la.
- 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çon | Appel | Réponse |
|---|---|---|
| Par son adresse | GET /api/v1/pipeline, les paramètres après ? | Le résultat, tel quel. |
| Par son nom | POST /api/v1/tools/get_pipeline, les paramètres dans le corps, en JSON | Le 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.nullquand il n'est pas disponible, jamais 0.status:signed(validé par le DAF),reconciled(rapproché),provisional(provisoire),estimate(estimation) ounot_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.lowethigh: sa fourchette, pour une prévision.
Trois règles valent partout :
- Les montants sont en centimes, en nombres entiers, hors taxes.
18450000vaut 184 500 €. - Les dates s'écrivent
AAAA-MM-JJ, les moisAAAA-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
| Limite | Valeur |
|---|---|
| Requêtes | 1 000 par heure et par clé |
| Corps d'une requête | 4 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.