File d'attente (Jobs)

La file d'attente permet de planifier l'exécution d'automations et de pipelines de manière asynchrone. Contrairement au /trigger (exécution immédiate), l'endpoint /enqueue place la tâche dans une queue qui sera traitée dès que possible.

Idéal pour les cas d'usage batch, les intégrations n8n/Zapier, ou quand vous souhaitez un callback webhook à la fin de l'exécution.

Mettre en file une automation

POST /api/v1/automations/:id/enqueue

Scope requis : automation:execute

curl -X POST https://api.gurren.leandre.io/api/v1/automations/665a.../enqueue \
  -H "x-api-key: gfac_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "values": { "0": "john@example.com" },
    "useProxy": true,
    "enableAI": false,
    "webhookUrl": "https://example.com/callback"
  }'

Body :

Paramètre	Type	Défaut	Description
values	object	—	Valeurs dynamiques pour les actions (index → valeur)
sessionId	string	—	Réutiliser une session navigateur existante
useProxy	boolean	true	Utiliser un proxy
enableAI	boolean	true	Activer les fonctionnalités IA
prompt	string	—	Prompt IA personnalisé
captureAllSteps	boolean	false	Capturer un screenshot à chaque étape
webhookUrl	string	—	URL appelée à la fin de l'exécution (POST)

Réponse :

{
  "success": true,
  "jobId": "aaa1b2c3d4e5f6a7b8c9d0e1",
  "statusUrl": "/api/v1/jobs/aaa1b2c3d4e5f6a7b8c9d0e1"
}

---

Mettre en file un pipeline

POST /api/v1/pipelines/:id/enqueue

Scope requis : pipeline:execute

curl -X POST https://api.gurren.leandre.io/api/v1/pipelines/888a.../enqueue \
  -H "x-api-key: gfac_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session_id_optionnel",
    "webhookUrl": "https://example.com/callback"
  }'

Body :

Paramètre	Type	Description
sessionId	string	Session navigateur à réutiliser
webhookUrl	string	URL appelée à la fin de l'exécution

Réponse :

{
  "success": true,
  "jobId": "bbb1b2c3d4e5f6a7b8c9d0e2",
  "statusUrl": "/api/v1/jobs/bbb1b2c3d4e5f6a7b8c9d0e2"
}

---

Lister les jobs

GET /api/v1/jobs

Scope requis : automation:read. Filtres : status, type (automation|pipeline|intent), workspaceId (jobs d'intention de ce workspace).

curl "https://api.gurren.leandre.io/api/v1/jobs?status=pending&type=automation" \
  -H "x-api-key: gfac_votre_cle"

Query parameters :

Paramètre	Type	Valeurs possibles	Description
status	string	pending, processing, completed, failed	Filtrer par statut
type	string	automation, pipeline	Filtrer par type

Réponse :

[
  {
    "_id": "aaa1b2c3d4e5f6a7b8c9d0e1",
    "type": "automation",
    "targetId": "665a1b2c3d4e5f6a7b8c9d0e",
    "status": "pending",
    "options": {
      "values": { "0": "john@example.com" },
      "useProxy": true
    },
    "webhookUrl": "https://example.com/callback",
    "webhookStatus": "pending",
    "priority": 0,
    "createdAt": "2024-06-01T10:00:00.000Z"
  }
]

---

Détail d'un job

GET /api/v1/jobs/:id

Scope requis : automation:read

curl https://api.gurren.leandre.io/api/v1/jobs/aaa1b2c3d4e5f6a7b8c9d0e1 \
  -H "x-api-key: gfac_votre_cle"

Réponse :

{
  "_id": "aaa1b2c3d4e5f6a7b8c9d0e1",
  "type": "automation",
  "targetId": "665a1b2c3d4e5f6a7b8c9d0e",
  "status": "completed",
  "options": { "values": { "0": "john@example.com" }, "useProxy": true },
  "executionId": "777b2c3d4e5f6a7b8c9d0eee",
  "result": { "status": "completed" },
  "webhookUrl": "https://example.com/callback",
  "webhookStatus": "delivered",
  "startedAt": "2024-06-01T10:00:01.000Z",
  "completedAt": "2024-06-01T10:01:30.000Z",
  "createdAt": "2024-06-01T10:00:00.000Z"
}

---

Statuts d'un job

Statut	Description
pending	En attente de traitement
processing	En cours d'exécution
completed	Terminé avec succès
failed	Terminé en erreur

Callback webhook

Si vous avez fourni un webhookUrl, Gurren enverra un POST à cette URL une fois le job terminé :

{
  "jobId": "aaa1b2c3d4e5f6a7b8c9d0e1",
  "type": "automation",
  "status": "completed",
  "executionId": "777b2c3d4e5f6a7b8c9d0eee",
  "result": { "status": "completed" },
  "completedAt": "2024-06-01T10:01:30.000Z"
}

Pour un système de webhooks plus complet avec signature HMAC et gestion des événements, voir Webhooks.