Tâches

Une tâche est un correctif à faire pour que les assistants IA disent juste sur la marque : réécrire une description produit, corriger un prix dans la boutique, ajouter des données structurées à une page… Les tâches sont créées à la main, ou par Skoup depuis une alerte, un check SEO ou readiness en échec, un écart de perception, une opportunité de positionnement ou une source à conquérir (source). Chacune dit quoi changer (kind : writeback, content, technical), sa taille (effort : s, m, l) et, quand Skoup sait comment faire, un guide pas à pas.

Statuts d’une tâche

todoin_progressin_verificationverified

Une tâche avance ou recule d'une colonne à la fois. Passer en in_verification planifie la vérification (verify_at = prochain sampling hebdo). Une tâche née d'une alerte passe verified d'elle-même quand son alerte est résolue.

Je veux…

Je veux…	Appel
Créer une tâche	`POST /v1/brands/{brand}/tasks` (`title`, `kind`)
Faire avancer une tâche	`PATCH /v1/brands/{brand}/tasks/{task}` avec `status`
La marquer vérifiée avec le gain mesuré	`PATCH …/tasks/{task}` avec `status: "verified"` et `gain`
Modifier ses champs	`PATCH …/tasks/{task}` (`title`, `description`, `effort`, `impact`…)
Lister ce qui reste à faire	`GET /v1/brands/{brand}/tasks?status=todo`
Lister les correctifs nés d’alertes	`GET /v1/brands/{brand}/tasks?source=alert`
Lire une tâche et son guide	`GET /v1/brands/{brand}/tasks/{task}`
Lire le plan adapté rédigé dans l’app	`GET /v1/brands/{brand}/tasks/{task}/plan`

Scopes : tasks:read, tasks:write. Events : task.created, task.updated (avec previous_attributes), task.verified.

Scénario : synchroniser les correctifs Skoup dans Jira

Abonnez un endpoint à task.created et task.updated.
Sur task.created, créez le ticket Jira depuis data.object (titre, description, guide) et stockez-y l’id task_….
Quand le ticket avance, faites avancer la tâche Skoup d’une colonne à la fois :


curl -X PATCH https://api.skoup.ai/v1/brands/br_034PJIMnN3EOTCU3TMUdLS/tasks/task_031CQmvL2QQbe3t38Gyo91 \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{"status":"in_progress"}'

Quand le ticket est fermé, envoyez {"status":"in_verification"} : Skoup vérifie le correctif au prochain sampling hebdo. Sur task.updated, mettez le ticket à jour depuis data.object.status.

Pièges

Une colonne à la fois. todo → in_verification en un appel répond 422 invalid_transition et ne change rien : envoyez chaque étape.
Un PATCH, deux events. Un PATCH qui modifie des champs et le statut émet un task.updated par changement.
Pas de responsable par l’API : les membres de l’espace ne sont jamais exposés ; assignee est en lecture seule ({ name }).
guide ou plan ? guide est la marche à suivre standard de la famille de correctif (texte fixe, version Shopify si la marque est sur Shopify). Le plan est cette marche à suivre réécrite par une IA pour la plateforme de la marque, son activité et la preuve de la tâche. Il n’existe que si quelqu’un a cliqué « Générer un plan adapté » dans l’app : sinon 404 resource_missing. L’API le lit, elle ne le génère jamais. Un plan failed n’a pas de content : suivez le guide.
Mode test : la tâche est créée et déplacée sur le bac à sable, puis annulée — l’event task.created atteint tout de même vos endpoints de test avec livemode: false.