> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linkuma.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Panier & Commandes

> Calculez des prix, soumettez des commandes de backlinks et consultez vos paniers via l'API Linkuma.

## Description

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

<Note>
  Tous les endpoints de cette section nécessitent une authentification via Bearer token.
</Note>

***

## 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.

<ParamField body="type" type="string" required>
  Type de commande. Valeurs : `basic`, `standard`, `premium`.
</ParamField>

<ParamField body="url" type="string" required>
  URL de destination du backlink (votre page cible).
</ParamField>

<ParamField body="project_id" type="integer" required>
  Identifiant du projet auquel rattacher cette commande.
</ParamField>

<ParamField body="thematic_id" type="integer" required>
  Identifiant de la thématique choisie pour le site hôte (voir endpoint [Thématiques](/api-reference/endpoint/thematiques)).
</ParamField>

<ParamField body="qty" type="integer" required>
  Nombre de backlinks à commander pour cet article.
</ParamField>

<ParamField body="anchor" type="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`)
</ParamField>

<ParamField body="anchor_value" type="string">
  Texte de l'ancre personnalisée. Obligatoire si `anchor` vaut `custom`.
</ParamField>

<ParamField body="distribution" type="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`
</ParamField>

<ParamField body="distribution_value" type="string">
  Nombre de jours sur lesquels étaler les publications. Obligatoire si `distribution` vaut `schedule`. Exemple : `"30"` pour 30 jours.
</ParamField>

<ParamField body="started_at" type="string (ISO 8601)">
  Date de démarrage souhaitée de la campagne. Utilisé avec `distribution: schedule`.
</ParamField>

<ParamField body="fast_publication" type="boolean">
  Si `true`, active la publication accélérée (surcoût éventuel). Par défaut : `false`.
</ParamField>

<ParamField body="pagekw" type="string">
  Mot-clé principal de la page cible. Aide nos rédacteurs à contextualiser l'article.
</ParamField>

<ParamField body="brief" type="string">
  Brief rédactionnel libre à destination de nos équipes de rédaction.
</ParamField>

<ParamField body="category_id" type="integer">
  Identifiant d'une sous-catégorie pour affiner la sélection de sites hôtes.
</ParamField>

<ParamField body="additional_words_count" type="integer">
  Nombre de mots supplémentaires à ajouter à l'article (au-delà du format standard). Valeurs acceptées : `100`, `200`, `300`, `400`, `500`.
</ParamField>

<ParamField body="ytg_keyword" type="string">
  Mot-clé cible utilisé pour optimiser l'article dans une perspective SEO.
</ParamField>

***

## Calculer un prix

<api>POST /api/v1/carts/price</api>

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

<ParamField body="items" type="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](#champs-dun-article-de-commande).
</ParamField>

### Requête

```bash theme={null}
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

<ResponseField name="total_ht" type="number">
  Montant total hors taxes en euros.
</ResponseField>

<ResponseField name="total_ttc" type="number">
  Montant total TTC en euros.
</ResponseField>

<ResponseField name="items" type="array">
  Détail du prix par article.
</ResponseField>

```json theme={null}
{
  "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

<api>POST /api/v1/carts/order</api>

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

### Corps de la requête

<ParamField body="items" type="array" required>
  Liste des articles à commander. Même structure que pour le calcul de prix.
</ParamField>

<ParamField body="payment_method" type="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)
</ParamField>

### Requête

```bash theme={null}
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

<ResponseField name="cart_id" type="integer">
  Identifiant du panier créé.
</ResponseField>

<ResponseField name="status" type="string">
  Statut de la commande. Ex : `pending`, `in_progress`, `completed`.
</ResponseField>

<ResponseField name="total_ht" type="number">
  Montant total débité hors taxes.
</ResponseField>

<ResponseField name="orders" type="array">
  Liste des commandes individuelles créées.
</ResponseField>

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

<Warning>
  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.
</Warning>

***

## Lister les paniers

<api>GET /api/v1/carts</api>

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

### Requête

```bash theme={null}
curl https://app.linkuma.com/api/v1/carts \
  -H "Authorization: Bearer VOTRE_TOKEN_ICI" \
  -H "Accept: application/json"
```

### Réponse

<ResponseField name="data" type="array">
  Liste de vos paniers.

  <Expandable title="Propriétés d'un panier">
    <ResponseField name="id" type="integer">
      Identifiant unique du panier.
    </ResponseField>

    <ResponseField name="status" type="string">
      Statut global du panier (`pending`, `in_progress`, `completed`).
    </ResponseField>

    <ResponseField name="total_ht" type="number">
      Montant total HT du panier.
    </ResponseField>

    <ResponseField name="created_at" type="string (ISO 8601)">
      Date de création du panier.
    </ResponseField>

    <ResponseField name="orders_count" type="integer">
      Nombre de commandes dans ce panier.
    </ResponseField>
  </Expandable>
</ResponseField>

```json theme={null}
{
  "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

<api>GET /api/v1/carts/{cart_id}</api>

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

### Paramètre de chemin (path)

<ParamField path="cart_id" type="integer" required>
  Identifiant unique du panier.
</ParamField>

### Requête

```bash theme={null}
curl https://app.linkuma.com/api/v1/carts/1089 \
  -H "Authorization: Bearer VOTRE_TOKEN_ICI" \
  -H "Accept: application/json"
```

### Réponse

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Simulez avant de commander" icon="calculator">
    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.
  </Card>

  <Card title="Groupez vos articles" icon="layer-group">
    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.
  </Card>

  <Card title="Planifiez la distribution" icon="calendar">
    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.
  </Card>

  <Card title="Vérifiez votre solde" icon="wallet">
    Avant un batch de commandes, appelez `GET /account` pour vérifier votre solde de crédits. Un solde insuffisant retourne une erreur `422`.
  </Card>
</CardGroup>

## Erreurs courantes

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>
</AccordionGroup>