Jusqu'ici, un backend qui envoyait des achats à Provedly utilisait une clé par widget, générée dans l'onglet Data de ce widget. Cela fonctionne pour un widget. Pour une entreprise avec plusieurs sites ou plusieurs widgets, cela voulait dire plusieurs secrets à stocker et à renouveler. L'API Records accepte désormais aussi une clé d'API de compte, la même clé provedly_ que celle utilisée par l'API REST et le serveur MCP : un seul secret peut couvrir tous les widgets du compte.
Cet article explique quand migrer, comment, et ce qui ne change pas. La référence complète des champs se trouve toujours dans le guide de l'API Records.
Ce qui a changé et ce qui n'a pas changé
Le point d'accès est le même :
POST https://provedly.app/api/v1/widgets/{token}/records
Authorization: Bearer <widget key or account key>
Content-Type: application/json
Les champs sont les mêmes : name, city, state, country, product_name, price, avatar_url, external_id, occurred_at et visitor. Les valeurs external_id en double sont toujours rejetées par widget, les nouvelles tentatives restent donc sans risque.
Ce qui a changé, c'est l'en-tête. Vous pouvez maintenant envoyer une clé de compte avec le niveau d'accès Read and write au lieu de la clé propre au widget. Une clé de compte en lecture seule est refusée sur ce point d'accès, car ajouter un enregistrement est une écriture.
Les clés de widget continuent de fonctionner. Rien ne casse si vous ne touchez pas à une intégration existante.
Quelle clé utiliser, et quand
Gardez la clé de widget quand l'intégration n'écrit jamais que dans un seul widget et que vous appréciez ce périmètre restreint. Une clé de widget divulguée ne peut ajouter des enregistrements qu'à ce widget.
Utilisez une clé de compte quand un même service écrit dans plusieurs widgets, par exemple un service de checkout qui sert trois boutiques, chacune avec son propre widget. Un seul secret dans l'environnement, le widget étant choisi par le token dans l'URL.
Si vous migrez, créez une clé dédiée au service dans Settings, sous API keys, et nommez-la d'après le service : « Checkout service, production ». Ne réutilisez pas la clé donnée à votre assistant IA. Des clés séparées vous permettent d'en révoquer une sans casser l'autre.
Un exemple concret
Un service qui traite les commandes payées de deux boutiques pourrait ressembler à ceci dans les grandes lignes :
const WIDGETS = {
'shop-eu': 'pp_eu_widget_token',
'shop-us': 'pp_us_widget_token',
};
async function sendRecord(order) {
const token = WIDGETS[order.storefront];
const res = await fetch(
`https://provedly.app/api/v1/widgets/${token}/records`,
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PROVEDLY_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: order.customerFirstName,
city: order.city,
country: order.countryCode,
product_name: order.productName,
price: order.displayPrice,
external_id: order.id,
occurred_at: order.paidAt,
visitor: order.provedlyVisitorId,
}),
},
);
if (res.status === 422) return; // duplicate external_id or invalid data
if (!res.ok) throw new Error(`Provedly ${res.status}`);
}
Appelez-le une fois le paiement confirmé, jamais à la création de la commande. Un enregistrement pour un checkout qui a échoué ensuite, c'est une notification pour un achat qui n'a pas eu lieu.
Le champ visitor transporte l'identifiant visiteur Provedly issu du navigateur : c'est lui qui permet de compter la commande parmi les commandes assistées par la preuve dans vos statistiques. Sans lui, l'enregistrement s'affiche quand même, et la mesure d'attribution le laisse simplement de côté. Voir mesurer les commandes assistées par la preuve.
Comment ces enregistrements apparaissent
Les enregistrements envoyés via l'API conservent la source API, quelle que soit la clé utilisée. Ils s'affichent dans le widget avec une étiquette visible « Imported » et sans la marque Vérifié, et la page de vérification publique les compte sous « Site owner's backend (API) ».
Si vos commandes passent par Stripe, Shopify ou WooCommerce, la connexion par webhook signé est la meilleure voie : ces enregistrements arrivent vérifiés sans aucun code de votre côté. L'API Records sert à tout ce que ces connexions ne couvrent pas. Pourquoi votre assistant ne peut pas vérifier un achat explique pourquoi un appel d'API, quelle que soit son authentification, ne peut pas produire un enregistrement vérifié.
Vérifier depuis votre assistant
Le même compte est visible par votre assistant IA via le serveur MCP, avec une clé distincte. Après avoir déployé le changement, vous pouvez demander :
Liste mes widgets et donne-moi les statistiques de la dernière journée.
puis comparer la réponse avec votre propre journal de commandes. Le recueil de prompts contient d'autres exemples. Si vous voulez d'abord tester l'intégration à la main, l'assistant peut appeler add_record pour une seule commande réelle, un moyen rapide de voir exactement comment un enregistrement s'affiche.
Questions fréquentes
Une clé de compte me permet-elle d'envoyer vers un widget d'un autre compte ?
Non. Une clé de compte ne fonctionne que pour les widgets de son propre compte. Un token d'un autre compte est refusé.
Dois-je renouveler mes clés de widget maintenant ?
Seulement si vous passez à une clé de compte. Une fois que le service utilise la nouvelle clé, renouvelez l'ancienne clé de widget dans l'onglet Data du widget pour qu'elle ne fonctionne plus.
Existe-t-il un point d'accès groupé pour l'historique ?
Non. Pour les commandes passées, utilisez l'import CSV dans l'onglet Data du widget, décrit dans importer des commandes passées depuis un CSV. L'API sert au flux en direct.
L'API Records et les clés de compte sont disponibles sur le plan Free : créez un compte.