# Démarrage rapide

https://gorally.games/developpeurs/demarrage-rapide

Ce guide te mène de zéro au classement d’une catégorie, lu par l’API. Compte une dizaine de minutes.

## Avant de commencer

- Ton organisation a le forfait Ligues : c’est lui qui permet d’émettre une clé.
- Tu gères l’organisation : seules ces personnes voient l’écran Intégrations.
- Ton logiciel tourne sur un serveur. L’API ne répond pas aux appels d’un navigateur.

Il n’y a pas de bac à sable. Une clé `rk_live_` agit sur les vraies données de ton organisation. Commence donc par une clé `read`, qui ne peut rien modifier.

## Créer une clé

1. Dans Rally Ligues, ouvre la page de ton organisation.
2. Clique sur « Réglages : intégrations (clés d’API et webhooks) ».
3. Dans « Émettre une clé », donne-lui un nom, par exemple celui de ton logiciel.
4. Coche seulement la permission `read`.
5. Clique sur « Émettre la clé ».
6. Copie le secret avec « Copier le secret ». Rally ne le montre qu’une fois.

Range le secret dans une variable d’environnement de ton serveur, jamais dans ton code source. Les exemples de ce guide le lisent dans `RALLY_API_KEY`.

## Premier appel : lister tes ligues

Toutes les opérations partent de `https://gorally.games/v1`. La clé voyage dans l’en-tête `Authorization`.

**curl**

```bash
curl https://gorally.games/v1/leagues \
  -H "Authorization: Bearer $RALLY_API_KEY"
```

**JavaScript**

```js
const response = await fetch('https://gorally.games/v1/leagues', {
  headers: {
    Authorization: `Bearer ${process.env.RALLY_API_KEY}`,
  },
});
const data = await response.json();
```

**Python**

```python
import os

import requests

response = requests.get(
    "https://gorally.games/v1/leagues",
    headers={"Authorization": f"Bearer {os.environ['RALLY_API_KEY']}"},
    timeout=10,
)
data = response.json()
```

La réponse est une liste. Les ligues sont dans `data`, et `has_more` dit s’il reste une page à lire.

```json
{
  "object": "list",
  "data": [
    {
      "id": "5b0c2f9e-8a41-4d6b-9f3e-1a2b3c4d5e6f",
      "name": "Ligue du mardi",
      "sport": "CURLING",
      "sportLabel": null,
      "profile": {
        "key": "CURLING",
        "label": "Curling",
        "version": 3,
        "resourceKind": "SHEET",
        "cadence": {
          "unitsPerMatch": 8,
          "minutesPerUnit": 15,
          "matchesPerNight": 1,
          "scoreTarget": null,
          "seasonWeeks": {
            "min": 10,
            "max": 30
          }
        },
        "vocabulary": {
          "resource": {
            "one": "feuille",
            "many": "feuilles",
            "genre": "F"
          },
          "unit": {
            "one": "bout",
            "many": "bouts",
            "genre": "M"
          },
          "match": {
            "one": "partie",
            "many": "parties",
            "genre": "F"
          },
          "scoreUnit": {
            "one": "point",
            "many": "points",
            "genre": "M"
          }
        }
      },
      "timeZone": "America/Toronto"
    }
  ],
  "has_more": false
}
```

## Trouver une catégorie

Un classement appartient à une catégorie, qui appartient à une saison. Descends ce chemin une fois, puis garde les identifiants.

1. `GET /leagues/{leagueId}` rend la ligue et ses saisons, dans `seasons`.
2. `GET /seasons/{seasonId}/categories` rend les catégories de la saison.

## Lire le classement

**curl**

```bash
curl https://gorally.games/v1/categories/e2b4d6f8-1a3c-4e5b-9d7f-0c2e4a6b8d1f/standings \
  -H "Authorization: Bearer $RALLY_API_KEY"
```

**JavaScript**

```js
const response = await fetch('https://gorally.games/v1/categories/e2b4d6f8-1a3c-4e5b-9d7f-0c2e4a6b8d1f/standings', {
  headers: {
    Authorization: `Bearer ${process.env.RALLY_API_KEY}`,
  },
});
const data = await response.json();
```

**Python**

```python
import os

import requests

response = requests.get(
    "https://gorally.games/v1/categories/e2b4d6f8-1a3c-4e5b-9d7f-0c2e4a6b8d1f/standings",
    headers={"Authorization": f"Bearer {os.environ['RALLY_API_KEY']}"},
    timeout=10,
)
data = response.json()
```

Les équipes arrivent dans l’ordre du classement. `rank` donne la place, et `tied` vaut `true` quand deux équipes partagent la même.

```json
{
  "object": "list",
  "data": [
    {
      "leagueTeamId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Les Pierres",
      "rank": 1,
      "tied": false,
      "played": 4,
      "wins": 3,
      "draws": 0,
      "losses": 1,
      "scoreFor": 29,
      "scoreAgainst": 18,
      "diff": 11,
      "gamePointsFor": 0,
      "gamePointsAgainst": 0,
      "points": 9
    },
    {
      "leagueTeamId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "name": "Les Balais",
      "rank": 2,
      "tied": false,
      "played": 4,
      "wins": 2,
      "draws": 1,
      "losses": 1,
      "scoreFor": 24,
      "scoreAgainst": 21,
      "diff": 3,
      "gamePointsFor": 0,
      "gamePointsAgainst": 0,
      "points": 7
    }
  ]
}
```

Le classement est calculé à chaque lecture. Pour le suivre, écoute l’événement `match.completed` par webhook, puis relis le classement.

## Et ensuite

- Lis le guide « Authentification et scopes » avant de demander plus que `read`.
- Branche les webhooks pour ne plus interroger l’API en boucle.
- Garde le guide « Erreurs » sous la main : chaque erreur porte un `code` stable.