Bien démarrer avec l’API REST

L’API REST de Scratcher permet à vos propres systèmes de lire vos campagnes, vos leads et vos listes, d’ajouter et de mettre à jour des leads, et de gérer des produits. Cet article s’adresse au développeur chargé de la mise en place. L’API est incluse à partir du forfait Basic.

Créer un jeton d’accès

1. Allez dans Paramètres > API (sous Développeurs).
2. Sous Jetons d’accès personnels, cliquez sur Créer un jeton d’accès personnel.
3. Donnez-lui un Nom, comme « Entrepôt de données », et choisissez les Portées dont il a besoin. Ne lui donnez que les accès nécessaires.
4. Cliquez sur Enregistrer et copiez le jeton sous Secret. Il ne s’affiche qu’une seule fois : conservez-le en lieu sûr, par exemple dans un gestionnaire de mots de passe.

Un jeton appartient à votre utilisateur et donne accès à tous les comptes dont vous êtes membre. Pour retirer l’accès, ouvrez le jeton et cliquez sur Révoquer.

Portées

• read:campaigns : lire les campagnes
• read:lists : lire les listes de leads
• read:leads et write:leads : lire, créer, mettre à jour et supprimer des leads
• read:placements et write:placements : lire et gérer les placements
• read:products et write:products : lire et gérer les produits

Envoyer une requête

L’URL de base est https://platform.scratcher.io/api/v1/. Envoyez le jeton dans l’en-tête Authorization :

curl https://platform.scratcher.io/api/v1/accounts \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" 

Principaux endpoints

• GET /me : l’utilisateur auquel appartient le jeton
• GET /accounts : les comptes auxquels vous avez accès
• GET /accounts/{account}/campaigns et /campaigns/{campaign} : vos campagnes
• GET /accounts/{account}/campaigns/{campaign}/leads : les leads d’une campagne, avec les lots, les codes et les consentements accordés
• GET /accounts/{account}/lists et /lists/{list}/leads : les listes de leads et leurs leads, ainsi que POST, PUT et DELETE pour gérer les leads
• /accounts/{account}/products : les produits
• /accounts/{account}/placements : les placements

Les résultats sont paginés avec ?page=. La limite est de 60 requêtes par minute et par utilisateur.

La référence complète, avec des exemples et une collection Postman, se trouve dans la documentation de référence de l’API. Le bouton Référence de l’API de la plateforme y renvoie aussi.

Applications OAuth

Si vous développez une application à laquelle d’autres utilisateurs de Scratcher se connectent, enregistrez-la sous Mes apps > Créer une app avec un Nom de l’application et une URI de redirection. Vous obtenez un ID client et un Secret client. Le secret ne s’affiche qu’une seule fois. Les applications que les gens ont approuvées sont listées sous Apps autorisées, où leur accès peut être révoqué.