Connecter vos utilisateurs

Reliez un utilisateur final à son portefeuille Fleeex en amont, sans appel de chat et sans 402.

getConnection() vous permet de vérifier si le couple (app, utilisateur) configuré est relié à un portefeuille Fleeex et approvisionné, sans provoquer de 402 sur un premier appel de chat, et vous rend un lien d'onboarding à ouvrir.

const { connected, funded, connectUrl } = await client.getConnection();
 
if (!connected || !funded) {
  redirect(connectUrl); // se connecter → autoriser l'app → recharger
}

La méthode renvoie un ConnectionStatus :

Contrairement au proxy et à getBalance(), getConnection() ne lève jamais de 402. Elle renvoie toujours l'état. connectUrl est le même lien d'onboarding signé qu'aurait rendu un 402, émis à la demande, sans appel de chat et sans facturation.

Ce qui se passe sur connectUrl

Fleeex héberge cette page ; votre application y confie l'utilisateur puis le récupère. Trois choses s'y produisent, et celle du milieu mérite d'être connue :

1. L'utilisateur se connecte à son propre compte Fleeex, car le portefeuille est le sien et non celui de votre application.
2. Il autorise votre application nommément. La page indique quelle application demande l'accès et le plafond mensuel qu'elle pourra dépenser, et l'utilisateur doit confirmer ce nom. Fleeex vérifie cette confirmation côté serveur, face à l'application que le lien désigne réellement.
3. Il approvisionne le portefeuille, si nécessaire.

Cette étape de consentement existe parce qu'un lien d'onboarding est émis sur le plan de données, pour un identifiant utilisateur choisi par l'application appelante : quiconque peut enregistrer une application pourrait donc en émettre un et l'envoyer à quelqu'un d'autre. Nommer l'application, et vérifier ce nom, est ce qui empêche un lien transmis de lier l'application de quelqu'un d'autre au portefeuille de celui qui clique.

Deux conséquences pour votre intégration :

• Enregistrez un nom que vos utilisateurs reconnaîtront. C'est le nom qu'on leur demande d'approuver, et un nom méconnaissable est une étape qu'ils abandonneront. C'est le name que vous posez à l'enregistrement de l'application.
• Vous n'envoyez jamais cette confirmation vous-même. Elle appartient à la session de l'utilisateur connecté sur la page Fleeex, si bien que le 403 APP_CONSENT_MISMATCH qui la protège n'est pas une erreur que votre application peut recevoir. Une clé d'API n'atteint tout simplement pas cette route.

L'utilisateur peut ensuite révoquer votre application, et une correspondance révoquée est délibérément impossible à distinguer d'une correspondance qui n'a jamais existé : connected vaut false et un appel de chat répond le 402 générique. Ni l'un ni l'autre n'annonce un retrait d'accès. Voir la référence des erreurs.

Ramener l'utilisateur dans votre application

Passez un redirectUri pour que Fleeex renvoie l'utilisateur une fois qu'il est connecté et approvisionné :

const { connected, funded, connectUrl } = await client.getConnection({
  redirectUri: "https://app.example.com/fleeex/return",
});

Le redirectUri doit correspondre exactement à l'une des URI de redirection enregistrées sur votre application (gérées sur celle-ci), sinon l'appel échoue avec un 400 (FleeexApiError). C'est une protection contre les redirections ouvertes.

Quand l'utiliser

• Onboarding : connectez un utilisateur la première fois qu'il ouvre une fonctionnalité IA, au lieu d'attendre que le premier appel échoue.
• Conditionner l'interface : affichez un état « Connecter Fleeex » quand connected ou funded vaut faux, sans rien dépenser pour le savoir.