Το REST API του Scratcher επιτρέπει στα δικά σας συστήματα να διαβάζουν τις καμπάνιες, τα leads και τις λίστες σας, να προσθέτουν και να ενημερώνουν leads και να διαχειρίζονται προϊόντα και τοποθετήσεις. Αυτό το άρθρο απευθύνεται στον προγραμματιστή που κάνει τη ρύθμιση.
Το API περιλαμβάνεται στα πακέτα που προσφέρουν Webhooks & API (Basic και άνω). Στα υπόλοιπα πακέτα τα κουμπιά για τη δημιουργία διακριτικών και εφαρμογών είναι κλειδωμένα.
Δημιουργία προσωπικού διακριτικού πρόσβασης
Το προσωπικό διακριτικό πρόσβασης είναι ο γρηγορότερος τρόπος να καλείτε το API από τα δικά σας scripts και συστήματα.
- Μεταβείτε στις Settings > API (στην ενότητα Developers).
- Στην ενότητα Personal access tokens, κάντε κλικ στο Create personal access token. Το παράθυρο διαλόγου γράφει «Generate a token to authenticate API requests.»
- Δώστε του ένα Name που θα αναγνωρίζετε αργότερα, π.χ. «Data warehouse».
- Στην ενότητα Scopes, επιλέξτε τι επιτρέπεται να κάνει το διακριτικό (δείτε παρακάτω). Το Select all επιλέγει όλα τα δικαιώματα. Δώστε στο διακριτικό μόνο την πρόσβαση που χρειάζεται.
- Κάντε κλικ στο Save. Εμφανίζεται το μήνυμα «Your access token has been created».
- Αντιγράψτε το διακριτικό από το πεδίο Secret. «Save the secret above, as this is the only time you will see it.» Φυλάξτε το με ασφάλεια, για παράδειγμα σε έναν διαχειριστή κωδικών πρόσβασης.
- Κάντε κλικ στο Close.
Ένα διακριτικό ανήκει στον χρήστη σας. Έχει πρόσβαση σε κάθε λογαριασμό Scratcher του οποίου είστε μέλος, με τα δικαιώματα που επιλέξατε.
Δικαιώματα (scopes)
read:campaigns(View campaigns): προβολή λίστας και ανάγνωση καμπανιώνread:lists(View lists): προβολή λίστας και ανάγνωση λιστών leadsread:leads(View leads): ανάγνωση leadswrite:leads(Write leads): δημιουργία, ενημέρωση και διαγραφή leads σε μια λίσταread:placements(View placements): ανάγνωση τοποθετήσεωνwrite:placements(Write placements): δημιουργία, ενημέρωση και διαγραφή τοποθετήσεωνread:products(View products): ανάγνωση προϊόντωνwrite:products(Write products): δημιουργία, ενημέρωση και διαγραφή προϊόντων
Για να διαβάσει τα leads μιας καμπάνιας, το διακριτικό χρειάζεται και το read:campaigns και το read:leads. Για τη δημιουργία και την αλλαγή τοποθετήσεων χρειάζεται επίσης η δυνατότητα Embed / URL στο πακέτο σας.
Ανάκληση διακριτικού
Κάντε κλικ στο διακριτικό στη λίστα για να ανοίξει το Show personal access token. Εμφανίζονται τα πεδία Name και Scopes. Κάντε κλικ στο Revoke και επιβεβαιώστε («Are you sure you want to delete this token? This cannot be undone!»). Ό,τι χρησιμοποιεί το διακριτικό σταματά αμέσως να λειτουργεί.
Αποστολή αιτήματος
Το βασικό URL είναι https://platform.scratcher.io/api/v1/. Στείλτε το διακριτικό στην κεφαλίδα Authorization και ζητήστε JSON:
curl https://platform.scratcher.io/api/v1/accounts \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" Κύρια endpoints
GET /me: ο χρήστης στον οποίο ανήκει το διακριτικόGET /accounts: οι λογαριασμοί στους οποίους έχετε πρόσβαση. Χρησιμοποιήστε το id του λογαριασμού στις υπόλοιπες κλήσεις.GET /accounts/{account}/campaignsκαι/campaigns/{campaign}: οι καμπάνιες σαςGET /accounts/{account}/campaigns/{campaign}/leads: τα leads μιας καμπάνιας, με τα νεότερα πρώτα, μαζί με τα πεδία τους, τις αποδεκτές συγκαταθέσεις και, για τους νικητές, το έπαθλο και τον κωδικόGET /accounts/{account}/listsκαι/lists/{list}: οι λίστες leads σας/accounts/{account}/lists/{list}/leads: τα leads μιας λίστας.GETγια ανάγνωση,POSTγια δημιουργία,PUTγια ενημέρωση καιDELETEγια διαγραφή. Κάθε lead έχειemail,phone_numberκαι προαιρετικόcustom_token./accounts/{account}/products: προϊόντα (GET,POST,PUT,DELETE)/accounts/{account}/placements: τοποθετήσεις (GET,POST,PUT,DELETE)
Οι λίστες επιστρέφονται σε σελίδες: προσθέστε ?page=2 κ.ο.κ. Έχετε πρόσβαση μόνο σε λογαριασμούς των οποίων είστε μέλος· άλλα id λογαριασμών επιστρέφουν σφάλμα.
Όρια
Μπορείτε να κάνετε 60 αιτήματα ανά λεπτό ανά χρήστη. Αν τα ξεπεράσετε, το API απαντά με κωδικό κατάστασης 429· περιμένετε λίγο και δοκιμάστε ξανά.
Τεκμηρίωση API
Η πλήρης τεκμηρίωση, με όλα τα πεδία, τα φίλτρα, παραδείγματα και μια συλλογή Postman, βρίσκεται στην τεκμηρίωση αναφοράς του API. Εκεί οδηγεί επίσης το κουμπί API reference στο πάνω μέρος της σελίδας Settings > API.
Δημιουργία εφαρμογής με OAuth
Αν αναπτύσσετε μια εφαρμογή που άλλοι χρήστες του Scratcher θα συνδέουν με τον δικό τους λογαριασμό, καταχωρίστε μια εφαρμογή OAuth αντί να χρησιμοποιήσετε προσωπικό διακριτικό.
- Μεταβείτε στις Settings > API. Στην ενότητα My apps, κάντε κλικ στο Create app («Register an OAuth application for the API.»).
- Συμπληρώστε το Application name (το βλέπουν οι χρήστες όταν εγκρίνουν την εφαρμογή σας) και το Redirect URI (πού επιστρέφουν οι χρήστες μετά την έγκριση).
- Κάντε κλικ στο Save. Εμφανίζεται το μήνυμα «Your app has been created!» μαζί με το Client ID και το Client secret.
- Αντιγράψτε αμέσως το client secret: «Save the client secret above, as this is the only time you will see it.» Κάντε κλικ στο Continue.
Η εφαρμογή σας στέλνει τους χρήστες στο https://platform.scratcher.io/oauth/authorize με το client ID, το redirect URI και τα δικαιώματα που χρειάζεται. Ο χρήστης συνδέεται στο Scratcher και βλέπει ένα Authorization request: «This application will be able to:» ακολουθούμενο από τα δικαιώματα. Κάνει κλικ στο Authorize ή στο Cancel. Στη συνέχεια, η εφαρμογή σας ανταλλάσσει τον κωδικό με διακριτικά στο https://platform.scratcher.io/oauth/token.
- Τα διακριτικά πρόσβασης OAuth ισχύουν για δύο μήνες. Τα refresh tokens ισχύουν για τρεις μήνες· χρησιμοποιήστε τα για να λάβετε νέο διακριτικό πρόσβασης.
- Για να αλλάξετε το όνομα ή το redirect URI, κάντε κλικ στην εφαρμογή στην ενότητα My apps, κάντε την αλλαγή και πατήστε Save («Your settings have been saved»). «You cannot view your secret afterwards.»
- Το Delete app διαγράφει την εφαρμογή και η σύνδεση κάθε χρήστη με αυτήν σταματά να λειτουργεί: «Are you sure you want to delete this app? This cannot be undone!»
Εφαρμογές που έχετε εγκρίνει
Η ενότητα Authorized apps εμφανίζει τις εφαρμογές στις οποίες έχετε δώσει πρόσβαση στον λογαριασμό σας, όπως το Zapier, μαζί με τα δικαιώματά τους. Κάντε κλικ στο Revoke για να ανακαλέσετε την πρόσβαση.
Ποιος μπορεί να χρησιμοποιήσει το API;
Η σελίδα API εμφανίζεται σε χρήστες με ρόλο Owner, Admin ή Manager. Ένα διακριτικό δεν μπορεί ποτέ να κάνει περισσότερα από τον χρήστη που το δημιούργησε.