Documentation API REST
Documentation complète pour intégrer l'API REST Ludiks
URL de Base
Base URL
https://api.ludiks.ioAuthentification
Toutes les requêtes nécessitent votre clé API dans l'en-tête Authorization
Authorization: Bearer ldk_live_abc123...
Remplacez YOUR_API_KEY par votre vraie clé API
Points de Terminaison
POST/end-user
Crée ou met à jour un utilisateur dans votre projet
En-têtes
Content-Type: application/json Authorization: Bearer YOUR_API_KEY
Corps de la Requête
idRequired
string
Identifiant unique de l'utilisateur
fullNameOptional
string
Nom complet de l'utilisateur
emailOptional
string
Adresse email de l'utilisateur
Exemple de Requête
curl -X POST https://api.ludiks.io/end-user \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"id": "user-123",
"fullName": "John Doe",
"picture": "https://example.com/picture.jpg",
"email": "john@example.com"
}'Réponse (201 Created)
{
"success": true,
"user": {
"id": "user-123",
"fullName": "John Doe",
"picture": "https://example.com/picture.jpg",
"email": "john@example.com",
"externalId": "user-123",
"metadata": {},
"createdAt": "2024-01-01T00:00:00Z",
"lastLoginAt": "2024-01-01T00:00:00Z"
}
}POST/tracking
Envoie un événement pour tracker la progression de l'utilisateur
En-têtes
Content-Type: application/json Authorization: Bearer YOUR_API_KEY
Corps de la Requête
userIdRequired
string
Identifiant de l'utilisateur
eventNameRequired
string
Nom de l'événement à tracker
valueOptional
number
Valeur numérique associée à l'événement
timestampOptional
string (ISO 8601)
Horodatage de l'événement
Exemple de Requête
curl -X POST https://api.ludiks.io/tracking \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"userId": "user-123",
"eventName": "purchase",
"value": 99.99,
"timestamp": "2024-01-20T15:30:00Z"
}'Réponse (200 OK)
{
"success": true,
"stepCompleted": true,
"points": 150,
"rewards": [
{
"name": "Big Spender",
"description": "Made a significant purchase"
}
],
"circuitCompleted": false,
"currentStreak": 5
}GET/end-user/{userId}
Récupère le profil complet et les statistiques de l'utilisateur
En-têtes
Authorization: Bearer YOUR_API_KEY
Paramètres de Chemin
userIdRequired
string
Identifiant de l'utilisateur à récupérer
Exemple de Requête
curl -X GET https://api.ludiks.io/end-user/user-123 \ -H "Authorization: Bearer YOUR_API_KEY"
Réponse (200 OK)
{
"id": "user-123",
"fullName": "John Doe",
"email": "john@example.com",
"externalId": "user-123",
"currentStreak": 5,
"longestStreak": 12,
"metadata": {
"plan": "premium",
"signupSource": "website"
},
"circuitProgress": [
{
"id": "circuit-1",
"circuitName": "Onboarding",
"status": "completed",
"points": 500,
"startedAt": "2024-01-01T00:00:00Z",
"completedAt": "2024-01-15T10:30:00Z"
},
{
"id": "circuit-2",
"circuitName": "Power User",
"status": "in_progress",
"points": 250,
"startedAt": "2024-01-16T00:00:00Z"
}
],
"createdAt": "2024-01-01T00:00:00Z",
"lastLoginAt": "2024-01-20T15:30:00Z"
}Réponses d'Erreur
Format des réponses d'erreur de l'API
400 Bad Request
{
"error": "Invalid request",
"message": "Missing required field: userId",
"code": "VALIDATION_ERROR"
}401 Unauthorized
{
"error": "Unauthorized",
"message": "Invalid or missing API key",
"code": "AUTH_ERROR"
}404 Not Found
{
"error": "Not found",
"message": "User not found",
"code": "USER_NOT_FOUND"
}Limitation de Débit
Limites d'utilisation de l'API
- • 1000 requêtes par heure par clé API
- • 100 requêtes par minute par clé API
- • En-têtes de limitation inclus dans chaque réponse
Exemples d'Intégration
Workflow Complet avec cURL
Exemple d'un workflow complet depuis la création d'utilisateur jusqu'au suivi d'événements.
# 1. Create a new user
curl -X POST https://api.ludiks.io/end-user \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"id": "user-456",
"fullName": "Alice Smith",
"email": "alice@example.com"
}'
# 2. Track user events
curl -X POST https://api.ludiks.io/tracking \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"userId": "user-456",
"eventName": "signup_completed"
}'
curl -X POST https://api.ludiks.io/tracking \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"userId": "user-456",
"eventName": "purchase",
"value": 49.99
}'
# 3. Get user profile with progress
curl -X GET https://api.ludiks.io/end-user/user-456 \
-H "Authorization: Bearer YOUR_API_KEY"Intégration JavaScript
Exemple d'intégration JavaScript avec gestion d'erreurs et fonctions utilitaires.
const API_BASE = 'https://api.ludiks.io';
const API_KEY = 'your-api-key';
const headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + API_KEY
};
async function createUser(userData) {
const response = await fetch(API_BASE + '/end-user', {
method: 'POST',
headers,
body: JSON.stringify(userData)
});
return response.json();
}
async function trackEvent(userId, eventName, value = null) {
const response = await fetch(API_BASE + '/tracking', {
method: 'POST',
headers,
body: JSON.stringify({
userId,
eventName,
value,
timestamp: new Date().toISOString()
})
});
return response.json();
}
async function getUserProfile(userId) {
const response = await fetch(API_BASE + '/end-user/' + userId, {
headers
});
return response.json();
}
// Usage example
(async () => {
try {
// Create user
const user = await createUser({
id: 'user-789',
fullName: 'Bob Johnson',
email: 'bob@example.com'
});
// Track events
const loginEvent = await trackEvent('user-789', 'login');
const purchaseEvent = await trackEvent('user-789', 'purchase', 199.99);
// Get profile
const profile = await getUserProfile('user-789');
console.log('User streak:', profile.currentStreak);
} catch (error) {
console.error('API Error:', error);
}
})();