Przejdź do głównej zawartości

Scoutello API

API Scoutello to interfejs serwer-serwer służący do dwukierunkowej synchronizacji kontaktów, zadań, protokołów, szans sprzedaży, projektów, kamieni milowych i wydarzeń w organizacji. Udostępnia również historię poczty wychodzącej tylko do odczytu, wyszukiwanie osób możliwych do przypisania oraz wykrywanie tagów uwzględniające typ encji. Trasy przyrostowe GET/list oraz idempotentne zbiorcze operacje upsert stanowią w tej wersji podstawowe mechanizmy synchronizacji. API nie udostępnia operacji usuwania ani webhooków.

Bazowy adres URL API:

https://admin.scoutello.com/api/v1

Jest również wyświetlany w sekcji Ustawienia organizacji → Developer/API. Dokument OpenAPI jest dostępny pod adresem:

https://admin.scoutello.com/api/v1/openapi.json

Tworzenie i ochrona klucza​

W organizacjach modułowych moduł CRM musi być aktywny, oprócz wymaganych zakresów uprawnień klucza. Prawidłowy klucz nie może aktywować brakującego modułu. Żądania zwracają HTTP 403 z kodem błędu module_not_active, gdy dostęp do CRM jest niedostępny. Osoba z uprawnieniami administracyjnymi organizacji może sprawdzić lub aktywować CRM w sekcji Subskrypcja; ponowić próbę po aktywowaniu dostępu.

Osoba z uprawnieniami administracyjnymi organizacji może utworzyć integrację i klucz API w sekcji Ustawienia organizacji → Developer/API. Pełny klucz jest wyświetlany tylko raz. Przed zamknięciem okna dialogowego skopiować go do menedżera sekretów; Scoutello nie może ponownie wyświetlić pełnego klucza.

  • Używać osobnej integracji i klucza dla każdego zewnętrznego systemu i środowiska.
  • Przyznawać tylko zakresy uprawnień wymagane przez dany system.
  • Nigdy nie umieszczać klucza w kodzie przeglądarki, adresie URL, systemie kontroli wersji, logach, wiadomościach do pomocy technicznej ani w pamięci po stronie klienta.
  • Regularnie rotować klucze. Po rotacji aktywnej integracji nowy klucz działa natychmiast, a poprzedni pozostaje ważny maksymalnie przez 15 minut, aby zewnętrzny system mógł przełączyć się bez przestoju. Wcześniej ustawiony termin wygaśnięcia nadal obowiązuje, dlatego poprzedni klucz może przestać działać wcześniej.
  • Jeśli istnieje ryzyko ujawnienia klucza, wstrzymać integrację przed jego rotacją. Wstrzymanie tymczasowo odrzuca wszystkie klucze integracji. Rotacja podczas wstrzymania nie zapewnia okresu przejściowego: poprzedni klucz pozostaje wyłączony, a nowy klucz pozostaje wyłączony do czasu wznowienia integracji.
  • Przy odłączaniu zewnętrznego systemu trwale unieważnić całą integrację. Unieważnienie wyłącza wszystkie jej klucze i jest nieodwracalne.

Klucz przesyłać przy każdym uwierzytelnionym żądaniu:

Authorization: Bearer YOUR_API_KEY

Preferowane jest uwierzytelnianie Bearer. Klienci, którzy nie mogą ustawić Authorization, mogą zamiast tego użyć x-api-key. Nie przesyłać obu nagłówków; żądania zawierające różne wartości w obu nagłówkach są odrzucane.

API jest przeznaczone dla klientów backendowych i nie umożliwia dostępu przeglądarek między różnymi źródłami.

Po skonfigurowaniu klucza użyć GET /whoami, aby zweryfikować integrację, organizację, zakresy uprawnień i limity klucza bez pobierania danych osobowych użytkowników.

Zakresy uprawnień​

ZakresUmożliwia
contacts.readWyświetlanie listy i pobieranie kontaktów. Kontakty należące do konta organizacji oraz kontakty członków z uprawnieniami dostępu są wykluczone.
contacts.writeSprawdzanie poprawności i stosowanie operacji upsert na kontaktach.
tasks.readWyświetlanie listy i pobieranie zadań nieprywatnych.
tasks.writeSprawdzanie poprawności i stosowanie operacji upsert na zadaniach.
protocols.readWyświetlanie listy i pobieranie protokołów nieprywatnych.
protocols.writeSprawdzanie poprawności i stosowanie operacji upsert na protokołach.
opportunities.readWyświetlanie listy i pobieranie szans sprzedażowych.
opportunities.writeSprawdzanie poprawności i stosowanie operacji upsert na szansach sprzedażowych.
projects.readWyświetlanie listy i pobieranie projektów.
projects.writeSprawdzanie poprawności i stosowanie operacji upsert na projektach i uczestnikach.
milestones.readWyświetlanie listy i pobieranie etapów projektów.
milestones.writeSprawdzanie poprawności i stosowanie operacji upsert na etapach.
members.readWyświetlanie listy zaakceptowanych członków wyłącznie z identyfikatorem klienta członka, identyfikatorem użytkownika i nazwą wyświetlaną.
events.readWyświetlanie listy i pobieranie wydarzeń oraz podstawowych harmonogramów.
events.writeSprawdzanie poprawności i stosowanie operacji upsert na wydarzeniach.
mails.readOdczytywanie historii wysłanych i niedostarczonych wiadomości wychodzących należących do organizacji.
mail-drafts.readOdczytywanie roboczych wersji wiadomości e-mail tej integracji, przeznaczonych do zatwierdzenia niezależnie od innych procesów, oraz statusu ich dostarczenia.
mail-drafts.writePrzygotowywanie lub zmienianie roboczych wersji wiadomości e-mail do zatwierdzenia przez osobę uprawnioną; nigdy nie zatwierdza ani nie wysyła wiadomości.
tags.readWyszukiwanie dostępnych tagów dla obsługiwanych typów encji.

Prywatne zadania i protokoły nigdy nie są zwracane przez ten interfejs API. Brak zakresu uprawnień powoduje błąd autoryzacji; nie jest traktowany jako pusty wynik.

Kontakt CRM niebędący członkiem może być odczytywany i używany jako odwołanie, nawet jeśli jest powiązany z loginem Scoutello. Odpowiedź zawiera wyłącznie pola CRM organizacji, nigdy dane tożsamości użytkownika ani pola dostępu. Kontakty z rolą, uprawnieniami, zaproszeniem, akceptacją lub statusem konta organizacji pozostają ukryte. Edytowanie kontaktu powiązanego z loginem jest nadal niedozwolone (protected_contact), w tym także edytowanie pól CRM, które w pozostałym zakresie nie uległy zmianie. Aby użyć istniejącego, odczytywalnego kontaktu w zadaniu/protokole, contacts.write może ustanowić jego zewnętrzne powiązanie wyłącznie przy użyciu externalId, scoutelloId oraz opcjonalnie externalUpdatedAt. Późniejsze aktualizacje obejmujące wyłącznie metadane powiązania używają externalId oraz opcjonalnie externalUpdatedAt; po ustanowieniu powiązania należy pominąć scoutelloId. Nie zmienia to kontaktu ani jego użytkownika. Przypisywanie zaakceptowanych członków odbywa się za pomocą odrębnego odwzorowania members.read.

Nowe klucze używają prefiksu sctl_api_ i początkowo mają wyłącznie contacts.write. Każdy dodatkowy zakres wymaga jawnego przyznania przez osobę z uprawnieniami administracyjnymi organizacji podczas tworzenia lub rotacji klucza. Istniejące dane uwierzytelniające zachowują obecne zakresy i pozostają ważne.

Kontakty powiązane z projektem i szkice e-maili​

Operacje upsert kontaktów akceptują opcjonalne pary projectScoutelloId / projectExternalId i companyScoutelloId / companyExternalId (wybierz jedną wartość z każdej pary). Kontakt, relacja z firmą i uczestnictwo w projekcie są zapisywane atomowo dla każdego elementu. Dodanie uczestnictwa wymaga projects.write; pominięte odwołania zachowują inne relacje i uczestnictwa. Odczyt szczegółów kontaktu obejmuje projectParticipations, gdy przyznano projects.read. Agenci projektu sprzedażowego muszą jawnie podawać kontekst projektu również przy ponownym użyciu kontaktu.

Samodzielne szkice korzystają z istniejącego systemu zatwierdzania przez człowieka, bez uruchomienia przepływu pracy:

MetodaŚcieżkaCel
GET/mail-draftsStronicowane szkice należące do integracji; opcjonalne filtry projectScoutelloId i status.
GET/mail-drafts/{scoutelloId}Bieżąca wersja, link do przeglądu, skrót treści, status zatwierdzenia/wysyłki i ewentualny identyfikator wiadomości.
GET/mail-drafts/external/{externalId}Wyszukanie stabilnego zewnętrznego identyfikatora integracji.
POST/mail-drafts/batch-upsertWeryfikacja lub zastosowanie przygotowania szkicu.

Przygotowanie szkicu wymaga mail-drafts.write, contacts.read i projects.write. Wskazany kontakt staje się uczestnikiem projektu. Osoba zatwierdzająca musi być zaakceptowanym członkiem organizacji z uprawnieniem do edycji e-maili. Wybór nadawcy korzysta z istniejących dozwolonych ustawień nadawcy organizacji lub osobistych ustawień tego członka; dowolne adresy From nie są akceptowane.

{
"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."
}
}]
}

Sprawdź każdy wynik weryfikacji przed ponowieniem z mode: "apply". Odczytaj wynikowy identyfikator, aby uzyskać reviewUrl, draftVersion, contentHash, status, dispatchStatus i mailScoutelloId. Używaj expectedVersion: 0 tylko przy tworzeniu, a zwróconej bieżącej wersji przy poprawkach. Kontekst i osoba zatwierdzająca są niezmienne; szkice już przejrzane lub wysłane odrzucają zmienioną treść. Identyczne ponowienia zwracają pierwotny szkic.

Wersje robocze pojawiają się na kartach Email projektu/kontaktu oraz w powiadomieniach o zatwierdzeniu na pulpicie. Przygotowanie przez API nie wysyła wiadomości e-mail, w tym wiadomości z powiadomieniami; dotychczasowe działanie wiadomości e-mail w powiadomieniach workflow pozostaje bez zmian. Przypisana osoba może edytować odbiorców, temat, treść i obsługiwane załączniki, zapisać wersję, a następnie wybrać Zatwierdź i wyślij. Integracje nie mogą zatwierdzać ani wysyłać wiadomości. Nieudana lub niejednoznaczna dostawa nigdy nie jest bezwarunkowo ponawiana. Podczas konwertowania wersji roboczych opartych na protokołach należy zachować protokoły i utworzyć odsyłacze do ich zamienników.

Dostęp MCP​

Tego samego klucza API Scoutello i tych samych zakresów można używać z punktem końcowym MCP streamable HTTP:

https://admin.scoutello.com/api/v1/mcp

Skonfiguruj klienta MCP tak, aby wysyłał Authorization: Bearer YOUR_API_KEY. Starszy adres URL /api/mcp pozostaje aliasem ścieżki zapewniającym zgodność, ale w nowych klientach należy używać wersjonowanego punktu końcowego. Poświadczenia sctl_mcp_ nie są akceptowane; należy zastąpić je kluczem integracji API Scoutello.

Narzędzia MCP odwzorowują bezpośrednio kontrakt REST i korzystają z tych samych schematów środowiska uruchomieniowego, kontroli dzierżawcy, cyklu życia integracji, limitu szybkości oraz metod usług. Na przykład contacts_list, contacts_get, contacts_get_by_external_id i contacts_batch_upsert odpowiadają czterem trasom kontaktów. Ten sam wzorzec dotyczy zadań, protokołów, szans sprzedaży, projektów, kamieni milowych i wydarzeń; moduł poczty udostępnia mails_list i mails_get, członkowie udostępniają members_list, a tagi udostępniają tags_list.

Serwer udostępnia wyłącznie narzędzia dozwolone przez zakresy bieżącego klucza. Klucz z contacts.read może wykrywać narzędzia odczytu kontaktów, ale nie contacts_batch_upsert; klucz z contacts.write otrzymuje narzędzie zbiorczego tworzenia lub aktualizowania, ale nie narzędzia odczytu. whoami jest zawsze dostępne. Narzędzia zapisu mają takie same natychmiastowe skutki jak ich odpowiedniki REST, dlatego gdy wywołujący powinien sprawdzić partię bez jej zastosowania, należy użyć mode: "validate".

MCP działa również między serwerami i nie umożliwia dostępu przeglądarek z innych źródeł. Transport JSON-RPC wymaga dedykowanego adresu URL, dlatego nie może współdzielić adresu URL pojedynczego zasobu REST, mimo że uwierzytelnianie i sposób obsługi danych są wspólne.

Pełną konfigurację klienta, instrukcje weryfikacji, mapowanie narzędzi i rozwiązywanie problemów opisano w przewodniku integracji MCP.

Odczyt rekordów​

Kontakty, zadania, protokoły, szanse sprzedaży, projekty, kamienie milowe i wydarzenia korzystają z tych samych tras odczytu:

GET /contacts?limit=50&updatedSince=2026-09-01T00:00:00.000Z
GET /contacts/{scoutelloId}
GET /contacts/external/{externalId}

Zastąp contacts wartością tasks, protocols, opportunities, projects, milestones lub events dla pozostałych zasobów synchronizacji. externalId pojawia się w DTO odczytu, gdy rekord został połączony przez tę integrację.

Odpowiedź listowa ma następującą strukturę:

{
"data": [],
"page": {
"nextCursor": null,
"hasMore": false,
"snapshotAt": "2026-09-01T12:00:00.000Z"
},
"requestId": "request-id"
}

limit musi mieć wartość od 1 do 100. Wyniki są uporządkowane według efektywnego czasu zmiany ich publicznej reprezentacji API, a następnie według identyfikatora Scoutello. Ten efektywny czas może być późniejszy niż zwrócona encja updatedAt, gdy zmienią się metadane linku integracji. Kursory są nieprzezroczyste: należy je przechowywać i przesyłać bez zmian, nie wyciągając znaczenia z ich zawartości.

Pierwsza odpowiedź ustala wartość snapshotAt dla tego przebiegu. Należy korzystać z nextCursor aż do momentu, gdy hasMore będzie mieć wartość false, a dopiero potem rozpocząć kolejny odczyt przyrostowy. Zapobiega to destabilizacji bieżącego przebiegu przez zmiany rekordów zachodzące podczas stronicowania.

W przypadku synchronizacji przyrostowej należy przetworzyć każdą stronę kursora, a następnie zapisać snapshotAt tego przebiegu jako znacznik czasu high-water. Przy kolejnym przebiegu należy przekazać go jako wartość updatedSince w formacie ISO 8601. Dolna granica jest włącznie, dlatego ponowienie ukończonego migawkowego odczytu może zwrócić rekordy graniczne, ale nie może ich pominąć.

Odpowiedź dla pojedynczego rekordu ma następującą strukturę:

{
"data": {},
"requestId": "request-id"
}

Odpowiedzi dotyczące pojedynczego kontaktu zawierają również tablicę relations. Każda relacja zachowuje identyfikator relacji Scoutello, czas utworzenia, typ, notatki oraz odwołania do kontaktów connectedFrom i connectedTo. Odwołania do kontaktów zawierają identyfikator Scoutello oraz zewnętrzny identyfikator tej integracji, jeśli istnieje. Kontakty wykluczone przez granicę prywatności dostępu organizacji API nie są udostępniane w relacjach. Odpowiedź z listą kontaktów pozostaje zwięzła i nie zawiera relacji; gdy potrzebne są szczegóły relacji, należy użyć jednej z tras dotyczących pojedynczego kontaktu.

Filtry pracy i zakres kursora​

Listy kontaktów obsługują search, type (person, company, supplier, other), status oraz tagIds. Wyszukiwanie usuwa zbędne białe znaki, nie uwzględnia wielkości liter i jest ograniczone do 200 znaków / 10 tokenów rozdzielonych białymi znakami. Każdy token musi wystąpić w co najmniej jednym z firstName, lastName lub companyName, w tym w historycznych nazwach firm przechowywanych w lastName. Znaki takie jak % i _ są dopasowywane dosłownie. Tagi używają dopasowania dowolny z z 1–50 identyfikatorami. Wszystkie podane filtry są łączone operatorem AND. REST koduje identyfikatory tagów jako powtarzane parametry, a MCP przekazuje tablicę:

GET /contacts?search=Hamburg%20Hotel&type=company&status=prospect&tagIds=tag-one&tagIds=tag-two

Kursory kontaktów są powiązane z organizacją, integracją oraz każdym filtrem. Filtry należy zachować na każdej stronie; zmiana filtra powoduje odrzucenie kursora. Kolejność tagów, duplikaty oraz kolejność, wielkość liter i białe znaki w tokenach wyszukiwania nie zmieniają efektywnego filtra.

Trasy listy pracy akceptują następujące dodatkowe filtry; inne kombinacje zasobów i pól są odrzucane:

ZasóbFiltry
ZadaniaprojectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter
ProtokołyprojectScoutelloId, milestoneScoutelloId, status (draft lub final)
SzanseprojectScoutelloId, stage, ownerScoutelloUserId
Projektystatus, assignedContactScoutelloId
Kamienie miloweprojectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter

dueBefore jest wyłączny, a dueAfter — włączny. Porównywana jest data realizacji zadania lub data zakończenia kamienia milowego; rekordy bez takiej daty nie są uwzględniane. Należy podawać daty i godziny w formacie ISO z informacją o strefie czasowej. Wszystkie filtry są stosowane przed stronicowaniem. Kontynuowanie pracy z kursorem wymaga użycia dokładnie tych samych filtrów, w tym updatedSince, oraz tej samej organizacji i integracji. Rozmiar strony może się zmienić. Po tym wydaniu stare, nieprzypisane do zakresu kursory należy uruchomić ponownie od zapisanego znacznika czasu high-water.

Projekty, kamienie milowe, przypisania i notatki​

GET /members (MCP members_list) używa standardowego stronicowania i wymaga members.read. Zwraca scoutelloId (identyfikator członka Customer), scoutelloUserId (identyfikator User) oraz displayName. Pojawiają się wyłącznie zaakceptowane osoby członkowskie organizacji, które mają przypisaną rolę; wyszukiwanie nie udostępnia adresów e-mail ani uprawnień.

Zadania akceptują assignedScoutelloUserIds; szanse korzystają z ownerScoutelloUserId. Projekty i kamienie milowe korzystają z assignedContacts: [{"scoutelloId":"member-customer-id"}]. Przypisania wymagają zaakceptowanych członków organizacji powiązanej z poświadczeniem. Pominięte przypisania pozostają bez zmian; [] je usuwa. Importy projektów, kamieni milowych, zadań i protokołów odbywają się bez powiadomień: nie wysyłają powiadomień o przypisaniach ani innej komunikacji.

Zdarzenie assignedContacts obsługuje czytelne kontakty CRM oraz zaakceptowanych członków przekazanych za pomocą identyfikatora Customer członka. Zaakceptowani członkowie pozostają niedostępni jako zwykłe odwołania do kontaktów CRM lub cele linków zewnętrznych; do określania odpowiedzialności zespołu należy używać pola przypisania członka.

Twórz kamienie milowe za pomocą name oraz projectScoutelloId lub projectExternalId. Obsługują one description (Markdown), status (open, in_progress, completed, closed), wartości nullable startDate/endDate, order (domyślnie 0) oraz assignedContacts. Data zakończenia nie może przypadać przed datą rozpoczęcia. Każdy kamień milowy ma stabilny zewnętrzny link przypisany do integracji. Jego projektu nie można zmienić za pośrednictwem API. Tworzenie i aktualizowanie lokalizuje nazwę/opis w języku organizacji.

Zadania i protokoły akceptują odwołania do projektów, kamieni milowych i szans sprzedaży jako <entity>ScoutelloId lub <entity>ExternalId, na przykład milestoneExternalId. Dla każdej relacji podawaj tylko jeden zapis, także podczas czyszczenia za pomocą null. Wszystkie relacje muszą należeć do organizacji przypisanej do danych uwierzytelniających. Odwołanie wyłącznie do kamienia milowego pozwala wywnioskować projekt; sprzeczny projekt lub jawne wyczyszczenie projektu przy zachowaniu jego kamienia milowego zostaje odrzucone. Powiązana szansa sprzedaży z projektem musi wskazywać ten sam projekt co zadanie. Pominięte relacje zachowują bieżące wartości; jawne null usuwa relację, jeśli pozostały kontekst jest prawidłowy. Odczyty udostępniają oba zapisy identyfikatorów oraz przypisania zadań.

Planowanie zadań i przepływy pracy​

status zadania to niezmienny klucz statusu w efektywnym przepływie pracy zadania, a nie stała wartość wyliczenia. Dostępne przepływy pracy organizacji i projektów można odczytać za pomocą GET /task-workflows z zakresem tasks.read. Każdy status zawiera klucz, etykietę, type cyklu życia (backlog, unstarted, started, completed lub cancelled), kolor, kolejność, flagę domyślności oraz stan archiwizacji. Wpisy projektów wskazują, czy przepływ pracy organizacji jest dziedziczony. Konfiguracja przepływu pracy nadal jest zarządzana w panelu.

Zadania akceptują wartość nullable priority (low, medium, high lub urgent) i estimatedEffortMinutes, a także wartości nullable startDate i dueDate. Odczyty zadań zawierają zdenormalizowane statusType, odwołanie do zadania nadrzędnego, skrócone odwołania do podzadań oraz odwołania blockedBy / blocks.

Tworzenie lub aktualizowanie podzadania jednopoziomowego za pomocą parentTaskScoutelloId lub parentTaskExternalId; null promuje je do zadania najwyższego poziomu. Zależności korzystają z tablic zawierających odwołania { "scoutelloId": "..." } lub { "externalId": "..." } w polach blockedBy i blocks. Pominięte pola relacji pozostawiają je bez zmian, natomiast pusta tablica zależności usuwa zależności w danym kierunku. API odrzuca zagnieżdżone podzadania, zależności nadrzędny–podrzędny, zależności między organizacjami, duplikaty, odwołania do siebie oraz cykle bezpośrednie i przechodnie.

Filtry listy zadań obsługują dokładny workflow status, cykl życia statusType, priority, parentState (top_level, subtask lub parent) oraz blockedState (blocked, blocking lub unblocked).

Protokoły dodatkowo obsługują status: "draft" | "final" (nowe rekordy domyślnie otrzymują final). Nowy protokół wymaga type, date oraz kontaktu albo prawidłowego kontekstu projektu/kamienia milowego. contactExternalId: null usuwa kontakt tylko wtedy, gdy pozostaje kontekst projektu/kamienia milowego. Dzięki temu można tworzyć i odczytywać wewnętrzne notatki projektowe bez przypisywania nieistniejącego klienta. Wartości Draft/final opisują stan notatki i nigdy nie powodują wysłania komunikatu. Prywatne zadania i protokoły pozostają niedostępne.

Uczestnicy projektu​

Projekt participants zawiera operacje additive upsert identyfikowane przez odwołanie contact, na przykład:

{
"externalId": "gtm:hotels",
"participants": [{
"contact": {"scoutelloId": "prospect-contact-id"},
"role": "Potential pilot",
"notes": "Existing warm lead; qualify the next step.",
"groupScoutelloId": null
}]
}

Uczestnicy opisują potencjalnych klientów/klientów powiązanych z projektem; za przypisania odpowiedzialni są członkowie zespołu. Pominięci uczestnicy, pusta tablica oraz pominięte pola uczestników zachowują istniejące dane. null usuwa role, notes lub groupScoutelloId. Duplikaty rozpoznanych kontaktów w jednym żądaniu są odrzucane. Grupy muszą już należeć do wybranego projektu; odczyty zawierają participantGroups (identyfikator/nazwa), a także identyfikatory uczestników, kontakty, rolę, notatki i identyfikator grupy. Usuwanie uczestników lub tworzenie grup jest obecnie dostępne w panelu.

Zbiorcze tworzenie lub aktualizowanie rekordów​

Zapisz maksymalnie 100 rekordów za pomocą trasy zbiorczej zasobu:

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"
}
]
}

Zbiorcze operacje na zadaniach najpierw rozpoznają rekordy zadań, a dopiero potem stosują relacje nadrzędności i zależności. To dwuetapowe przetwarzanie pozwala, aby zadanie nadrzędne, blokujące lub zablokowane odwoływało się do innego zadania utworzonego w tym samym żądaniu zbiorczym za pomocą jego zewnętrznego identyfikatora, niezależnie od kolejności rekordów.

Dla pól i ograniczeń walidacji każdego zasobu należy korzystać z dokumentu OpenAPI. Każdy rekord musi zawierać stabilny externalId o długości od 1 do 200 znaków. Należy traktować go jako nieprzezroczysty identyfikator techniczny: nie używać adresu e-mail, imienia i nazwiska, klucza API ani innych danych osobowych. externalUpdatedAt jest opcjonalny, ale zdecydowanie zalecany, gdy system źródłowy udostępnia wiarygodny znacznik czasu modyfikacji.

Treść żądania jest ograniczona do 1 MiB. mode przyjmuje domyślnie wartość apply:

  • apply sprawdza poprawność i zapisuje zaakceptowane rekordy.
  • validate wykonuje tę samą walidację i dopasowanie bez zapisywania danych, zwracając wyniki would_*.

W przypadku importów kontaktów wartość matchByEmail można ustawić w żądaniu na true. Domyślnie używana jest wartość false; zewnętrzny identyfikator stanowi bezpieczniejszą domyślną granicę tożsamości.

Pominięte pola zachowują bieżącą wartość. Jawne null usuwa wartość pola dopuszczającego wartość null, a przekazana pusta tablica przypisań lub tagów usuwa tę relację. Projektowe participants są upsertami addytywnymi: pusta tablica pozostawia listę osób bez zmian. Operacje zapisu tagów kontaktów, zadań, szans sprzedaży i wydarzeń używają identyfikatorów tagów Scoutello. Zewnętrzne identyfikatory relacji są rozwiązywane wyłącznie za pośrednictwem linków należących do bieżącej integracji, natomiast identyfikatory użytkowników Scoutello używane do przypisywania właścicielstwa lub odpowiedzialności muszą wskazywać zaakceptowanych członków bieżącej organizacji.

Tworzenie szans sprzedaży wymaga konta lub kontaktu, a w przypadku przegranych szans sprzedaży wymagany jest powód utraty. Kwoty pieniężne są podawane w całkowitych centach. Nazwy i opisy projektów oraz wydarzeń są odczytywane i zapisywane w języku skonfigurowanym dla organizacji. Operacje zapisu wydarzeń obsługują jawne daty oraz cykliczność dzienną, tygodniową lub miesięczną z wykluczeniami; poziomy widoczności opublikowanych wydarzeń nadal podlegają bramkom gotowości prawnej Scoutello. API nie udostępnia obsługi biletów na wydarzenia, uczestników, multimediów, szablonów, newsletterów, współprac ani innych zaawansowanych funkcji zarządzania wydarzeniami.

Wyszukiwanie tagów​

Przed podaniem tagIds należy użyć punktu końcowego tagów:

GET /tags?entity=events&type=category

entity jest wymagany i przyjmuje wartości contacts, tasks, opportunities lub events. Mapuje on wartość na odpowiadającą jej zapisaną istotność tagu. type jest opcjonalny i przyjmuje wartość category lub attribute. Kategorie możliwe do wyboru mogą należeć do organizacji lub być globalne; wybieralne atrybuty pochodzą z wyselekcjonowanego globalnego zestawu atrybutów Scoutello. Wyniki zawierają scoutelloId, nazwę zlokalizowaną na język organizacji, type oraz relevancy. Identyfikatory tagów pochodzące z innej organizacji, identyfikatory o nieprawidłowej istotności oraz identyfikatory tagów niedostępnych do wyboru powodują odrzucenie danego elementu partii.

Odczytywanie historii poczty wychodzącej​

Historia poczty jest tylko do odczytu:

GET /mails?updatedSince=2026-09-01T00:00:00.000Z
GET /mails/{scoutelloId}

Zwracana jest wyłącznie poczta należąca do organizacji ze statusem sent lub failed. Odpowiedzi zawierają standardowe zapisane nagłówki i treść, pola BCC, statusy i znaczniki czasu, odwołania do projektów, wydarzeń i newsletterów, identyfikatory oraz typy załączników, a także zagregowane statystyki dostarczeń, otwarć, kliknięć, odbić, skarg i odrzuceń odbiorców. Wersje robocze, wiadomości w kolejce lub zaplanowane, wiersze dotyczące poszczególnych odbiorców, wyrenderowane migawki, surowe błędy dostawcy oraz adresy URL pobierania załączników nigdy nie są udostępniane. Późniejsza aktualizacja dostarczenia do odbiorcy przesuwa efektywny znacznik czasu synchronizacji wiadomości, dzięki czemu wiadomość ponownie pojawia się w odczytach przyrostowych. Nie ma tras zapisu poczty.

Wynik zastosowania może mieć wartość created, updated, linked, unchanged, stale_ignored lub rejected. Walidacja używa wartości would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale lub rejected. Prawidłowe żądanie zbiorcze zwraca HTTP 200, nawet gdy poszczególne rekordy zostaną odrzucone, dlatego zawsze należy sprawdzić każdy element oraz podsumowanie odpowiedzi. Zachowaj odpowiedź requestId podczas proszenia zespołu pomocy technicznej Scoutello o zbadanie błędu.

Znaczniki czasu i konflikty​

Jeśli obecny jest externalUpdatedAt, Scoutello używa go do odrzucenia nieaktualnych zmian bez przerywania przetwarzania pozostałych elementów partii. Wynik stale_ignored jest ostateczny dla starszego ładunku danych; przed podjęciem decyzji o wysłaniu nowszej wersji pobierz bieżący rekord.

Traktuj znaczniki czasu jako wartości UTC w formacie ISO 8601. Zachowaj ich pierwotną precyzję i nie zastępuj czasu wykonania zadania synchronizacji czasem modyfikacji rekordu źródłowego.

Idempotencja​

Granica idempotencji obejmuje integrację oraz externalId. Scoutello porównuje kanoniczny skrót ładunku danych i opcjonalną wartość externalUpdatedAt, dlatego ponowienie próby dla tego samego rekordu nie tworzy duplikatów i może zwrócić unchanged.

W przypadku externalUpdatedAt ten sam znacznik czasu i ładunek danych oznaczają unchanged, starszy znacznik czasu oznacza stale_ignored, a ten sam znacznik czasu z innym ładunkiem danych oznacza konflikt wersji. W przypadku połączenia, które nigdy nie zaakceptowało znacznika czasu, ten sam ładunek danych bez znacznika czasu pozostaje unchanged, natomiast zmieniony ładunek danych jest stosowany w kolejności nadejścia. Po zaakceptowaniu znacznika czasu przez połączenie zmieniony ładunek danych, w którym pominięto externalUpdatedAt, zostaje odrzucony jako konflikt wersji, aby dane bez wersjonowania nie mogły zastąpić stanu wersjonowanego. Dlatego zdecydowanie zaleca się używanie znaczników czasu modyfikacji po stronie źródła.

Ścieżka audytu​

Akceptowane działania API dotyczące tworzenia, aktualizowania i synchronizacji obejmującej wyłącznie powiązania pojawiają się w dziennikach zmian Scoutello ze źródłem Public API i są przypisane do odpowiedniej integracji. Podsumowania operacyjne zachowują identyfikatory żądań oraz zagregowane liczby wyników na potrzeby rozwiązywania problemów; nie zachowują danych rekordów ani sekretów API.

Błędy i ponawianie prób​

Błędy na poziomie żądania korzystają z następującej koperty:

{
"error": {
"code": "error_code",
"message": "Safe error message",
"requestId": "request-id",
"details": {}
}
}

Ponawiać próby dla odpowiedzi HTTP 429 i przejściowych odpowiedzi 5xx, stosując wykładnicze opóźnienie i losowe odchylenie. Honorować Retry-After, jeśli występuje. Awaria sieci mogła nastąpić po zaakceptowaniu żądania przez Scoutello; ponowne wysłanie tej samej partii jest bezpieczne, ponieważ każdy rekord jest idempotentny na podstawie zewnętrznego identyfikatora i kanonicznego ładunku. Nie ponawiać automatycznie prób w przypadku uwierzytelniania, autoryzacji, walidacji, konfliktu wersji ani pojedynczych wyników rejected bez zmiany żądania.

Zalecana pętla synchronizacji dwukierunkowej​

  1. Wywołać /whoami podczas konfiguracji i sprawdzić, czy organizacja oraz zakresy uprawnień są prawidłowe.
  2. Odczytać każdą stronę zmienioną od ostatniego ukończonego znacznika wysokiej wody i idempotentnie zastosować te zmiany w systemie zewnętrznym.
  3. Wysłać zmiany zewnętrzne do /batch-upsert, używając stałych zewnętrznych identyfikatorów oraz znaczników czasu modyfikacji źródła.
  4. Zapisywać punkty kontrolne dopiero po obsłużeniu wszystkich stron i wyników elementów.
  5. Rozwiązywać konflikty zgodnie z zasadami własności systemu źródłowego; nie emulować usunięć przez wysyłanie pustych rekordów.

W tej pierwszej wersji Scoutello celowo nie udostępnia publicznej trasy usuwania. Do czasu wprowadzenia udokumentowanej operacji cyklu życia obsługiwać zasady usuwania lub archiwizacji poza API.

Posty społecznościowe do weryfikacji przez osoby​

Interfejs API mediów społecznościowych przygotowuje posty dla wskazanej osoby weryfikującej. Nie może ich zatwierdzać ani publikować. REST i MCP korzystają z tych samych zakresów uprawnień i usługi.

ZakresPunkty końcowe w ramach /api/v1
social-channels.readGET /social-channels
social-posts.readGET /social-posts, GET /social-posts/{scoutelloId}
social-post-drafts.readGET /social-post-drafts, GET /social-post-drafts/{scoutelloId}, GET /social-post-drafts/external/{externalId}
social-post-drafts.writePOST /social-post-drafts/batch-upsert, POST /social-media/uploads, POST /social-media/uploads/{assetId}/finalize

Nowe zakresy uprawnień muszą być przyznawane jawnie. Istniejące dane uwierzytelniające nie uzyskują dodatkowego dostępu. Używać members.read do ustalania identyfikatorów użytkowników będących członkami i wybierać osobę weryfikującą z uprawnieniem do publikowania (newsletter.edit). Wersje robocze nie wymagają kontaktu CRM ani projektu.

{
"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"]
}]
}
}]
}

Użyj publishMode: "now" i scheduledAt: null, aby opublikować po zatwierdzeniu. Każdy wariant kanału zawiera kompletny tekst, ustawienia i uporządkowane identyfikatory multimediów. Wyszukiwanie kanałów zwraca obsługiwane formaty, limity i ustawienia. Obecnie obsługiwane kanały to profile i strony LinkedIn, Facebook, Instagram oraz Threads. Instagram wymaga multimediów. Wariant może zawierać maksymalnie dziesięć obrazów lub filmów.

Partie mogą zawierać maksymalnie 100 unikalnych zewnętrznych identyfikatorów w ramach istniejącego limitu 1 MiB na żądanie. mode: "validate" sprawdza odwołania i wersje bez zapisywania wersji roboczych, przesyłania zasobów, tworzenia powiadomień ani umieszczania zadań w kolejce. Wyniki zastosowania obejmują identyfikatory, linki do weryfikacji, wersje i wyniki dla poszczególnych rekordów. Częściowe błędy nie wycofują pomyślnie przetworzonych elementów. Błąd powiadomienia zwraca ostrzeżenie wraz z zapisanym adresem URL do weryfikacji.

Przed wprowadzeniem zmian w oczekującej wersji roboczej pobierz jej aktualną wersję za pomocą draftVersion. Identyczne ponowienia są idempotentne i zachowują późniejsze zmiany wprowadzone przez osoby weryfikujące. Osób weryfikujących nie można zmieniać w miejscu. Po zatwierdzeniu lub odrzuceniu użyj nowego zewnętrznego identyfikatora dla kolejnej propozycji. Odczyt wersji roboczych jest ograniczony do wywołującej integracji; historia publikacji obejmuje wszystkie zapisane kampanie utworzone w Scoutello w organizacji, w tym posty utworzone z poziomu panelu, skryptu i starszych wersji Scoutello. Nie importuje historii zewnętrznych kanałów.

Listy używają standardowych parametrów limit, cursor i updatedSince. Posty i wersje robocze akceptują również channelId, status, after, before i search; zachowuj wszystkie filtry na kolejnych stronach kursora. Filtry dat dotyczą czasu publikacji (czasu utworzenia w przypadku oczekujących wersji roboczych publikowanych natychmiast). status wersji roboczej filtruje status zatwierdzenia; status posta dopasowuje status kampanii lub dostarczenia w kanale. Odczyty udostępniają ostatni znany stan dostarczenia, błędy dla poszczególnych kanałów, publiczne linki i znaczniki czasu uzgodnienia. Przyrostowe odczyty wersji roboczych uwzględniają również zmiany w dostarczeniu kampanii.

Przesyłanie multimediów​

  1. Wywołać POST /social-media/uploads z clientUploadId, filename, contentType, size w bajtach oraz małą literą zapisaną szesnastkowo sha256 oryginalnych bajtów. Obsługiwane typy to PNG, JPEG, WebP, MP4, WebM, QuickTime oraz M4V. Limit przesyłanego pliku wynosi 500 MiB.
  2. Wysłać oryginalne bajty za pomocą HTTP PUT do zwróconego upload.url, używając jego nagłówków. Adresy URL przesyłania wygasają po 15 minutach. Do ponawiania prób dla tego samego pliku używać clientUploadId; wygasłe sesje lub inne pliki wymagają nowego identyfikatora.
  3. Wywołać POST /social-media/uploads/{assetId}/finalize z treścią JSON {}. Finalizacja sprawdza rozmiar, typ, sygnaturę i sumę kontrolną, zamraża prywatną kopię i zwraca identyfikator zasobu do mediaIds. Wielokrotna finalizacja jest bezpieczna.

Własność przesyłania jest powiązana z organizacją i integracją. Wersje robocze mogą odwoływać się do sfinalizowanych zasobów należących do ich organizacji. Adresy URL podglądu są tymczasowe; aby je odświeżyć, ponownie pobrać wersję roboczą. Adresy URL przesyłania nigdy nie są wydawane dla sfinalizowanych obiektów.

Weryfikacja przez osoby i publikacja​

Osoba weryfikująca otrzymuje powiadomienie na pulpicie i może otworzyć post w sekcji Postings lub za pomocą adresu URL weryfikacji. Edycja tworzy kolejną niezmienną wersję. Zatwierdzenie korzysta z wyświetlanej wersji i skrótu treści, ponownie sprawdza członkostwo, kanały i zasoby oraz atomowo tworzy jedną trwałą kampanię. Jeśli proponowany czas już minął, osoba weryfikująca musi zapisać wyraźnie nowy czas albo wybrać publikację po zatwierdzeniu.

Ponowienia prób kolejki wykorzystują ponownie kampanię i potwierdzenia z platformy. Zatwierdzonych kampanii nie można edytować w miejscu. Anulowanie za pomocą pulpitu zachowuje historię zatwierdzeń i multimedia; anulowanie nie może przerwać aktywnego wysyłania. Odpytywać wersję roboczą lub kampanię, aby odróżnić zatwierdzenie od faktycznej publikacji na platformie.