# Démarrage rapide

> Créez une clé d'API et effectuez vos premières appels à l'API TradeCatalog en cinq minutes.

Vous devez être le **propriétaire** d'un espace de travail TradeCatalog avec une licence Pro ou un compte pilote. Les espaces de travail de démonstration ne peuvent pas utiliser l'API.

## 1. Créer une clé d'API

1. Ouvrez votre espace de travail et allez dans **Paramètres → API**.
2. Donnez un nom à la clé que vous reconnaîtrez plus tard, comme « synchronisation des stocks Sage ».
3. Choisissez **Lecture seule** pour consulter des informations, ou **Lecture et écriture** pour mettre à jour des produits, clients et commandes.
4. Cliquez sur **Créer la clé** et copiez-la. Elle commence par `tc_live_`.

**Copiez-la maintenant:** Nous ne montrons une clé qu'une seule fois, et nous ne conservons qu'un hachage de celle-ci. Si vous la perdez, révoquez-la et créez-en une nouvelle.

Placez la clé dans une variable d'environnement pour qu'elle reste hors de votre code :

```bash
export TRADECATALOG_API_KEY="tc_live_…"
```

## 2. Vérifier que la clé fonctionne

```bash
curl https://tradecatalog.app/api/v1/workspace \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"
```

```json
{
  "data": {
    "id": "0b6c1f5e-6f7a-4a57-9a0c-2f4d4c1e8a11",
    "slug": "northgate",
    "name": "Northgate Fixings",
    "currency": "GBP",
    "timezone": "Europe/London",
    "taxLabel": "ex VAT",
    "key": { "name": "Sage stock sync", "scope": "write" }
  }
}
```

## 3. Rechercher des produits

```bash
curl "https://tradecatalog.app/api/v1/products?q=hinge&limit=2" \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"
```

L'argent est toujours en **unités mineures** de la devise de l'espace de travail, donc `1850` est £18.50.. Voir [Conventions](/docs/api/conventions).

## 4. Obtenir le prix d'un client

Transmettez le code (ou l'identifiant) du compte client et un SKU :

```bash
curl "https://tradecatalog.app/api/v1/prices?customer=OAK01&sku=HX-8510&qty=10" \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"
```

```json
{
  "data": {
    "customer": {
      "id": "7d2e4f0a-1b3c-4d5e-8f90-a1b2c3d4e5f6",
      "accountCode": "OAK01",
      "name": "Oakfield Joinery"
    },
    "sku": "HX-8510",
    "name": "Hex bolt M10 x 50 zinc",
    "qty": 10,
    "unit": 1573,
    "line": 15730,
    "list": 1850,
    "discountBp": 1500,
    "source": "brand",
    "label": "Brand discount −15%"
  },
  "currency": "GBP"
}
```

[Comment sont calculés les prix](/docs/api/prices) explique `source` et `label`.

## 5. Créer ou mettre à jour un produit

Cela nécessite une clé **Lecture et écriture**.

```bash
curl -X PUT https://tradecatalog.app/api/v1/products \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "sku": "HX-8512",
        "name": "Hex bolt M12 x 50 zinc",
        "listPrice": 2240,
        "unitLabel": "Box of 100",
        "brand": "Northgate",
        "category": "Bolts"
      }
    ]
  }'
```

```json
{
  "data": {
    "created": 1,
    "updated": 0,
    "priceChanges": 0,
    "priceChangeId": null,
    "unknownCustomers": []
  }
}
```

Les nouveaux produits sont immédiatement disponibles à leur prix de liste. Si vous envoyez un prix différent pour un produit déjà existant, le prix ne change pas encore. Il est placé dans un changement de prix en brouillon que vous devez examiner et publier dans l'application. Voir [Produits](/docs/api/products#create-or-update-products).

## Le même code en JavaScript

```js
const api = (path, init = {}) =>
  fetch(`https://tradecatalog.app/api/v1${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}`,
      'Content-Type': 'application/json',
      ...init.headers,
    },
  }).then(async (res) => {
    const body = await res.json()
    if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`)
    return body
  })

const { data: workspace } = await api('/workspace')
const { data: price } = await api('/prices?customer=OAK01&sku=HX-8510&qty=10')
console.log(`${workspace.name}: ${price.name} is ${price.unit / 100} each`)
```

## Étapes suivantes

- [Authentification](/docs/api/authentication) : portées, révocation des clés, sécurisation.
- [Erreurs](/docs/api/errors) : chaque code d'erreur et comment réessayer.
- [Synchronisation avec votre ERP](/docs/guides/erp-sync) : une synchronisation nocturne complète et un poller de commandes.
- [OpenAPI](/docs/api/openapi) : générer un client typé.