Scoutello API
Το Scoutello API είναι ένα API από διακομιστή σε διακομιστή για αμφίδρομο συγχρονισμό των επαφών, των εργασιών, των πρωτοκόλλων, των ευκαιριών, των έργων, των ορόσημων και των συμβάντων ενός οργανισμού. Παρέχει επίσης ιστορικό εξερχόμενης αλληλογραφίας μόνο για ανάγνωση, αναζήτηση μελών που μπορούν να ανατεθούν και ανακάλυψη ετικετών με επίγνωση οντοτήτων. Οι διαδρομές GET/list για σταδιακή ανάκτηση και οι ειδικοί παρτίδων με idempotency είναι τα βασικά στοιχεία συγχρονισμού σε αυτή την έκδοση. Δεν παρέχει λειτουργίες διαγραφής ή webhooks.
Η βασική διεύθυνση URL του API είναι:
https://admin.scoutello.com/api/v1
Εμφανίζεται επίσης στις Ρυθμίσεις οργανισμού → Developer/API. Το έγγραφο OpenAPI είναι διαθέσιμο στη διεύθυνση:
https://admin.scoutello.com/api/v1/openapi.json
Δημιουργία και προστασία κλειδιού
Για αρθρωτούς οργανισμούς, η ενότητα CRM πρέπει να είναι ενεργή, επιπλέον των απαιτούμενων πεδίων πρόσβασης του κλειδιού. Ένα έγκυρο κλειδί δεν μπορεί να ενεργοποιήσει μια ανενεργή ενότητα. Τα αιτήματα επιστρέφουν HTTP 403 με κωδικό σφάλματος module_not_active όταν η πρόσβαση στο CRM δεν είναι διαθέσιμη. Ένα άτομο με δικαιώματα διαχείρισης οργανισμού μπορεί να ελέγξει ή να ενεργοποιήσει το CRM στην ενότητα Συνδρομή· επανάληψη του αιτήματος μετά την ενεργοποίηση της πρόσβασης.
Ένα άτομο με δικαιώματα διαχείρισης οργανισμού μπορεί να δημιουργήσει μια ενσωμάτωση και ένα κλειδί API στις Ρυθμίσεις οργανισμού → Developer/API. Το πλήρες κλειδί εμφανίζεται μία φορά. Αντιγραφή του σε διαχειριστή μυστικών πριν από το κλείσιμο του διαλόγου· το Scoutello δεν μπορεί να εμφανίσει ξανά το πλήρες κλειδί.
- Χρήση ξεχωριστής ενσωμάτωσης και κλειδιού για κάθε εξωτερικό σύστημα και περιβάλλον.
- Χορήγηση μόνο των πεδίων πρόσβασης που χρειάζεται το εκάστοτε σύστημα.
- Να μην τοποθετείται ποτέ κλειδί σε κώδικα προγράμματος περιήγησης, URL, σύστημα ελέγχου εκδόσεων, αρχεία καταγραφής, μηνύματα υποστήριξης ή αποθηκευτικό χώρο στην πλευρά του πελάτη.
- Περιοδική αντικατάσταση των κλειδιών. Όταν αντικαθίσταται ένα ενεργό κλειδί, το νέο κλειδί λειτουργεί αμέσως και το προηγούμενο παραμένει έγκυρο για έως 15 λεπτά, ώστε το εξωτερικό σύστημα να πραγματοποιήσει την αλλαγή χωρίς διακοπή. Εξακολουθεί να ισχύει τυχόν προγενέστερη ημερομηνία λήξης, επομένως το προηγούμενο κλειδί μπορεί να σταματήσει να λειτουργεί νωρίτερα.
- Σε περίπτωση πιθανής έκθεσης ενός κλειδιού, προσωρινή παύση της ενσωμάτωσης πριν από την αντικατάστασή του. Η παύση απορρίπτει προσωρινά όλα τα κλειδιά της ενσωμάτωσης. Αντικατάσταση ενώ η ενσωμάτωση βρίσκεται σε παύση δεν παρέχει περίοδο επικάλυψης: το προηγούμενο κλειδί παραμένει απενεργοποιημένο και το νέο κλειδί παραμένει απενεργοποιημένο μέχρι την επανενεργοποίηση της ενσωμάτωσης.
- Οριστική ανάκληση ολόκληρης της ενσωμάτωσης κατά την αποσύνδεση ενός εξωτερικού συστήματος. Η ανάκληση απενεργοποιεί όλα τα κλειδιά της και δεν μπορεί να αναιρεθεί.
Αποστολή του κλειδιού σε κάθε πιστοποιημένο αίτημα:
Authorization: Bearer YOUR_API_KEY
Η πιστοποίηση Bearer προτιμάται. Οι πελάτες που δεν μπορούν να ορίσουν το Authorization μπορούν να χρησιμοποιήσουν αντ’ αυτού το x-api-key. Να μην αποστέλλονται και οι δύο κεφαλίδες· τα αιτήματα με διαφορετικές τιμές στις δύο κεφαλίδες απορρίπτονται.
Το API προορίζεται για πελάτες backend και δεν επιτρέπει πρόσβαση προγράμματος περιήγησης μεταξύ διαφορετικών προελεύσεων.
Χρήση του GET /whoami μετά τη ρύθμιση ενός κλειδιού, για την επαλήθευση της ενσωμάτωσης, του οργανισμού, των πεδίων πρόσβασης και των ορίων του κλειδιού, χωρίς ανάκτηση προσωπικών δεδομένων χρηστών.
Πεδία πρόσβασης
| Εμβέλεια | Επιτρέπει |
|---|---|
contacts.read | Καταχώριση και ανάκτηση επαφών. Εξαιρούνται οι επαφές λογαριασμών οργανισμού και μελών με δικαιώματα πρόσβασης. |
contacts.write | Επικύρωση και εφαρμογή ενημερώσεων ή εισαγωγών επαφών. |
tasks.read | Καταχώριση και ανάκτηση μη ιδιωτικών εργασιών. |
tasks.write | Επικύρωση και εφαρμογή ενημερώσεων ή εισαγωγών εργασιών. |
protocols.read | Καταχώριση και ανάκτηση μη ιδιωτικών πρωτοκόλλων. |
protocols.write | Επικύρωση και εφαρμογή ενημερώσεων ή εισαγωγών πρωτοκόλλων. |
opportunities.read | Καταχώριση και ανάκτηση ευκαιριών. |
opportunities.write | Επικύρωση και εφαρμογή ενημερώσεων ή εισαγωγών ευκαιριών. |
projects.read | Καταχώριση και ανάκτηση έργων. |
projects.write | Επικύρωση και εφαρμογή ενημερώσεων ή εισαγωγών έργων και συμμετεχόντων. |
milestones.read | Καταχώριση και ανάκτηση οροσήμων έργων. |
milestones.write | Επικύρωση και εφαρμογή ενημερώσεων ή εισαγωγών οροσήμων. |
members.read | Καταχώριση αποδεκτών μελών, μόνο με το Customer ID μέλους, το User ID και το εμφανιζόμενο όνομα. |
events.read | Καταχώριση και ανάκτηση συμβάντων και βασικών προγραμμάτων. |
events.write | Επικύρωση και εφαρμογή ενημερώσεων ή εισαγωγών συμβάντων. |
mails.read | Ανάγνωση ιστορικού εξερχόμενης αλληλογραφίας που ανήκει στον οργανισμό και έχει αποσταλεί ή αποτύχει. |
mail-drafts.read | Ανάγνωση των αυτόνομων προσχεδίων έγκρισης email και της κατάστασης παράδοσης της συγκεκριμένης ενσωμάτωσης. |
mail-drafts.write | Προετοιμασία ή αναθεώρηση προσχεδίων email για ανθρώπινη έγκριση· ποτέ έγκριση ή αποστολή. |
tags.read | Εντοπισμός επιλέξιμων ετικετών για τους υποστηριζόμενους τύπους οντοτήτων. |
Οι ιδιωτικές εργασίες και τα ιδιωτικά πρωτόκολλα δεν επιστρέφονται ποτέ από αυτό το API. Αν λείπει μια εμβέλεια, επιστρέφεται σφάλμα εξουσιοδότησης· δεν αντιμετωπίζεται ως κενό αποτέλεσμα.
Μια επαφή CRM που δεν είναι μέλος μπορεί να αναγνωστεί και να χρησιμοποιηθεί ως αναφορά, ακόμη και όταν είναι συνδεδεμένη με σύνδεση Scoutello. Η απόκριση περιέχει μόνο τα πεδία CRM του οργανισμού και ποτέ στοιχεία ταυτότητας ή πρόσβασης User. Οι επαφές με ρόλο, δικαιώματα, πρόσκληση, αποδοχή ή κατάσταση λογαριασμού οργανισμού παραμένουν κρυφές. Η επεξεργασία μιας επαφής που συνδέεται με σύνδεση παραμένει απαγορευμένη (protected_contact), συμπεριλαμβανομένων πεδίων CRM που κατά τα άλλα δεν έχουν αλλάξει. Για την αναφορά μιας υπάρχουσας αναγνώσιμης επαφής από εργασία ή πρωτόκολλο, το contacts.write μπορεί να δημιουργήσει τον εξωτερικό σύνδεσμό της μόνο με τα externalId, scoutelloId και προαιρετικά το externalUpdatedAt. Οι μεταγενέστερες ενημερώσεις μόνο των μεταδεδομένων σύνδεσης χρησιμοποιούν το externalId και προαιρετικά το externalUpdatedAt· παραλείπεται το scoutelloId αρχικής σύνδεσης αφού ολοκληρωθεί η σύνδεση. Αυτό δεν αλλάζει ποτέ την επαφή ή το User της. Η ανάθεση αποδεκτού μέλους χρησιμοποιεί την ξεχωριστή προβολή members.read.
Τα νέα κλειδιά χρησιμοποιούν το πρόθεμα sctl_api_ και ξεκινούν μόνο με το contacts.write. Κάθε άλλο scope απαιτεί ρητή συγκατάθεση, την οποία πρέπει να παραχωρήσει ένα άτομο με δικαιώματα διαχείρισης του οργανισμού κατά τη δημιουργία ή την περιστροφή ενός κλειδιού. Τα υπάρχοντα διαπιστευτήρια διατηρούν τα τρέχοντα scope τους και παραμένουν έγκυρα.
Επαφές συνδεδεμένες με έργα και προσχέδια email
Οι upsert λειτουργίες επαφών δέχονται προαιρετικά ζεύγη projectScoutelloId / projectExternalId και companyScoutelloId / companyExternalId (επιλέξτε ένα από κάθε ζεύγος). Η επαφή, η σχέση με την εταιρεία και η συμμετοχή στο έργο αποθηκεύονται ατομικά και ατομικά. Η προσθήκη συμμετοχής σε έργο απαιτεί projects.write· οι παραλειπόμενες αναφορές διατηρούν τις υπόλοιπες σχέσεις και συμμετοχές. Οι αναγνώσεις των στοιχείων επαφής περιλαμβάνουν το projectParticipations όταν έχει παραχωρηθεί το projects.read. Οι agents έργων πωλήσεων πρέπει να περιλαμβάνουν ρητά την αναφορά στο έργο, ακόμη και όταν επαναχρησιμοποιούν μια επαφή.
Τα αυτόνομα προσχέδια χρησιμοποιούν το υπάρχον σύστημα έγκρισης από άτομο, χωρίς εκτέλεση ροής εργασίας:
| Μέθοδος | Διαδρομή | Σκοπός |
|---|---|---|
| GET | /mail-drafts | Σελιδοποιημένα προσχέδια που ανήκουν στην ενσωμάτωση· προαιρετικά φίλτρα projectScoutelloId και status. |
| GET | /mail-drafts/{scoutelloId} | Τρέχουσα έκδοση, σύνδεσμος ελέγχου, hash περιεχομένου, κατάσταση έγκρισης/αποστολής και τελικό ID email. |
| GET | /mail-drafts/external/{externalId} | Αναζήτηση σταθερού εξωτερικού ID της ενσωμάτωσης. |
| POST | /mail-drafts/batch-upsert | Επικύρωση ή εφαρμογή προετοιμασίας προσχεδίου. |
Η προετοιμασία προσχεδίου απαιτεί mail-drafts.write, contacts.read και projects.write. Η αναφερόμενη επαφή γίνεται συμμετέχουσα στο έργο. Το άτομο που εγκρίνει πρέπει να είναι αποδεκτό μέλος του οργανισμού με δικαίωμα επεξεργασίας email. Η επιλογή αποστολέα χρησιμοποιεί τις υφιστάμενες επιτρεπόμενες ρυθμίσεις αποστολέα του συγκεκριμένου μέλους για τον οργανισμό ή για προσωπική χρήση· αυθαίρετες διευθύνσεις From δεν γίνονται αποδεκτές.
{
"mode": "validate",
"records": [{
"externalId": "sales:indoor:outreach:museum:v1",
"expectedVersion": 0,
"project": { "externalId": "sales:indoor" },
"contact": { "externalId": "sales:indoor:museum:person" },
"approverScoutelloUserId": "ACCEPTED_MEMBER_USER_ID",
"senderScope": "organization",
"content": {
"to": ["verified-recipient@example.com"],
"subject": "Indoor tour proposal",
"body": "The intended email copy only.",
"notes": "Internal research and review context; not sent."
}
}]
}
Ελέγξτε κάθε αποτέλεσμα επικύρωσης πριν επαναλάβετε τη διαδικασία με mode: "apply". Διαβάστε το ID που προέκυψε για να λάβετε τα reviewUrl, draftVersion, contentHash, status, dispatchStatus και mailScoutelloId. Χρησιμοποιήστε το expectedVersion: 0 μόνο για τη δημιουργία και την τρέχουσα έκδοση που επιστράφηκε για τις αναθεωρήσεις. Το περιβάλλον και το άτομο που εγκρίνει είναι αμετάβλητα· τα προσχέδια που έχουν ελεγχθεί ή αποσταλεί απορρίπτουν αλλαγμένο περιεχόμενο. Οι ταυτόσημες επαναλήψεις επιστρέφουν το αρχικό προσχέδιο.
Τα προσχέδια εμφανίζονται στις καρτέλες email των έργων και των επαφών και στις ειδοποιήσεις έγκρισης του πίνακα ελέγχου. Η προετοιμασία μέσω API δεν στέλνει email, ούτε email ειδοποίησης· η υπάρχουσα συμπεριφορά των email ειδοποίησης των ροών εργασίας παραμένει αμετάβλητη. Το αρμόδιο άτομο μπορεί να επεξεργαστεί παραλήπτες, θέμα, κείμενο και υποστηριζόμενα συνημμένα, να αποθηκεύσει την έκδοση και να επιλέξει Έγκριση και αποστολή. Οι ενσωματώσεις δεν μπορούν να εγκρίνουν ή να στέλνουν. Οι αποτυχημένες ή αβέβαιες παραδόσεις δεν επαναλαμβάνονται ποτέ χωρίς έλεγχο. Κατά τη μετατροπή προσχεδίων που βασίζονται σε πρωτόκολλα, διατηρήστε τα πρωτόκολλα και προσθέστε αμοιβαίες αναφορές στις αντικαταστάσεις τους.
Πρόσβαση μέσω MCP
Το ίδιο κλειδί API του Scoutello και τα ίδια πεδία πρόσβασης μπορούν να χρησιμοποιηθούν στο τελικό σημείο MCP με streamable HTTP:
https://admin.scoutello.com/api/v1/mcp
Ρυθμίστε τον πελάτη MCP ώστε να στέλνει Authorization: Bearer YOUR_API_KEY. Το παλιό URL /api/mcp παραμένει ως ψευδώνυμο συμβατότητας διαδρομής, αλλά οι νέοι πελάτες πρέπει να χρησιμοποιούν το τελικό σημείο με έκδοση. Τα παλαιότερα διαπιστευτήρια sctl_mcp_ δεν γίνονται δεκτά· αντικαταστήστε τα με κλειδί ενσωμάτωσης API του Scoutello.
Τα εργαλεία MCP αντιστοιχούν άμεσα στη σύμβαση REST και χρησιμοποιούν τα ίδια σχήματα χρόνου εκτέλεσης, ελέγχους οργανισμού, κύκλο ζωής ενσωμάτωσης, όρια ρυθμού και μεθόδους υπηρεσίας. Για παράδειγμα, τα contacts_list, contacts_get, contacts_get_by_external_id και contacts_batch_upsert αντιστοιχούν στις τέσσερις διαδρομές επαφών. Το ίδιο ισχύει για εργασίες, πρωτόκολλα, ευκαιρίες, έργα, ορόσημα και εκδηλώσεις· για email υπάρχουν τα mails_list και mails_get, για μέλη το members_list και για ετικέτες το tags_list.
Ο διακομιστής ανακοινώνει μόνο εργαλεία που επιτρέπονται από τα πεδία πρόσβασης του τρέχοντος κλειδιού. Ένα κλειδί με contacts.read εντοπίζει τα εργαλεία ανάγνωσης επαφών αλλά όχι το contacts_batch_upsert· ένα κλειδί με contacts.write λαμβάνει το εργαλείο μαζικής εισαγωγής ή ενημέρωσης αλλά όχι τα εργαλεία ανάγνωσης. Το whoami είναι πάντα διαθέσιμο. Τα εργαλεία εγγραφής έχουν τις ίδιες άμεσες επιπτώσεις με τα αντίστοιχα REST. Χρησιμοποιήστε mode: "validate" για έλεγχο μιας δέσμης χωρίς εφαρμογή της.
Το MCP προορίζεται επίσης για επικοινωνία μεταξύ διακομιστών και δεν ενεργοποιεί πρόσβαση προγράμματος περιήγησης μεταξύ διαφορετικών προελεύσεων. Η μεταφορά JSON-RPC απαιτεί ειδικό URL, οπότε το MCP δεν μπορεί να χρησιμοποιεί το ίδιο URL με έναν μεμονωμένο πόρο REST, παρότι ο έλεγχος ταυτότητας και η συμπεριφορά δεδομένων είναι ίδια.
Ο οδηγός ενσωμάτωσης MCP παρέχει πλήρεις οδηγίες για ρύθμιση πελάτη, επαλήθευση, αντιστοίχιση εργαλείων και αντιμετώπιση προβλημάτων.
Ανάγνωση εγγραφών
Οι επαφές, εργασίες, πρωτόκολλα, ευκαιρίες, έργα, ορόσημα και εκδηλώσεις χρησιμοποιούν τις ίδιες διαδρομές ανάγνωσης:
GET /contacts?limit=50&updatedSince=2026-09-01T00:00:00.000Z
GET /contacts/{scoutelloId}
GET /contacts/external/{externalId}
Για τους άλλους πόρους συγχρονισμού, αντικαταστήστε το contacts με tasks, protocols, opportunities, projects, milestones ή events. Το externalId εμφανίζεται σε ένα DTO ανάγνωσης όταν η εγγραφή έχει συνδεθεί από αυτή την ενσωμάτωση.
Μια απόκριση λίστας έχει αυτό το περίβλημα:
{
"data": [],
"page": {
"nextCursor": null,
"hasMore": false,
"snapshotAt": "2026-09-01T12:00:00.000Z"
},
"requestId": "request-id"
}
Το limit πρέπει να είναι από 1 έως 100. Τα αποτελέσματα ταξινομούνται σύμφωνα με τον ενεργό χρόνο κατά τον οποίο άλλαξε η αναπαράστασή τους στο δημόσιο API και, στη συνέχεια, σύμφωνα με το Scoutello ID. Αυτός ο ενεργός χρόνος μπορεί να είναι μεταγενέστερος από το updatedAt της επιστρεφόμενης οντότητας, όταν άλλαξαν μεταδεδομένα συνδέσμου ενοποίησης. Οι δρομείς είναι αδιαφανείς: αποθηκεύστε και στείλτε τους χωρίς αλλαγές και μην εξάγετε συμπεράσματα από το περιεχόμενό τους.
Η πρώτη απόκριση καθορίζει το snapshotAt για αυτήν τη διέλευση. Ακολουθήστε το nextCursor μέχρι το hasMore να είναι false, πριν ξεκινήσετε άλλη επαυξητική ανάγνωση. Έτσι αποτρέπεται η αστάθεια της τρέχουσας διέλευσης λόγω αλλαγών σε εγγραφές κατά την σελιδοποίηση.
Για επαυξημένο συγχρονισμό, καταναλώστε κάθε σελίδα του δρομέα και, στη συνέχεια, αποθηκεύστε το snapshotAt της συγκεκριμένης διέλευσης ως χρονική σήμανση υψηλού ορίου. Περάστε το ως τιμή updatedSince σε μορφή ISO 8601 στην επόμενη διέλευση. Το κάτω όριο συμπεριλαμβάνεται, επομένως η επανάληψη ενός ολοκληρωμένου στιγμιότυπου μπορεί να επιστρέψει εγγραφές ορίου, αλλά δεν μπορεί να τις παραλείψει.
Μια απόκριση μίας εγγραφής έχει αυτό το περίβλημα:
{
"data": {},
"requestId": "request-id"
}
Οι αποκρίσεις για μεμονωμένες επαφές περιλαμβάνουν επίσης έναν πίνακα relations. Κάθε σχέση διατηρεί το ID σχέσης του Scoutello, τον χρόνο δημιουργίας, τον τύπο, τις σημειώσεις, καθώς και τις αναφορές επαφών connectedFrom και
connectedTo. Οι αναφορές επαφών περιέχουν το Scoutello ID
και το εξωτερικό ID αυτής της ενοποίησης, όταν υπάρχει. Οι επαφές που εξαιρούνται από το όριο απορρήτου πρόσβασης του οργανισμού στο API δεν εμφανίζονται μέσω σχέσεων.
Η απόκριση λίστας επαφών παραμένει συνοπτική και δεν περιλαμβάνει σχέσεις· χρησιμοποιήστε
οποιαδήποτε διαδρομή μεμονωμένης επαφής, όταν απαιτούνται λεπτομέρειες σχέσεων.
Φίλτρα εργασίας και εμβέλεια δρομέα
Οι λίστες επαφών δέχονται τα search, type (person, company, supplier, other), status και tagIds. Η αναζήτηση περικόπτεται, δεν κάνει διάκριση πεζών-κεφαλαίων και περιορίζεται σε 200 χαρακτήρες / 10 διακριτά στοιχεία χωρισμένα με κενά. Κάθε στοιχείο πρέπει να εμφανίζεται σε τουλάχιστον ένα από τα firstName, lastName ή companyName, συμπεριλαμβανομένων των παλαιών ονομάτων εταιρειών που είναι αποθηκευμένα στο lastName. Χαρακτήρες όπως οι % και _ αντιστοιχίζονται κυριολεκτικά. Οι ετικέτες χρησιμοποιούν αντιστοίχιση οποιουδήποτε από με 1–50 ID. Όλα τα παρεχόμενα φίλτρα συνδυάζονται με AND. Το REST κωδικοποιεί τα ID ετικετών ως επαναλαμβανόμενες παραμέτρους· το MCP παρέχει έναν πίνακα:
GET /contacts?search=Hamburg%20Hotel&type=company&status=prospect&tagIds=tag-one&tagIds=tag-two
Οι δρομείς επαφών συνδέονται με τον οργανισμό, την ενοποίηση και κάθε φίλτρο. Διατηρείτε τα φίλτρα σε κάθε σελίδα· η αλλαγή φίλτρου απορρίπτει τον δρομέα. Η σειρά και οι διπλότυπες ετικέτες, καθώς και η σειρά, η πεζοκεφαλαιοποίηση και τα κενά των στοιχείων αναζήτησης, δεν αλλάζουν το ενεργό φίλτρο.
Οι διαδρομές λιστών εργασίας δέχονται τα ακόλουθα πρόσθετα φίλτρα· άλλοι συνδυασμοί πόρων/πεδίων απορρίπτονται:
| Πόρος | Φίλτρα |
|---|---|
| Εργασίες | projectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter |
| Πρωτόκολλα | projectScoutelloId, milestoneScoutelloId, status (draft ή final) |
| Ευκαιρίες | projectScoutelloId, stage, ownerScoutelloUserId |
| Έργα | status, assignedContactScoutelloId |
| Ορόσημα | projectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter |
Το dueBefore είναι αποκλειστικό· το dueAfter είναι συμπεριληπτικό. Συγκρίνουν την ημερομηνία λήξης της εργασίας ή την ημερομηνία λήξης του ορόσημου· οι εγγραφές χωρίς αυτή την ημερομηνία δεν ταιριάζουν. Παρέχετε ημερομηνίες-ώρες ISO με πληροφορίες ζώνης ώρας. Όλα τα φίλτρα εφαρμόζονται πριν από τη σελιδοποίηση. Συνεχίστε έναν δρομέα με ακριβώς τα ίδια φίλτρα, συμπεριλαμβανομένου του updatedSince, και τον ίδιο οργανισμό/την ίδια ενσωμάτωση. Το μέγεθος σελίδας μπορεί να αλλάξει. Οι παλιοί δρομείς χωρίς πεδίο εφαρμογής πρέπει, μετά από αυτή την έκδοση, να ξεκινούν ξανά από τη σωσμένη χρονική σήμανση υψηλότερου ορίου.
Έργα, ορόσημα, αναθέσεις και σημειώσεις
Το GET /members (MCP members_list) χρησιμοποιεί τυπική σελιδοποίηση και απαιτεί το members.read. Επιστρέφει το scoutelloId (ID μέλους Customer), το scoutelloUserId (ID User) και το displayName. Εμφανίζονται μόνο αποδεκτά μέλη του οργανισμού με ρόλο· η αναζήτηση δεν αποκαλύπτει email ή δικαιώματα.
Οι εργασίες δέχονται το assignedScoutelloUserIds· οι ευκαιρίες χρησιμοποιούν το ownerScoutelloUserId. Τα έργα και τα ορόσημα χρησιμοποιούν το assignedContacts: [{"scoutelloId":"member-customer-id"}]. Οι αναθέσεις απαιτούν αποδεκτά μέλη του οργανισμού του διαπιστευτηρίου. Οι παραλειπόμενες αναθέσεις παραμένουν αμετάβλητες· το [] τις διαγράφει. Οι εισαγωγές έργων, ορόσημων, εργασιών και πρωτοκόλλων πραγματοποιούνται αθόρυβα: δεν αποστέλλουν ειδοποιήσεις αναθέσεων ή άλλες επικοινωνίες.
Το συμβάν assignedContacts υποστηρίζει ευανάγνωστες επαφές CRM και αποδεκτά μέλη που παρέχονται μέσω του Customer ID του μέλους. Τα αποδεκτά μέλη παραμένουν μη διαθέσιμα ως συνήθεις αναφορές επαφών CRM ή ως στόχοι εξωτερικών συνδέσμων· χρησιμοποιήστε το πεδίο ανάθεσης μέλους για την ευθύνη της ομάδας.
Δημιουργία ορόσημων με name και είτε projectScoutelloId είτε projectExternalId. Υποστηρίζουν description (Markdown), status (open, in_progress, completed, closed), nullable startDate/endDate, order (με προεπιλεγμένη τιμή 0) και assignedContacts. Οι ημερομηνίες δεν μπορούν να ολοκληρώνονται πριν από την ημερομηνία έναρξης. Κάθε ορόσημο διαθέτει σταθερό εξωτερικό σύνδεσμο με εμβέλεια την ενσωμάτωση. Το έργο του δεν μπορεί να αλλάξει μέσω του API. Η δημιουργία και η ενημέρωση τοπικοποιούν το όνομα και την περιγραφή στη γλώσσα του οργανισμού.
Οι εργασίες και τα πρωτόκολλα δέχονται αναφορές σε έργο, ορόσημο και ευκαιρία ως <entity>ScoutelloId ή <entity>ExternalId, για παράδειγμα milestoneExternalId. Να παρέχεται μόνο μία ονομασία για κάθε σχέση, ακόμη και κατά την εκκαθάριση με null. Όλες οι σχέσεις πρέπει να ανήκουν στον οργανισμό του διαπιστευτηρίου. Μια αναφορά μόνο σε ορόσημο συμπεραίνει το έργο. Αντικρουόμενο έργο ή ρητή εκκαθάριση ενός έργου ενώ διατηρείται το αντίστοιχο ορόσημο απορρίπτεται. Μια συνδεδεμένη ευκαιρία με έργο πρέπει να συμφωνεί με το έργο της εργασίας. Οι σχέσεις που παραλείπονται διατηρούν τις τρέχουσες τιμές. Η ρητή τιμή null εκκαθαρίζει μια σχέση όταν το υπόλοιπο περιβάλλον είναι έγκυρο. Οι αναγνώσεις εμφανίζουν και τις δύο ονομασίες ID, καθώς και τις αναθέσεις εργασιών.
Σχεδιασμός εργασιών και ροές εργασίας
Το status της εργασίας είναι το αμετάβλητο κλειδί μιας κατάστασης στην ενεργή ροή εργασίας της εργασίας και όχι μια προκαθορισμένη απαρίθμηση. Ανάγνωση των διαθέσιμων ροών εργασίας του οργανισμού και του έργου με GET /task-workflows χρησιμοποιώντας το πεδίο tasks.read. Κάθε κατάσταση περιλαμβάνει το κλειδί, την ετικέτα, τον κύκλο ζωής type (backlog, unstarted, started, completed ή cancelled), το χρώμα, τη σειρά, την ένδειξη προεπιλογής και την κατάσταση αρχειοθέτησης. Οι εγγραφές έργων υποδεικνύουν αν η ροή εργασίας του οργανισμού κληρονομείται. Η διαμόρφωση των ροών εργασίας εξακολουθεί να διαχειρίζεται από τον πίνακα ελέγχου.
Οι εργασίες δέχονται nullable priority (low, medium, high ή urgent) και estimatedEffortMinutes, καθώς και nullable startDate και dueDate. Οι αναγνώσεις εργασιών περιλαμβάνουν το αποκανονικοποιημένο statusType, την αναφορά γονικής εργασίας, συμπαγείς αναφορές υποεργασιών και αναφορές blockedBy / blocks.
Δημιουργήστε ή ενημερώστε μια υποεργασία ενός επιπέδου με είτε parentTaskScoutelloId είτε parentTaskExternalId· το null την προάγει σε εργασία ανώτατου επιπέδου. Οι εξαρτήσεις χρησιμοποιούν πίνακες αναφορών { "scoutelloId": "..." } ή { "externalId": "..." } στα blockedBy και blocks. Τα πεδία σχέσεων που παραλείπονται διατηρούν τις υπάρχουσες σχέσεις, ενώ ένας κενός πίνακας εξαρτήσεων διαγράφει τη συγκεκριμένη κατεύθυνση. Το API απορρίπτει ένθετες υποεργασίες, εξαρτήσεις γονέα-παιδιού, εξαρτήσεις μεταξύ οργανισμών, διπλότυπα, αναφορές στον ίδιο τον πόρο και άμεσους ή μεταβατικούς κύκλους.
Τα φίλτρα της λίστας εργασιών δέχονται ακριβές status ροής εργασίας, statusType κύκλου ζωής, priority, parentState (top_level, subtask ή parent) και blockedState (blocked, blocking ή unblocked).
Τα πρωτόκολλα δέχονται επιπλέον status: "draft" | "final" (οι νέες εγγραφές ορίζονται από προεπιλογή σε final). Για ένα νέο πρωτόκολλο απαιτούνται type, date και είτε μια επαφή είτε έγκυρο πλαίσιο έργου/ορόσημου. Το contactExternalId: null διαγράφει την επαφή του μόνο όταν παραμένει το πλαίσιο έργου/ορόσημου. Έτσι, μπορούν να δημιουργούνται και να διαβάζονται εσωτερικές σημειώσεις έργου χωρίς να επινοείται πελάτης. Τα Draft/final περιγράφουν την κατάσταση της σημείωσης και δεν αποστέλλουν ποτέ επικοινωνία. Οι ιδιωτικές εργασίες και τα πρωτόκολλα παραμένουν μη προσβάσιμα.
Συμμετέχοντες έργου
Το έργο participants περιέχει προσθετικές ενημερώσεις ή εισαγωγές, με κλειδί μια αναφορά contact, για παράδειγμα:
{
"externalId": "gtm:hotels",
"participants": [{
"contact": {"scoutelloId": "prospect-contact-id"},
"role": "Potential pilot",
"notes": "Existing warm lead; qualify the next step.",
"groupScoutelloId": null
}]
}
Οι συμμετέχοντες περιγράφουν υποψήφιους πελάτες/πελάτες που συνδέονται με ένα έργο· τα υπεύθυνα μέλη χρησιμοποιούν αναθέσεις. Οι συμμετέχοντες που παραλείπονται, ένας κενός πίνακας και τα πεδία συμμετεχόντων που παραλείπονται διατηρούν τα υπάρχοντα δεδομένα. Το null διαγράφει το role, το notes ή το groupScoutelloId. Οι διπλότυπες επιλυμένες επαφές στο ίδιο φορτίο απορρίπτονται. Οι ομάδες πρέπει ήδη να ανήκουν στο επιλεγμένο έργο· οι αναγνώσεις περιλαμβάνουν το participantGroups (ID/όνομα), καθώς και ID συμμετεχόντων, επαφές, ρόλο, σημειώσεις και ID ομάδας. Η αφαίρεση συμμετεχόντων ή η δημιουργία ομάδων είναι προς το παρόν διαθέσιμη στον πίνακα ελέγχου.
Μαζική εισαγωγή ή ενημέρωση εγγραφών
Εγγράψτε έως και 100 εγγραφές μέσω της διαδρομής μαζικής επεξεργασίας του πόρου:
POST /contacts/batch-upsert
Content-Type: application/json
{
"mode": "apply",
"records": [
{
"externalId": "record-123",
"externalUpdatedAt": "2026-09-01T11:45:00.000Z",
"type": "person",
"firstName": "Alex",
"lastName": "Example",
"email": "alex@example.com"
}
]
}
Οι μαζικές επεξεργασίες εργασιών επιλύουν τις εγγραφές εργασιών πριν εφαρμόσουν τις σχέσεις γονέα και εξαρτήσεων. Αυτή η επεξεργασία δύο φάσεων επιτρέπει σε μια εργασία γονέα, αποκλεισμού ή αποκλεισμένη εργασία να αναφέρεται σε άλλη εργασία που δημιουργείται στην ίδια μαζική επεξεργασία μέσω του εξωτερικού ID της, ανεξάρτητα από τη σειρά των εγγραφών.
Χρησιμοποιήστε το έγγραφο OpenAPI για τα πεδία και τους περιορισμούς επικύρωσης κάθε πόρου. Κάθε εγγραφή πρέπει να διαθέτει ένα σταθερό externalId μήκους 1 έως 200 χαρακτήρων. Αντιμετωπίστε το ως αδιαφανή τεχνικό αναγνωριστικό: μην χρησιμοποιείτε διεύθυνση email, όνομα, μυστικό API ή άλλα προσωπικά δεδομένα. Το externalUpdatedAt είναι προαιρετικό, αλλά συνιστάται ιδιαίτερα όταν το σύστημα προέλευσης παρέχει αξιόπιστη χρονική σήμανση τροποποίησης.
Το σώμα του αιτήματος περιορίζεται σε 1 MiB. Το mode έχει ως προεπιλογή το apply:
- Το
applyεπικυρώνει και καταχωρίζει τις αποδεκτές εγγραφές. - Το
validateεκτελεί την ίδια επικύρωση και αντιστοίχιση χωρίς καταχώριση και επιστρέφει αποτελέσματαwould_*.
Για εισαγωγές επαφών, το matchByEmail μπορεί να οριστεί σε true στο αίτημα. Έχει ως προεπιλογή το false· το εξωτερικό ID αποτελεί το ασφαλέστερο προεπιλεγμένο όριο ταυτοποίησης.
Τα πεδία που παραλείπονται διατηρούν την τρέχουσα τιμή τους. Ένα ρητό null εκκαθαρίζει ένα πεδίο που επιτρέπει την τιμή null, ενώ ένας παρεχόμενος κενός πίνακας αναθέσεων/ετικετών εκκαθαρίζει τη συγκεκριμένη σχέση. Τα Project participants είναι προσθετικές ενημερώσεις ή εισαγωγές: ένας κενός πίνακας αφήνει το ρόστερ αμετάβλητο. Οι εγγραφές ετικετών για επαφές, εργασίες, ευκαιρίες και συμβάντα χρησιμοποιούν τα ID ετικετών του Scoutello. Τα εξωτερικά ID σχέσεων επιλύονται μόνο μέσω συνδέσμων που ανήκουν στην τρέχουσα ενσωμάτωση, ενώ τα ID χρηστών του Scoutello που χρησιμοποιούνται για ιδιοκτησία ή υπευθυνότητα πρέπει να αντιστοιχούν σε αποδεκτά μέλη του τρέχοντος οργανισμού.
Για τη δημιουργία ευκαιριών απαιτείται λογαριασμός ή επαφή, ενώ για τις χαμένες ευκαιρίες απαιτείται αιτία απώλειας. Τα χρηματικά ποσά χρησιμοποιούν ακέραια λεπτά. Τα ονόματα και οι περιγραφές έργων και συμβάντων διαβάζονται και εγγράφονται στη διαμορφωμένη γλώσσα του οργανισμού. Οι εγγραφές συμβάντων υποστηρίζουν συγκεκριμένες ημερομηνίες και ημερήσια, εβδομαδιαία ή μηνιαία επανάληψη με εξαιρέσεις· τα επίπεδα ορατότητας των δημοσιευμένων συμβάντων εξακολουθούν να υπόκεινται στους ελέγχους νομικής ετοιμότητας του Scoutello. Το API δεν παρέχει πρόσβαση σε έκδοση εισιτηρίων για συμβάντα, συμμετέχοντες, πολυμέσα, πρότυπα, ενημερωτικά δελτία, συνεργασίες ή άλλους προηγμένους ελέγχους διαχείρισης συμβάντων.
Εντοπισμός ετικετών
Χρησιμοποιήστε το endpoint ετικετών πριν καταχωρίσετε το tagIds:
GET /tags?entity=events&type=category
Το entity είναι υποχρεωτικό και δέχεται contacts, tasks, opportunities ή events. Αντιστοιχίζεται στη σχετική αποθηκευμένη συνάφεια ετικέτας. Το type είναι προαιρετικό και δέχεται category ή attribute. Οι επιλέξιμες κατηγορίες μπορεί να ανήκουν στον οργανισμό ή να είναι καθολικές· τα επιλέξιμα χαρακτηριστικά προέρχονται από το επιμελημένο καθολικό σύνολο χαρακτηριστικών του Scoutello. Τα αποτελέσματα περιλαμβάνουν το scoutelloId, το όνομα μεταφρασμένο στη γλώσσα του οργανισμού, το type και το relevancy. ID ετικετών από άλλον οργανισμό, με εσφαλμένη συνάφεια ή μη επιλέξιμα απορρίπτουν το αντίστοιχο στοιχείο της δέσμης.
Ανάγνωση ιστορικού εξερχόμενης αλληλογραφίας
Το ιστορικό αλληλογραφίας είναι μόνο για ανάγνωση:
GET /mails?updatedSince=2026-09-01T00:00:00.000Z
GET /mails/{scoutelloId}
Επιστρέφεται μόνο αλληλογραφία που ανήκει στον οργανισμό και βρίσκεται σε κατάσταση sent ή failed. Οι αποκρίσεις περιέχουν κοινές αποθηκευμένες κεφαλίδες και το σώμα του μηνύματος, BCC, την κατάσταση και τις χρονικές σημάνσεις, αναφορές σε έργα/εκδηλώσεις/ενημερωτικά δελτία, αναγνωριστικά και τύπους συνημμένων, καθώς και συγκεντρωτικά στατιστικά παράδοσης/ανοίγματος/κλικ/αναπηδήσεων/παραπόνων/απόρριψης παραληπτών. Τα πρόχειρα, η αλληλογραφία σε ουρά ή σε προγραμματισμένη αποστολή, οι εγγραφές ανά παραλήπτη, τα αποτυπωμένα στιγμιότυπα, τα ακατέργαστα σφάλματα παρόχου και τα URL λήψης συνημμένων δεν εκτίθενται ποτέ. Μια μεταγενέστερη ενημέρωση παράδοσης παραλήπτη προωθεί την αποτελεσματική χρονική σήμανση συγχρονισμού της αλληλογραφίας, ώστε αυτή να εμφανιστεί ξανά σε αυξητικές αναγνώσεις. Δεν υπάρχουν διαδρομές εγγραφής αλληλογραφίας.
Το αποτέλεσμα εφαρμογής μπορεί να είναι created, updated, linked, unchanged, stale_ignored ή rejected. Η επικύρωση χρησιμοποιεί would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale ή rejected. Ένα έγκυρο αίτημα δέσμης επιστρέφει HTTP 200 ακόμη και όταν απορρίπτονται μεμονωμένες εγγραφές, επομένως ελέγχετε πάντα κάθε στοιχείο και τη σύνοψη της απόκρισης. Διατηρήστε την απόκριση requestId όταν ζητάτε από την υποστήριξη του Scoutello να διερευνήσει μια αποτυχία.
Χρονικές σημάνσεις και διενέξεις
Όταν υπάρχει το externalUpdatedAt, το Scoutello το χρησιμοποιεί για να απορρίπτει παρωχημένες αλλαγές χωρίς να αποτυγχάνει η υπόλοιπη δέσμη. Ένα αποτέλεσμα stale_ignored είναι οριστικό για εκείνο το παλαιότερο φορτίο· ανακτήστε την τρέχουσα εγγραφή πριν αποφασίσετε αν θα στείλετε νεότερη έκδοση.
Αντιμετωπίζετε τις χρονικές σημάνσεις ως τιμές UTC ISO 8601. Διατηρείτε την αρχική ακρίβειά τους και μην αντικαθιστάτε την ώρα εκτέλεσης μιας εργασίας συγχρονισμού με την ώρα τροποποίησης της εγγραφής προέλευσης.
Ιδempotency
Το όριο ιδιοδυναμίας είναι η ενοποίηση μαζί με το externalId. Το Scoutello συγκρίνει ένα κανονικοποιημένο hash του φορτίου και την προαιρετική τιμή externalUpdatedAt, επομένως η επανάληψη της ίδιας εγγραφής δεν δημιουργεί διπλότυπα και μπορεί να επιστρέψει unchanged.
Με το externalUpdatedAt, η ίδια χρονική σήμανση και το ίδιο φορτίο είναι unchanged, μια παλαιότερη χρονική σήμανση είναι stale_ignored και η ίδια χρονική σήμανση με διαφορετικό φορτίο αποτελεί διένεξη έκδοσης. Για έναν σύνδεσμο που δεν έχει αποδεχτεί ποτέ χρονική σήμανση, ένα φορτίο χωρίς χρονική σήμανση που παραμένει ίδιο είναι unchanged, ενώ ένα αλλαγμένο φορτίο εφαρμόζεται με τη σειρά άφιξης. Αφού ένας σύνδεσμος αποδεχτεί χρονική σήμανση, ένα αλλαγμένο φορτίο που παραλείπει το externalUpdatedAt απορρίπτεται ως διένεξη έκδοσης, ώστε τα δεδομένα χωρίς έκδοση να μην μπορούν να αντικαταστήσουν την κατάσταση με έκδοση. Γι’ αυτό συνιστάται ιδιαίτερα η χρήση χρονικών σημάνσεων τροποποίησης από την πηγή.
Ίχνος ελέγχου
Οι αποδεκτές ενέργειες δημιουργίας, ενημέρωσης και συγχρονισμού μόνο συνδέσεων μέσω API εμφανίζονται στα αρχεία αλλαγών του Scoutello με πηγή Public API και συνδέονται με την υπεύθυνη ενσωμάτωση. Οι συνοπτικές αναφορές λειτουργίας διατηρούν τα αναγνωριστικά αιτημάτων και τις συγκεντρωτικές μετρήσεις αποτελεσμάτων για αντιμετώπιση προβλημάτων· δεν διατηρούν φορτία εγγραφών ή μυστικά API.
Σφάλματα και επαναπροσπάθειες
Τα σφάλματα σε επίπεδο αιτήματος χρησιμοποιούν το εξής περίβλημα:
{
"error": {
"code": "error_code",
"message": "Safe error message",
"requestId": "request-id",
"details": {}
}
}
Εκτελείτε εκ νέου τα αιτήματα HTTP 429 και τις προσωρινές αποκρίσεις 5xx με εκθετική καθυστέρηση και τυχαιότητα. Τηρείτε το Retry-After όταν υπάρχει. Οι αποτυχίες δικτύου ενδέχεται να έχουν προκύψει αφού το Scoutello αποδέχτηκε ένα αίτημα· η εκ νέου αποστολή της ίδιας δέσμης είναι ασφαλής, επειδή κάθε εγγραφή είναι ιδιοδύναμη βάσει εξωτερικού ID και κανονικοποιημένου φορτίου. Μην εκτελείτε αυτόματα εκ νέου αιτήματα για αποτελέσματα ελέγχου ταυτότητας, εξουσιοδότησης, επικύρωσης, διένεξης έκδοσης ή μεμονωμένων rejected χωρίς να αλλάξετε το αίτημα.
Προτεινόμενος αμφίδρομος βρόχος συγχρονισμού
- Καλέστε το
/whoamiκατά τη ρύθμιση και επαληθεύστε τον αναμενόμενο οργανισμό και τα πεδία πρόσβασης. - Διαβάστε κάθε σελίδα που έχει αλλάξει από το τελευταίο ολοκληρωμένο υψηλό σημείο και εφαρμόστε τις αλλαγές στο εξωτερικό σύστημα με ιδιοδύναμο τρόπο.
- Στείλτε τις εξωτερικές αλλαγές στο
/batch-upsert, χρησιμοποιώντας σταθερά εξωτερικά ID και χρονικές σημάνσεις τροποποίησης της πηγής. - Αποθηκεύστε σημεία ελέγχου μόνο αφού ολοκληρωθεί η επεξεργασία όλων των σελίδων και των αποτελεσμάτων των στοιχείων.
- Επιλύστε τις διενέξεις σύμφωνα με τους κανόνες κυριότητας του συστήματος-πηγής· μην προσομοιώνετε διαγραφές στέλνοντας κενές εγγραφές.
Το Scoutello δεν παρέχει σκόπιμα δημόσια διαδρομή διαγραφής σε αυτήν την πρώτη έκδοση. Διαχειριστείτε τις πολιτικές διαγραφής ή αρχειοθέτησης εκτός API, μέχρι να εισαχθεί μια τεκμηριωμένη λειτουργία κύκλου ζωής.
Αναρτήσεις κοινωνικών δικτύων για ανθρώπινη αξιολόγηση
Το API κοινωνικών δικτύων προετοιμάζει αναρτήσεις για έναν ονομασμένο ανθρώπινο αξιολογητή. Δεν μπορεί να τις εγκρίνει ή να τις δημοσιεύσει. Τα REST και MCP χρησιμοποιούν τα ίδια πεδία πρόσβασης και την ίδια υπηρεσία.
| Πεδίο πρόσβασης | Τελικά σημεία υπό το /api/v1 |
|---|---|
social-channels.read | GET /social-channels |
social-posts.read | GET /social-posts, GET /social-posts/{scoutelloId} |
social-post-drafts.read | GET /social-post-drafts, GET /social-post-drafts/{scoutelloId}, GET /social-post-drafts/external/{externalId} |
social-post-drafts.write | POST /social-post-drafts/batch-upsert, POST /social-media/uploads, POST /social-media/uploads/{assetId}/finalize |
Τα νέα πεδία πρόσβασης πρέπει να παραχωρούνται ρητά. Τα υπάρχοντα διαπιστευτήρια δεν αποκτούν πρόσθετη πρόσβαση. Χρησιμοποιήστε το members.read για να εντοπίσετε τα ID χρηστών των μελών και επιλέξτε αξιολογητή με δικαίωμα ανάρτησης (newsletter.edit). Τα προσχέδια δεν απαιτούν επαφή CRM ή έργο.
{
"mode": "apply",
"records": [{
"externalId": "campaign:autumn:launch",
"expectedVersion": 0,
"approverScoutelloUserId": "REVIEWER_USER_ID",
"content": {
"title": "Autumn launch",
"publishMode": "schedule",
"scheduledAt": "2026-10-01T09:00:00+02:00",
"variants": [{
"channelId": "CHANNEL_SCOUTELLO_ID",
"content": "Explore the autumn collection.",
"settings": {},
"mediaIds": ["FINALIZED_ASSET_ID"]
}]
}
}]
}
Χρησιμοποιήστε τα publishMode: "now" και scheduledAt: null για δημοσίευση μετά την έγκριση. Κάθε
παραλλαγή καναλιού περιλαμβάνει το πλήρες κείμενο, τις ρυθμίσεις και τα ID πολυμέσων με τη σωστή σειρά.
Η ανακάλυψη καναλιών επιστρέφει τις υποστηριζόμενες μορφές, τα όρια και τις ρυθμίσεις. Τα κανάλια που
υποστηρίζονται αυτήν τη στιγμή είναι προφίλ/σελίδες LinkedIn, Facebook, Instagram και Threads.
Το Instagram απαιτεί πολυμέσα. Μια παραλλαγή δέχεται έως δέκα εικόνες ή βίντεο.
Οι δέσμες δέχονται έως 100 μοναδικά εξωτερικά ID εντός του υπάρχοντος ορίου αιτήματος των
1 MiB. Το mode: "validate" ελέγχει τις αναφορές και τις εκδόσεις χωρίς να αποθηκεύει προσχέδια,
να ανεβάζει στοιχεία, να δημιουργεί ειδοποιήσεις ή να τοποθετεί εργασίες στην ουρά. Τα αποτελέσματα εφαρμογής περιλαμβάνουν
ID, συνδέσμους ελέγχου, εκδόσεις και αποτελέσματα ανά εγγραφή. Οι μερικές αποτυχίες δεν επαναφέρουν
τις επιτυχείς εγγραφές. Σε περίπτωση αποτυχίας ειδοποίησης επιστρέφεται προειδοποίηση μαζί με το αποθηκευμένο
URL ελέγχου.
Ανακτήστε το τρέχον draftVersion πριν από την αναθεώρηση ενός εκκρεμούς προσχεδίου. Οι ίδιες
επαναλήψεις είναι ειδωλοδύναμες και διατηρούν τις μεταγενέστερες αλλαγές από άτομα που πραγματοποιούν έλεγχο. Οι ελεγκτές
δεν μπορούν να αλλάξουν επιτόπου. Μετά την έγκριση ή την απόρριψη, χρησιμοποιήστε νέο εξωτερικό ID για
νέα πρόταση. Η ανάγνωση προσχεδίων περιορίζεται στην καλούσα ενσωμάτωση. Το ιστορικό δημοσιεύσεων καλύπτει όλες
τις καμπάνιες που δημιουργήθηκαν και αποθηκεύτηκαν από το Scoutello στον οργανισμό, συμπεριλαμβανομένων δημοσιεύσεων από
τον πίνακα ελέγχου, το σενάριο και παλαιότερες δημοσιεύσεις Scoutello. Δεν εισάγει εξωτερικό ιστορικό καναλιών.
Οι λίστες χρησιμοποιούν τις τυπικές παραμέτρους limit, cursor και updatedSince. Οι δημοσιεύσεις και
τα προσχέδια δέχονται επίσης τα channelId, status, after, before και search. Διατηρήστε
όλα τα φίλτρα στις επόμενες σελίδες του δρομέα. Τα φίλτρα ημερομηνίας εφαρμόζονται στον χρόνο δημοσίευσης
(στον χρόνο δημιουργίας για άμεσα εκκρεμή προσχέδια). Το status προσχεδίων φιλτράρει
την κατάσταση έγκρισης. Το status δημοσιεύσεων αντιστοιχίζει την κατάσταση παράδοσης καμπάνιας ή καναλιού. Οι αναγνώσεις εμφανίζουν
την τελευταία γνωστή κατάσταση παράδοσης, τις αποτυχίες ανά κανάλι, τους δημόσιους συνδέσμους και τις χρονικές
σημάνσεις συμφωνίας. Οι αυξητικές αναγνώσεις προσχεδίων αντικατοπτρίζουν επίσης τις αλλαγές στην παράδοση καμπανιών.
Μεταφόρτωση πολυμέσων
- Καλέστε το
POST /social-media/uploadsμε ταclientUploadId,filename,contentType,sizeσε bytes και το πεζό δεκαεξαδικόsha256των αρχικών bytes. Οι υποστηριζόμενοι τύποι είναι PNG, JPEG, WebP, MP4, WebM, QuickTime και M4V. Το ανώτατο όριο μεταφόρτωσης είναι 500 MiB. - Στείλτε τα αρχικά bytes με HTTP
PUTστη διεύθυνσηupload.urlπου επιστράφηκε, χρησιμοποιώντας τις κεφαλίδες της. Οι διευθύνσεις URL μεταφόρτωσης λήγουν μετά από 15 λεπτά. Χρησιμοποιήστε ξανά τοclientUploadIdγια επαναλήψεις της ίδιας μεταφόρτωσης· για ληγμένες συνεδρίες ή διαφορετικά αρχεία απαιτείται νέο ID. - Καλέστε το
POST /social-media/uploads/{assetId}/finalizeμε σώμα JSON{}. Η οριστικοποίηση ελέγχει το μέγεθος, τον τύπο, την υπογραφή και το άθροισμα ελέγχου, παγώνει ένα ιδιωτικό αντίγραφο και επιστρέφει το ID του στοιχείου γιαmediaIds. Η επαναλαμβανόμενη οριστικοποίηση είναι ασφαλής.
Η ιδιοκτησία των μεταφορτώσεων συνδέεται με τον οργανισμό και την ενσωμάτωση. Τα πρόχειρα μπορούν να αναφέρονται σε οριστικοποιημένα στοιχεία του οργανισμού τους. Οι διευθύνσεις URL προεπισκόπησης είναι προσωρινές· ανακτήστε ξανά το πρόχειρο για να τις ανανεώσετε. Δεν εκδίδονται ποτέ διευθύνσεις URL μεταφόρτωσης για οριστικοποιημένα αντικείμενα.
Έλεγχος από άτομα και παράδοση
Το άτομο που πραγματοποιεί τον έλεγχο λαμβάνει ειδοποίηση στον πίνακα ελέγχου και μπορεί να ανοίξει την ανάρτηση από τις Αναρτήσεις ή από τη διεύθυνση URL ελέγχου. Η επεξεργασία δημιουργεί μια ακόμη αμετάβλητη έκδοση. Η έγκριση χρησιμοποιεί την εμφανιζόμενη έκδοση και το κατακερματισμένο αποτύπωμα περιεχομένου, επανελέγχει τη συμμετοχή, τα κανάλια και τα στοιχεία και δημιουργεί ατομικά μία μόνιμη καμπάνια. Αν η προτεινόμενη ώρα έχει παρέλθει, απαιτείται αποθήκευση μιας ρητά νέας ώρας ή επιλογή δημοσίευσης κατά την έγκριση.
Οι επαναλήψεις της ουράς χρησιμοποιούν ξανά την καμπάνια και τις αποδείξεις της πλατφόρμας. Οι εγκεκριμένες καμπάνιες δεν μπορούν να υποστούν επεξεργασία επιτόπου. Η ακύρωση μέσω του πίνακα ελέγχου διατηρεί το ιστορικό έγκρισης και τα πολυμέσα· η ακύρωση δεν μπορεί να διακόψει μια ενεργή αποστολή. Πραγματοποιήστε δημοσκόπηση στο πρόχειρο ή την καμπάνια για να διακρίνετε την έγκριση από την πραγματική παράδοση στην πλατφόρμα.