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. Publiez la version du flow.

Le canal est maintenant lié. Les requêtes qui lui sont envoyées exécuteront ce flow.

É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":"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",
  "conversation_id": "b1f2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "success",
  "output": { "text": "L'utilisateur est bloqué après une réinitialisation de mot de passe. Vérifiez l'état du compte." },
  "usage": { "prompt_tokens": 48, "completion_tokens": 16, "total_tokens": 64 },
  "error": null
}

Si vous recevez 404, le canal n'est pas lié à un flow 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 au corps pour recevoir un flux SSE :

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

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

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

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

Étape 5 - Appeler depuis TypeScript

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

async function summarizeTicket(ticket: string): Promise<string> {
  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: ticket, stream: false }),
  });

  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?.text ?? '';
}

Étape 6 - Reprendre une conversation multi-tour

Le conversation_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: 'Résume ce ticket : …' }),
});
const { conversation_id } = await first.json();

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

Omettez conversation_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.