Utiliser l''API Records pour les achats de votre propre backend

Si vos achats ne passent pas par Stripe Checkout, Shopify ou WooCommerce, c'est l'API Records qui les fait parvenir à Provedly. Un POST de serveur à serveur par commande, authentifié par une clé bearer propre à chaque widget, et l'achat apparaît en notification dans la fenêtre de rétrospective. Les enregistrements créés de cette façon portent une étiquette visible « Imported » et jamais la mention « Verified » ; cet article explique cette règle autant que la mécanique.

L'endpoint

POST https://provedly.app/api/v1/widgets/{token}/records
Authorization: Bearer <widget api key>
Content-Type: application/json

La clé est générée pour chaque widget dans l'onglet Data, où vous pouvez aussi la renouveler. Traitez-la comme n'importe quel secret : une variable d'environnement côté serveur, jamais dans le code côté client. L'endpoint s'utilise uniquement de serveur à serveur ; un appel depuis un navigateur est visible par quiconque ouvre les devtools, et une clé divulguée permet à un inconnu de publier des enregistrements dans votre widget.

Champs

Envoyez ce que vous avez. Un enregistrement avec seulement name est valide et s'affichera avec le produit par défaut du widget et sans lieu.

Un exemple minimal

curl -X POST https://provedly.app/api/v1/widgets/pp_your_token/records \
  -H "Authorization: Bearer $PROVEDLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "city": "Berlin",
    "country": "DE",
    "product_name": "Pro Plan",
    "price": "€49",
    "external_id": "order_123",
    "occurred_at": "2026-08-12T14:03:00Z"
  }'

Réponses :

201 Created
{ "id": 812, "hash": "9c1e0b7a…", "verified": false, "occurred_at": "2026-08-12T14:03:00+00:00" }

401 Unauthorized   wrong or missing bearer key
422 Unprocessable  validation errors, including a duplicate external_id

Remarquez "verified": false dans la réponse de succès. Ce n'est pas un bug, et aucun paramètre ne permet de le changer.

Quand l'appeler

Appelez-le une fois le paiement confirmé, pas à la création de la commande. Un enregistrement pour un checkout abandonné ou échoué est une fausse notification, précisément ce que le système cherche à éviter. Dans la plupart des backends, cela correspond au gestionnaire du callback de succès de votre prestataire de paiement, ou à la tâche qui marque une commande comme payée.

Envoyez toujours external_id. Les callbacks de paiement sont relancés, les files d'attente redistribuent les messages, et les déploiements redémarrent les workers en pleine tâche. Avec external_id égal à votre numéro de commande, la deuxième tentative renvoie 422 et vous pouvez la traiter comme un succès. Sans lui, vous finirez par afficher deux fois le même achat.

Renseignez occurred_at avec l'heure réelle du paiement plutôt que de laisser la valeur par défaut. Si une file d'attente prend vingt minutes de retard, la notification dit quand même la bonne chose, et l'enregistrement se place au bon endroit sur la page de vérification.

Attribution

L'indicateur des commandes assistées par la preuve, dans le dashboard, compte les acheteurs qui ont vu une notification avant d'acheter, rapprochés par identifiant visiteur dans une fenêtre de 30 jours. Pour les enregistrements envoyés par l'API, cela ne fonctionne que si vous transmettez cet identifiant.

Côté client, au moment où le visiteur commence le checkout :

const visitor = window.Provedly?.visitorId();
// include it in your checkout form or API call

Côté serveur, transmettez-le dans le champ visitor de l'enregistrement. Si votre checkout se trouve sur un autre domaine que le widget, faites passer l'identifiant dans l'URL ou dans votre session. Provedly n'estime jamais l'attribution : un identifiant manquant donne un indicateur vide plutôt qu'un indicateur faux. Voir Mesurer les commandes assistées par la preuve.

Pourquoi les enregistrements de l'API ne sont jamais « Verified »

Provedly peut vérifier un webhook Stripe, Shopify ou WooCommerce parce que le prestataire signe le contenu avec un secret et que Provedly contrôle la signature. Un POST depuis votre serveur porte une clé bearer, qui prouve que l'appelant détient la clé, pas qu'un paiement a eu lieu. Un marchand pourrait générer cent enregistrements avec une simple boucle. Vu de l'extérieur, Provedly ne peut pas faire la différence ; les enregistrements de l'API n'obtiennent donc jamais la mention Verified. Ils s'affichent dans le widget avec une étiquette « Imported » qu'aucun réglage, plan ou demande au support ne peut retirer, et la page de vérification publique les liste sous « Site owner's backend (API) ».

C'est un choix délibéré, et c'est la raison principale pour laquelle Provedly existe. La plupart des outils de notification, en octobre 2026 et d'après leurs fiches, acceptent des achats saisis arbitrairement et les présentent exactement comme les vrais. Un visiteur n'a aucun moyen de le savoir. Avec Provedly, seules les commandes signées affichent la mention Verified, et la page de vérification liste toutes les sources. Si vous voulez la mention Verified, faites passer vos paiements par un prestataire doté d'un webhook signé, comme décrit dans Les webhooks Stripe pour des achats vérifiés.

Reprise de l'historique

Pour l'historique, ne bouclez pas sur l'API avec les commandes de l'an dernier. Utilisez plutôt l'import CSV de l'onglet Data : il gère les doublons par nom et ville à l'intérieur d'une même heure, définit occurred_at ligne par ligne et stocke sans les afficher les lignes situées hors de la fenêtre de rétrospective. L'API sert au flux en temps réel. Voir Importer des commandes passées depuis un CSV.

Questions fréquentes

Y a-t-il une limite de débit ?

Publiez un enregistrement par commande au fil de l'eau et vous n'atteindrez aucune limite. Pour un historique en masse, utilisez l'import CSV.

Puis-je modifier ou supprimer un enregistrement après l'avoir publié ?

Les enregistrements peuvent être supprimés depuis le dashboard. Il n'existe pas d'endpoint de mise à jour ; publiez un enregistrement corrigé avec un nouvel external_id et supprimez l'ancien.

Puis-je envoyer un prix dans une devise que le widget ne connaît pas ?

Oui. price est un texte libre de 30 caractères maximum, affiché tel que vous l'envoyez. Formatez-le de votre côté, symbole de devise compris.

L'API et les webhooks vérifiés sont inclus dans le plan Free : lisez la référence complète ou créez un widget.