Automatisation avancée

Ce guide s’adresse aux agences SEO et aux utilisateurs avancés qui souhaitent pousser l’API Linkuma à son plein potentiel : imports CSV massifs, dashboards personnalisés, alertes en temps réel et workflows de bout en bout.

Les exemples ci-dessous supposent que vous disposez d’un Bearer token valide et que vous avez lu la documentation de référence de l’API.

Commandes en masse via CSV + API

Principe

Plutôt que de saisir chaque commande manuellement, préparez un fichier CSV avec toutes vos URLs et ancres, puis laissez un script Python passer les commandes automatiquement.

Format du CSV attendu

project_id,target_url,anchor,budget_max,niche
proj_001,https://monsite.fr/produit-a,chaussures running,35,sport
proj_001,https://monsite.fr/produit-b,trail homme,50,sport
proj_002,https://agence-client.fr/seo,consultant SEO Paris,70,marketing
proj_002,https://agence-client.fr/audit,audit SEO gratuit,35,marketing

Script Python : import CSV en masse

import csv
import time
import requests
from pathlib import Path

API_BASE = "https://app.linkuma.com/api/v1"
API_TOKEN = "VOTRE_TOKEN_ICI"
CSV_FILE = Path("commandes.csv")

HEADERS = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

# Paramètres de sécurité
DELAY_BETWEEN_REQUESTS = 1.2  # secondes (respecte le rate limit 60 req/min)
DRY_RUN = False  # Passer à True pour simuler sans passer de commandes


def place_order(row: dict) -> dict:
    """Passe une commande depuis une ligne CSV."""
    payload = {
        "project_id": row["project_id"],
        "target_url": row["target_url"],
        "anchor": row["anchor"],
        "budget_max": int(row["budget_max"]),
        "niche": row.get("niche", "auto")
    }

    if DRY_RUN:
        print(f"[DRY RUN] Commande simulée : {payload['target_url']} ({payload['anchor']})")
        return {"data": {"order_id": "dry_run", "status": "simulated"}}

    response = requests.post(f"{API_BASE}/orders", headers=HEADERS, json=payload)
    response.raise_for_status()
    return response.json()


def process_csv(filepath: Path):
    results = []
    errors = []

    with open(filepath, newline="", encoding="utf-8") as f:
        reader = csv.DictReader(f)
        rows = list(reader)

    print(f"{len(rows)} commandes à traiter...")

    for i, row in enumerate(rows, 1):
        print(f"[{i}/{len(rows)}] {row['target_url']}", end=" → ")
        try:
            result = place_order(row)
            order_id = result["data"]["order_id"]
            print(f"OK ({order_id})")
            results.append({**row, "order_id": order_id, "status": "success"})
        except requests.HTTPError as e:
            print(f"ERREUR ({e.response.status_code})")
            errors.append({**row, "error": str(e)})
        except Exception as e:
            print(f"ERREUR inattendue ({e})")
            errors.append({**row, "error": str(e)})

        time.sleep(DELAY_BETWEEN_REQUESTS)

    # Rapport
    print(f"\n✅ Succès : {len(results)} | ❌ Erreurs : {len(errors)}")

    # Export des erreurs pour retraitement
    if errors:
        error_file = filepath.with_name(f"{filepath.stem}_errors.csv")
        with open(error_file, "w", newline="", encoding="utf-8") as f:
            writer = csv.DictWriter(f, fieldnames=errors[0].keys())
            writer.writeheader()
            writer.writerows(errors)
        print(f"Erreurs exportées dans : {error_file}")

    return results, errors


if __name__ == "__main__":
    process_csv(CSV_FILE)

Ne dépassez pas 50 commandes par batch sans pause. Si vous traitez plus de 50 URLs, ajoutez une pause de 5 secondes toutes les 50 requêtes pour éviter tout blocage temporaire de votre token.

Dashboard custom de suivi

Script Python : génération d’un rapport HTML

Ce script interroge l’API et génère un fichier HTML autonome avec un tableau de bord complet.

import requests
from datetime import datetime
from pathlib import Path

API_BASE = "https://app.linkuma.com/api/v1"
API_TOKEN = "VOTRE_TOKEN_ICI"
HEADERS = {"Authorization": f"Bearer {API_TOKEN}"}


def fetch_all_orders() -> list:
    orders, page = [], 1
    while True:
        res = requests.get(
            f"{API_BASE}/orders",
            headers=HEADERS,
            params={"limit": 100, "page": page}
        )
        res.raise_for_status()
        data = res.json()
        batch = data.get("data", [])
        if not batch:
            break
        orders.extend(batch)
        if len(orders) >= data["meta"]["total"]:
            break
        page += 1
    return orders


def generate_dashboard(orders: list, output_path: str = "linkuma-dashboard.html"):
    # Calcul des métriques
    total = len(orders)
    delivered = sum(1 for o in orders if o["status"] == "delivered")
    in_progress = sum(1 for o in orders if o["status"] == "in_progress")
    pending = sum(1 for o in orders if o["status"] == "pending")
    total_spent = sum(o.get("amount", 0) for o in orders)

    rows_html = ""
    for o in orders:
        status_badge = {
            "delivered": '<span style="color:green">✅ Livré</span>',
            "in_progress": '<span style="color:orange">⏳ En cours</span>',
            "pending": '<span style="color:gray">🕐 En attente</span>',
            "cancelled": '<span style="color:red">❌ Annulé</span>',
        }.get(o["status"], o["status"])

        rows_html += f"""
        <tr>
          <td>{o.get('order_id','N/A')}</td>
          <td>{o.get('project_name','N/A')}</td>
          <td><a href="{o.get('target_url','')}" target="_blank">{o.get('target_url','N/A')[:50]}…</a></td>
          <td>{o.get('anchor','N/A')}</td>
          <td>{status_badge}</td>
          <td>{o.get('amount','N/A')}€</td>
        </tr>"""

    html = f"""<!DOCTYPE html>
<html lang="fr">
<head>
  <meta charset="UTF-8">
  <title>Dashboard Linkuma</title>
  <style>
    body {{ font-family: sans-serif; padding: 2rem; background: #f9f9f9; }}
    h1 {{ color: #1a1a2e; }}
    .cards {{ display: flex; gap: 1rem; margin-bottom: 2rem; }}
    .card {{ background: white; border-radius: 8px; padding: 1.5rem; flex: 1;
             box-shadow: 0 2px 8px rgba(0,0,0,.08); text-align: center; }}
    .card .value {{ font-size: 2rem; font-weight: bold; color: #1a1a2e; }}
    table {{ width: 100%; border-collapse: collapse; background: white;
             border-radius: 8px; overflow: hidden; box-shadow: 0 2px 8px rgba(0,0,0,.08); }}
    th {{ background: #1a1a2e; color: white; padding: .75rem 1rem; text-align: left; }}
    td {{ padding: .65rem 1rem; border-bottom: 1px solid #eee; font-size: .9rem; }}
    tr:last-child td {{ border-bottom: none; }}
  </style>
</head>
<body>
  <h1>Dashboard Linkuma : {datetime.now().strftime('%d/%m/%Y %H:%M')}</h1>
  <div class="cards">
    <div class="card"><div class="value">{total}</div>Total commandes</div>
    <div class="card"><div class="value" style="color:green">{delivered}</div>Livrées</div>
    <div class="card"><div class="value" style="color:orange">{in_progress}</div>En cours</div>
    <div class="card"><div class="value" style="color:gray">{pending}</div>En attente</div>
    <div class="card"><div class="value">{total_spent}€</div>Dépensé</div>
  </div>
  <table>
    <thead><tr>
      <th>ID</th><th>Projet</th><th>URL cible</th><th>Ancre</th><th>Statut</th><th>Montant</th>
    </tr></thead>
    <tbody>{rows_html}</tbody>
  </table>
</body>
</html>"""

    Path(output_path).write_text(html, encoding="utf-8")
    print(f"Dashboard généré : {output_path}")


if __name__ == "__main__":
    orders = fetch_all_orders()
    generate_dashboard(orders)

Alertes automatiques

Recevez une notification dès qu’une commande change de statut, sans vous connecter manuellement à la plateforme.

Webhook Slack : commande livrée

import requests
import json

LINKUMA_TOKEN = "VOTRE_TOKEN_ICI"
SLACK_WEBHOOK_URL = "https://hooks.slack.com/services/XXX/YYY/ZZZ"
API_BASE = "https://app.linkuma.com/api/v1"

def check_newly_delivered(last_check_timestamp: str) -> list:
    """Récupère les commandes livrées depuis le dernier check."""
    res = requests.get(
        f"{API_BASE}/orders",
        headers={"Authorization": f"Bearer {LINKUMA_TOKEN}"},
        params={"status": "delivered", "delivered_after": last_check_timestamp}
    )
    res.raise_for_status()
    return res.json().get("data", [])


def notify_slack(order: dict):
    """Envoie une notification Slack pour une commande livrée."""
    payload = {
        "text": f"*Backlink livré ✅*",
        "blocks": [
            {
                "type": "section",
                "text": {
                    "type": "mrkdwn",
                    "text": (
                        f"*Commande #{order['order_id']}* livrée !\n"
                        f"• Projet : `{order['project_name']}`\n"
                        f"• URL cible : <{order['target_url']}|{order['target_url']}>\n"
                        f"• Ancre : `{order['anchor']}`\n"
                        f"• Lien livré : <{order.get('delivered_url', 'N/A')}|Voir le lien>"
                    )
                }
            }
        ]
    }
    requests.post(SLACK_WEBHOOK_URL, json=payload)
    print(f"Slack notifié pour {order['order_id']}")


# Exécution (à appeler via cron toutes les heures)
if __name__ == "__main__":
    from datetime import datetime, timedelta, timezone
    one_hour_ago = (datetime.now(timezone.utc) - timedelta(hours=1)).isoformat()
    orders = check_newly_delivered(one_hour_ago)
    for order in orders:
        notify_slack(order)
    print(f"{len(orders)} commande(s) notifiée(s).")

Planifiez ce script via cron ou un service comme GitHub Actions pour une surveillance continue. Exemple crontab : 0 * * * * python3 /opt/scripts/linkuma-alerts.py

Rotation de projets et budgets

Pour les agences gérant plusieurs clients, automatisez la répartition des commandes selon les budgets alloués.

import requests
from dataclasses import dataclass

API_BASE = "https://app.linkuma.com/api/v1"
API_TOKEN = "VOTRE_TOKEN_ICI"
HEADERS = {"Authorization": f"Bearer {API_TOKEN}", "Content-Type": "application/json"}


@dataclass
class Client:
    name: str
    project_id: str
    monthly_budget: float  # Budget mensuel en euros
    spent: float = 0.0

    @property
    def remaining(self) -> float:
        return self.monthly_budget - self.spent


def get_project_spending(project_id: str) -> float:
    """Calcule le total dépensé sur un projet ce mois-ci."""
    from datetime import datetime
    start_of_month = datetime.now().replace(day=1, hour=0, minute=0, second=0).isoformat()
    res = requests.get(
        f"{API_BASE}/orders",
        headers=HEADERS,
        params={"project_id": project_id, "created_after": start_of_month}
    )
    res.raise_for_status()
    orders = res.json().get("data", [])
    return sum(o.get("amount", 0) for o in orders)


def allocate_orders(clients: list[Client], orders_to_place: list[dict]):
    """
    Répartit une liste de commandes entre les clients
    en respectant leurs budgets restants.
    """
    # Mise à jour du spending actuel
    for client in clients:
        client.spent = get_project_spending(client.project_id)
        print(f"{client.name}: {client.spent}€ / {client.monthly_budget}€ (reste: {client.remaining}€)")

    placed = []
    skipped = []

    for order in orders_to_place:
        client = next((c for c in clients if c.project_id == order["project_id"]), None)
        if not client:
            skipped.append({**order, "reason": "projet introuvable"})
            continue

        if client.remaining < order["budget_max"]:
            skipped.append({**order, "reason": f"budget insuffisant ({client.remaining}€ restant)"})
            continue

        # Passer la commande
        res = requests.post(f"{API_BASE}/orders", headers=HEADERS, json=order)
        if res.ok:
            client.spent += order["budget_max"]
            placed.append(order)
            print(f"✅ Commande placée pour {client.name}: {order['target_url']}")
        else:
            skipped.append({**order, "reason": f"API error {res.status_code}"})

    print(f"\nBilan : {len(placed)} placées, {len(skipped)} ignorées")
    return placed, skipped

Monitoring SEO avec Google Search Console

Combinez l’API Linkuma avec l’API Google Search Console pour mesurer l’impact réel de vos backlinks sur vos positions.

Script Python : suivi de positions après achat de liens

import requests
from datetime import datetime, timedelta
from google.oauth2 import service_account
from googleapiclient.discovery import build

# Configuration Google Search Console
SCOPES = ['https://www.googleapis.com/auth/webmasters.readonly']
SERVICE_ACCOUNT_FILE = 'credentials.json'
SITE_URL = 'https://votresite.fr'

# Pages cibles à surveiller (celles sur lesquelles vous achetez des liens)
PAGES_TO_MONITOR = [
    '/categorie-principale/',
    '/produit-best-seller/',
    '/guide-achat/',
]

def get_gsc_data(start_date: str, end_date: str, pages: list) -> list:
    """Récupère les données de positions depuis Google Search Console."""
    credentials = service_account.Credentials.from_service_account_file(
        SERVICE_ACCOUNT_FILE, scopes=SCOPES
    )
    service = build('searchconsole', 'v1', credentials=credentials)

    results = []
    for page in pages:
        response = service.searchanalytics().query(
            siteUrl=SITE_URL,
            body={
                'startDate': start_date,
                'endDate': end_date,
                'dimensions': ['query', 'page'],
                'dimensionFilterGroups': [{
                    'filters': [{
                        'dimension': 'page',
                        'operator': 'contains',
                        'expression': page
                    }]
                }],
                'rowLimit': 25
            }
        ).execute()

        for row in response.get('rows', []):
            results.append({
                'page': page,
                'query': row['keys'][0],
                'clicks': row['clicks'],
                'impressions': row['impressions'],
                'ctr': round(row['ctr'] * 100, 2),
                'position': round(row['position'], 1)
            })

    return results


def compare_periods(days_back: int = 30):
    """Compare les positions entre deux périodes pour mesurer la progression."""
    today = datetime.now()

    # Période actuelle
    current_end = (today - timedelta(days=3)).strftime('%Y-%m-%d')
    current_start = (today - timedelta(days=3 + days_back)).strftime('%Y-%m-%d')

    # Période précédente
    previous_end = (today - timedelta(days=3 + days_back)).strftime('%Y-%m-%d')
    previous_start = (today - timedelta(days=3 + days_back * 2)).strftime('%Y-%m-%d')

    current = get_gsc_data(current_start, current_end, PAGES_TO_MONITOR)
    previous = get_gsc_data(previous_start, previous_end, PAGES_TO_MONITOR)

    # Créer un index pour la comparaison
    prev_index = {(r['page'], r['query']): r for r in previous}

    print(f"\n📊 Évolution des positions ({previous_start} → {current_end})\n")
    print(f"{'Page':<30} {'Mot-clé':<35} {'Pos. avant':>10} {'Pos. après':>10} {'Δ':>6}")
    print("-" * 95)

    for row in sorted(current, key=lambda x: x['position']):
        key = (row['page'], row['query'])
        prev = prev_index.get(key)
        if prev:
            delta = prev['position'] - row['position']
            arrow = '↑' if delta > 0 else '↓' if delta < 0 else '='
            print(f"{row['page']:<30} {row['query']:<35} {prev['position']:>10.1f} {row['position']:>10.1f} {arrow}{abs(delta):>4.1f}")


if __name__ == '__main__':
    compare_periods(30)

Lancez ce script 4 à 8 semaines après vos commandes de backlinks pour mesurer l’impact réel sur vos positions. Les backlinks mettent généralement 3 à 12 semaines pour produire leur plein effet.

Workflow agence complet

Ce workflow couvre le cycle de vie complet d’une mission client : du brief initial à la livraison du rapport.

Réception du brief client

Le client remplit un formulaire Google Forms ou Typeform avec :

Les URLs à booster
Les ancres souhaitées
Le budget mensuel
La thématique du site

Un Zap ou Make récupère les réponses et les formate en CSV.

Création automatique du projet Linkuma

curl -X POST https://app.linkuma.com/api/v1/projects \
  -H "Authorization: Bearer VOTRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Client : Nom du site",
    "website": "https://site-client.fr",
    "niche": "e-commerce",
    "notes": "Brief reçu le 21/02/2026 via Typeform"
  }'

Import des commandes depuis le CSV du brief

Lancez le script d’import CSV décrit dans la section précédente avec le project_id nouvellement créé.

Monitoring automatique

Configurez le script d’alertes Slack pour surveiller les livraisons. Le client peut être invité dans un canal Slack dédié pour suivre en temps réel.

Génération du rapport mensuel

À J+30, lancez le script de dashboard HTML et transmettez-le au client par email ou partagez-le via un lien Drive.

python3 generate-dashboard.py --project proj_001 --output rapport-client-fevrier.html

Exemple de rapport automatisé envoyé par email

import smtplib
from email.mime.multipart import MIMEMultipart
from email.mime.text import MIMEText
from email.mime.base import MIMEBase
from email import encoders
from pathlib import Path

def send_report(to_email: str, client_name: str, report_path: str):
    """Envoie le rapport HTML en pièce jointe par email."""
    msg = MIMEMultipart()
    msg["From"] = "reporting@votre-agence.fr"
    msg["To"] = to_email
    msg["Subject"] = f"Rapport Linkuma : {client_name} (Février 2026)"

    body = f"""Bonjour,

Veuillez trouver en pièce jointe votre rapport de backlinks Linkuma pour le mois de février.

Résumé :
- X liens livrés
- Budget consommé : YY€
- Prochaine livraison estimée : dans Z jours

Pour toute question, répondez à cet email.

Cordialement,
L'équipe SEO"""

    msg.attach(MIMEText(body, "plain"))

    with open(report_path, "rb") as f:
        part = MIMEBase("application", "octet-stream")
        part.set_payload(f.read())
        encoders.encode_base64(part)
        part.add_header("Content-Disposition", f"attachment; filename={Path(report_path).name}")
        msg.attach(part)

    with smtplib.SMTP_SSL("smtp.votre-agence.fr", 465) as server:
        server.login("reporting@votre-agence.fr", "MOT_DE_PASSE")
        server.send_message(msg)

    print(f"Rapport envoyé à {to_email}")

Récapitulatif des bonnes pratiques

Respectez le rate limit

Ajoutez toujours un délai de 1 seconde entre vos requêtes en mode batch. Au-delà de 60 req/min, l’API retourne un code 429 Too Many Requests.

Gérez les erreurs

Implémentez un retry avec backoff exponentiel pour les codes 429 et 5xx. Ne relancez pas en cas de 400 ou 404 sans corriger le payload.

Utilisez DRY_RUN

Avant tout passage massif, simulez toujours avec le mode DRY_RUN = True pour valider votre CSV et vos mappings sans consommer de budget.

Exportez les logs

Conservez un fichier de log horodaté pour chaque batch. En cas d’incident, vous pourrez identifier rapidement les commandes concernées.

​Automatisation avancée

​Commandes en masse via CSV + API

​Principe

​Format du CSV attendu

​Script Python : import CSV en masse

​Dashboard custom de suivi

​Script Python : génération d’un rapport HTML

​Alertes automatiques

​Webhook Slack : commande livrée

​Rotation de projets et budgets

​Monitoring SEO avec Google Search Console

​Script Python : suivi de positions après achat de liens

​Workflow agence complet

​Récapitulatif des bonnes pratiques

Respectez le rate limit

Gérez les erreurs

Utilisez DRY_RUN

Exportez les logs

Automatisation avancée

Commandes en masse via CSV + API

Principe

Format du CSV attendu

Script Python : import CSV en masse

Dashboard custom de suivi

Script Python : génération d’un rapport HTML

Alertes automatiques

Webhook Slack : commande livrée

Rotation de projets et budgets

Monitoring SEO avec Google Search Console

Script Python : suivi de positions après achat de liens

Workflow agence complet

Récapitulatif des bonnes pratiques