콘텐츠로 이동

멤버 초대



POST /api/v1/workspace/member/batch_invitation

개요

이메일을 통해 사용자를 현재 워크스페이스에 일괄 초대하고 역할을 미리 설정합니다.

호출 전 및 사용 단계

이메일 배열, 비어 있지 않은 roleUUIDs 및 method=email을 준비합니다. API Key는 OpenAPI 모드로 초대하며 프런트엔드 인증 코드를 요구하지 않습니다. 그래도 워크스페이스 멤버 상한, 초대 빈도 및 역할 할당 가능 범위를 검증합니다. 역할 목록에 wsAdmin이 포함되어 있다고 해서 현재 신원이 반드시 관리자를 초대할 수 있는 것은 아니며, owner/wsAdmin 신원만 이렇게 작업할 수 있습니다. 초대 권한만 가진 사용자 정의 역할은 할당 가능 범위도 제한합니다. 초대 이메일은 비동기로 발송되며 수신 또는 사용자의 가입 완료를 의미하지 않습니다. 초대 링크 캐시 유효 기간은 24시간이며, 동일한 응답 대기 이메일을 다시 초대하면 이전 초대가 무효화됩니다. 승인 대기 이메일은 발송을 건너뛰지만, 현재 waitAuditEmail에는 이전에 응답 대기 상태였을 뿐이고 이번에 다시 발송된 이메일도 포함될 수 있으므로 이것만으로는 승인 상태나 발송 여부를 판단할 수 없으며 콘솔의 초대 기록 상태와 함께 확인해야 합니다. 사이트에서 초대 기능이 비활성화되었거나 현재 이메일 방식을 지원하지 않는 경우에도 API가 message 설명과 함께 성공을 반환할 수 있으므로 HTTP 200만으로 판단해서는 안 됩니다. 멤버 관계, 역할, 토큰 및 캐시 등의 처리는 단계별로 저장될 수 있습니다. 예외나 타임아웃이 발생하면 먼저 멤버 및 역할 상태를 읽은 다음 재시도를 결정합니다.

요청 헤더

파라미터명 유형 필수 설명
DF-API-KEY string Y 워크스페이스의 OpenAPI 인증 자격 증명입니다.
예시: <DF-API-KEY>
가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다.

Body 요청 파라미터

파라미터명 유형 필수 설명
to[*] string 배열의 단일 문자열 식별자입니다.
예시: xxx@guance.com
가져오기 또는 입력 방법: 초대할 사람의 실제 이메일을 입력하며 예시 주소는 교체해야 합니다. 아직 가입하지 않은 사용자일 수 있습니다.
roleUUIDs[*] string 배열의 단일 문자열 식별자입니다.
예시: readOnly
가져오기 또는 입력 방법: 역할 목록의 content.data[].uuid에서 현재 워크스페이스의 사용 가능한 역할을 가져옵니다. 내장 식별자는 wsAdmin 관리자, general 표준 멤버, readOnly 읽기 전용 멤버이며, role_로 시작하는 것은 사용자 정의 역할입니다.
method string Y 초대 방식이며 필수이고 현재는 email만 지원합니다.
null 허용: False
선택 가능 값: ['email']
예시: email
가져오기 또는 입력 방법: 현재 공개 API에서는 email을 고정으로 입력합니다.
roleUUIDs array Y 모든 초대 대상에게 일괄 부여할 역할 UUID 배열이며 반드시 비어 있지 않아야 합니다. owner는 허용되지 않으며, wsAdmin은 owner/wsAdmin 신원의 초대에만 한정됩니다. 다른 역할에는 tokenRead/tokenReplace 권한이 있어서는 안 됩니다.
null 허용: False
예시: ["readOnly"]
가져오기 또는 입력 방법: 역할 목록의 content.data[].uuid에서 현재 워크스페이스의 사용 가능한 역할을 가져옵니다. 내장 식별자는 wsAdmin 관리자, general 표준 멤버, readOnly 읽기 전용 멤버이며, role_로 시작하는 것은 사용자 정의 역할입니다.
to array Y 초대할 이메일 배열이며 필수입니다. 발송 전에 빈 값을 직접 제거하고 이메일을 검증해야 하며 null을 전달하지 마십시오.
null 허용: True
예시: ["xxx@guance.com"]
가져오기 또는 입력 방법: 초대할 사람의 실제 이메일을 입력하며 예시 주소는 교체해야 합니다. 아직 가입하지 않은 사용자일 수 있습니다.

파라미터 추가 설명

API는 초대 링크나 계정 UUID를 반환하지 않으며, 멤버가 실제로 가입한 후 멤버 목록을 통해 UUID를 가져옵니다. to에 null이 허용된다는 과거 선언이 존재하지만 현재 구현은 순회 가능한 이메일 배열을 요구하므로 클라이언트는 예시에 따라 배열을 전달해야 합니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/workspace/member/batch_invitation' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"to":["xxx@guance.com"],"roleUUIDs":["readOnly"],"method":"email"}'

응답

HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.

필드 유형 설명
content.waitAuditEmail array<string> 현재 반환에는 과거 승인 대기 또는 응답 대기 초대 기록과 관련된 이메일이 포함됩니다. 이번에 다시 발송된 이메일도 포함될 수 있으므로 단독으로 승인 대기 여부나 발송 여부를 판단할 수 없습니다.
content.waitAuditEmail[] string 과거 초대 기록과 관련된 단일 이메일이며, 단독으로 승인 또는 발송 상태를 판정할 수 없습니다.
content.message string 초대가 활성화되지 않았거나 현재 방식이 지원되지 않을 때의 설명입니다. 이 분기에서는 waitAuditEmail이 반환되지 않을 수 있습니다.
content.declaration object 또는 null 워크스페이스 공용 선언입니다.
{
  "code": 200,
  "content": {
    "waitAuditEmail": [],
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

사이트에서 초대 기능이 활성화되지 않은 경우 다음이 반환될 수 있습니다.

{
  "code": 200,
  "content": {
    "message": "서비스가 활성화되지 않았습니다",
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.

HTTP 상태 errorCode 발생 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 요청 필드 누락 또는 필드 값이 선언된 검증 조건을 위반함 파라미터 구문 분석 실패 파라미터 위치, 필드명, 유형 및 값을 확인합니다.
400 ft.RequestJsonFormatError 요청 JSON 구문이 유효하지 않음 요청 JSON 형식 오류 content.reason, line, column에 따라 JSON을 수정합니다.
400 ft.JsonFormatError JSON 최상위가 객체가 아님 일부 json 파일 형식 오류 단일 JSON 객체를 제출합니다.
406 ft.InvalidEmail to에 유효하지 않은 이메일이 포함됨 유효하지 않은 이메일 주소 이메일 형식에 맞게 수정하고 빈 값을 제거합니다.
400 ft.RoleUUIDNullError roleUUIDs가 비어 있음 역할 uuid 목록이 비어 있음 현재 공간에서 사용 가능한 역할을 하나 이상 선택합니다.
400 ft.RoleInvitationWsAdminPermissionError 초대 역할에 owner가 포함됨 초대 멤버 역할은 소유자일 수 없음 소유자 이전은 전용 프로세스를 사용하며 초대를 통해 설정하지 않습니다.
400 ft.RoleInvitationPermissionError wsAdmin 외 대상 역할에 Token 읽기 또는 교체 권한이 있음 Token 보기 또는 Token 수정 권한이 포함된 역할은 초대할 수 없음 이 권한이 없는 초대 역할을 선택하고, 가입 후 권한 부여 프로세스에 따라 조정합니다.
400 ft.MemberRoleNotFound 대상 역할이 존재하지 않거나 삭제되었거나 현재 공간에 적용할 수 없음 현재 워크스페이스에서 지정한 멤버 역할을 찾을 수 없음 역할 목록에서 다시 선택합니다.
403 ft.Forbidden 현재 초대 신원이 선택한 역할을 할당할 수 없거나 owner/wsAdmin이 아닌 신원이 관리자를 초대함 작업 권한이 없습니다 해당 권한 범위를 가진 신원을 사용하거나 자신이 할당할 수 있는 역할을 선택합니다.
403 ft.ForbiddenFreeEditionLimit 워크스페이스 멤버 수가 현재 플랜 상한에 도달함 무료 플랜 워크스페이스 {}이(가) 상한({}개)에 도달하여 새로 생성할 수 없습니다. 상용 플랜을 개통하면 제한을 해제할 수 있습니다. 멤버 수와 워크스페이스 플랜을 확인합니다.
400 ft.InvitationEmailTooMany 이번 추가 및 기존 발송량이 현재 사이트의 초대 빈도 제한을 초과함 귀하의 초대 이메일 수가 1시간 내 기본 최댓값({}개)을 초과했습니다. 나중에 다시 시도하십시오. 배치 수를 줄이고 빈도 기간이 끝난 후 다시 시도합니다. 기본값은 워크스페이스당 시간당 20개 이메일이며 사이트 설정으로 재정의할 수 있습니다.
404 ft.MemberAlreadyExistsInWorkspace 초대 대상 이메일이 이미 현재 공간에 직접 연결된 일반 멤버임 워크스페이스에 이미 해당 멤버가 존재함 요청에서 기존 멤버를 제거합니다. 역할 조정이 필요하면 멤버 수정을 사용합니다.
500 ft.InternalServerError 데이터 저장, 관련 리소스 또는 캐시 처리 실패 내부 오류 먼저 멤버 및 권한의 현재 상태를 확인한 후 재시도를 결정합니다. 지속적으로 실패하면 traceId와 마스킹된 요청을 제공합니다.

문서 평가

이 페이지가 도움이 되었나요?