Bonnes pratiques

Ce guide rassemble ce que votre jeton peut et ne peut pas faire, quelles réponses d'échec de l'API valent la peine d'être retentées, comment rendre une écriture sûre à exécuter deux fois, et quoi transmettre au support quand quelque chose se passe mal. Il vous faut seulement un jeton d'API et votre URL de base, comme indiqué dans le guide de démarrage. C'est une synthèse, pas un nouveau sujet — il renvoie vers Champs, formats et mise en forme des réponses, Interrogation : filtres, tri et pagination et Créer, modifier et supprimer des fiches plutôt que de les réexpliquer ; lisez-les d'abord si ce n'est pas déjà fait.

1. Savoir ce que votre jeton peut faire

Un jeton d'accès personnel appartient à exactement un utilisateur Initiative — ce n'est pas une identité de service séparée avec son propre jeu de permissions. Tout ce que cet utilisateur peut voir et faire dans l'interface est exactement ce que le jeton peut voir et faire via l'API : le même accès aux modules, les mêmes règles de partage des fiches, les mêmes permissions au niveau des champs.

curl -sS -H "Authorization: Bearer itv_YOUR_TOKEN_HERE" "https://app.initiative-crm.com/api/v1/me" | jq '.data.attributes, .meta'

{
  "first_name": "Taylor",
  "last_name": "Morgan",
  "user_name": "[email protected]",
  "email1": "[email protected]",
  "language": "fr_fr",
  "hour_format": "24",
  "date_format": "dd-mm-yyyy",
  "time_zone": "Europe/Brussels",
  "is_admin": true,
  "status": "Active"
}
{
  "request_id": "701f8f59-715e-43b8-82b3-65ffccac42ed",
  "instance_name": "your-instance"
}

GET /api/v1/me indique à quel utilisateur appartient un jeton, et cet utilisateur est celui qui possède les fiches créées sans assigned_user_id explicite.

2. Bien gérer les jetons

Quelques règles qui ne sont propres à aucun endpoint en particulier :

• Un jeton par intégration, pas un seul jeton réutilisé partout. Si une intégration est compromise ou mise hors service, vous révoquez uniquement son jeton et rien d'autre ne casse.
• Jamais dans du code côté client ou un dépôt public. Un jeton est un identifiant complet pour tout ce que son utilisateur propriétaire peut faire — traitez-le comme un mot de passe, pas comme une clé d'API publique.
• Faites une rotation en cas de doute sur une exposition. Créez un nouveau jeton, basculez l'intégration dessus, puis révoquez l'ancien.
• Révoquez depuis Mes préférences → Jetons d'API. N'importe qui peut révoquer ses propres jetons depuis cette page ; un administrateur peut révoquer le jeton de n'importe quel utilisateur depuis cette même zone.

3. Quels échecs valent la peine d'être retentés

Les commandes ci-dessous reproduisent les formes d'échec de premier niveau que cette API renvoie — le tableau qui suit est la réponse complète à la question de savoir lesquelles valent la peine d'être retentées :

curl -sS "https://app.initiative-crm.com/api/v1/contacts"                                                           # pas de jeton
curl -sS -H "Authorization: Bearer itv_not_a_real_token" "https://app.initiative-crm.com/api/v1/contacts"           # un jeton invalide
curl -sS -H "Authorization: Bearer itv_YOUR_TOKEN_HERE" "https://app.initiative-crm.com/api/v1/contacts/999999999"  # une fiche inexistante
curl -sS -X DELETE -H "Authorization: Bearer itv_YOUR_TOKEN_HERE" "https://app.initiative-crm.com/api/v1/me"        # un verbe que l'endpoint ne prend pas en charge
curl -sS -G -H "Authorization: Bearer itv_YOUR_TOKEN_HERE" "https://app.initiative-crm.com/api/v1/contacts" \
  --data-urlencode 'filter[nope]=1'                                                                                 # un champ de filtre inconnu

400, 401, 404 et 405 ci-dessus correspondent à des cas concrets : une requête non authentifiée et un jeton invalide renvoient tous deux 401/UNAUTHORIZED, GET /contacts/999999999 renvoie 404/NOT_FOUND, DELETE /api/v1/me renvoie 405/METHOD_NOT_ALLOWED, et le champ de filtre inconnu renvoie 400/INVALID_FILTER. Chacun d'eux porte un request_id.

Un 500 signifie qu'une défaillance s'est produite côté serveur. Réessayez quelques fois avec une temporisation exponentielle ; si cela persiste, arrêtez et contactez le support avec le request_id. Un cas ne se rétablira pas avec une nouvelle tentative : un jeton mal formé peut renvoyer 500 au lieu de 401. Si un 500 apparaît juste après avoir généré, copié ou fait tourner un jeton, vérifiez d'abord le jeton lui-même.

4. Bien lire les erreurs de validation

Une 422 VALIDATION_ERROR liste tous les champs en échec à la fois dans details[], pas seulement le premier rencontré — corrigez-les tous avant de renvoyer, plutôt que de corriger un champ, renvoyer, et découvrir le suivant. La forme complète de l'enveloppe, les différences entre PATCH/PUT, et comment lire details[] sont couvertes dans Créer, modifier et supprimer des fiches ; rien dans ce mécanisme n'est spécifique à ce guide.

5. Découvrir, ne pas coder en dur

Les noms de champs, les valeurs des options de picklist et les identifiants de référence/propriétaire diffèrent entre ces exemples de documentation et vos propres données — une option de picklist montrée ici peut ne pas exister, ou être libellée différemment, chez vous, et un id de fiche tiré d'un exemple n'est presque certainement pas valide pour vous. GET /api/v1/modules/{module} est la source de vérité pour les champs et options réels d'un module — consultez Champs, formats et mise en forme des réponses pour savoir comment le lire. Ne supposez jamais qu'un id ou une valeur d'option d'un exemple de ces guides s'applique à vos propres données.

6. Les horaires sont en UTC

Envoyez et attendez des horodatages ISO 8601 avec un Z final — 2026-08-04T12:00:00Z, jamais une heure locale brute ni un décalage de type +02:00. Chaque createdtime, modifiedtime et deleted_at montré dans ces guides revient exactement sous cette forme. Convertissez vers le fuseau horaire local d'un utilisateur à la périphérie de votre propre application — pas celle de l'API.

7. Rendre les écritures sûres à répéter

Cette API n'a aucun mécanisme de clé d'idempotence — rien ne rejette un POST en double ni ne le fusionne dans une fiche qui existe déjà. Envoyer deux fois le corps de création identique produit deux fiches distinctes avec deux ids différents, pas une seule et pas d'erreur :

curl -sS -X POST -H "Authorization: Bearer itv_YOUR_TOKEN_HERE" -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"firstname":"Idem","lastname":"Potency-Test","email":"[email protected]","assigned_user_id":"7206"}}}' \
  "https://app.initiative-crm.com/api/v1/contacts"

Premier appel → "data":{"id":"1629", ...}. Le même corps exact renvoyé à nouveau → "data":{"id":"1630", ...} — une seconde fiche distincte, pas la première à nouveau. (Les deux ont été supprimées immédiatement après cette vérification ; ce ne sont pas de vraies données laissées derrière.)

Si votre intégration peut s'exécuter deux fois — une requête retentée, un webhook relivré, une tâche planifiée qui se chevauche — conservez votre propre référence externe (un numéro de commande, un id du système avec lequel vous synchronisez) dans un champ de la fiche, et recherchez cette référence avant de créer. Consultez Interrogation : filtres, tri et pagination pour les opérateurs de filtre qui rendent cette recherche bon marché et précise. Ne créez que si la recherche revient vide.

8. Quand vous contactez le support

Chaque réponse d'erreur inclut son propre request_id. Transmettez-le au support pour qu'il sache exactement quelle requête a échoué, sans que vous ayez à reconstituer ou renvoyer quoi que ce soit.

9. Liste de contrôle avant lancement

• Jeton stocké dans un gestionnaire de secrets, pas dans le contrôle de version ni dans du code côté client (étape 2)
• 429 géré en attendant Retry-After, ni retenté immédiatement ni ignoré (étape 3)
• 422 remonté à un humain ou dans un journal, pas avalé silencieusement — une erreur de validation signifie que l'écriture n'a pas eu lieu (étape 3, Créer, modifier et supprimer des fiches)
• Pages de liste parcourues avec un tri stable (par exemple sort=id), pas celui par défaut, chaque fois que des fiches peuvent changer en plein parcours (voir Interrogation : filtres, tri et pagination)
• Suppressions consommées depuis le flux dédié /deleted, pas déduites d'une fiche disparaissant d'une liste (voir Synchroniser un autre système)
• Chaque horodatage envoyé et lu en UTC (Z), converti à la périphérie de votre application, pas celle de l'API (étape 6)
• Aucun id ni valeur d'option codé en dur copié d'un exemple de documentation (étape 5)
• request_id journalisé pour chaque requête, y compris celles réussies, pour qu'une conversation ultérieure avec le support n'exige pas une nouvelle exécution juste pour en obtenir un (étape 8)

Erreurs courantes

• Traiter tout 500 comme « il suffit de réessayer ». Une forme précise de jeton mal formé renvoie actuellement 500 INTERNAL_ERROR au lieu d'un 401 propre (étape 3). Si un 500 apparaît juste après avoir généré, copié ou fait tourner un jeton, vérifiez d'abord le jeton lui-même avant de supposer qu'une nouvelle tentative avec temporisation aidera.
• Construire une logique de nouvelle tentative autour d'un 422. Renvoyer un corps identique contre un 422 renvoie l'erreur identique — corrigez d'abord chaque champ nommé dans details[] (étape 4).
• Partager un seul jeton entre toutes les intégrations et tous les environnements. Le retirer ou le faire tourner casse alors d'un coup toutes les intégrations qui en dépendent, au lieu de seulement celle que vous vouliez changer (étape 2).
• Supposer qu'un id ou une valeur de picklist de l'un de ces guides fonctionne avec vos propres données. Ce n'est pas le cas — découvrez-le d'abord (étape 5).
• Renvoyer une soumission de formulaire, une requête retentée ou un webhook relivré sans vérifier d'abord par une recherche. Rien côté serveur n'empêche le doublon — vous obtiendrez deux fiches au lieu d'une (étape 7).