Construire votre première intégration API

Ce tutoriel vous guide à travers une première intégration complète avec le canal API de nAIxus. Vous créerez un canal, le lierez à un flow, l'appellerez depuis un backend et lirez une réponse JSON puis un streaming.

Scénario : Vous construisez un service Node.js qui demande à un assistant IA de résumer les tickets de support entrants.

Ce que vous aurez à la fin : une commande curl fonctionnelle et un exemple TypeScript qui appellent votre canal et affichent la réponse de l'IA.

Durée : environ 20 minutes.

Prérequis

• Un compte nAIxus avec au moins un tenant.
• Un flow publié contenant un nœud Trigger from Channel. Voir Concevoir un flow si vous n'en avez pas encore.
• curl installé pour les exemples shell.

Étape 1 - Créer un canal API

Ouvrez la console nAIxus, naviguez vers Canaux, et cliquez sur Créer un canal.

• Type : Canal API
• Nom : ticket-summarizer (ou tout autre libellé)
• Environnement : Production

Cliquez sur Créer. La console affiche le nouveau canal avec une clé d'API à usage unique commençant par nx_live_. Copiez-la maintenant - elle n'est affichée qu'une seule fois.

nx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Stockez-la dans une variable d'environnement sur votre serveur :

export NXAIXUS_API_KEY="nx_live_votre_cle_ici"

Étape 2 - Lier le canal à un flow

Dans le flow builder, ouvrez le flow que vous souhaitez utiliser. Trouvez ou ajoutez un nœud Trigger from Channel et sélectionnez le canal ticket-summarizer : la liaison est créée immédiatement. Publiez le flow, obligatoire pour ce canal de production.

Le canal est maintenant lié. Les requêtes qui lui sont envoyées exécuteront ce flow. La publication versionnée n'étant pas encore appliquée à l'exécution, c'est l'état enregistré du flow qui s'exécute.

Étape 3 - Envoyer une requête JSON

Vérifiez la connexion avec une simple commande curl :

curl -X POST "https://api.example.com/public/v1/api/execute" \
  -H "Authorization: Bearer $NXAIXUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payload":{"user_message":"Résume ce ticket : l'"'"'utilisateur ne peut pas se connecter après une réinitialisation du mot de passe."}}'

Une réponse réussie ressemble à :

{
  "run_id": "9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "session_id": "b1f2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "success",
  "output": {
    "result": { "text": "L'utilisateur est bloqué après une réinitialisation de mot de passe. Vérifiez l'état du compte." },
    "error": null,
    "messages": [
      {
        "id": "pub_7f6d8e9a",
        "role": "assistant",
        "content": "L'utilisateur est bloqué après une réinitialisation de mot de passe. Vérifiez l'état du compte."
      }
    ],
    "metadata": {
      "channel_id": "6f1e2d3c-…",
      "flow_id": "1a2b3c4d-…",
      "flow_name": "ticket-summarizer",
      "flow_version": { "version_number": 1, "version_id": "5e6f7a8b-…" },
      "environment": "prod",
      "livechat_mode": null,
      "execution_order": ["trigger_from_channel", "agent"],
      "started_at": "2026-08-04T10:00:00.000Z",
      "completed_at": "2026-08-04T10:00:01.500Z"
    }
  },
  "usage": { "total_nodes": 2, "duration_ms": 1500 },
  "error": null
}

output.messages contient les publications assistant de cet appel ; utilisez-le, pas output.result (qui reflète la sortie propre du flow et dépend entièrement de la façon dont il est construit) ni usage (compteurs de nœuds/durée, pas des compteurs de tokens LLM). Zéro, une ou plusieurs publications sont valides. Conservez chaque id de publication, même lorsque deux entrées ont un contenu identique.

Si vous recevez 404 channel_not_bound, aucun flow ne sélectionne le canal ; 409 no_published_version, le flow n'a pas été publié - revenez à l'étape 2. Si vous recevez 401, vérifiez la clé d'API.

Étape 4 - Envoyer une requête en streaming

Ajoutez ?stream=true à l'URL pour recevoir un flux SSE :

curl -X POST "https://api.example.com/public/v1/api/execute?stream=true" \
  -H "Authorization: Bearer $NXAIXUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payload":{"user_message":"Résume ce ticket : l'"'"'utilisateur ne peut pas se connecter."}}' \
  --no-buffer

Vous verrez un flux d'événements s'afficher dans le terminal :

data: {"type":"data-run","data":{"run_id":"9c1d…","session_id":"b1f2…"}}
data: {"type":"text-start","id":"pub_7f6d…"}
data: {"type":"text-delta","id":"pub_7f6d…","delta":"L'utilisateur est "}
data: {"type":"text-delta","id":"pub_7f6d…","delta":"bloqué après une réinitialisation."}
data: {"type":"text-end","id":"pub_7f6d…"}
data: {"type":"finish","finishReason":"stop"}
data: [DONE]

Le premier événement (data-run) porte à la fois run_id et session_id.

Étape 5 - Appeler depuis TypeScript

Voici une fonction Node.js minimale pour l'exécution JSON :

type AssistantPublication = {
  id: string;
  role: 'assistant';
  content: string;
};

async function summarizeTicket(ticket: string): Promise<AssistantPublication[]> {
  const response = await fetch(`https://api.example.com/public/v1/api/execute`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.NXAIXUS_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ payload: { user_message: ticket } }),
  });

  if (!response.ok) {
    const err = await response.json();
    throw new Error(`Erreur nAIxus : ${err.error?.code} - ${err.error?.message}`);
  }

  const data = await response.json();
  return data.output?.messages ?? [];
}

Étape 6 - Reprendre une conversation multi-tour

Le session_id retourné à l'étape 3 vous permet d'envoyer des messages de suivi dans le même contexte de conversation :

const first = await fetch(/* ... */, {
  body: JSON.stringify({ payload: { user_message: 'Résume ce ticket : …' } }),
});
const { session_id } = await first.json();

const followup = await fetch(/* ... */, {
  body: JSON.stringify({
    payload: { user_message: 'Quel niveau de priorité assignerais-tu ?' },
    session_id,
  }),
});

Omettez session_id chaque fois que vous voulez une nouvelle conversation indépendante.

Étape 7 (optionnel) - Activer les requêtes signées

Si vous souhaitez vérifier que les requêtes proviennent bien de votre serveur et n'ont pas été modifiées, activez les requêtes signées sur le canal :

1. Dans la console, ouvrez les paramètres du canal et activez Signature HMAC obligatoire.

2. Copiez le secret de signature à usage unique (whs_…).

3. Stockez-le avec la clé d'API :

   export NXAIXUS_SIGNING_SECRET="whs_votre_secret_ici"

4. Ajoutez un en-tête de signature à chaque requête :

   import { createHmac } from 'crypto';
   
   function signRequest(body: string, secret: string): string {
     const ts = Math.floor(Date.now() / 1000);
     const digest = createHmac('sha256', secret).update(`${ts}.${body}`).digest('hex');
     return `t=${ts},v1=${digest}`;
   }

5. Incluez-le :

   headers: {
     'X-Naixus-Signature': signRequest(body, process.env.NXAIXUS_SIGNING_SECRET!),
   }

Pour la référence HMAC complète et le guide de rotation, voir Signer les requêtes avec HMAC.

Prochaines étapes

Vous avez une intégration fonctionnelle. Vous pouvez maintenant :

• Ajouter la signature - protéger les appels serveur à serveur avec la signature HMAC.
• Gérer le streaming - intégrer le flux SSE dans votre interface avec le guide de streaming.
• Gérer les credentials - savoir quand et comment renouveler votre clé d'API ou votre secret de signature.
• Comprendre la conception - lire l'explication de l'architecture pour comprendre les compromis de sécurité.
• Chercher un champ - consulter la référence d'API pour les définitions exhaustives des champs et les codes d'erreur.