Scoutello API
Scoutello API는 조직의 연락처, 작업, 프로토콜, 영업 기회, 프로젝트, 마일스톤 및 이벤트를 양방향으로 동기화하기 위한 서버 간 API입니다. 또한 읽기 전용 발신 메일 기록, 할당 가능한 구성원 조회 및 엔터티별 태그 검색 기능을 제공합니다. 증분 GET/list 경로와 멱등적인 일괄 upsert가 이 버전의 동기화 기본 요소입니다. 삭제 작업이나 웹훅은 제공하지 않습니다.
API 기본 URL은 다음과 같습니다.
https://admin.scoutello.com/api/v1
조직 설정 → 개발자/API에서도 확인할 수 있습니다. OpenAPI 문서는 다음에서 확인할 수 있습니다.
https://admin.scoutello.com/api/v1/openapi.json
키 생성 및 보호
모듈형 조직에서는 키에 필요한 스코프 외에도 CRM 모듈이 활성화되어 있어야 합니다. 유효한 키로도 누락된 모듈을 활성화할 수는 없습니다. CRM에 액세스할 수 없으면 요청에서 오류 코드 module_not_active와 함께 HTTP 403이 반환됩니다. 조직 관리 권한이 있는 사람은 구독에서 CRM을 검토하거나 활성화할 수 있습니다. 액세스가 활성화된 후 다시 시도하세요.
조직 관리 권한이 있는 사람은 조직 설정 → 개발자/API에서 통합과 API 키를 생성할 수 있습니다. 전체 키는 한 번만 표시됩니다. 대화상자를 닫기 전에 키를 시크릿 관리자에 복사하세요. Scoutello에서는 전체 키를 다시 표시할 수 없습니다.
- 외부 시스템과 환경마다 별도의 통합과 키를 사용하세요.
- 해당 시스템에 필요한 스코프만 부여하세요.
- 키를 브라우저 코드, URL, 소스 관리 시스템, 로그, 지원 메시지 또는 클라이언트 측 저장소에 절대 넣지 마세요.
- 정기적으로 키를 교체하세요. 활성 통합의 키를 교체하면 교체된 키는 즉시 작동하며, 이전 키는 외부 시스템이 중단 없이 전환할 수 있도록 최대 15분 동안만 유효합니다. 기존에 설정된 더 이른 만료 시간이 있으면 해당 시간이 계속 적용되므로 이전 키가 더 빨리 작동하지 않을 수 있습니다.
- 키가 노출되었을 가능성이 있으면 키를 교체하기 전에 통합을 일시 중지하세요. 일시 중지하면 해당 통합의 모든 키 요청이 일시적으로 거부됩니다. 일시 중지 중에 키를 교체하면 중복 유효 기간이 없습니다. 이전 키는 계속 비활성화되고, 교체된 키도 통합을 다시 시작할 때까지 비활성화된 상태로 유지됩니다.
- 외부 시스템의 연결을 해제할 때는 통합 전체를 영구적으로 취소하세요. 취소하면 해당 통합의 모든 키가 비활성화되며 되돌릴 수 없습니다.
인증된 모든 요청에 키를 포함하세요.
Authorization: Bearer YOUR_API_KEY
Bearer 인증을 권장합니다. Authorization를 설정할 수 없는 클라이언트는 대신 x-api-key를 사용할 수 있습니다. 두 헤더를 모두 보내지 마세요. 두 헤더의 값이 서로 다르면 요청이 거부됩니다.
이 API는 백엔드 클라이언트용이며 출처 간 브라우저 액세스를 허용하지 않습니다.
키를 구성한 후 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 | 이 통합의 독립형 이메일 승인 초안과 전송 상태를 조회합니다. |
mail-drafts.write | 사람의 승인을 위해 이메일 초안을 작성하거나 수정합니다. 승인하거나 전송하지는 않습니다. |
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로만 시작합니다. 그 밖의 모든 스코프는 조직 관리자가 키를 생성하거나 교체할 때 부여해야 하는 명시적 옵트인 항목입니다. 기존 자격 증명은 현재 스코프를 유지하며 계속 유효합니다.
프로젝트 연결 연락처 및 이메일 초안
연락처 업서트는 선택적 projectScoutelloId / projectExternalId 쌍 또는 companyScoutelloId / companyExternalId 쌍을 허용합니다(각 쌍에서 하나 선택). 연락처, 회사 관계, 프로젝트 멤버십은 항목별로 원자적으로 저장됩니다. 프로젝트 멤버십을 추가하려면 projects.write가 필요합니다. 참조를 생략해도 다른 관계와 멤버십은 유지됩니다. 연락처 상세 조회 결과에는 projects.read가 부여된 경우 projectParticipations가 포함됩니다. 영업 프로젝트 에이전트는 연락처를 재사용하는 경우에도 프로젝트 참조를 명시적으로 포함해야 합니다.
독립형 초안은 워크플로 실행 없이 기존 사람 승인 시스템을 사용합니다.
| 메서드 | 경로 | 용도 |
|---|---|---|
| GET | /mail-drafts | 통합에서 소유한 초안의 페이지네이션 조회. 선택적 projectScoutelloId 및 status 필터 지원. |
| GET | /mail-drafts/{scoutelloId} | 현재 버전, 검토 링크, 콘텐츠 해시, 승인/전송 상태 및 최종 메일 ID 조회. |
| GET | /mail-drafts/external/{externalId} | 안정적인 통합 외부 ID 조회. |
| POST | /mail-drafts/batch-upsert | 초안 준비 검증 또는 적용. |
초안 준비에는 mail-drafts.write, contacts.read, projects.write가 필요합니다. 참조된 연락처는 프로젝트 참여자가 됩니다. 승인자는 이메일 편집 권한이 있는 조직의 승인된 멤버여야 합니다. 발신자 선택에는 해당 멤버에게 기존에 허용된 조직 또는 개인 발신자 설정이 사용됩니다. 임의의 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만 사용하고, 수정에는 현재 반환된 버전을 사용합니다. 컨텍스트와 승인자는 변경할 수 없습니다. 검토되었거나 발송된 초안은 변경된 콘텐츠를 거부합니다. 동일한 재시도 요청에는 원래 초안이 반환됩니다.
초안은 프로젝트/연락처 이메일 탭과 대시보드 승인 알림에 표시됩니다. API 준비 작업에서는 알림 이메일을 포함해 이메일이 전송되지 않으며, 기존 워크플로 알림 이메일 동작은 변경되지 않습니다. 지정된 담당자는 수신자, 제목, 본문 및 지원되는 첨부 파일을 편집하고 버전을 저장한 다음 승인 및 보내기를 선택할 수 있습니다. 통합 기능은 승인하거나 전송할 수 없습니다. 전송 실패 또는 모호한 전송 결과가 발생해도 무조건 재시도하지 않습니다. 프로토콜 기반 초안을 변환할 때는 프로토콜을 유지하고 대체 항목과 상호 참조를 추가합니다.
MCP 액세스
동일한 Scoutello API 키와 스코프를 스트리밍 가능한 HTTP MCP 엔드포인트에서도 사용할 수 있습니다.
https://admin.scoutello.com/api/v1/mcp
MCP 클라이언트가 Authorization: Bearer YOUR_API_KEY을 전송하도록 구성합니다. 기존 /api/mcp URL은 경로 호환성 별칭으로 계속 사용할 수 있지만, 새 클라이언트에서는 버전이 지정된 엔드포인트를 사용해야 합니다. 이전 sctl_mcp_ 자격 증명은 허용되지 않으므로 Scoutello API 통합 키로 교체합니다.
MCP 도구는 REST 계약에 직접 매핑되며 동일한 런타임 스키마, 테넌트 확인, 통합 수명 주기, 속도 제한 및 서비스 메서드를 사용합니다. 예를 들어 contacts_list, contacts_get, contacts_get_by_external_id 및 contacts_batch_upsert은 네 가지 연락처 라우트를 그대로 반영합니다. 동일한 패턴이 작업, 프로토콜, 영업 기회, 프로젝트, 마일스톤 및 이벤트에도 적용됩니다. 메일에서는 mails_list 및 mails_get을 제공하고, 멤버에서는 members_list을 제공하며, 태그에서는 tags_list을 제공합니다.
서버는 현재 키의 스코프에서 허용되는 도구만 공지합니다. contacts.read 권한이 있는 키는 연락처 조회 도구를 검색할 수 있지만 contacts_batch_upsert은 검색할 수 없습니다. contacts.write 권한이 있는 키는 일괄 업서트 도구를 사용할 수 있지만 조회 도구는 사용할 수 없습니다. whoami은 항상 사용할 수 있습니다. 쓰기 도구는 해당 REST 도구와 동일한 즉시 효과를 가지므로, 적용하지 않고 일괄 작업을 검사해야 할 때는 mode: "validate"을 사용합니다.
MCP 역시 서버 간 통신 방식이며 교차 출처 브라우저 액세스를 활성화하지 않습니다. JSON-RPC 전송에는 전용 URL이 필요하므로 인증 및 데이터 동작을 공유하더라도 개별 REST 리소스 URL을 함께 사용할 수 없습니다.
전체 클라이언트 구성, 확인, 도구 매핑 및 문제 해결 지침은 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으로 교체합니다. 레코드가 이 통합에 의해 연결된 경우 조회 DTO에 externalId이 표시됩니다.
목록 응답에는 다음과 같은 봉투가 있습니다:
{
"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를 하이워터 타임스탬프로 저장합니다. 다음 순회에서는 이를 ISO 8601 형식의 updatedSince 값으로 전달하세요. 하한값은 포함되므로 완료된 스냅샷을 다시 시도하면 경계 레코드가 반환될 수 있지만 해당 레코드를 건너뛸 수는 없습니다.
단일 레코드 응답에는 다음과 같은 봉투가 있습니다:
{
"data": {},
"requestId": "request-id"
}
단일 연락처 응답에는 relations 배열도 포함됩니다. 각 관계에는 Scoutello 관계 ID, 생성 시각, 유형, 메모, 그리고 connectedFrom 및 connectedTo 연락처 참조가 유지됩니다. 연락처 참조에는 Scoutello ID와 해당 ID가 존재하는 경우 이 통합의 외부 ID가 포함됩니다. API의 조직 액세스 개인정보 보호 경계에서 제외된 연락처는 관계를 통해 노출되지 않습니다.
연락처 목록 응답은 간결하게 유지되며 관계를 포함하지 않습니다. 관계 세부 정보가 필요한 경우 두 단일 연락처 라우트 중 하나를 사용하세요.
작업 필터 및 커서 범위
연락처 목록은 search, type (person, company, supplier, other), status 및 tagIds를 지원합니다. 검색어는 앞뒤 공백이 제거되고 대소문자를 구분하지 않으며, 최대 200자 및 공백으로 구분된 토큰 10개로 제한됩니다. 각 토큰은 firstName, lastName 또는 companyName 중 하나 이상에 포함되어야 하며, lastName에 저장된 기존 회사 이름도 검색 대상에 포함됩니다. % 및 _와 같은 문자는 그대로 일치합니다. 태그는 1~50개의 ID에 대해 any-of 방식으로 일치합니다. 제공된 모든 필터는 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(멤버 Customer ID), scoutelloUserId(User ID) 및 displayName를 반환합니다. 역할이 있는 승인된 조직 멤버만 표시되며, 이 조회에서는 이메일이나 권한을 노출하지 않습니다.
작업에는 assignedScoutelloUserIds를 사용하고, 영업 기회에는 ownerScoutelloUserId를 사용합니다. 프로젝트와 마일스톤에는 assignedContacts: [{"scoutelloId":"member-customer-id"}]를 사용합니다. 할당에는 자격 증명이 속한 조직의 승인된 멤버가 필요합니다. 할당을 생략하면 기존 할당이 유지되며, []는 할당을 삭제합니다. 프로젝트, 마일스톤, 작업 및 프로토콜 가져오기는 알림 없이 처리되며, 할당 알림이나 커뮤니케이션을 보내지 않습니다.
이벤트 assignedContacts는 읽을 수 있는 CRM 연락처와 멤버 Customer ID로 제공된 승인된 멤버를 지원합니다. 승인된 멤버는 일반 CRM 연락처 참조나 외부 링크 대상으로 사용할 수 없습니다. 팀 책임을 지정하려면 멤버 할당 필드를 사용해야 합니다.
name 및 projectScoutelloId 또는 projectExternalId 중 하나를 사용하여 마일스톤을 생성합니다. 마일스톤은 description(Markdown), status(open, in_progress, completed, closed), null을 허용하는 startDate/endDate, order(기본값 0), assignedContacts를 지원합니다. 종료일은 시작일보다 이전일 수 없습니다. 각 마일스톤에는 통합 범위 내에서 안정적인 외부 링크가 있습니다. API를 통해 마일스톤의 프로젝트를 변경할 수 없습니다. 생성 및 업데이트 시 이름/설명이 조직의 언어로 현지화됩니다.
작업과 프로토콜은 <entity>ScoutelloId 또는 <entity>ExternalId로 프로젝트, 마일스톤, 기회 참조를 허용합니다. 예: milestoneExternalId. 관계마다 하나의 표기만 제공해야 하며, null를 사용하여 관계를 삭제할 때도 마찬가지입니다. 모든 관계는 인증 정보가 속한 조직에 포함되어야 합니다. 마일스톤만 참조하면 프로젝트가 자동으로 추론됩니다. 프로젝트가 충돌하거나 마일스톤은 유지하면서 프로젝트를 명시적으로 삭제하면 요청이 거부됩니다. 프로젝트가 연결된 기회는 작업의 프로젝트와 일치해야 합니다. 관계를 생략하면 현재 값이 유지됩니다. 명시적인 null는 나머지 컨텍스트가 유효한 경우 관계를 삭제합니다. 조회 결과에는 두 ID 표기와 작업 할당이 모두 포함됩니다.
작업 계획 및 워크플로
작업 status는 고정된 열거형이 아니라 작업의 유효 워크플로에 있는 상태의 변경 불가능한 키입니다. tasks.read 범위를 사용하여 GET /task-workflows로 조직 및 프로젝트에서 사용 가능한 워크플로를 조회합니다. 각 상태에는 키, 레이블, 수명 주기 type(backlog, unstarted, started, completed 또는 cancelled), 색상, 순서, 기본값 여부 및 보관 상태가 포함됩니다. 프로젝트 항목에는 조직 워크플로가 상속되는지 여부가 표시됩니다. 워크플로 구성은 대시보드에서 관리합니다.
작업은 null을 허용하는 priority(low, medium, high 또는 urgent) 및 estimatedEffortMinutes, 그리고 null을 허용하는 startDate 및 dueDate를 지원합니다. 작업 조회에는 비정규화된 statusType, 상위 작업 참조, 간결한 하위 작업 참조, blockedBy / blocks 참조가 포함됩니다.
parentTaskScoutelloId 또는 parentTaskExternalId를 사용하여 한 단계 하위 작업을 생성하거나 업데이트합니다. null는 해당 작업을 최상위 작업으로 승격합니다. 종속성에는 blockedBy 및 blocks에서 { "scoutelloId": "..." } 또는 { "externalId": "..." } 참조의 배열을 사용합니다. 관계 필드를 생략하면 기존 관계가 유지되며, 빈 종속성 배열을 지정하면 해당 방향의 종속성이 삭제됩니다. API는 중첩된 하위 작업, 상위 작업과 하위 작업 간 종속성, 조직 간 종속성, 중복 항목, 자기 참조, 직접 또는 전이적 순환을 거부합니다.
작업 목록 필터는 정확한 워크플로 status, 수명 주기 statusType, priority, parentState(top_level, subtask 또는 parent), 그리고 blockedState(blocked, blocking 또는 unblocked)을 허용합니다.
프로토콜은 status: "draft" | "final"도 허용합니다(새 레코드의 기본값은 final). 새 프로토콜에는 type, date, 그리고 연락처 또는 유효한 프로젝트/마일스톤 컨텍스트 중 하나가 필요합니다. contactExternalId: null는 프로젝트/마일스톤 컨텍스트가 유지되는 경우에만 연락처를 삭제합니다. 따라서 고객을 임의로 생성하지 않고도 내부 프로젝트 메모를 생성하고 읽을 수 있습니다. 초안/최종 상태는 메모의 상태를 나타내며 어떤 커뮤니케이션도 전송하지 않습니다. 비공개 작업과 프로토콜은 계속 접근할 수 없습니다.
프로젝트 참여자
프로젝트 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"
}
]
}
작업 일괄 처리는 상위 작업 및 종속성 관계를 적용하기 전에 작업 레코드를 확인합니다. 이 2단계 처리 방식에서는 레코드 순서와 관계없이 동일한 일괄 처리에서 생성된 다른 작업을 외부 ID로 참조하여 상위 작업, 차단 작업 또는 차단된 작업을 지정할 수 있습니다.
각 리소스의 필드와 유효성 검사 제약 조건은 OpenAPI 문서를 사용하세요. 모든 레코드에는 1~200자 길이의 안정적인 externalId가 있어야 합니다. 이를 불투명한 기술 식별자로 취급하세요. 이메일 주소, 이름, API 시크릿 또는 기타 개인정보를 사용하지 마세요. externalUpdatedAt는 선택 사항이지만, 원본 시스템에서 신뢰할 수 있는 수정 타임스탬프를 제공하는 경우 사용을 강력히 권장합니다.
요청 본문은 1MiB로 제한됩니다. mode의 기본값은 apply입니다:
apply는 승인된 레코드의 유효성을 검사하고 기록합니다.validate는 기록하지 않고 동일한 유효성 검사와 매칭을 수행하며,would_*결과를 반환합니다.
연락처를 가져올 때는 요청에서 matchByEmail를 true로 설정할 수 있습니다. 기본값은 false입니다. 외부 ID가 더 안전한 기본 식별 경계입니다.
생략된 필드는 현재 값을 유지합니다. 명시적인 null는 null을 허용하는 필드를 지우며, 제공된 빈 할당/태그 배열은 해당 관계를 지웁니다. 프로젝트 participants는 추가 방식의 업서트입니다. 빈 배열을 사용해도 구성원 목록은 변경되지 않습니다. 연락처, 작업, 기회 및 이벤트의 태그 기록에는 Scoutello 태그 ID를 사용합니다. 관계 외부 ID는 현재 통합에 속한 링크를 통해서만 확인되며, 소유권 또는 담당자 지정에 사용되는 Scoutello 사용자 ID는 현재 조직의 승인된 구성원을 식별해야 합니다.
기회를 생성하려면 계정 또는 연락처가 필요하며, 실패한 기회에는 실패 사유가 필요합니다. 금액은 정수 센트 단위로 사용합니다. 프로젝트와 이벤트의 이름 및 설명은 조직에 설정된 언어로 읽고 기록합니다. 이벤트 기록은 명시적 날짜와 제외 날짜가 포함된 일간, 주간 또는 월간 반복을 지원합니다. 게시된 공개 범위 등급에는 Scoutello의 법적 준비 상태 게이트가 계속 적용됩니다. API는 이벤트 티켓 판매, 참가자, 미디어, 템플릿, 뉴스레터, 협업 또는 기타 고급 이벤트 관리 제어 기능을 제공하지 않습니다.
태그 검색
tagIds를 제공하기 전에 태그 엔드포인트를 사용하세요:
GET /tags?entity=events&type=category
entity는 필수이며 contacts, tasks, opportunities 또는 events를 허용합니다. 이는 해당 저장 태그 관련성에 매핑됩니다. type는 선택 사항이며 category 또는 attribute을 허용합니다. 선택 가능한 카테고리는 조직 소유이거나 전역일 수 있으며, 선택 가능한 속성은 Scoutello가 관리하는 큐레이션된 전역 속성 집합에서 가져옵니다. 결과에는 scoutelloId, 조직 언어로 현지화된 이름, type 및 relevancy가 포함됩니다. 조직 간 태그 ID, 잘못된 관련성의 태그 ID 및 선택할 수 없는 태그 ID가 포함되면 해당 배치 항목이 거부됩니다.
발신 메일 기록 읽기
메일 기록은 읽기 전용입니다:
GET /mails?updatedSince=2026-09-01T00:00:00.000Z
GET /mails/{scoutelloId}
sent 또는 failed 상태인 조직 소유 메일만 반환됩니다. 응답에는 저장된 공통 헤더와 본문, BCC, 상태 및 타임스탬프, 프로젝트/이벤트/뉴스레터 참조, 첨부 파일 ID와 유형, 그리고 수신자별 전달/열람/클릭/반송/신고/거부 통계의 집계가 포함됩니다. 초안, 대기열에 있거나 예약된 메일, 수신자별 행, 렌더링된 스냅샷, 공급자 원시 오류, 첨부 파일 다운로드 URL은 절대 노출되지 않습니다. 이후 수신자 전달 업데이트가 발생하면 메일의 유효 동기화 타임스탬프가 갱신되므로 해당 메일이 증분 읽기에 다시 표시됩니다. 메일 쓰기 라우트는 없습니다.
적용 결과는 created, updated, linked, unchanged, stale_ignored 또는 rejected일 수 있습니다. 유효성 검사는 would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale 또는 rejected를 사용합니다. 유효한 일괄 요청은 개별 레코드가 거부된 경우에도 HTTP 200을 반환하므로 항상 모든 항목과 응답 요약을 확인해야 합니다. 실패 조사를 Scoutello 지원팀에 요청할 때는 응답 requestId를 유지해야 합니다.
타임스탬프 및 충돌
externalUpdatedAt가 있으면 Scoutello는 이를 사용해 오래된 변경 사항을 거부하며, 나머지 일괄 처리에는 영향을 주지 않습니다. stale_ignored 결과는 해당 이전 페이로드에 대해 최종적이므로, 새 버전을 보낼지 결정하기 전에 현재 레코드를 가져와야 합니다.
타임스탬프는 UTC ISO 8601 값으로 처리해야 합니다. 원래 정밀도를 유지하고, 동기화 작업이 실행된 시간을 소스 레코드의 수정 시간으로 대체하지 않아야 합니다.
멱등성
멱등성의 경계는 통합과 externalId입니다. Scoutello는 표준화된 페이로드 해시와 선택적 externalUpdatedAt 값을 비교하므로 동일한 레코드를 재시도해도 중복이 생성되지 않으며 unchanged를 반환할 수 있습니다.
externalUpdatedAt인 경우 동일한 타임스탬프와 페이로드는 unchanged이고, 더 오래된 타임스탬프는 stale_ignored이며, 동일한 타임스탬프에 다른 페이로드를 사용하면 버전 충돌이 발생합니다. 타임스탬프를 한 번도 허용하지 않은 링크에서는 타임스탬프가 없는 동일한 페이로드가 계속 unchanged로 유지되지만, 변경된 페이로드는 도착 순서에 따라 적용됩니다. 링크가 타임스탬프를 허용한 후에는 externalUpdatedAt를 생략한 변경 페이로드가 버전 충돌로 거부되므로, 버전이 지정된 상태를 버전이 지정되지 않은 데이터로 덮어쓸 수 없습니다. 이러한 이유로 소스 수정 타임스탬프를 강력히 권장합니다.
감사 추적
승인된 API 생성, 업데이트 및 링크 전용 동기화 작업은 Scoutello 변경 로그에 소스가 Public API로 표시되며, 담당 통합에 연결됩니다. 운영 실행 요약에는 문제 해결을 위해 요청 ID와 집계된 결과 수가 보존되지만, 레코드 페이로드나 API 보안 정보는 보존되지 않습니다.
오류 및 재시도
요청 수준 오류는 다음 봉투 형식을 사용합니다.
{
"error": {
"code": "error_code",
"message": "Safe error message",
"requestId": "request-id",
"details": {}
}
}
HTTP 429 및 일시적인 5xx 응답은 지수 백오프와 지터를 사용해 재시도합니다. 해당하는 경우 Retry-After을 준수합니다. 네트워크 오류는 Scoutello가 요청을 수락한 후 발생했을 수 있습니다. 각 레코드는 외부 ID와 정규 페이로드를 기준으로 멱등성을 가지므로 동일한 배치를 다시 보내도 안전합니다. 인증, 권한 부여, 유효성 검사, 버전 충돌 또는 개별 rejected 결과는 요청을 변경하지 않은 상태에서 자동으로 재시도하지 않습니다.
권장 양방향 동기화 루프
- 설정 중
/whoami을 호출하고, 예상한 조직과 범위인지 확인합니다. - 마지막으로 완료된 하이워터마크 이후 변경된 모든 페이지를 읽고, 해당 변경 사항을 외부 시스템에 멱등적으로 적용합니다.
- 안정적인 외부 ID와 소스 수정 타임스탬프를 사용해 외부 변경 사항을
/batch-upsert으로 보냅니다. - 모든 페이지와 항목 결과를 처리한 후에만 체크포인트를 저장합니다.
- 소스 시스템의 소유권 규칙에 따라 충돌을 해결합니다. 빈 레코드를 보내 삭제를 모방하지 않습니다.
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에는 미디어가 필요합니다. 하나의 변형에는 이미지 또는 동영상을 최대 10개까지
지정할 수 있습니다.
배치에는 기존 1MiB 요청
제한 내에서 고유한 외부 ID를 최대 100개까지 지정할 수 있습니다. 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및 원본 바이트의 소문자 16진수sha256와 함께 호출합니다. 지원되는 형식은 PNG, JPEG, WebP, MP4, WebM, QuickTime 및 M4V입니다. 업로드 용량 한도는 500MiB입니다.- 반환된
upload.url에 HTTPPUT를 사용해 원본 바이트를 해당 헤더와 함께 전송합니다. 업로드 URL은 15분 후 만료됩니다. 동일한 파일을 재시도할 때는clientUploadId를 재사용합니다. 만료된 세션이나 다른 파일에는 새 ID가 필요합니다. {}의 JSON 본문과 함께POST /social-media/uploads/{assetId}/finalize를 호출합니다. 최종화 과정에서 크기, 형식, 시그니처 및 체크섬을 확인하고, 비공개 사본을 고정한 뒤mediaIds용 자산 ID를 반환합니다. 최종화를 반복해도 안전합니다.
업로드 소유권은 조직 및 통합에 연결됩니다. 초안에서는 해당 조직의 최종화된 자산을 참조할 수 있습니다. 미리보기 URL은 임시 URL이므로, 새 URL을 받으려면 초안을 다시 조회해야 합니다. 최종화된 객체에는 업로드 URL이 발급되지 않습니다.
사람에 의한 검토 및 게시
검토자는 대시보드 알림을 받고 Postings 또는 검토 URL에서 게시물을 열 수 있습니다. 편집하면 변경할 수 없는 새 버전이 생성됩니다. 승인 시 표시된 버전과 콘텐츠 해시를 사용하고, 멤버십·채널·자산을 다시 확인한 다음 내구성 있는 캠페인 하나를 원자적으로 생성합니다. 제안된 시간이 지났다면 검토자는 명시적으로 새 시간을 저장하거나 승인 시 게시를 선택해야 합니다.
대기열 재시도에서는 캠페인과 플랫폼 영수증을 재사용합니다. 승인된 캠페인은 기존 위치에서 편집할 수 없습니다. 대시보드에서 취소해도 승인 기록과 미디어는 유지되며, 취소로 진행 중인 전송을 중단할 수는 없습니다. 승인이 완료된 것과 실제 플랫폼 게시가 완료된 것을 구분하려면 초안 또는 캠페인을 폴링합니다.