bulk_update_competitor_status

bulk_update_competitor_status est le tool d'écriture du volet concurrents. Il met à jour le statut d'un ou plusieurs concurrents en un seul appel, jusqu'à 50 par batch. Utilisez-le pour agir sur la file d'auto-détection retournée par list_competitors : confirmer les vrais concurrents, rejeter le bruit, ou remettre à SUGGESTED une entrée précédemment écartée. Sur un projet e-commerce (voir update_project_settings), il déplace aussi une entité entre les trois groupes du tri de l'IA : marques concurrentes, revendeurs (là où l'acheteur est envoyé : Amazon, pharmacies, marketplaces) et produits (noms de produits).

Quand l'utiliser

Sortez-le quand l'utilisateur donne une instruction de modération du type "confirme tous les concurrents que je vois ici", "rejette ces trois faux positifs", ou "remets Otterly en suggested pour qu'on revoie". Sur un projet e-commerce, il traite aussi "Amazon est un revendeur, pas un concurrent". C'est le bon tool pour tout agent qui trie automatiquement la file de suggestions selon des règles. Combinez avec list_competitors (filtre status: ["SUGGESTED"]) pour récupérer les candidats avant l'appel.

Exige le rôle member minimum. Le rôle customer est rejeté.

Paramètres

Chaque update exige status, kind, ou les deux :

• kind: "COMPETITOR" confirme l'entité comme concurrent (statut CONFIRMED).
• kind: "RETAILER" ou "PRODUCT" la sort des concurrents : son verdict est posé et son statut passe à SUGGESTED, jamais CONFIRMED. Cela marche aussi sur une entité rejetée. Ces deux valeurs exigent un projet e-commerce, sinon l'item échoue avec not_ecommerce.

Réponse

La réponse renvoie les compteurs updated/failed et un tableau results item par item. Les erreurs par item ne bloquent pas le reste du batch : les updates valides s'appliquent quand même, et success passe à false uniquement pour signaler qu'au moins un item a échoué.

{
  "success": true,
  "updated": 2,
  "failed": 0,
  "results": [
    {
      "competitorId": "clxcomp001",
      "status": "success",
      "competitor": {
        "id": "clxcomp001",
        "canonicalName": "Otterly",
        "status": "CONFIRMED",
        "verdict": "COMPETITOR",
        "updatedAt": "2026-04-26T10:15:00.000Z"
      }
    },
    {
      "competitorId": "clxcomp002",
      "status": "success",
      "competitor": {
        "id": "clxcomp002",
        "canonicalName": "Amazon",
        "status": "SUGGESTED",
        "verdict": "RETAILER",
        "updatedAt": "2026-04-26T10:15:00.000Z"
      }
    }
  ]
}

Chaque competitor porte son nouveau status et son verdict (null quand l'entité n'a jamais été jugée).

Si un competitorId est invalide ou appartient à un autre projet, l'entrée renvoie status: "error" avec un code error (competitor_not_found) et un message. Un kind RETAILER ou PRODUCT sur un projet qui n'est pas e-commerce renvoie not_ecommerce. Dans les deux cas, success passe à false pour tout le batch. Les updates valides s'appliquent quand même.

Conseils et patterns

• Lisez toujours success et le results[].status de chaque item pour détecter les échecs partiels.
• Batchez jusqu'à la limite de 50 items pour minimiser les allers-retours. Au-delà, paginez côté agent.
• Gérez proprement le cas d'un utilisateur customer : attrapez l'erreur de rôle et renvoyez la requête vers un membre plus privilégié.
• Pour nettoyer un projet e-commerce, listez les entités avec list_competitors et filters.verdict, puis renvoyez les mauvaises avec kind.
• Réinitialiser à SUGGESTED réinjecte le concurrent dans la file de modération ; ne l'utilisez pas comme un soft-delete.

Tools liés

• list_competitors : lister les candidats à traiter (utiliser filters.status: ["SUGGESTED"]).
• list_competitor_sources : inspecter l'empreinte d'un concurrent avant de confirmer ou rejeter.
• update_project_settings : activer le mode e-commerce pour que RETAILER et PRODUCT soient acceptés.