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

# Introduction

> Comprendre quand et comment utiliser l'API GraphQL de Bonx.

[GraphQL](https://graphql.org/learn/) est un langage de requête pour les API. Il
permet de demander uniquement les données dont vous avez besoin.

L'API GraphQL de Bonx donne accès aux données de votre espace : commandes,
réceptions, expéditions, articles, stock, production, qualité, facturation,
tables additionnelles et champs additionnels.

## Quand utiliser GraphQL ?

Utilisez GraphQL pour lire plusieurs données liées en une seule requête. Par
exemple, vous pouvez récupérer une réception, ses lignes et les articles de ces
lignes dans le même appel.

Pour la plupart des intégrations et pour modifier des données, utilisez plutôt
l'[API REST](/fr/api-reference/list-sales-orders). GraphQL est destiné aux lectures
avancées. Une exception permet de [rattacher un document à une
fiche](/fr/graphql/files).

## Principes

* **Une seule URL** : envoyez toutes les requêtes en `POST` vers l'URL GraphQL de
  votre espace.
* **Une réponse ciblée** : listez les champs que vous voulez recevoir.
* **Un schéma consultable** : les outils compatibles peuvent lire le schéma et
  proposer les champs disponibles, y compris vos champs additionnels.

## Authentification

Chaque requête doit contenir un jeton d'API dans l'en-tête `x-api-key`. Consultez
[Authentification](/fr/authentication) pour créer ce jeton.

L'URL GraphQL de votre espace est fournie avec le jeton. Les exemples utilisent
les variables `$BONX_GRAPHQL_URL` et `$BONX_API_KEY`.

```bash theme={null}
curl -X POST "$BONX_GRAPHQL_URL" \
  -H "x-api-key: $BONX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ receivings(limit: 1) { id name } }"}'
```

<Warning>
  Un jeton donne accès aux données de votre espace. Ne l'ajoutez jamais dans du code exécuté dans un navigateur.
  Révoquez-le immédiatement s'il est exposé.
</Warning>

## Structure d'une requête

Envoyez un objet JSON avec une clé `query`. Ajoutez une clé `variables` si la
requête utilise des valeurs dynamiques.

```json theme={null}
{
  "query": "query GetReceiving($id: Int!) { receivingsByPk(id: $id) { id name } }",
  "variables": { "id": 412 }
}
```

Utilisez des variables au lieu d'insérer directement des valeurs dans la chaîne
`query`.

## Noms des opérations

| Action | Exemple |
| - | - |
| Lire une liste | `receivings`, `salesOrders` |
| Lire une fiche par son identifiant | `receivingsByPk(id: 412)` |
| Créer une fiche | `insertReceivingsOne(object: { … })` |
| Modifier une fiche | `updateReceivingsByPk(pkColumns: { id: 412 }, _set: { … })` |
| Compter ou calculer sur plusieurs fiches | `receivingsAggregate` |

Les droits du jeton déterminent les opérations disponibles. Toute modification
faite avec un jeton apparaît dans l'historique de la fiche et porte le nom de ce
jeton.

<Info>Passez maintenant au [Démarrage rapide](/fr/graphql/quickstart) pour envoyer votre première requête.</Info>