Droits et erreurs
Ce qu'une clé peut faire, et ce que répond l'API quand elle refuse.
Une clé porte les droits d'un membre
Une clé n'est pas « la clé de l'organisation » : elle agit pour le membre qui l'a créée.
- Elle lit ce que ce membre lit, et envoie ce qu'il a le droit de saisir. Ses droits sont lus à chaque appel : un droit accordé ou retiré à ce membre vaut tout de suite pour sa clé.
- Ce qu'elle envoie est écrit à son nom dans le journal d'audit, avec l'origine « API ».
- Elle est refusée dès que ce membre quitte l'organisation. S'il revient, il crée une nouvelle clé.
Chaque page de la référence dit le droit demandé, dans les mots de l'écran « Droits des membres », et les rôles qui l'ont par défaut. Le propriétaire et le CMO accordent ou retirent un droit membre par membre.
Trois cas à connaître :
- L'abonnement ne se lit qu'avec la clé du propriétaire.
- Les membres se lisent avec la clé du propriétaire ou de Marketing Ops.
- Le coût d'équipe ne s'envoie qu'avec la clé du propriétaire, ou d'un membre qui est aussi CMO : ce droit ne s'accorde pas membre par membre.
Ce que l'API n'écrit pas
L'API ne valide rien à votre place.
- Un envoi dépose une proposition, ou un brouillon. Une personne le valide à l'écran : voir Ce qui attend une personne.
- Elle ne supprime rien.
- Elle n'arrête pas un mois, ne publie pas un budget, ne confirme pas un contrat.
Les refus
Un refus répond en JSON, avec un message en français qui dit quoi corriger :
{ "message": "name : ne peut pas être vide ; fiscalYearStartMonth : requis" }{ "message": "Contrat 1 : canal « Télévision » inconnu" }| Statut | Ce qui s'est passé | Que faire |
|---|---|---|
400 | La demande est refusée : un paramètre manque ou sort de ses limites, ou le lecteur du fichier refuse une ligne. | Corrigez ce que dit le message. Un tableau refusé donne ses lignes, numérotées à partir de 1. |
401 | La clé manque, est invalide, expirée ou désactivée. | Vérifiez l'en-tête x-api-key. |
403 | Le membre de la clé n'a pas le droit demandé, a quitté l'organisation, ou l'offre de l'organisation ne contient pas ce module. | Utilisez la clé d'un membre qui a ce droit, ou faites-le accorder. |
404 | L'adresse n'existe pas, ou l'identifiant donné n'est pas dans cette organisation. | list_budgets et list_entities donnent les identifiants. |
413 | Le corps de la requête dépasse 4 Mo. | Envoyez le tableau en plusieurs fois. |
429 | La clé a dépassé 1 000 requêtes dans l'heure. | Le message dit quand réessayer. |
Un envoi est écrit en entier, ou pas du tout : après un refus, rien n'a été déposé.
Renvoyer sans doubler
Vous pouvez renvoyer le même contenu sans risque.
- Une proposition envoyée sous le même nom remplace celle qui attend.
- Un export déjà importé, cellule pour cellule, n'est pas importé une seconde fois.
- Un contrat qui attend déjà en brouillon n'est pas déposé une seconde fois.
Données personnelles
L'API ne garde pas ce que le produit ne garde pas.
- Contacts : réduits à des nombres dès la réception. Aucun nom, aucun e-mail, aucune ligne n'est gardé.
- E-mails de facturation : gardés sous forme d'empreinte SHA-256 seulement. Vous pouvez les envoyer déjà hachés.
- Coût d'équipe : des totaux par équipe, jamais une personne.
- Propriétaire d'un deal : jamais renvoyé par l'API.