생성¶
POST /api/v1/notification_schedule/add
개요¶
알림 일정과 해당 시간 구간, 유효 기간 및 로테이션 순서를 생성합니다.
호출 전 준비 및 사용 단계¶
먼저 알림 대상 목록 또는 워크스페이스 멤버 목록에서 유효한 알림 대상을 가져오고, 일정 시간대 기준으로 같은 날의 HH:MM 시간 구간을 제공합니다. 로테이션을 켜면 rotationCycle을 반드시 전달해야 하며, notifyTargets 순서대로 주기마다 하나의 대상이 적용됩니다. 로테이션을 끄면 모든 대상이 함께 적용됩니다. 로테이션은 rotationUpdateAt을 기준으로 합니다. 생성 또는 수정이 성공하면 당일 온콜 캐시가 정리됩니다. 쓰기와 후속 처리는 단계적으로 완료될 수 있으므로, 타임아웃이나 500 응답 후에는 먼저 목록이나 상세를 조회하여 저장 여부를 확인한 뒤 재시도를 결정해 중복 생성을 피합니다. 무료 또는 체험 워크스페이스에서 이메일을 사용하는 경우 기존 워크스페이스 멤버 이메일만 지원합니다.
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| notifyTargets[*] | string | 계정 UUID, 알림 대상 UUID 또는 이메일 중 하나입니다. 예: notify_example가져오기 또는 입력 방법: 멤버는 워크스페이스 멤버 목록의 계정 UUID에서 가져오고, 알림 대상은 알림 대상 목록의 uuid에서 가져오거나 유효한 이메일을 입력합니다. 모두 문자열이어야 합니다. |
|
| extend.effectiveTime.start | integer | 유효 기간 시작 초 수이며, 0이거나 생략하면 시작을 제한하지 않습니다. 예: 1785427200가져오기 또는 입력 방법: 시작 경계를 Unix 초로 제공합니다. |
|
| extend.effectiveTime.end | integer | 유효 기간 종료 초 수이며, 0이거나 생략하면 종료를 제한하지 않습니다. 예: 1788019200가져오기 또는 입력 방법: 종료 경계를 Unix 초로 제공하며, 0이 아닌 경우 시작보다 빨라서는 안 됩니다. |
|
| end | string | Y | HH:MM이며 start보다 늦어야 합니다. 종료 분에 59초를 더합니다. 자정을 넘는 경우 별도의 일정으로 나눠야 합니다. null 허용: False 최대 길이: 48 예: 18:00가져오기 또는 입력 방법: 선택한 일정 시간대 기준으로 같은 날의 종료 시각을 선택합니다. |
| extend | json | 전체 확장 구성이며, 생략하면 {}입니다. null 허용: False 예: {"enableRotateNotification": false}가져오기 또는 입력 방법: 로테이션 및 전체 유효 기간 필요에 따라 입력합니다. |
|
| extend.effectiveTime | json | 전체 유효 기간 객체이며, 생략하면 영구 유효입니다. 타임스탬프 단위는 초(보통 10자리)이고 밀리초가 아닙니다. null 허용: False 예: {"start": 1785427200, "end": 1788019200}가져오기 또는 입력 방법: 업무 유효 기간을 Unix 초로 변환합니다. JavaScript Date.getTime()은 1000으로 나눈 뒤 정수로 반올림합니다. |
|
| extend.enableRotateNotification | boolean | 로테이션 사용 여부이며 기본값은 false입니다. null 허용: False 예: false가져오기 또는 입력 방법: 모든 대상이 함께 온콜하는 경우 false, 단일 대상이 로테이션하는 경우 true를 사용합니다. |
|
| extend.rotationCycle | string | 로테이션을 켤 때 반드시 명시적으로 제공해야 합니다. day는 달력일 기준으로 로테이션하고, week는 월요일에 전환되며 누적 7일이 차야 전환되는 방식이 아닙니다. month는 자연월 기준으로 전환되고, workDay는 월요일부터 금요일까지만 영업일 단위로 로테이션하며 주말에는 적용되지 않습니다. weekend는 토요일/일요일만 일 단위로 로테이션하며 영업일에는 적용되지 않습니다. 법정 공휴일은 인식하지 않습니다. rotationUpdateAt을 기준으로 합니다. null 허용: False 선택 가능한 값: ['day', 'week', 'month', 'workDay', 'weekend'] 예: day가져오기 또는 입력 방법: day, week, month, workDay, weekend 중에서 선택합니다. |
|
| name | string | Y | 비어 있지 않은 이름이며 최대 256자이고, 이 워크스페이스 내에서 중복될 수 없습니다. 빈 문자열 허용: False null 허용: False 최대 길이: 256 예: 生产值班가져오기 또는 입력 방법: 일정 목록에서 이 워크스페이스 내 중복 여부를 확인한 후 입력합니다. |
| notifyTargets | array | Y | 전체 순서가 있는 문자열 배열입니다. 로테이션은 이 순서를 따르며, 빈 배열은 알림 대상이 없음을 의미합니다. null 허용: False 예: ["notify_example"]가져오기 또는 입력 방법: 멤버는 워크스페이스 멤버 목록의 계정 UUID에서 가져오고, 알림 대상은 알림 대상 목록의 uuid에서 가져오거나 유효한 이메일을 입력합니다. 모두 문자열이어야 합니다. |
| start | string | Y | HH:MM이며 00:00부터 23:59까지이고, end보다 빨라야 합니다. null 허용: False 최대 길이: 48 예: 09:00가져오기 또는 입력 방법: 선택한 일정 시간대 기준으로 매일의 시작 시각을 선택합니다. |
| timezone | string | 일정 시간대이며, 생략하면 기본값은 Asia/Shanghai입니다. null 허용: False 최대 길이: 48 예: Asia/Shanghai가져오기 또는 입력 방법: 실제 업무 시간대의 IANA 식별자(예: Asia/Shanghai, UTC)를 선택합니다. |
파라미터 추가 설명¶
시간 구간은 종료 분의 마지막 초를 포함합니다. 예를 들어 18:00은 실제로 18:00:59까지 적용될 수 있습니다. 전체 effectiveTime은 Unix 초를 사용합니다. 예시는 로테이션을 끄고 영구 유효 기간을 사용하며, 파라미터 표에 따라 전체 로테이션 구성을 추가할 수 있습니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/notification_schedule/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"生产值班","timezone":"Asia/Shanghai","start":"09:00","end":"18:00","notifyTargets":["notify_example"],"extend":{"enableRotateNotification":false}}'
응답¶
HTTP 200, application/json입니다. 아래 예시는 바로 확인할 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | object | 저장된 일정 엔터티와 유효 기간 표시 정보이며, notifyTargetsInfos는 포함하지 않습니다. |
| content.id | integer 또는 null | 데이터베이스 번호이며, 생성 시 아직 할당되지 않았을 수 있습니다. 작업 리소스는 uuid를 사용합니다. |
| content.uuid | string | 일정 UUID로, 조회, 수정, 삭제 및 알림 정책 참조에 사용됩니다. |
| content.workspaceUUID | string | 소속 워크스페이스 UUID입니다. |
| content.name | string | 일정 이름입니다. |
| content.timezone | string | 이 일정에서 당일 시간 구간과 적용 날짜를 해석하는 데 사용하는 IANA 시간대입니다. |
| content.start | string | 당일 시작 시각 HH:MM입니다. |
| content.end | string | 당일 종료 시각 HH:MM이며, 종료 분의 마지막 초까지 유효합니다. |
| content.notifyTargets | array<string> |
순서대로 저장된 멤버, 알림 대상 UUID 또는 이메일입니다. |
| content.notifyTargets[] | string | acnt_ 계정, notify_ 알림 대상 또는 이메일 문자열입니다. |
| content.extend | object | 확장 구성이며, 구성되지 않은 경우 {}일 수 있습니다. |
| content.extend.enableRotateNotification | boolean | 로테이션 사용 여부이며, 값이 없으면 false로 처리합니다. |
| content.extend.rotationCycle | string | 로테이션 사용 시 주기: day는 일 단위, week는 월요일 기준, month는 자연월 기준, workDay는 영업일만 일 단위, weekend는 주말만 일 단위입니다. 공휴일은 인식하지 않으며, 구성되지 않은 경우 생략될 수 있습니다. |
| content.extend.effectiveTime | object | 전체 유효 기간이며, 구성되지 않은 경우 생략될 수 있습니다. |
| content.extend.effectiveTime.start | integer | 유효 기간 시작 Unix 초이며, 0이거나 생략하면 제한하지 않습니다. |
| content.extend.effectiveTime.end | integer | 유효 기간 종료 Unix 초이며, 0이거나 생략하면 제한하지 않습니다. |
| content.rotationUpdateAt | integer | 로테이션 계산의 시작 시간이며 Unix 초입니다. 로테이션 관련 구성을 변경하면 재설정됩니다. |
| content.status | integer | 레코드 상태이며, 활성 레코드는 0입니다. |
| content.creator | string | 생성 호출 주체입니다. |
| content.updator | string | 최근 업데이트 주체이며, 업데이트되지 않은 경우 빈 문자열입니다. |
| content.createAt | integer | 생성 시간이며 Unix 초입니다. |
| content.updateAt | integer | 업데이트 시간이며 Unix 초입니다. 업데이트되지 않은 경우 -1입니다. |
| content.deleteAt | integer | 삭제 시간이며 Unix 초입니다. 삭제되지 않은 경우 -1입니다. |
| content.effectiveTimeInfos | object | 전체 유효 기간의 표시 정보이며, 목록, 생성, 수정 시에만 반환됩니다. |
| content.effectiveTimeInfos.timeStr | string | 일정 시간대 기준으로 YYYY/MM/DD HH:MM:SS~YYYY/MM/DD HH:MM:SS 형식으로 포맷됩니다. 한쪽만 설정되지 않은 경우 비어 있고, 양쪽 모두 설정되지 않은 경우 전체가 빈 문자열입니다. |
| content.effectiveTimeInfos.expired | boolean | 현재 시각이 유효 기간 종료를 초과했는지 여부이며, 종료 제한이 없는 경우 false입니다. |
| content.declaration | object 또는 null | 워크스페이스 공통 선언입니다. |
{
"code": 200,
"content": {
"id": null,
"uuid": "nsche_example",
"workspaceUUID": "wksp_example",
"name": "生产值班",
"timezone": "Asia/Shanghai",
"start": "09:00",
"end": "18:00",
"notifyTargets": [
"notify_example"
],
"extend": {
"enableRotateNotification": false
},
"rotationUpdateAt": 1785427200,
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"effectiveTimeInfos": {
"timeStr": "",
"expired": false
},
"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 객체를 제출합니다. |
| 400 | ft.InvalidStartEndTimeFromat | 당일 시간이 범위를 벗어나거나 종료가 시작보다 늦지 않음 | 유효하지 않은 시간 구간 형식 | 유효한 HH:MM을 사용하고 같은 날 start가 end보다 빠르도록 합니다. 파싱할 수 없는 종료 형식도 일반 500으로 이어질 수 있습니다. |
| 400 | ft.InvalidEffectiveTime | 0이 아닌 종료 유효 기간이 시작보다 빠름 | 유효하지 않은 적용 시간 | 동일한 단위의 Unix 초를 사용하고 종료 경계를 조정합니다. |
| 406 | ft.InvalidEmail | 알림 대상이 계정/알림 대상 UUID도 아니고 유효한 이메일도 아님 | 유효하지 않은 이메일 주소 | 실제 UUID 또는 유효한 이메일 문자열을 사용합니다. |
| 400 | ft.UnsupportExternalEmail | 무료 또는 체험 워크스페이스에서 워크스페이스 멤버 이메일이 아닌 이메일을 사용함 | 체험版 워크스페이스에서는 알림 대상으로 외부 이메일을 지원하지 않습니다 | 워크스페이스에 이미 있는 멤버 이메일로 변경하거나, 워크스페이스 버전이 외부 이메일을 지원하는지 확인합니다. |
| 400 | ft.scheduleSameNameExists | 현재 워크스페이스에 같은 이름의 활성 일정이 이미 있음 | 같은 이름의 일정이 이미 존재합니다 | 목록에서 중복 여부를 확인한 후 이름을 수정합니다. |
| 400 | ft.MissingCustomParameters | 로테이션을 활성화했지만 rotationCycle을 전달하지 않음 | {} 필드 누락 | 지원되는 rotationCycle을 함께 제공합니다. |
| 500 | ft.InternalServerError | 알 수 없는 IANA 시간대, 유효하지 않은 실제 날짜, 문자열이 아닌 알림 대상 또는 파싱할 수 없는 시각 등으로 내부 실패가 발생함 | 내부 오류 | 호출 전에 파라미터 표에 따라 시간대, 실제 날짜, HH:MM 및 문자열 배열을 검증합니다. 쓰기 작업 실패 후에는 먼저 상세를 조회하여 저장 여부를 확인한 뒤 재시도를 결정하고 traceId를 보관합니다. |