Connecter une intégration en toute sécurité

Avant de commencer

L’API permet à une intégration autorisée de travailler avec les informations de Talento. Chaque identifiant appartient à une personne en activité dans l’entreprise : les requêtes sont exécutées avec ses autorisations et dans ce même compte.

Ce fonctionnement applique à l’intégration les mêmes contrôles d’accès que dans l’application. Le choix de l’identité, de ses autorisations et du mode de conservation du jeton fait donc pleinement partie de la sécurité de l’intégration.

!Attention

Un jeton API doit être protégé comme un mot de passe. Ne le collez jamais dans une conversation, un ticket, un document, une adresse web ou un dépôt de code. Conservez-le dans le gestionnaire de secrets de l’intégration et transmettez-le uniquement via HTTPS.

Authentifier une requête avec Bearer

Envoyez le jeton dans l’en-tête HTTP Authorization avec le schéma Bearer :

Authorization: Bearer VOTRE_JETON

Remplacez VOTRE_JETON dans la configuration sécurisée de l’intégration ; ne saisissez jamais la valeur réelle dans un exemple, un journal ou le code source. Effectuez les appels vers l’adresse de l’entreprise et la ressource API documentée pour l’opération.

Avant d’accepter la requête, l’API vérifie trois conditions :

• le jeton est valide ;
• l’accès à l’API est toujours actif et la personne l’est également ;
• la personne est autorisée à effectuer l’opération demandée.

Consignez les erreurs et les identifiants techniques utiles à l’assistance, mais configurez l’application afin de masquer l’en-tête Authorization et tout autre secret.

Envoyer des indicateurs de prospects sans endpoint dédié

Un produit externe peut utiliser les champs personnalisés génériques de Prospect sans nécessiter son propre endpoint Talento. Créez ou modifiez d’abord une définition sur /api/v3/custom_field_definitions avec target_type: "Lead", un field_type scalaire et track_history: true. Les définitions et options de sélection utilisent leurs UUID publics. La création d’un prospect valide toujours tous les champs de Prospect obligatoires, même si custom_fields est omis.

Enregistrez chaque mesure sur /api/v3/leads/{lead_uuid}/custom_field_observations avec l’UUID de la définition, une value du bon type et, facultativement, un observed_at ISO 8601, une source et une idempotency_key. La valeur peut être scalaire, { "amount": 18, "currency_code": "eur" } pour une devise, ou null pour l’effacer. Réutiliser une clé d’idempotence avec la même requête canonique renvoie l’observation initiale ; modifier la requête renvoie 409. Une valeur non valide, un suivi désactivé ou une date de plus de cinq minutes dans le futur renvoie 422.

Listez la même ressource pour obtenir l’historique du plus récent au plus ancien et le filtrer par définition ou dates d’observation. Les réponses de liste et de détail des prospects exposent les lignes de champs existantes, avec observed_at et source ; une définition jamais renseignée est omise.

Résoudre une réponse non autorisée

En cas de réponse 401 Non autorisé, vérifiez dans cet ordre :

1. l’en-tête utilise exactement le schéma Bearer et le jeton n’est pas envoyé dans l’URL ;
2. le secret configuré correspond au jeton actuel et non à celui qui précédait un renouvellement ;
3. l’accès à l’API est toujours actif ;
4. la personne est active et appartient à l’entreprise depuis laquelle l’appel est effectué ;
5. l’adresse et la ressource demandée sont correctes.

Si l’authentification fonctionne mais qu’une opération précise est refusée, vérifiez les autorisations de la personne. Accordez uniquement l’accès indispensable ; ne lui attribuez pas le rôle d’administration pour contourner une intégration au périmètre limité.

Problèmes fréquents

Si une option n’apparaît pas, cela peut dépendre de vos autorisations, des fonctionnalités actives ou de la configuration de l’entreprise. Demandez à l’équipe d’administration de vérifier votre accès ; vous n’avez pas besoin de recommencer la tâche ni de choisir une solution qui ne correspond pas à votre situation.