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

# Introduction à l'API Linkuma

> Tout ce qu'il faut savoir pour commencer à utiliser l'API REST Linkuma : authentification, URL de base, rate limiting et codes de statut HTTP.

## Vue d'ensemble

L'API Linkuma vous permet d'intégrer la plateforme de backlinks directement dans vos outils, CRM ou workflows automatisés. Elle expose des endpoints REST qui acceptent et renvoient du JSON.

Vous pouvez l'utiliser pour :

* Consulter les types de commandes et les thématiques disponibles
* Gérer vos projets
* Calculer des prix et soumettre des commandes de backlinks
* Suivre l'état de vos commandes
* Consulter votre solde de crédits

<Info>
  L'API est en accès **bêta**. Des évolutions peuvent intervenir sur certains endpoints.
</Info>

***

## URL de base

Toutes les requêtes doivent être adressées à :

```
https://app.linkuma.com
```

Exemple complet :

```
https://app.linkuma.com/api/v1/orders/types
```

***

## Authentification

L'API utilise des tokens **Bearer**. Chaque requête aux endpoints protégés doit inclure votre token dans l'en-tête `Authorization`.

### Obtenir votre token

1. Connectez-vous à votre compte sur [app.linkuma.com](https://app.linkuma.com)
2. Accédez à votre page **Profil**
3. Copiez votre **clé API** dans la section dédiée

<Warning>
  Votre token est confidentiel. Ne le partagez pas et ne le commitez pas dans un dépôt de code.
</Warning>

### Utiliser le token

Ajoutez l'en-tête suivant à chaque requête authentifiée :

```http theme={null}
Authorization: Bearer VOTRE_TOKEN_ICI
```

### Exemple avec cURL

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

***

## En-têtes communs

| En-tête         | Valeur             | Obligatoire                  |
| --------------- | ------------------ | ---------------------------- |
| `Authorization` | `Bearer <token>`   | Oui (endpoints authentifiés) |
| `Content-Type`  | `application/json` | Oui (requêtes avec body)     |
| `Accept`        | `application/json` | Recommandé                   |

***

## Rate Limiting

L'API est limitée à **60 requêtes par minute** par token. Au-delà de cette limite, les requêtes reçoivent une réponse `429 Too Many Requests`.

Les en-têtes suivants sont présents dans chaque réponse pour vous aider à gérer votre consommation :

| En-tête                 | Description                                           |
| ----------------------- | ----------------------------------------------------- |
| `x-ratelimit-limit`     | Nombre maximum de requêtes autorisées par minute      |
| `x-ratelimit-remaining` | Nombre de requêtes restantes dans la fenêtre en cours |

### Exemple de réponse en cas de dépassement

```json theme={null}
{
  "message": "Too Many Requests"
}
```

<Tip>
  Surveillez `x-ratelimit-remaining` dans vos boucles d'appels et ajoutez un délai dès qu'il approche de zéro pour éviter les erreurs 429.
</Tip>

***

## Codes de statut HTTP

| Code  | Signification         | Description                                             |
| ----- | --------------------- | ------------------------------------------------------- |
| `200` | OK                    | La requête a été traitée avec succès                    |
| `201` | Created               | La ressource a été créée avec succès                    |
| `400` | Bad Request           | Le corps ou les paramètres de la requête sont invalides |
| `401` | Unauthorized          | Token manquant ou invalide                              |
| `403` | Forbidden             | Accès refusé à la ressource demandée                    |
| `404` | Not Found             | La ressource demandée n'existe pas                      |
| `422` | Unprocessable Entity  | Erreur de validation des données envoyées               |
| `429` | Too Many Requests     | Limite de rate limiting atteinte                        |
| `500` | Internal Server Error | Erreur interne côté serveur                             |

### Format des erreurs

Les réponses d'erreur renvoient systématiquement un objet JSON avec un champ `message` :

```json theme={null}
{
  "message": "Unauthenticated."
}
```

Pour les erreurs de validation (`422`), un champ `errors` détaille les champs concernés :

```json theme={null}
{
  "message": "The given data was invalid.",
  "errors": {
    "name": ["Le champ name est obligatoire."]
  }
}
```

***

## Premiers pas avec l'API

<Steps>
  <Step title="Récupérez votre token">
    Connectez-vous sur [app.linkuma.com](https://app.linkuma.com), allez dans **Profil → API** et copiez votre Bearer token.
  </Step>

  <Step title="Testez avec un appel simple">
    Vérifiez que votre token fonctionne en appelant l'endpoint des types de commandes :

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

    Cet endpoint est public et ne nécessite pas d'authentification (parfait pour tester votre setup).
  </Step>

  <Step title="Listez vos projets">
    Votre premier appel authentifié :

    ```bash theme={null}
    curl https://app.linkuma.com/api/v1/projects \
      -H "Authorization: Bearer VOTRE_TOKEN" \
      -H "Accept: application/json"
    ```
  </Step>

  <Step title="Simulez un prix">
    Avant de passer commande, simulez le coût avec l'endpoint de calcul de prix (`POST /api/v1/carts/price`). Aucun débit n'est effectué.
  </Step>

  <Step title="Passez votre première commande">
    Utilisez `POST /api/v1/carts/order` pour soumettre votre commande. Consultez la [documentation Panier](/api-reference/endpoint/panier) pour le détail des champs.
  </Step>
</Steps>

<Info>
  Besoin d'aide ? Consultez nos [exemples d'intégration](/guides/integrations) avec Zapier, Make, Python et Node.js, ou nos [scénarios d'automatisation avancée](/guides/automatisation-avancee) pour les agences.
</Info>