# Démarrage rapide

En moins de 5 minutes, vous allez :

1. Obtenir votre clé API
2. Faire votre premier appel à l’endpoint `/v7/vote-check`
3. Comprendre comment interpréter la réponse
4. Intégrer la logique dans votre bot, CMS ou site web

{% hint style="warning" %}
Il est nécessaire d'avoir la permission `ADMINISTRATOR` sur le serveur Discord visés !
{% endhint %}

### 🧩 Obtenir votre clé API

Votre clé API est **liée à votre serveur Discord**.\
Elle permet d’authentifier vos requêtes et doit rester secrète.

Pour récupérer votre clé API :

1. Rendez-vous sur le tableau de bord DiscordTop
2. Allez dans **Développeur & API**
3. Cliquez sur **Générer ma clé API**
4. Copiez-la et stockez-la dans une variable d’environnement

<div data-full-width="false"><figure><img src="https://4036411232-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ1O8haSztScRfu0fy1yo%2Fuploads%2FUl5pZo9oSipMeZtQvASe%2FSans%20titre-1.png?alt=media&#x26;token=e4601f48-f304-431e-a5ea-0d23db95fc46" alt=""><figcaption></figcaption></figure> <figure><img src="https://4036411232-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ1O8haSztScRfu0fy1yo%2Fuploads%2FuvzIpASK34fDw2bh8x78%2FSans%20titre-1.png?alt=media&#x26;token=02fd1c36-464f-4d6a-8fff-e9c324768cc5" alt=""><figcaption></figcaption></figure></div>

Stockez votre clé API dans une variable d'environnement, par exemple :&#x20;

```ini
DISCORDTOP_API_TOKEN="dtop_xxxxxxxxxxxxxxxxxxxxxxxxxx"
```

{% hint style="info" %}
Votre clé API est stocké par serveur, donc l'ensemble des membres de votre serveur possédant la permission ADMINISTRATOR aura accès à la clé API !
{% endhint %}

{% hint style="info" %}
En cas de vol de votre clé, vous pouvez regénéré une nouvelle clé depuis votre tableau de bord !
{% endhint %}

{% hint style="danger" %}
⚠️ **Ne partagez jamais votre clé API publiquement.**
{% endhint %}

{% hint style="danger" %}
⚠️ **Ne l’envoyez jamais dans votre front-end (seulement côté serveur).**
{% endhint %}

### 🔌 Faire votre premier appel

L’endpoint principal est :

```bash
GET https://api.discordtop.net/v7/vote-check
```

Vous pouvez identifier un utilisateur de deux façons :

#### 👉 Avec son **discord\_id**

(identifiant Discord, recommandé si vous avez un bot où si vous utilisez l'oAuth2)

#### 👉 Avec un **external\_id**

(pseudo Minecraft, identifiant de site, ID interne, etc.)

### Exemple : vérifier un vote via `discord_id`

```sh
curl -X GET "https://api.discordtop.net/v7/vote-check?discord_id=123456789012345678" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Accept-Language: fr"
```

#### Exemple en JavaScript (Node)

```js
const res = await fetch(
  "https://api.discordtop.net/v7/vote-check?discord_id=123456789012345678",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.DISCORDTOP_API_TOKEN}`,
      "Accept-Language": "fr", // optionnel
    },
  }
);

// Exemple de gestion d'erreur
if (res.status === 429) {
  const body = await res.json();
  console.log("Rate limited, retry after", body.retry_after, "seconds");
  process.exit(1);
}

const data = await res.json();
console.log(data);
/*
  {
    has_voted: true,
    cooldown_remaining_seconds: 0
  }
*/
```

### 📥Réponse

Exemple de réponse complète :

```json
{
  "ok": true,
  "guild_id": "1071463831638900836",
  "has_voted": true,
  "last_vote_at": "2025-11-27T17:57:33.017+01:00",
  "next_vote_at": "2025-11-27T18:57:33.017+01:00",
  "cooldown_remaining_seconds": 3579.103
}
```

{% hint style="info" %}
Référez-vous à API Référence afin d'avoir des détails sur la réponse
{% endhint %}

#### Résumé logique :

* `has_voted = true` → **L’utilisateur a voté cette dernière heure**
* `has_voted = false` → **L’utilisateur n'a pas voté sur les 60 dernières minutes (1h)**

#### 🧪 Exemple d’intégration simple

Bot Discord (JavaScript)

```js
if (!data.has_voted) {
  await interaction.reply("🎉 Merci pour ton vote ! Voici ta récompense.");
} else {
  const minutes = Math.ceil(data.cooldown_remaining_seconds / 60);
  await interaction.reply(`⏳ Tu pourras revoter dans ${minutes} minutes.`);
}
```

### Exemple : vérifier un vote via `external_id`

```sh
curl -X GET "https://api.discordtop.net/v7/vote-check?external_id=PlayerNameForExemple" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Accept-Language: fr"
```

**Cas typiques d’utilisation :**

* vérifier les votes d’un joueur Minecraft (pseudo)
* vérifier les votes d’un compte d’un site web (ID utilisateur)
* synchroniser un système interne à votre projet

{% hint style="warning" %}
Attention, l'utilisation du external\_id nécessite un lien de vote personnalisé afin que les données puissent être utilisées ! Ce système n'est pas compatible avec le vote depuis le bot DTOP !
{% endhint %}

Exemple de lien de vote :&#x20;

```bash
https://discordtop.net/guild/SERVER_ID/vote?external_id=YOUR_EXTERNAL_ID
```

Vous trouverez plus de détail dans la section dédié.