Recherche de plusieurs appareils

📡 POST /devices/lookup

Permet de récupérer plusieurs appareils à partir de leurs identifiants en une seule requête. Cette route est utile pour obtenir en batch les informations de plusieurs casques Pulse ou terminaux Android déjà enregistrés dans la base de données.

---

🧭 Endpoint

POST /devices/lookup
Content-Type: application/json

---

🧱 Description

Cette route accepte une liste d’identifiants (ids) et renvoie tous les appareils correspondants. Les identifiants invalides ou introuvables sont signalés séparément dans la réponse, mais ne bloquent pas la requête, sauf si le mode strict est activé.

---

🧩 Body JSON

Champ	Type	Requis	Description
ids	string[]	✅ Oui	Tableau des identifiants MongoDB des appareils à récupérer.
projection	string[]	❌ Non	Liste optionnelle des champs à inclure dans la réponse (ex. ["name", "brand"]). Si non fourni, tous les champs sont renvoyés.
strict	boolean	❌ Non	Si true, renvoie une erreur 404 si un ou plusieurs IDs sont invalides ou manquants. Par défaut false.

---

🧠 Règles de validation

• ids doit être un tableau non vide.

• Maximum 1000 IDs par requête.

• Chaque id doit être un identifiant MongoDB valide (24 caractères hexadécimaux).

• Si strict est true, la requête échoue si un seul ID est invalide ou introuvable.

---

🧾 Exemple de requête

curl -X POST https://api.pulse.fr/devices/lookup \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "66f2b5e00c0d4c3ac3b7a111",
      "66f2b5e00c0d4c3ac3b7a222",
      "not-an-objectid"
    ],
    "projection": ["name", "brand", "androidId"],
    "strict": false
  }'

---

🧩 Exemple de réponse (succès)

{
  "requested": 3,
  "returned": 1,
  "invalidIds": ["not-an-objectid"],
  "notFoundIds": ["66f2b5e00c0d4c3ac3b7a222"],
  "results": [
    {
      "_id": "66f2b5e00c0d4c3ac3b7a111",
      "name": "Pico G2 4K #12",
      "brand": "Pico",
      "androidId": "9a8a57aa9e4a6b23"
    }
  ]
}

---

🚫 Exemple de réponse (mode strict activé)

{
  "message": "Certains IDs sont invalides ou introuvables (mode strict).",
  "invalidIds": ["not-an-objectid"],
  "notFoundIds": ["66f2b5e00c0d4c3ac3b7a222"]
}

📎 Code HTTP : 404 Not Found

---

📦 Exemple de réponse (erreur serveur)

{
  "message": "Database connection failed"
}

📎 Code HTTP : 500 Internal Server Error

---

🧮 Champs de la réponse (succès)

Champ	Type	Description
requested	number	Nombre total d’IDs envoyés dans la requête.
returned	number	Nombre d’appareils effectivement trouvés.
invalidIds	string[]	Liste des identifiants invalides (non conformes à un ObjectId MongoDB).
notFoundIds	string[]	Liste des identifiants valides mais non trouvés dans la base.
results	Device[]	Liste des objets Device trouvés (structure dépend du modèle Device).

---

🧱 Structure type d’un objet Device

(Les champs exacts peuvent varier selon ton modèle Mongoose)

{
  "_id": "66f2b5e00c0d4c3ac3b7a111",
  "name": "Pico G2 4K #12",
  "product": "Pico G2 4K",
  "brand": "Pico",
  "androidId": "9a8a57aa9e4a6b23",
  "typeDevice": "vr",
  "ip": "192.168.1.33",
  "createdAt": "2025-10-29T09:45:00.000Z",
  "updatedAt": "2025-10-29T09:45:00.000Z"
}

---

🧰 Notes techniques

• ⚙️ Méthode HTTP : POST

• 📦 Consommation : JSON

• 🕒 Latence moyenne : dépend du nombre d’IDs (≈ 10 ms / 100 IDs)

• 🔒 Authentification : Requiert un token valide (selon ton middleware auth).

• 💾 Optimisation MongoDB : Utilise un $in unique avec projection optionnelle et .lean() pour des performances optimales.

---

🧭 Exemples d’usages côté client

En JavaScript (Fetch API)

const res = await fetch("/devices/lookup", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    ids: ["66f2b5e00c0d4c3ac3b7a111", "66f2b5e00c0d4c3ac3b7a222"],
    projection: ["name", "brand"]
  })
});

const data = await res.json();
console.log(data.results);