API, MCP et webhooks
API et MCP : branchez Netlinko sur vos outils et vos agents
Pour les agences, les éditeurs de sites, les éditeurs de logiciels et les équipes qui utilisent des assistants et agents automatisés : le catalogue, les commandes et leur paiement, la gestion de vos sites et de vos ventes, et des webhooks signés quand un lien est publié ou qu’une vente arrive.
- Clés à portées par domaine
- Serveur MCP pour vos agents
- Mêmes règles que l’espace membre
Le principe
Une API pour automatiser vos achats et vos ventes de liens
L’API des membres de Netlinko (netlinko/api/v1) donne accès, depuis vos propres outils, à ce que vous faites dans l’espace membre. Côté acheteur : consulter le catalogue ouvert à votre niveau, passer et payer des commandes, suivre leur état, la page publiée, le contrôle du lien et son indexation. Côté vendeur : soumettre vos sites, régler leurs prix et leurs prestations, accepter ou refuser les commandes reçues, publier, suivre votre solde.
- Authentification par clé : en-tête Authorization: Bearer suivi de votre clé, ou en-tête X-Netlinko-Key. Jamais par les cookies d’une session.
- Des portées par domaine, cochées à la création de la clé : catalogue, commandes, sites vendeurs, ventes, solde, webhooks. Les actions d’argent (payer avec le porte-monnaie, demander un versement) exigent leur portée cochée.
- Des clés protégées : affichées une seule fois à leur création, conservées sous forme d’empreinte, révocables à tout moment, avec un journal de leurs appels.
- Des limites claires : un nombre de requêtes par minute et par clé (120 par défaut) ; une commande envoyée deux fois avec la même clé d’idempotence n’en crée qu’une.
- Les mêmes règles que l’espace membre : prix, accès, délais et contrôles sont décidés par la plateforme.
La documentation détaillée, avec les paramètres de chaque route, est dans votre espace, rubrique « API et webhooks ».
Les portées
Une clé ne fait que ce que vous lui permettez
Cochez seulement ce dont votre outil a besoin. Une clé liée à une personne de votre équipe est aussi limitée par son rôle.
| Portée | Ce qu’elle permet | Côté |
|---|---|---|
| catalog:read | Lire le catalogue de votre niveau et les mots clés positionnés | Acheteur |
| orders:read / orders:write | Lire vos commandes ; commander, écrire à l’éditeur, signaler un problème, annuler | Acheteur |
| wallet:read / wallet:pay | Lire le porte-monnaie ; payer avec son solde (action d’argent) | Acheteur |
| seller:read | Lire vos sites, leur état, vos ventes et leurs échéances | Vendeur |
| seller:sites / seller:orders | Soumettre et régler vos sites ; accepter, refuser, publier vos ventes | Vendeur |
| payouts:read / payouts:request | Lire votre solde ; demander un versement (action d’argent) | Vendeur |
| webhooks:read / webhooks:write | Lire et gérer vos webhooks | Tous |
Les routes
Ce que permet l’API
Un aperçu des routes principales ; le détail des paramètres est dans votre espace.
| Méthode et route | Droit | Usage |
|---|---|---|
| GET /me | Toute clé | Votre compte : niveau, accès au catalogue, liens offerts, portées de la clé |
| GET /catalog | catalog:read | Les sites ouverts à votre niveau, avec filtres (langue, prestation, prix, TF, DR, trafic) |
| POST /orders | orders:write | Passer une commande : site, prestation, page visée, ancre, consignes ; réponse avec le lien de paiement |
| POST /orders/pay | orders:write ou wallet:pay | Payer plusieurs commandes en une fois : lien de paiement par carte, ou porte-monnaie |
| GET /orders | orders:read | Vos commandes et leur état |
| GET /orders/{id} | orders:read | Une commande : paiement, page publiée, contrôle du lien, indexation, rapport |
| POST /orders/{id}/dispute | orders:write | Signaler un problème sur une commande |
| POST /webhooks | webhooks:write | Créer un webhook ; le secret de signature est affiché une fois |
Vendeurs
Gérez vos sites et vos ventes sans ouvrir l’espace
Les mêmes contrôles que l’espace vendeur : vos sites et vos ventes uniquement, les délais d’acceptation et de publication, la preuve de propriété demandée par la plateforme.
| Méthode et route | Portée | Usage |
|---|---|---|
| GET /seller/sites | seller:read | Vos sites et leur état : actif, en attente, propriété à vérifier, vacances, non éligible |
| POST /seller/sites | seller:sites | Soumettre un site : adresse, nom, langue, thématiques ; la réponse donne la preuve de propriété à mettre en place (extension, fichier ou DNS) |
| POST /seller/sites/{id}/verify | seller:sites | Lancer la vérification du fichier ou de l’entrée DNS |
| POST /seller/sites/{id} | seller:sites | Régler prix, prestations, formules, ancres acceptées, données montrées, promotion. Jamais de chiffres : trafic et métriques sont mesurés par la plateforme |
| POST /seller/vacation | seller:sites | Mode vacances : tous vos sites retirés du catalogue, puis de retour |
| GET /seller/orders | seller:read | Les commandes reçues et leurs échéances (accepter avant, publier avant) |
| POST /seller/orders/{id}/accept | seller:orders | Accepter une commande ; refuser avec /refuse et un motif vu par l’acheteur |
| GET /seller/orders/{id}/content | seller:read | Le contenu à publier, avec le lien à garder tel quel |
| POST /seller/orders/{id}/publish | seller:orders | Déclarer la page publiée : elle est lue avant la mise en ligne |
| GET /seller/balance | payouts:read | Votre solde : sous garantie, disponible, en cours de virement |
| POST /seller/payouts | payouts:request | Demander un versement : traité à partir du 1er du mois suivant la demande |
MCP
Un serveur MCP pour vos assistants et agents automatisés
Le Model Context Protocol (MCP) est le protocole ouvert qui permet à un assistant ou à un agent automatisé d’utiliser des outils. Netlinko a son propre serveur MCP : branchez-le dans votre client MCP, il y trouve les actions de votre compte sous forme d’outils, chacun décrit avec ses paramètres.
- Une seule adresse : https://netlinko.com/wp-json/netlinko/v1/mcp, transport HTTP « streamable » (un message JSON-RPC 2.0 par requête POST, une réponse JSON, sans session).
- La même clé que l’API, avec ses portées : votre agent ne voit que les outils que la clé permet, et le journal des appels garde chaque outil utilisé.
- Votre accord avant l’argent : les outils qui paient, annulent, refusent une commande ou demandent un versement sont marqués comme destructifs et demandent une confirmation explicite.
- Les mêmes règles : chaque outil passe par l’API, avec ses contrôles (vos objets seulement, délais, quarantaine, gels).
- Les clients récents et ceux d’avant : version dans chaque requête (server/discover) ou ouverture par initialize.
L’espace membre, rubrique « API et webhooks », donne la configuration à copier dans votre client MCP. Les outils, les portées et la confirmation des actions sensibles sont détaillés sur la page MCP : Netlinko pour les assistants et agents automatisés.
Exemples
Vos premiers appels avec curl
Remplacez nlk_… par une clé créée dans votre espace, et les identifiants par ceux que renvoie l’API.
Chercher dans le catalogue
Portée catalog:read.
curl "https://netlinko.com/wp-json/netlinko/api/v1/catalog?language=fr&service=article&price_max=150" \
-H "Authorization: Bearer nlk_…"Passer une commande
Portée orders:write ; la réponse contient le lien de paiement.
curl -X POST https://netlinko.com/wp-json/netlinko/api/v1/orders \
-H "Authorization: Bearer nlk_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: commande-001" \
-d '{"site":"<id du catalogue>","service":"article","target_url":"https://mon-site.fr/page/","anchor":"mon ancre","accept_terms":true}'Accepter une commande reçue
Portée seller:orders ; refusez avec /refuse et {"reason": "…"}.
curl -X POST https://netlinko.com/wp-json/netlinko/api/v1/seller/orders/<id>/accept \
-H "Authorization: Bearer nlk_…"Lister les outils du serveur MCP
La même clé ; les outils listés dépendent de ses portées.
curl -X POST https://netlinko.com/wp-json/netlinko/v1/mcp \
-H "Authorization: Bearer nlk_…" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "MCP-Protocol-Version: 2026-07-28" \
-H "Mcp-Method: tools/list" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}'Les événements
Les webhooks : vos outils prévenus en temps réel
Choisissez les événements à recevoir pour chaque adresse. Côté acheteur, ceux de vos commandes :
| Événement | Quand il est envoyé | Exemple d’usage |
|---|---|---|
| order.paid | La commande est payée | Mettre à jour le budget consommé du client |
| order.accepted | L’éditeur accepte la commande | Prévenir le chef de projet |
| order.published | Le lien est en ligne | Ajouter le lien au rapport du client |
| order.problem | Un problème est détecté sur le lien | Créer une tâche de suivi |
| order.cancelled | La commande est annulée | Mettre à jour la facturation interne |
Événements vendeur
Vos ventes, vos sites et vos versements suivis par vos outils
Les mêmes écrans et les mêmes routes que les acheteurs : chaque webhook reçoit les événements que vous cochez. Le message ne contient que des identifiants et des états (jamais l’adresse d’une de vos pages ni l’identité de l’acheteur), les montants en nombre et en texte à deux décimales ; un compte en quarantaine ne reçoit que les événements de sa quarantaine et de son solde.
| Événement | Quand il est envoyé | Exemple d’usage |
|---|---|---|
| sale.received | Une nouvelle commande est à accepter | Prévenir la rédaction du site |
| sale.accept_due_soon / sale.accept_overdue | L’échéance d’acceptation est demain, puis dépassée (commande annulée) | Relancer la personne qui valide les commandes |
| sale.content_ready | Le contenu est prêt à publier, ou envoyé à l’extension du site | Planifier la publication |
| sale.publish_due_soon / sale.publish_overdue | L’échéance de publication est demain, puis dépassée (commande annulée) | Alerter le responsable du site |
| sale.message | L’acheteur ou l’équipe écrit sur une vente | Ouvrir un ticket dans votre outil |
| sale.cancelled | La vente est annulée : par l’acheteur, l’équipe ou un délai | Retirer la tâche de publication |
| sale.dispute_opened / sale.dispute_decided | Un litige ou un signalement est ouvert, puis décidé | Suivre la réponse à apporter |
| sale.link_problem | Le lien est absent, en nofollow ou sa page en noindex pendant la garantie | Rétablir le lien sans attendre |
| sale.acquired | La garantie est terminée : votre part est disponible | Mettre à jour votre comptabilité |
| payout.scheduled / payout.sent / payout.refused | Un versement est programmé, puis envoyé ou refusé | Rapprocher les virements reçus |
| site.approved / site.refused / site.paused / site.ineligible | Un site est validé, refusé, mis en pause ou non éligible | Tenir à jour la liste de vos sites |
| account.quarantined / account.reactivated | Le compte est mis en quarantaine, puis réactivé | Prévenir votre équipe |
Exemple de message
Une nouvelle vente reçue par votre webhook
Un POST JSON signé (en-tête Netlinko-Signature). L’identifiant id est unique pour chaque événement : il reste le même à chaque nouvel essai, dédoublonnez sur lui.
sale.received
Votre part hors taxes, la date limite d’acceptation, les identifiants de la vente et du site.
{
"id": "evt_5f0c2a9e41b7d3c8a6e1f2b4d9c7e0a1",
"type": "sale.received",
"created": 1793606400,
"created_at": "2026-11-02T08:00:00+00:00",
"data": {
"sale": {
"id": "k3f9q2m7x1c8d",
"reference": "K3F9-Q2M7-X1C8D",
"site": "p7d2w9n4b6t1s",
"service": "article",
"status": "accepted",
"seller_state": "to_send",
"amount": 85.5,
"amount_text": "85.50",
"currency": "EUR",
"accept_by": "2026-11-05T08:00:00+00:00",
"accepted_at": null,
"publish_by": null,
"publish_on": null,
"published": false
},
"offered": false
}
}
Sécurité des webhooks
Des messages signés, livrés avec persévérance
- Signés : chaque message porte l’en-tête Netlinko-Signature, avec l’heure et une signature HMAC-SHA256 calculée avec votre secret. Refusez les messages de plus de 5 minutes : pas de rejeu possible.
- Relivrés : en cas d’échec, nouvel essai après 1 min, 5 min, 30 min, 2 h puis 12 h ; un webhook en échec 20 fois de suite est mis en pause et vous êtes prévenu.
- Protégés : adresses HTTPS sur l’internet public uniquement, jamais de redirection, adresse vérifiée à chaque envoi.
- Testables : envoyez un message de test depuis l’API ou votre espace.
Cas d’usage
Ce que les équipes en font
Quelques usages possibles, à adapter à vos outils.
Tableaux de bord clients
Afficher les liens publiés, leur état et leur indexation dans le reporting de chaque client.
Gestion de projet
Créer une tâche quand un lien est publié ou qu’un problème est détecté.
Sélection outillée
Filtrer le catalogue de votre niveau par prix, TF, DR ou trafic depuis votre propre interface.
Commandes en volume
Passer et payer plusieurs commandes en une fois depuis votre outil interne.
Démarrer
Vos premiers appels en cinq étapes
- Créez une clé dans la rubrique « API et webhooks » de votre espace, en lecture pour commencer. Copiez-la : elle ne sera plus jamais affichée.
- Testez votre accès avec la route /me : elle renvoie votre niveau, votre accès au catalogue, vos liens offerts et les portées de la clé.
- Interrogez le catalogue de votre niveau avec /catalog et ses filtres : langue, prestation, prix maximal, Trust Flow, Domain Rating ou trafic minimal.
- Passez une commande avec une clé qui a la portée orders:write : site, prestation, page visée, ancre et consignes, avec une clé d’idempotence ; la réponse contient le lien de paiement sécurisé.
- Créez un webhook pour être prévenu quand la commande est payée, acceptée, publiée, en difficulté ou annulée.
Les erreurs sont explicites et les limites annoncées : au-delà de la limite de requêtes par minute, l’API répond 429 ; une portée manquante est nommée dans la réponse 403.
Bonnes pratiques
Utiliser l’API en toute sécurité
- Une clé par outil ou par agent, avec les seules portées nécessaires : la lecture pour un tableau de bord, l’écriture seulement pour l’outil qui commande, les actions d’argent seulement si vous les confiez vraiment.
- Gardez vos clés côté serveur, jamais dans une page web ou une application installée chez un client.
- Vérifiez chaque webhook : signature, horodatage de moins de 5 minutes, puis traitement.
- Répondez rapidement (code 2xx) puis traitez le message : en cas d’échec, il vous est renvoyé plus tard.
- Révoquez sans attendre une clé dont vous n’êtes plus sûr, et consultez le journal de ses appels.
Exemple
Exemple : un reporting client automatique
Une agence gère le netlinking d’une vingtaine de clients. Elle range chaque commande dans le projet du client, puis crée un webhook sur les événements « commande payée », « lien publié » et « problème ». À chaque lien publié, son outil interne reçoit le message signé, vérifie la signature, interroge la commande pour récupérer la page publiée, l’ancre et l’état d’indexation, et ajoute une ligne au rapport mensuel du client. Quand un problème est détecté, une tâche est créée pour le chef de projet.
Résultat : plus de copier-coller entre l’espace membre et les rapports, et des clients informés sans délai. Le tout avec une clé en lecture pour le reporting, et une clé qui a la portée des commandes, réservée à l’outil qui les passe.
Le scénario type
Une commande passée de bout en bout par l’API
La plupart des intégrations suivent le même scénario. Une clé est créée dans votre espace, en lecture ou en écriture. Vos outils interrogent le catalogue ouvert à votre niveau, avec les prix, les formules des liens loués et les types d’ancres acceptés par chaque site.
La commande précise le site, la prestation, la page visée, l’ancre et les consignes. Elle se paie par le lien de paiement renvoyé, en une fois pour plusieurs commandes, et le porte-monnaie se consulte par l’API.
Les webhooks ferment la boucle : un appel signé prévient vos outils quand la commande est payée, acceptée, publiée, en difficulté ou annulée. Les règles restent celles de l’espace membre : mêmes contrôles, même garantie. Le détail des contrôles transmis par les webhooks est expliqué sur la page indexation et suivi des liens. Les agences trouveront le reste de leurs outils sur la page agences SEO, et les indépendants sur celle des consultants SEO.
- CléCréée dans votre espace, en lecture ou en écriture.
- CatalogueLes sites ouverts à votre niveau, leurs prix et les ancres acceptées.
- CommandeSite, prestation, page visée, ancre, consignes.
- PaiementPar le lien de paiement renvoyé, en une fois pour plusieurs commandes.
- WebhooksUn appel signé quand la commande est payée, acceptée, publiée, en difficulté ou annulée.
FAQ
Questions sur l’API
Une autre question ? Écrivez-nous, nous répondons rapidement.
Qui peut utiliser l’API ?
Tout membre acheteur ou vendeur dont le compte est validé : créez une clé depuis la rubrique « API et webhooks » de votre espace, avec les portées dont votre outil a besoin.
Puis-je confier mon compte à un assistant ou à un agent automatisé ?
Oui, par le serveur MCP ou par l’API, avec une clé limitée aux portées utiles. Les actions qui engagent de l’argent ou refusent une commande demandent une confirmation explicite, et le journal des appels garde chaque action.
L’API donne-t-elle accès à plus de sites que l’espace ?
Non : le catalogue de l’API est celui de votre niveau, aux mêmes prix. Les règles sont celles de l’espace membre.
Comment vérifier un webhook ?
Recalculez la signature HMAC-SHA256 du message avec votre secret et comparez-la à l’en-tête Netlinko-Signature ; refusez les messages de plus de 5 minutes.
Que faire si ma clé est compromise ?
Révoquez-la depuis votre espace : la révocation est immédiate. Créez-en une nouvelle et mettez à jour vos outils.
L’API permet-elle de payer sans passer par une page ?
Par carte, non : la commande renvoie un lien vers la page de paiement sécurisée de Stripe. Avec le porte-monnaie, oui, mais seulement avec une clé qui en a la portée cochée (wallet:pay). Plusieurs commandes peuvent être payées en une fois.
Puis-je utiliser l’API pour plusieurs clients ?
Oui : passez les commandes depuis votre compte et rangez-les par projet client. Vos outils récupèrent ensuite les commandes et leur état, client par client.
Les webhooks sont-ils envoyés dans l’ordre ?
Ils sont envoyés depuis une file d’attente, avec de nouveaux essais en cas d’échec : traitez chaque message selon son type et son horodatage, et interrogez la commande pour connaître son état à jour.
Faut-il un niveau particulier pour utiliser l’API ?
Non : tout membre dont le compte est validé peut créer une clé. Le catalogue renvoyé est celui de votre niveau, comme dans l’espace membre.
L’API permet-elle d’utiliser mes liens offerts ?
La route /me indique vos liens offerts disponibles ; leur placement se demande depuis votre espace, où vous choisissez vos sites (ou laissez l’équipe les choisir).
Automatisez le netlinking de vos clients
Créez votre compte, puis votre première clé d’API depuis votre espace.
Paiement à la commande · Lien contrôlé régulièrement pendant la garantie · Factures en PDF