Développeurs
API d'intégration
Votre boutique envoie chaque commande payée à ProvedBuy. Nous programmons l'invitation, l'envoyons au client après le délai que vous avez choisi, et l'avis publié porte la mention « commande vérifiée ».
Démarrer en 4 étapes
1
Créer la clé
Dans votre espace, page Paramètres, bloc API. La clé s'affiche une seule fois : rangez-la dans une variable d'environnement de votre serveur, jamais dans votre code ni dans le navigateur.
2
Vérifier la clé
Appelez GET /api/v1/integration/ping. La réponse donne le nom de votre boutique, votre offre et votre délai d'envoi.
3
Essayer en mode test
Envoyez une vraie commande avec "test": true. Rien n'est créé, le client ne reçoit rien, et vous recevez un aperçu de l'invitation.
4
Passer en réel
Retirez "test": true. Chaque commande payée est alors programmée et l'invitation part seule après le délai.
Authentification
Chaque appel porte l'en-tête X-Api-Key avec votre clé. L'API est réservée à l'offre Pro. Les appels se font depuis votre serveur : une clé envoyée par le navigateur serait visible de tous. Si une clé fuit, créez-en une nouvelle dans vos paramètres : l'ancienne cesse aussitôt de fonctionner.
- Adresse de base
- https://provedbuy.com/api/v1/integration
- Langue des messages
- Les messages sont en français. Ajoutez l'en-tête X-Lang: en pour les recevoir en anglais.
Vérifier la clé
GEThttps://provedbuy.com/api/v1/integration/ping
Ne crée rien et n'envoie rien. À appeler à l'installation, ou depuis une page d'administration de votre boutique pour afficher l'état de la liaison.
Code curl
curl https://provedbuy.com/api/v1/integration/ping \
-H "X-Api-Key: $PROVEDBUY_API_KEY"Réponse
{
"succeeded": true,
"messages": ["Clé d'API valide"],
"data": {
"company": "Ma Boutique",
"slug": "ma-boutique.fr",
"plan": "Pro",
"invitationDelayDays": 7,
"sendingActive": true,
"remainingThisMonth": null
}
}| Champ | Rôle |
|---|---|
| company | Nom de votre boutique sur ProvedBuy. |
| slug | Identifiant de votre page publique et de votre badge. |
| plan | Votre offre. |
| invitationDelayDays | Délai entre la réception de la commande et l'envoi de l'invitation, en jours. |
| sendingActive | false tant que votre adresse e-mail n'est pas confirmée : les invitations attendent. |
| remainingThisMonth | Invitations encore possibles ce mois-ci, null quand c'est illimité. |
Envoyer des commandes
POSThttps://provedbuy.com/api/v1/integration/invitations
Appelez cette adresse une fois la commande payée, pas à sa création. Une commande annulée avant paiement ne doit pas recevoir d'invitation.
Corps de la requête (JSON)
| Champ | Type | Rôle |
|---|---|---|
| items | tableau, obligatoire | De 1 à 500 commandes par appel. |
| items[].customerName | texte | Prénom et nom du client, 80 caractères au plus. Sert à la formule de politesse. |
| items[].customerEmail | texte, obligatoire | Adresse à laquelle part l'invitation. |
| items[].orderReference | texte, obligatoire | Votre numéro de commande, 80 caractères au plus. Une même commande n'est jamais invitée deux fois. |
| test | booléen | true pour le mode test. Absent ou false : envoi réel. |
Réponse
| Champ | Rôle |
|---|---|
| created | Commandes programmées (en mode test : celles qui le seraient). |
| skipped | Commandes écartées. |
| skippedReasons | La raison de chaque ligne écartée, 20 au plus. |
| test | true quand l'appel était en mode test. |
| previewSentTo | En mode test, l'adresse qui a reçu l'aperçu. |
Mode test
Ajoutez "test": true au corps de la requête. Les commandes passent par les mêmes contrôles qu'en réel, mais aucune invitation n'est créée, aucun e-mail ne part chez le client et votre quota ne bouge pas.
- La réponse indique, ligne par ligne, ce qui serait accepté ou écarté.
- Un aperçu de l'invitation part à l'adresse de votre compte ProvedBuy, avec le nom et la commande de la première ligne acceptée.
- Vous pouvez donc tester avec de vraies commandes, sans risque pour vos clients.
Exemples par langage
Chaque exemple envoie une commande en mode test. Retirez test pour passer en réel. La clé est lue dans la variable d'environnement PROVEDBUY_API_KEY.
Code curl
curl -X POST https://provedbuy.com/api/v1/integration/invitations \
-H "X-Api-Key: $PROVEDBUY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"test": true,
"items": [
{ "customerName": "Lea Martin", "customerEmail": "lea@example.com", "orderReference": "CMD-1001" }
]
}'WooCommerce, PrestaShop, Shopify
Il n'existe pas encore d'extension à installer. Voici où brancher l'appel dans chaque outil.
WooCommerce
Dans le fichier functions.php de votre thème enfant ou dans une petite extension. Déclenché quand le paiement est confirmé. Définissez PROVEDBUY_API_KEY dans wp-config.php.
Code WooCommerce
add_action('woocommerce_payment_complete', function ($order_id) {
$order = wc_get_order($order_id);
wp_remote_post('https://provedbuy.com/api/v1/integration/invitations', [
'timeout' => 10,
'headers' => [
'X-Api-Key' => PROVEDBUY_API_KEY,
'Content-Type' => 'application/json',
],
'body' => wp_json_encode([
'items' => [[
'customerName' => $order->get_billing_first_name() . ' ' . $order->get_billing_last_name(),
'customerEmail' => $order->get_billing_email(),
'orderReference' => $order->get_order_number(),
]],
]),
]);
});PrestaShop
Dans un module qui s'accroche à actionValidateOrder. Rangez la clé dans la configuration du module.
Code PrestaShop
public function hookActionValidateOrder($params)
{
$order = $params['order'];
$customer = $params['customer'];
$payload = json_encode(['items' => [[
'customerName' => $customer->firstname . ' ' . $customer->lastname,
'customerEmail' => $customer->email,
'orderReference' => $order->reference,
]]]);
$ch = curl_init('https://provedbuy.com/api/v1/integration/invitations');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
CURLOPT_HTTPHEADER => ['X-Api-Key: ' . Configuration::get('PROVEDBUY_API_KEY'), 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => $payload,
]);
curl_exec($ch);
curl_close($ch);
}Shopify
Créez un webhook « Paiement de commande » (orders/paid) qui appelle votre serveur, puis votre serveur appelle ProvedBuy. Exemple avec Node.js et Express, à compléter par la vérification de la signature Shopify.
Code Shopify
app.post("/webhooks/shopify/orders-paid", express.raw({ type: "application/json" }), async (req, res) => {
res.sendStatus(200);
const order = JSON.parse(req.body);
await fetch("https://provedbuy.com/api/v1/integration/invitations", {
method: "POST",
headers: { "X-Api-Key": process.env.PROVEDBUY_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
items: [{
customerName: [order.customer?.first_name, order.customer?.last_name].filter(Boolean).join(" "),
customerEmail: order.email,
orderReference: order.name,
}],
}),
});
});Réponses et erreurs
Toutes les réponses ont la même forme : succeeded, messages et data.
Réponse en mode test
{
"succeeded": true,
"messages": ["Mode test : 1 invitation(s) seraient programmée(s), aucune n'a été créée"],
"data": {
"created": 1,
"skipped": 0,
"skippedReasons": [],
"test": true,
"previewSentTo": "vous@ma-boutique.fr"
}
}Clé refusée
{
"succeeded": false,
"messages": ["Clé d'API invalide"],
"data": 0
}| Statut HTTP | Rôle |
|---|---|
| 200 | Appel traité. Lisez succeeded : false signifie qu'aucune commande n'a été acceptée (liste vide, plus de 500 lignes). |
| 401 | Clé absente, invalide, remplacée, ou offre sans API. |
| 413 | Corps de plus de 1 Mo : découpez l'envoi. |
| 429 | Plus de 60 appels par minute : attendez une minute, puis renvoyez. |
| 5xx | Incident de notre côté : renvoyez plus tard. Une commande déjà reçue est reconnue et n'est pas invitée deux fois. |
Règles et limites
- Une commande n'est invitée qu'une fois : renvoyer le même numéro ne crée pas de doublon. Vous pouvez donc renvoyer sans risque après une erreur réseau.
- Les adresses de votre propre domaine ne sont jamais invitées.
- L'invitation part après votre délai d'envoi, réglable de 0 à 30 jours dans vos paramètres.
- Les invitations ne partent qu'une fois votre adresse e-mail confirmée.
- Appelez l'API en tâche de fond : une panne de notre côté ne doit jamais bloquer votre commande.
- Un avis reçu par invitation porte la mention « commande vérifiée » et ne peut être ni supprimé ni masqué par la boutique.
Prêt à brancher votre boutique ?
Créez votre clé dans vos paramètres, puis lancez un premier appel en mode test.