Le serveur MCP attire l'attention, mais il repose sur une simple API REST, et tout ce que l'assistant peut faire, un script peut le faire aussi. Cet article parcourt les points d'accès dans l'ordre où vous en aurez probablement besoin, avec une commande curl pour chacun. Si vous préférez passer par Claude, commencez plutôt par l'article de lancement.
URL de base et authentification
Base URL: https://provedly.app/api/v1
Header: Authorization: Bearer provedly_…
La clé est une clé d'API de compte, créée dans Settings, sous API keys. Elle commence par provedly_, n'est affichée qu'une fois et peut être révoquée à tout moment. Choisissez Read only pour les scripts qui se contentent de rapporter, et Read and write pour tout ce qui modifie un état. La différence est expliquée dans choisir une clé d'API.
Pour les exemples, placez la clé dans une variable d'environnement pour qu'elle n'apparaisse pas dans l'historique de votre shell :
export PROVEDLY_KEY="provedly_your_key_here"
Les clés ont leur place sur des serveurs et dans votre propre terminal. N'en livrez jamais une dans du JavaScript côté navigateur.
Lire votre compte
Commencez par le point d'accès du compte. Il renvoie votre plan, ses limites et la consommation actuelle, ce qui donne le contexte de tout le reste.
curl https://provedly.app/api/v1/account \
-H "Authorization: Bearer $PROVEDLY_KEY"
Puis les éléments du compte :
curl https://provedly.app/api/v1/sites -H "Authorization: Bearer $PROVEDLY_KEY"
curl https://provedly.app/api/v1/widgets -H "Authorization: Bearer $PROVEDLY_KEY"
curl https://provedly.app/api/v1/bars -H "Authorization: Bearer $PROVEDLY_KEY"
Les éléments individuels se trouvent sous /widgets/{id} et /bars/{id}. Les widgets, barres et sites peuvent être désignés par leur identifiant, qui est un UUID, ou par leur token, selon ce que vous avez sous la main. Un script qui détient déjà un token de widget issu de votre snippet d'installation n'a pas besoin de chercher d'abord l'UUID.
Statistiques
curl "https://provedly.app/api/v1/stats?days=30" \
-H "Authorization: Bearer $PROVEDLY_KEY"
La réponse couvre les impressions, les clics, les commandes vérifiées et les commandes assistées par la preuve avec leur chiffre d'affaires, sur le nombre de jours demandé. « Assistée par la preuve » signifie que l'acheteur a vu une notification avant d'acheter, rapprochée par visiteur sur une fenêtre de 30 jours : c'est la même définition que dans le tableau de bord, expliquée dans mesurer les commandes assistées par la preuve. Passez days à 7 pour un rapport hebdomadaire.
Modifier les widgets et les barres
Tout ce qui suit dans cette section nécessite une clé en lecture et écriture. Mettre en pause ou réactiver un widget se fait avec un PATCH :
curl -X PATCH https://provedly.app/api/v1/widgets/WIDGET_ID \
-H "Authorization: Bearer $PROVEDLY_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "paused"}'
Envoyez "active" pour réactiver. C'est à la réactivation que les limites du plan apparaissent : si le plan autorise un nombre fixe de widgets actifs et que vous l'avez atteint, la requête est refusée avec une raison au lieu de dépasser discrètement. Une clé en lecture seule est refusée sur toute écriture, quel que soit le contenu.
Créer une barre se fait avec un POST sur /bars. Gardez le contenu dans un fichier pour pouvoir le relire facilement :
curl -X POST https://provedly.app/api/v1/bars \
-H "Authorization: Bearer $PROVEDLY_KEY" \
-H "Content-Type: application/json" \
-d @winter-launch.json
Une nouvelle barre créée via l'API démarre en pause. C'est voulu : personne ne la voit tant que vous ne l'avez pas vérifiée, et une faute de frappe dans un script ne peut pas mettre une barre à moitié rédigée devant les visiteurs. La mise en ligne est un second appel :
curl -X PATCH https://provedly.app/api/v1/bars/BAR_ID \
-H "Authorization: Bearer $PROVEDLY_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "active"}'
L'activation respecte la limite de barres de votre plan, de la même manière que la réactivation des widgets.
Le même point d'accès PATCH modifie le nom, le message et la date de fin d'une barre, et la met en pause ou la réactive. Pour les dates de fin, ends_at accepte soit une heure locale comme "2026-12-01 09:00", lue dans le fuseau horaire de la barre, soit un horodatage ISO 8601 complet :
curl -X PATCH https://provedly.app/api/v1/bars/BAR_ID \
-H "Authorization: Bearer $PROVEDLY_KEY" \
-H "Content-Type: application/json" \
-d '{"ends_at": "2026-12-01 09:00"}'
La forme locale est généralement celle qu'il vous faut pour un lancement, car « 9 h » signifie 9 h là où la barre est réglée, pas là où se trouve votre serveur. Plus de détails sur les dates dans programmer des comptes à rebours de lancement.
Ajouter des enregistrements
L'API Records, POST /widgets/{token}/records, garde la même forme et accepte désormais aussi une clé de compte : une seule clé peut alimenter tous les widgets du compte au lieu d'une clé de widget distincte pour chacun. Les champs et les règles d'idempotence se trouvent dans la référence de l'API Records, et la version avec clé de compte est détaillée dans envoyer des enregistrements avec une clé de compte.
Les enregistrements créés ainsi conservent la source API et s'affichent dans le widget avec une étiquette visible « Imported », sans la marque Vérifié. L'API n'a aucun champ qui marque un enregistrement comme vérifié, et aucun niveau de clé ne l'ajoute. Seuls les webhooks signés de Stripe, Shopify et WooCommerce produisent des enregistrements vérifiés.
Comprendre les refus
La plupart des échecs se rangent dans quelques catégories :
| Situation | Ce que vous obtenez |
|---|---|
| Clé absente, erronée ou révoquée | Une erreur d'authentification |
| Clé en lecture seule sur un point d'accès d'écriture | Un refus indiquant que la clé est en lecture seule |
| Modification qui dépasserait une limite du plan | Un refus qui nomme la limite |
| Champ invalide, comme une date incorrecte | Une erreur de validation pour ce champ |
Les scripts doivent traiter les refus liés aux limites du plan comme une information destinée à une personne, pas comme quelque chose à retenter.
Questions fréquentes
L'API est-elle la même que celle utilisée par le serveur MCP ?
Les outils MCP couvrent les mêmes actions avec les mêmes règles : mêmes clés, mêmes limites de plan, même refus de vérifier des enregistrements. Utilisez celui qui convient à la tâche.
Puis-je créer une barre qui passe en ligne immédiatement ?
Pas en un seul appel. Les barres créées via l'API démarrent en pause, et vous les activez avec une seconde requête. C'est une ligne de plus dans un script, et cela évite les mauvaises surprises.
Quels plans incluent l'API ?
Tous, y compris Free. Les limites de widgets, de barres et d'impressions du plan s'appliquent comme d'habitude.
Consultez ce que permet chaque plan sur la page des tarifs.