# 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="/files/W3n3lLuGHgCK0nkKNSqa" alt=""><figcaption></figcaption></figure> <figure><img src="/files/vNqWnDuusDDj2HEi0kSg" 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é.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.discordtop.net/documentation/getting-started/quickstart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.