Panier & Commandes - Linkuma Docs

Description

Les endpoints de panier permettent de simuler un devis, de passer une commande, et de consulter l’historique de vos paniers.

Tous les endpoints de cette section nécessitent une authentification via Bearer token.

Champs d’un article de commande

Avant de passer une commande, voici la description complète des champs acceptés pour chaque article (item) dans votre panier.

type

string

required

Type de commande. Valeurs : basic, standard, premium.

url

string

required

URL de destination du backlink (votre page cible).

project_id

integer

required

Identifiant du projet auquel rattacher cette commande.

thematic_id

integer

required

Identifiant de la thématique choisie pour le site hôte (voir endpoint Thématiques).

qty

integer

required

Nombre de backlinks à commander pour cet article.

anchor

string

required

Type d’ancre du lien. Valeurs acceptées :

url : L’ancre est l’URL cible elle-même
generic : Ancre générique choisie par nos rédacteurs
custom : Ancre personnalisée (renseignez anchor_value)

anchor_value

string

Texte de l’ancre personnalisée. Obligatoire si anchor vaut custom.

distribution

string

required

Mode de distribution des publications. Valeurs :

direct : Publication immédiate dès que les sites sont sélectionnés
schedule : Publication planifiée selon la valeur de distribution_value

distribution_value

string

Nombre de jours sur lesquels étaler les publications. Obligatoire si distribution vaut schedule. Exemple : "30" pour 30 jours.

started_at

string (ISO 8601)

Date de démarrage souhaitée de la campagne. Utilisé avec distribution: schedule.

fast_publication

boolean

Si true, active la publication accélérée (surcoût éventuel). Par défaut : false.

pagekw

string

Mot-clé principal de la page cible. Aide nos rédacteurs à contextualiser l’article.

brief

string

Brief rédactionnel libre à destination de nos équipes de rédaction.

category_id

integer

Identifiant d’une sous-catégorie pour affiner la sélection de sites hôtes.

additional_words_count

integer

Nombre de mots supplémentaires à ajouter à l’article (au-delà du format standard). Valeurs acceptées : 100, 200, 300, 400, 500.

ytg_keyword

string

Mot-clé cible utilisé pour optimiser l’article dans une perspective SEO.

Calculer un prix

Simule le calcul du prix total pour une liste d’articles avant de passer commande. Aucun débit ni engagement.

Corps de la requête

items

array

required

Liste des articles pour lesquels calculer le prix. Chaque article suit la structure décrite dans la section Champs d’un article de commande.

Requête

curl -X POST https://app.linkuma.com/api/v1/carts/price \
  -H "Authorization: Bearer VOTRE_TOKEN_ICI" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "items": [
      {
        "type": "basic",
        "url": "https://monsite.fr/ma-page",
        "project_id": 42,
        "thematic_id": 13,
        "qty": 3,
        "anchor": "custom",
        "anchor_value": "logiciel de comptabilité",
        "distribution": "direct",
        "fast_publication": false,
        "pagekw": "logiciel comptabilité PME"
      }
    ]
  }'

Réponse

total_ht

number

Montant total hors taxes en euros.

total_ttc

number

Montant total TTC en euros.

items

array

Détail du prix par article.

{
  "total_ht": 21.00,
  "total_ttc": 25.20,
  "items": [
    {
      "type": "basic",
      "qty": 3,
      "unit_price_ht": 7.00,
      "subtotal_ht": 21.00
    }
  ]
}

Passer une commande

Soumet une commande et débite votre compte en crédits.

Corps de la requête

items

array

required

Liste des articles à commander. Même structure que pour le calcul de prix.

payment_method

string

required

Mode de paiement. Valeurs acceptées :

direct_credits : Débit immédiat des crédits disponibles sur votre compte
reversed_credits : Utilisation des crédits inversés (crédits accordés par Linkuma)

Requête

curl -X POST https://app.linkuma.com/api/v1/carts/order \
  -H "Authorization: Bearer VOTRE_TOKEN_ICI" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "payment_method": "direct_credits",
    "items": [
      {
        "type": "basic",
        "url": "https://monsite.fr/ma-page",
        "project_id": 42,
        "thematic_id": 13,
        "qty": 3,
        "anchor": "custom",
        "anchor_value": "logiciel de comptabilité",
        "distribution": "schedule",
        "distribution_value": "30",
        "started_at": "2026-03-01T00:00:00Z",
        "fast_publication": false,
        "pagekw": "logiciel comptabilité PME",
        "additional_words_count": 100
      }
    ]
  }'

Réponse

cart_id

integer

Identifiant du panier créé.

status

string

Statut de la commande. Ex : pending, in_progress, completed.

total_ht

number

Montant total débité hors taxes.

orders

array

Liste des commandes individuelles créées.

{
  "cart_id": 1089,
  "status": "pending",
  "total_ht": 21.00,
  "orders": [
    {
      "id": 5512,
      "type": "basic",
      "url": "https://monsite.fr/ma-page",
      "qty": 3,
      "status": "pending"
    }
  ]
}

Assurez-vous d’avoir un solde de crédits suffisant avant de soumettre une commande. Une réponse 422 est retournée si le solde est insuffisant.

Lister les paniers

Retourne la liste de tous vos paniers (commandes groupées).

Requête

curl https://app.linkuma.com/api/v1/carts \
  -H "Authorization: Bearer VOTRE_TOKEN_ICI" \
  -H "Accept: application/json"

Réponse

data

array

Liste de vos paniers.

Show Propriétés d'un panier

integer

Identifiant unique du panier.

status

string

Statut global du panier (pending, in_progress, completed).

total_ht

number

Montant total HT du panier.

created_at

string (ISO 8601)

Date de création du panier.

orders_count

integer

Nombre de commandes dans ce panier.

{
  "data": [
    {
      "id": 1089,
      "status": "in_progress",
      "total_ht": 21.00,
      "created_at": "2026-02-21T14:00:00Z",
      "orders_count": 1
    },
    {
      "id": 1045,
      "status": "completed",
      "total_ht": 84.00,
      "created_at": "2026-01-10T09:00:00Z",
      "orders_count": 4
    }
  ]
}

Récupérer un panier

Retourne le détail complet d’un panier, incluant toutes ses commandes.

Paramètre de chemin (path)

cart_id

integer

required

Identifiant unique du panier.

Requête

curl https://app.linkuma.com/api/v1/carts/1089 \
  -H "Authorization: Bearer VOTRE_TOKEN_ICI" \
  -H "Accept: application/json"

Réponse

{
  "data": {
    "id": 1089,
    "status": "in_progress",
    "total_ht": 21.00,
    "created_at": "2026-02-21T14:00:00Z",
    "orders": [
      {
        "id": 5512,
        "type": "basic",
        "url": "https://monsite.fr/ma-page",
        "thematic": "Marketing & SEO",
        "qty": 3,
        "anchor": "logiciel de comptabilité",
        "status": "in_progress",
        "distribution": "schedule",
        "started_at": "2026-03-01T00:00:00Z"
      }
    ]
  }
}

Bonnes pratiques

Simulez avant de commander

Utilisez toujours POST /carts/price avant POST /carts/order. Cela vous permet de valider le montant total et de détecter d’éventuelles erreurs dans vos paramètres sans risque de débit.

Groupez vos articles

Passez un maximum d’articles dans un seul panier plutôt que de créer un panier par article. Cela facilite le suivi et la facturation.

Planifiez la distribution

Pour les campagnes de plus de 5 liens, utilisez distribution: schedule avec une valeur de 30 à 60 jours. Cela simule une acquisition naturelle de liens et évite les pics suspects.

Vérifiez votre solde

Avant un batch de commandes, appelez GET /account pour vérifier votre solde de crédits. Un solde insuffisant retourne une erreur 422.

Erreurs courantes

422 : Solde insuffisant

Votre compte n’a pas assez de crédits pour couvrir le montant total de la commande. Rechargez votre compte depuis le dashboard, puis relancez la commande.

422 : Projet introuvable

Le project_id renseigné n’existe pas ou n’appartient pas à votre compte. Vérifiez avec GET /projects la liste de vos projets actifs.

422 : Thématique invalide

Le thematic_id n’est pas reconnu. Consultez GET /thematics pour récupérer la liste des thématiques disponibles et leurs identifiants.

422 : Ancre custom sans valeur

Vous avez renseigné anchor: custom sans fournir de anchor_value. Ajoutez le texte d’ancre souhaité dans le champ anchor_value.

​Description

​Champs d’un article de commande

​Calculer un prix

​Corps de la requête

​Requête

​Réponse

​Passer une commande

​Corps de la requête

​Requête

​Réponse

​Lister les paniers

​Requête

​Réponse

​Récupérer un panier

​Paramètre de chemin (path)

​Requête

​Réponse

​Bonnes pratiques

Simulez avant de commander

Groupez vos articles

Planifiez la distribution

Vérifiez votre solde

​Erreurs courantes

Description

Champs d’un article de commande

Calculer un prix

Corps de la requête

Requête

Réponse

Passer une commande

Corps de la requête

Requête

Réponse

Lister les paniers

Requête

Réponse

Récupérer un panier

Paramètre de chemin (path)

Requête

Réponse

Bonnes pratiques

Erreurs courantes