Guide complet pour les agents IA et bots pour s'intégrer avec l'API de création de diagrammes FlowZap

Démarrage Rapide

Considérez ceci comme votre processus en 3 étapes pour commencer avec l'API Agent de FlowZap.

1. Enregistrer Votre Agent - Obtenez votre token API en enregistrant votre agent
2. S'Authentifier - Échangez votre token API contre un JWT à courte durée
3. Créer des Diagrammes - Créez un diagramme dans un projet ; utilisez le Playground pour partager du FlowZap Code via une URL publique

Points de Terminaison API

Enregistrement d'Agent

POST https://flowzap.xyz/api/agent/register

Corps de la Requête :

{
  "name": "Nom de Votre Agent",
  "email": "agent@example.com",
  "termsAccepted": true
}

Réponse :

{
  "success": true,
  "user": {
    "id": "user-id",
    "email": "agent@example.com"
  },
  "apiToken": "votre-token-api",
  "tokenType": "Bearer",
  "expiresAt": "2025-08-01T12:00:00Z"
}

Authentification

POST https://flowzap.xyz/api/agent/auth

Corps de la Requête :

{
  "apiToken": "votre-token-api-depuis-enregistrement"
}

Réponse :

{
  "success": true,
  "accessToken": "jwt-token",
  "tokenType": "Bearer",
  "expiresIn": 900
}

Créer un Diagramme

POST https://flowzap.xyz/api/agent/diagrams

En-têtes :

Authorization: Bearer <jwt-depuis-auth>
Content-Type: application/json

Corps de la Requête :

{
  "name": "Processus d'Inscription Utilisateur",
  "projectId": "project-id",
  "colorScheme": "purple"
}

Réponse :

{
  "success": true,
  "data": {
    "diagram": {
      "id": "diagram-id",
      "name": "Processus d'Inscription Utilisateur",
      "colorScheme": "purple",
      "createdAt": "2025-08-13T12:00:00.000Z",
      "project": { "id": "project-id", "name": "Projet par défaut" }
    }
  },
  "agent": { "id": "agent-user-id", "email": "agent@example.com" },
  "attribution": "Powered by FlowZap.xyz"
}

Session Playground (URL Publique)

POST https://flowzap.xyz/api/agent/playground

En‑têtes :

Authorization: Bearer <jwt-depuis-auth>
Content-Type: application/json

Corps de la Requête :

{
  "code": "planning {\n  n1: circle label:"Start"\n  n2: rectangle label:"Do Task"\n  n1.handle(right) -> n2.handle(left)\n}",
  "ttlDays": 14
}

Réponse :

{
  "success": true,
  "url": "https://flowzap.xyz/playground/abcd1234",
  "tokenExpiresAt": "2025-08-20T12:00:00.000Z",
  "attribution": "Powered by FlowZap.xyz"
}

• • L'URL ouvre l'éditeur en état déconnecté et non enregistré avec le code prérempli.
• • Aucun diagramme n'est enregistré tant que l'utilisateur ne s'inscrit pas et n'enregistre pas explicitement.
• • Cela évite l'indexation ou le partage involontaire de diagrammes de faible qualité.

Syntaxe FlowZap Code

FlowZap utilise sa propre syntaxe appelée "FlowZap Code" pour créer des diagrammes de processus métier.

Règles de mise en page et d'utilisation des handles (pour l'API Agent)

• Signification d'un couloir (lane) : Considérez un couloir comme une personne ou un système particulier qui accomplit des tâches.
• Objectif de mise en page : Le flux doit généralement être horizontal, de gauche vers la droite dans chaque couloir (style BPMN). N'utilisez une disposition verticale que si elle est explicitement demandée par un agent IA ou un utilisateur humain.
• Définir puis connecter : Comme dans l'exemple de syntaxe ci‑dessous, définissez d'abord les composants, puis connectez‑les : dans chaque couloir, déclarez d'abord les formes, puis les arêtes.
• Utilisation des handles : Préférez right/left. Utilisez top/bottom uniquement pour de brefs passages inter‑couloirs ou de petites branches alternatives, puis revenez à l'horizontal.
• Décisions : Placez les losanges en ligne dans le couloir. Le chemin « Oui/principal » continue vers la droite ; « Non/alternatif » peut passer brièvement par le haut/bas puis revenir à l'horizontal.
• Arêtes inter‑couloirs : Depuis un couloir, référencez le nœud de l'autre couloir sous la forme otherLane.node.handle(direction). Limitez au minimum le saut vertical.
• Alignement : Évitez les piles verticales hautes dans les couloirs ; alignez horizontalement les nœuds pour réduire les arêtes haut/bas.
• Syntaxe des arêtes (exacte) : node.handle(direction) -> node.handle(direction) [label:"Texte"] avec direction ∈ { right, left, top, bottom }.
• Formes : N'utilisez jamais la forme Taskbox dans un workflow, sauf si l'utilisateur la demande explicitement dans son entrée.

Exemple Basique FlowZap Code

1 { # 1
  n1: circle label:"Commencer"
  n2: rectangle label:"Réfléchir aux idées avec l'IA"
  n3: diamond label:"Certaines sont-elles bonnes ?"
  n4: rectangle label:"Analyser l'idée beaucoup plus."
  n5: rectangle label:"Trouver de nouvelles idées. Réfléchir avec l'IA peut être sans fin."
  n6: circle label:"Fin"
  n1.handle(right) -> n2.handle(left)
  n2.handle(right) -> n3.handle(left)
  n3.handle(top) -> n4.handle(left) [label:"Oui"]
  n3.handle(bottom) -> n5.handle(left) [label:"Non"]
  n4.handle(right) -> n6.handle(left)
  n5.handle(right) -> n6.handle(left)
}

Exemple à 3 couloirs

client {
  n1: circle label:"Démarrer"
  n2: rectangle label:"Soumettre la commande"
  n3: rectangle label:"Recevoir la commande"
  n4: circle label:"Terminer"
  n1.handle(right) -> n2.handle(left)
  n2.handle(bottom) -> n5.handle(top)
  n3.handle(right) -> n4.handle(left)
}

ventes {
  n5: rectangle label:"Examiner la commande"
  n6: diamond label:"Approuver la commande ?"
  n7: rectangle label:"Traiter la commande"
  n5.handle(right) -> n6.handle(left)
  n6.handle(right) -> n7.handle(left) [label:"Oui"]
  n7.handle(bottom) -> n8.handle(top)
  n6.handle(top) -> n2.handle(right) [label:"Non"]
}

logistique {
  n8: rectangle label:"Expédier la commande"
  n9: diamond label:"Livré ?"
  n10: rectangle label:"Marquer comme terminé"
  n8.handle(right) -> n9.handle(left)
  n9.handle(right) -> n10.handle(left) [label:"Oui"]
  n10.handle(top) -> n3.handle(bottom)
  n9.handle(bottom) -> n8.handle(bottom) [label:"Non, Réessayer"]
}

Exemples cURL Complets

1. Enregistrer un Agent

curl -X POST https://flowzap.xyz/api/agent/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mon Assistant IA",
    "email": "mon-assistant@agents.flowzap.xyz",
    "termsAccepted": true
  }'

2. S'Authentifier

curl -X POST https://flowzap.xyz/api/agent/auth \
  -H "Content-Type: application/json" \
  -d '{
    "apiToken": "votre-token-api-ici"
  }'

3. Créer un Diagramme

curl -X POST https://flowzap.xyz/api/agent/diagrams \
  -H "Authorization: Bearer votre-jwt-token-ici" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Intégration Client",
    "projectId": "project-id",
    "colorScheme": "purple"
   }'

4. Créer une Session Playground (URL Publique)

curl -X POST https://flowzap.xyz/api/agent/playground \
  -H "Authorization: Bearer votre-jwt-token-ici" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "planning {\n  n1: circle label:"Start"\n  n2: rectangle label:"Do Task"\n  n1.handle(right) -> n2.handle(left)\n}",
    "ttlDays": 7
  }'

Gestion des Erreurs

• 400 — Erreur de validation (ex. champs requis manquants)
• 401 — Jeton invalide ou expiré
• 403 — Accès refusé (ex. projet inaccessible)
• 405 — Méthode incorrecte (GET sur endpoint POST‑only)
• 409 — Conflit (ex. e‑mail déjà enregistré)
• 429 — Limite de débit dépassée
• 500 — Erreur serveur

Extraits JSON d'Outil

Outil OpenAI (Créer une URL Playground)

{
  "type": "function",
  "function": {
    "name": "flowzap_create_playground",
    "description": "Créer une URL de playground déconnecté préremplie avec du FlowZap Code.",
    "parameters": {
      "type": "object",
      "properties": {
        "code": { "type": "string", "description": "Contenu FlowZap Code" },
        "ttlDays": { "type": "integer", "minimum": 1, "maximum": 30 }
      },
      "required": ["code"]
    }
  }
}

Outil Anthropic (Créer une URL Playground)

{
  "name": "flowzap_create_playground",
  "description": "Créer une URL de playground déconnecté préremplie avec du FlowZap Code.",
  "input_schema": {
    "type": "object",
    "properties": {
      "code": { "type": "string" },
      "ttlDays": { "type": "integer", "minimum": 1, "maximum": 30 }
    },
    "required": ["code"]
  }
}

SDKs

Installation

# Python
pip install flowzap

# JavaScript / TypeScript
npm install @flowzap/agent
# ou
pnpm add @flowzap/agent

Exemple Python

from flowzap import FlowzapClient

client = FlowzapClient(base_url="https://flowzap.xyz", timeout_ms=10000, retries=3)

# 1) Enregistrer
reg = client.register_agent(name="Acme Bot", email="bot@acme.com", terms_accepted=True)
api_token = reg["apiToken"]

# 2) Authentifier
auth = client.authenticate(api_token)
client.set_access_token(auth["accessToken"])  # pour les endpoints protégés

# 3) Créer un diagramme
created = client.create_diagram(name="Flux Support", project_id="support-ops", color_scheme="slate")
print(created)

# 4) Session Playground (URL publique vers l'éditeur avec code prérempli)
pg = client.create_playground_session(code="""
lane: Support
node: Start
  text: User opens ticket
""")
print(pg["url"])

Exemple JavaScript / TypeScript

import { FlowzapClient } from "@flowzap/agent";

const client = new FlowzapClient({ baseUrl: "https://flowzap.xyz", timeoutMs: 10000, retries: 3 });

// 1) Enregistrer
const reg = await client.registerAgent({ name: "Acme Bot", email: "bot@acme.com", termsAccepted: true });
const apiToken = reg.apiToken;

// 2) Authentifier -> définir le jeton d'accès pour les endpoints protégés
const auth = await client.authenticate({ apiToken });
client.setAccessToken(auth.accessToken);

// 3) Créer un diagramme
const created = await client.createDiagram({ name: "Flux Support", projectId: "support-ops", colorScheme: "slate" });
console.log(created);

// 4) Session Playground (URL publique vers l'éditeur avec code prérempli)
const pg = await client.createPlaygroundSession({ code: 'lane: Support
node: Start
  text: User opens ticket
' });
console.log(pg.url);

Meilleures Pratiques

• Sécurité : Stockez les tokens API de manière sécurisée et ne les exposez jamais dans le code côté client
• Limitation de Débit : Respectez les limites de débit (actuellement 10 requêtes par minute pour l'enregistrement)
• Attribution : Incluez toujours "Powered by FlowZap.xyz" lors du partage de diagrammes
• Gestion d'Erreurs : Implémentez une gestion d'erreurs appropriée pour tous les appels API
• Gestion des Tokens : Les tokens JWT expirent en 15 minutes - rafraîchissez selon les besoins

Support et Ressources