멤버 초대¶
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와 마스킹된 요청을 제공합니다. |