API développeurs · Cubaria · Marketplace de ressources Minecraft

Introduction

L'API expose en lecture le catalogue public, et en lecture/téléchargement les données liées à votre compte (commandes, achats, ressources vendues). Il n'y a pas de limite de requêtes appliquée actuellement.

Authentification

Deux méthodes, au choix selon votre cas d'usage :

Clé API personnelle - générée depuis votre profil › onglet API. Donne accès à toutes les portées de votre propre compte. Idéale pour un script perso.
Jeton OAuth - obtenu via le flow authorization_code pour une application tierce agissant au nom d'un utilisateur, avec accès limité aux portées accordées. Voir OAuth.

Dans les deux cas, envoyez le jeton dans l'en-tête de chaque requête protégée :

Authorization: Bearer VOTRE_JETON

Alternative pour les clés API : en-tête X-Api-Key: VOTRE_CLE_API.

Erreurs

Les erreurs renvoient un corps JSON avec un champ message (endpoints /api/*) et le code HTTP correspondant.

{
  "message": "Portée « profile » requise pour ce jeton."
}

Code	Signification
`401`	Jeton manquant, invalide ou expiré.
`403`	Portée insuffisante, ou ressource ne vous appartenant pas.
`404`	Ressource ou fichier introuvable.

Produits

Ressources publiées sur la marketplace. Endpoints publics, aucune authentification requise.

GET /api/products Public

Lister les ressources

Recherche et filtre les ressources publiées (non privées).

Paramètre	Type	Requis	Description
`q`	string	non	Recherche plein texte sur le titre, la description courte et les mots-clés (tags).
`category`	string	non	Slug de catégorie. Un slug inconnu renvoie une liste vide.
`free`	bool	non	À 1, ne renvoie que les ressources gratuites (prix = 0).
`sort`	string	non	recent (défaut), popular, rating, price_asc, price_desc.
`page`	int	non	Numéro de page. Défaut 1.
`per_page`	int	non	Résultats par page. Défaut 20, max 100.

Requête

curl "https://cubaria.fr/api/products?q=bedwars&sort=popular&per_page=10"

Réponse

{
  "data": [
    {
      "id": 12,
      "slug": "serveur-bedwars-8-equipes",
      "title": "Serveur BedWars 8 équipes",
      "short_description": "Serveur BedWars préconfiguré, prêt à l'emploi.",
      "tags": ["serveur", "préconfiguré", "prêt à l'emploi"],
      "category": { "name": "Serveurs préconfigurés", "slug": "serveurs-preconfigures" },
      "seller": { "name": "Studio Redstone" },
      "price": 19.99,
      "compare_at_price": null,
      "is_free": false,
      "minecraft_version": "1.20.6",
      "rating": { "average": 4.8, "count": 1 },
      "sales": 61,
      "thumbnail": "https://cubaria.test/storage/products/bedwars.png",
      "url": "https://cubaria.test/ressources/serveur-bedwars-8-equipes"
    }
  ],
  "meta": { "current_page": 1, "last_page": 2, "per_page": 10, "total": 16 }
}

200 Résultats renvoyés (liste vide possible).

GET /api/products/{slug} Public

Détail d'une ressource

Description complète, versions et changelog. Une ressource privée n'est visible que par son propriétaire authentifié.

Paramètre	Type	Requis	Description
`slug`	string	oui	Slug de la ressource, dans l'URL.

Requête

curl "https://cubaria.fr/api/products/serveur-bedwars-8-equipes"

Réponse

{
  "data": {
    "id": 12,
    "slug": "serveur-bedwars-8-equipes",
    "title": "Serveur BedWars 8 équipes",
    "short_description": "Serveur BedWars préconfiguré, prêt à l'emploi.",
    "tags": ["serveur", "préconfiguré", "prêt à l'emploi"],
    "category": { "name": "Serveurs préconfigurés", "slug": "serveurs-preconfigures" },
    "seller": { "name": "Studio Redstone" },
    "price": 19.99,
    "compare_at_price": null,
    "is_free": false,
    "minecraft_version": "1.20.6",
    "rating": { "average": 4.8, "count": 1 },
    "sales": 61,
    "thumbnail": "https://cubaria.test/storage/products/bedwars.png",
    "url": "https://cubaria.test/ressources/serveur-bedwars-8-equipes",
    "description": "Texte complet de la fiche produit...",
    "requirements": "Hébergement Minecraft Java (Paper/Spigot recommandé), compatible 1.20.6.",
    "support_url": "https://discord.gg/studio-redstone",
    "versions": [
      {
        "version": "1.2.0",
        "minecraft_version": "1.20.6",
        "loader": "paper",
        "status": "release",
        "changelog": "Correctifs de configuration.",
        "file_size": 5242880,
        "released_at": "2026-07-25T10:00:00+00:00"
      }
    ]
  }
}

200 Ressource trouvée.

404 Introuvable, non publiée, ou privée et non possédée.

Catégories

Catégories disponibles sur la marketplace, avec nombre de ressources publiées.

GET /api/categories Public

Lister les catégories

Requête

curl "https://cubaria.fr/api/categories"

Réponse

{
  "data": [
    { "name": "Maps", "slug": "maps", "products_count": 3 },
    { "name": "Serveurs préconfigurés", "slug": "serveurs-preconfigures", "products_count": 4 }
  ]
}

200 Toujours.

Mon compte

Nécessite une authentification (clé API ou jeton OAuth). Chaque endpoint exige la portée indiquée.

GET /api/me Portée profile

Profil courant

Requête

curl "https://cubaria.fr/api/me" \
  -H "Authorization: Bearer VOTRE_CLE_API"

Réponse

{
  "data": {
    "id": 8,
    "name": "T-Tron",
    "email": "ttron@example.com",
    "is_seller": true,
    "balance": 42.5
  }
}

200 OK.

401 Jeton manquant, invalide ou expiré.

403 Portée profile manquante.

GET /api/me/orders Portée orders

Mes commandes

Requête

curl "https://cubaria.fr/api/me/orders" \
  -H "Authorization: Bearer VOTRE_CLE_API"

Réponse

{
  "data": [
    {
      "reference": "CMD-2026-00042",
      "total": 39.99,
      "status": "paid",
      "created_at": "2026-08-14T09:12:00+00:00",
      "items": [
        { "title": "Éclats de Rubis", "price": 39.99 }
      ]
    }
  ]
}

200 OK.

401 Jeton manquant, invalide ou expiré.

403 Portée orders manquante.

GET /api/me/downloads Portée downloads

Mes téléchargements

Ressources achetées, avec lien de téléchargement direct.

Requête

curl "https://cubaria.fr/api/me/downloads" \
  -H "Authorization: Bearer VOTRE_CLE_API"

Réponse

{
  "data": [
    {
      "product_id": 12,
      "slug": "serveur-bedwars-8-equipes",
      "title": "Serveur BedWars 8 équipes",
      "category": "Serveurs préconfigurés",
      "downloads_count": 2,
      "download_url": "https://cubaria.fr/api/products/serveur-bedwars-8-equipes/download"
    }
  ]
}

200 OK.

401 Jeton manquant, invalide ou expiré.

403 Portée downloads manquante.

GET /api/products/{slug}/download Portée downloads

Télécharger une ressource achetée

Renvoie le fichier .zip de la dernière version (ou du fichier historique si aucune version n'en a). Incrémente le compteur de téléchargements.

Paramètre	Type	Requis	Description
`slug`	string	oui	Slug de la ressource, dans l'URL.

Requête

curl -L "https://cubaria.fr/api/products/serveur-bedwars-8-equipes/download" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -o ressource.zip

Réponse

Corps binaire (application/zip), pas de JSON.

200 Fichier renvoyé.

401 Jeton manquant, invalide ou expiré.

403 Ressource non achetée, ou portée downloads manquante.

404 Fichier indisponible.

Mes ressources (vendeur)

Gestion de vos propres ressources publiées, y compris privées. Réservé au propriétaire de chaque ressource.

GET /api/me/resources Portée resources:private

Lister mes ressources

Inclut vos ressources non publiées et privées.

Requête

curl "https://cubaria.fr/api/me/resources" \
  -H "Authorization: Bearer VOTRE_CLE_API"

Réponse

{
  "data": [
    {
      "id": 12,
      "slug": "serveur-bedwars-8-equipes",
      "title": "Serveur BedWars 8 équipes",
      "category": "Serveurs préconfigurés",
      "price": 19.99,
      "is_published": true,
      "is_private": false,
      "sales": 61,
      "download_url": "https://cubaria.fr/api/me/resources/serveur-bedwars-8-equipes/download"
    }
  ]
}

200 OK.

401 Jeton manquant, invalide ou expiré.

403 Portée resources:private manquante.

GET /api/me/resources/{slug}/download Portée resources:private

Télécharger une de mes ressources

Renvoie le fichier .zip, sans vérifier d'achat (propriétaire uniquement).

Paramètre	Type	Requis	Description
`slug`	string	oui	Slug de la ressource, dans l'URL.

Requête

curl -L "https://cubaria.fr/api/me/resources/serveur-bedwars-8-equipes/download" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -o ressource.zip

Réponse

Corps binaire (application/zip), pas de JSON.

200 Fichier renvoyé.

401 Jeton manquant, invalide ou expiré.

403 Vous n'êtes pas propriétaire de cette ressource, ou portée manquante.

404 Fichier indisponible.

OAuth - vue d'ensemble

Permet à une application tierce d'agir au nom d'un utilisateur Cubaria, avec un accès limité aux portées qu'il accorde explicitement (flow authorization_code).

1. Créez une application dans Profil › API › Applications OAuth pour obtenir un client_id et un client_secret, en déclarant votre redirect_uri.

Portée	Donne accès à
`profile`	Lire votre profil (nom, e-mail).
`orders`	Consulter vos commandes.
`downloads`	Lister et télécharger vos ressources achetées.
`resources:read`	Lire les ressources publiques.
`resources:private`	Accéder à vos ressources privées.

OAuth - Autorisation

2. Redirigez l'utilisateur vers l'écran de consentement :

https://cubaria.fr/oauth/authorize?client_id=VOTRE_CLIENT_ID
  &redirect_uri=VOTRE_REDIRECT_URI
  &scope=profile+downloads+resources:private
  &state=xyz

3. Si l'utilisateur accepte, Cubaria redirige vers votre redirect_uri avec ?code=...&state=.... S'il refuse : ?error=access_denied&state=....

Les portées demandées non reconnues sont ignorées ; sans portée valide, profile est accordée par défaut. Le code d'autorisation expire après 10 minutes et n'est utilisable qu'une fois.

OAuth - Échange du jeton

4. Échangez le code contre un jeton d'accès :

POST /oauth/token Public (authentifié par client_secret)

curl -X POST "https://cubaria.fr/oauth/token" \
  -d grant_type=authorization_code \
  -d client_id=VOTRE_CLIENT_ID \
  -d client_secret=VOTRE_CLIENT_SECRET \
  -d redirect_uri=VOTRE_REDIRECT_URI \
  -d code=LE_CODE

Réponse

{
  "token_type": "Bearer",
  "access_token": "...",
  "expires_in": 2592000,
  "scope": "profile downloads"
}

Le jeton d'accès est valable 30 jours. Utilisez-le comme un Bearer sur les endpoints ci-dessus, dans la limite des portées accordées.

Erreur	Code	Cause
`unsupported_grant_type`	400	`grant_type` autre que `authorization_code`.
`invalid_client`	401	Client inconnu, révoqué, ou `client_secret` incorrect.
`invalid_grant`	400	Code inconnu, déjà utilisé, expiré, ou `redirect_uri` différent de celui de l'autorisation.

API Cubaria

Introduction

Authentification

Erreurs

Produits

Lister les ressources

Détail d'une ressource

Catégories

Lister les catégories

Mon compte

Profil courant

Mes commandes

Mes téléchargements

Télécharger une ressource achetée

Mes ressources (vendeur)

Lister mes ressources

Télécharger une de mes ressources

OAuth - vue d'ensemble

OAuth - Autorisation

OAuth - Échange du jeton