TaskFlow개발자 문서

TaskFlow 개발자 문서

TaskFlow 의 기본 기능은 그대로 두고, 우리 조직에 필요한 화면·서버 동작·자동화·외부 연동을 직접 더하는 방법입니다.

SDK 판 2 · 마지막 갱신 2026-10-24 · TypeScript 형식 정의(taskflow-sdk.d.ts) · 확장·자동화·웹훅·연동 키는 조직의 관리자·경영관리자가 만들고, 직원은 설정 › 플러그인에서 설치해 씁니다.

무엇을 만들 수 있나

확장 화면HTML 한 장으로 만든 화면을 왼쪽 메뉴·업무 상세 탭·홈 카드·업무 메뉴에 붙입니다. 자세히
서버 동작API 키가 필요한 바깥 서비스 호출, 정해진 시간마다 자료 모으기처럼 서버에서 해야 할 일. 자세히
자동화 규칙업무가 만들어지거나 상태·담당·마감이 바뀌면 알림·기록·후속 업무 등을 대신 합니다. 코드가 필요 없습니다. 자세히
웹훅업무 사건을 우리 서버·n8n·Zapier·Make 로 바로 보냅니다(서명 포함). 자세히
REST API바깥 프로그램이 연동 키로 업무를 읽고 만들고, 확장 저장소에 자료를 넣습니다. 자세히
기존 기능 바꾸기원본은 그대로 두고 결재·프로젝트 화면에 덧붙이거나, 원본 대신 쓸 화면을 만들어 언제든 되돌립니다. 자세히
AI 로 만들기설정 › 확장 만들기 › AI로 만들기에서 원하는 기능을 설명하면 앱 AI 가 초안을 씁니다. 게시는 사람이 확인한 뒤 합니다.
하고 싶은 일쓰는 것
"완료되면 만든 사람에게 알려 줘" 같은 반복 일자동화 규칙
우리 조직만의 표·입력 화면·대시보드 카드확장 화면
사내 ERP·CRM API 와 주고받기(키 필요)확장 화면 + 서버 동작 + 비밀 값
업무가 바뀌면 바깥 시스템도 바로 알기웹훅
바깥 시스템에서 업무를 만들거나 조회REST API(연동 키)
결재 문서·프로젝트에 우리 회사만의 칸·화면 더하기덧붙이기(결재 문서 구역·프로젝트 탭) + 확장 전용 표
"금액이 크면 재무합의를 넣어라" 같은 결재 규칙저장 전 규칙(서버 동작)
전자결재 화면을 우리 방식으로 바꾸기원본 대신 쓰기(복제 시작본) — 언제든 원본으로 되돌림

5분 시작

  1. 설정 › 확장 만들기 › 새 확장 — 이름과 시작 틀(예: 업무 상세 탭)을 고릅니다.
  2. 코드 탭에서 HTML 을 고치면 오른쪽 미리보기에 바로 보입니다(저장 전 코드, 실제 데이터).
  3. 자리·권한 탭에서 붙을 자리와 필요한 권한만 고릅니다.
  4. 초안 저장 → 게시. 게시 창에서 자리·권한·바깥 주소를 확인합니다.
  5. 직원은 설정 › 플러그인 › 우리 조직이 만든 확장에서 설치합니다(관리자는 '조직 전원에게 설치'도 가능).
<div class="tf-stack">
  <h2>내 진행 업무</h2>
  <table class="tf-table"><tbody id="rows"></tbody></table>
</div>
<script>
taskflow.ready().then(async (ctx) => {
  const list = await taskflow.tasks.list({ mine: true, status: 'in-progress' });
  const tbody = document.getElementById('rows');
  if (!list.length) { tbody.innerHTML = '<tr><td class="tf-empty">진행 중인 업무가 없습니다</td></tr>'; return; }
  for (const t of list) {
    const tr = document.createElement('tr'), td = document.createElement('td'), a = document.createElement('a');
    a.href = '#'; a.textContent = t.title;                       // 사람이 쓴 글은 textContent 로
    a.onclick = (e) => { e.preventDefault(); taskflow.ui.openTask(t.id); };
    td.appendChild(a); tr.appendChild(td); tbody.appendChild(tr);
  }
});
</script>

매니페스트

확장이 어디에 붙고 무엇을 할 수 있는지 적는 JSON 입니다. 확장 만들기 화면의 '자리·권한'·'서버 동작' 탭이 이 값을 만듭니다.

{
  "slots": [
    { "type": "task-tab", "title": "고객 정보", "icon": "users", "height": 480 }
  ],
  "permissions": ["tasks:read", "tasks:write"],
  "network": ["https://api.example.com"],
  "server": {
    "actions": ["syncCustomer"],
    "schedules": [{ "action": "syncCustomer", "every": "1h" }]
  },
  "tables": { "customers": { "label": "거래처", "columns": { "name": "text", "taskId": "task" } } },
  "hooks": [{ "event": "approval.beforeSubmit", "action": "checkAmount" }]
}
칸설명
slots붙는 자리. 종류마다 하나씩, 1개 이상. title 40자, height 120~1200(px, 페이지 자리는 화면 전체)
permissions요청하는 권한. 필요한 것만 — 게시·설치 화면에 그대로 보입니다
network화면·서버 코드가 통신할 바깥 주소(https, 도메인, 10개까지). https://*.example.com 처럼 하위 도메인 전체도 가능. 여기 없는 주소로는 어떤 방법으로도 보낼 수 없습니다
server(선택) 서버 동작 이름 목록과 예약. 서버 동작
tables(선택) 확장 전용 표 — 정한 칸·종류만 저장됩니다. 확장 전용 표
hooks(선택) 저장 전 규칙 — 원본 화면이 저장 직전에 부를 서버 동작. 저장 전 규칙
slots[].replaces(선택, page 자리만) 원본 대신 쓸 기능. 지금은 "approval"(전자결재). 원본 대신 쓰기

붙는 자리

type위치문맥(ctx)
page왼쪽 메뉴에 버튼, 넓은 화면 하나(모바일은 위 메뉴)사용자
task-tab업무 상세 창의 탭사용자 + ctx.task
home-card홈 화면 카드사용자
task-action업무 오른쪽 클릭(모바일 길게 누르기) 메뉴 → 작은 창. 끝나면 taskflow.ui.close()사용자 + ctx.task
approval-section결재 문서 상세의 신청 내용 아래 구역(권한 approval:read 필요)사용자 + ctx.approval
project-tab프로젝트 상세의 탭(모바일은 상세 화면 안 구역, 권한 projects:read 필요)사용자 + ctx.project

권한

권한은 확장이 요청할 수 있는 범위일 뿐이고, 실제로는 언제나 지금 쓰는 사람이 볼 수 있고 고칠 수 있는 것까지만 됩니다.

권한할 수 있는 일
tasks:read업무 목록·내용 읽기
tasks:write업무 만들기, 상태·담당·마감·필드 고치기(만든 사람·담당자·관리자일 때)
projects:read프로젝트 목록 읽기
users:read구성원 이름·부서·직책 읽기
approval:read내가 올렸거나 결재·참조로 지정된 결재 문서와 양식 읽기(경영관리자는 모든 상신 문서)
approval:act내 차례인 문서 승인·반려 — 원본 결재 화면과 같은 처리(다음 결재자 알림·조직 규칙 포함)
(없음)확장 저장소(taskflow.data)·화면 동작(taskflow.ui)·서버 동작 부르기는 권한 없이 됩니다

SDK 참조 — window.taskflow

확장 화면에는 SDK 가 미리 들어 있습니다. 모든 함수는 Promise 를 돌려주고, 실패하면 한국어 메시지를 담은 Error 를 던집니다.

문맥

함수설명
taskflow.ready()문맥 ctx 를 받을 때까지 기다립니다. { user:{id,name,role,isManager}, task?, approval?, project?, replaces?, tables, slot, mobile, dark, permissions, extension:{id,name,version} }
taskflow.onContext(fn)문맥이 바뀔 때마다(업무 상태가 바뀌는 등) fn(ctx)
taskflow.context마지막으로 받은 문맥

업무 · 프로젝트 · 구성원

함수돌려주는 값
tasks.list({ mine, status, projectId, search, includeDone, ids, limit })업무 배열(기본 완료 제외, limit 최대 200). status 는 todo·accepted·in-progress·done 또는 배열
tasks.get(id)업무 하나 + description
tasks.create({ title, description, status, priority, assignees, dueDate, startDate, projectId, customFields }){ id }. 담당자를 안 주면 만든 사람
tasks.update(id, { title, description, status, priority, assignees, dueDate, startDate, progress, customFields })고친 업무. customFields 는 합쳐집니다
projects.list()[{ id, name, status, color, startDate, endDate }]
users.list()[{ id, name, color, department, position }]

업무 모양: { id, title, status, statusLabel, priority, assignees, managers, followers, startDate, dueDate, progress, projectId, activityId, parentId, taskType, customFields, createdBy, createdAt, updatedAt, completedAt } — 날짜는 YYYY-MM-DD, 우선순위는 low·medium·high.

확장 저장소

함수설명
data.get(모음, id, { scope })값 하나(없으면 null)
data.list(모음, { scope, limit })[{ id, data, updatedAt, updatedBy }], 최근 바뀐 순, 최대 1000
data.query(표, { 칸: 값 }, { scope, limit, order })같은 값인 행 찾기 → [{ id, data, updatedAt, updatedBy }]. 값은 글자·숫자·true/false, order: 'oldest' 면 오래된 순
data.set(모음, id, 값, { scope })저장(있으면 덮어씀). 값 하나 250KB 이하. tables 에 정한 표면 정한 칸·종류만
data.remove(모음, id, { scope })지우기

scope 기본 'org'(조직 공용) · 'user' = 나만 보는 칸. 모음 이름은 영문·숫자·_.- 64자, id 는 128자까지. 확장마다 2만 건까지.

화면 동작 · 서버

함수설명
ui.toast(글)앱 아래 짧은 알림
ui.openTask(id)업무 상세 열기
ui.openApproval(id)원본 결재 화면에서 문서 열기(null 이면 결재 홈). 원본 대신 쓰는 중이어도 원본을 엽니다
ui.navigate(tab)dashboard·tasks·projects·chat·approval·attendance·expense·settings
ui.openUrl(url)https 주소를 새 창으로 — 사용자에게 주소를 보여 주고 허락을 받습니다. <a href="https://…"> 클릭도 같은 길로 갑니다
ui.confirm(글)확인 창 → true/false
ui.close()업무 메뉴 창 닫기
server.call(동작, 입력)서버 동작 실행 → 결과. 서버 동작

기본 모양

앱과 같은 느낌의 클래스와 색 변수가 들어 있습니다. 변수로 쓰면 다크 모드가 저절로 맞습니다.

tf-card흰 면·1px 선·둥근 16px 카드
tf-btn / tf-btn tf-btn-primary보조 버튼 / 주 버튼(검정 알약)
tf-input tf-select tf-textarea tf-label입력
tf-table · tf-chip(.success .warning .error)표 · 꼬리표
tf-row · tf-stack · tf-muted · tf-empty가로 줄 · 세로 간격 · 보조 글 · 빈 상태
--text-primary --text-secondary --text-muted --border --bg-secondary --accent-blue색 변수

권장: 글자 12px 이상, 카드 속 카드 대신 여백·선 한 줄, 이모지 대신 글, 상태에만 색. 예시 자료를 지어내지 말고 없으면 tf-empty 로 할 일 하나를 보여 주세요.

실행 환경 규칙

확장 화면은 앱과 분리된 샌드박스(불투명 출처 iframe)에서 돕니다. 그래서 아래는 되지 않거나 다르게 동작합니다.

안 되는 것대신
localStorage·sessionStorage·쿠키taskflow.data(scope:'user' 면 개인 칸)
앱 화면(window.parent)·로그인 정보 접근SDK 함수
매니페스트에 없는 주소로 fetch·이미지·폼 보내기network 에 주소 추가 후 다시 게시
새 창(window.open)·자기 페이지 이동taskflow.ui.openUrl(사용자 확인). 다른 주소로 이동하면 확장이 멈춥니다
스크립트 불러오기cdn.jsdelivr.net · cdnjs.cloudflare.com · unpkg.com 만 가능
alert·confirmtaskflow.ui.toast·taskflow.ui.confirm
게시한 코드는 쓰는 사람의 권한으로 돕니다. 게시 전에 미리보기로 확인하고, 코드에 API 키를 적지 마세요 — 키는 비밀 값에.

기존 기능 바꾸기

TaskFlow 의 기본 기능(업무·결재·프로젝트…) 코드와 데이터는 고치지 않습니다. 대신 두 가지 방법으로 바꿉니다. 어느 쪽이든 원본은 그대로 남아 언제든 돌아갈 수 있습니다.

방법무엇을되돌리기
① 덧붙이기원본 화면의 자리(approval-section·project-tab·task-tab…)에 화면을 붙이고, 추가 데이터는 확장 전용 표에 담습니다. 저장 전 규칙으로 결재 요청·승인·반려 직전에 막기·확인·결재자 추가를 합니다.확장을 끄면 원본 그대로. 표의 데이터는 남습니다
② 원본 대신 쓰기원본을 본뜬 화면을 확장으로 만들어, 사람마다(또는 조직 기본으로) 원본 메뉴 자리에 씁니다. 처리는 결재 SDK — 원본과 같은 함수입니다.화면 위 [원본으로 되돌리기] 한 번. [원본 화면 보기]로 잠깐 오가기도 됩니다
원본 표(업무·결재 문서·프로젝트)에 칸을 붙이거나 표를 직접 고치는 방법은 없습니다. 칸을 붙이면 TaskFlow 업데이트와 부딪히고, 표를 직접 고치면 다음 결재자 알림·완료 처리 같은 원본의 처리가 빠져 원본 화면에서도 문서가 꼬이기 때문입니다. 업무 자체에 칸이 필요하면 설정 › 권한·태스크 종류의 사용자 정의 필드를 쓰세요(customFields 로 읽고 씁니다).

확장 만들기 › 새 확장의 기존 기능 바꾸기 시작 틀: 결재 문서에 거래처 정보 구역 · 프로젝트 위험 관리 탭 · 결재 규칙(금액이 크면 재무합의 추가) · 전자결재 복제본(원본 대신 쓰기).

확장 전용 표

"tables": {
  "vendor_info": { "label": "거래처 정보",
    "columns": { "docId": "approval", "vendor": "text", "bizNo": "text", "amount": "number", "checked": "boolean" } }
}

칸 종류: text · number · boolean · date(YYYY-MM-DD) · datetime(ISO) · json · 연결 칸 task · approval · project · user(원본 기록의 id). 표 20개, 표마다 칸 50개까지. 표 이름은 영문 소문자로 시작.

// 결재 문서 구역에서 — 그 문서에 이어 둔 거래처 정보 읽고 쓰기
const ctx = await taskflow.ready();
const row = await taskflow.data.get('vendor_info', ctx.approval.id);
await taskflow.data.set('vendor_info', ctx.approval.id, { docId: ctx.approval.id, vendor: 'ACME', amount: 1200000 });
// 조건으로 찾기
const open = await taskflow.data.query('risks', { projectId: ctx.project.id, closed: false });

정하지 않은 칸이나 종류가 틀린 값은 Error 로 거절됩니다(화면 SDK·서버 SDK 같은 규칙). 표로 정하지 않은 모음은 예전처럼 자유 형식입니다. 확장 만들기 › 데이터 표에서 행을 보고 지우고 CSV 로 내려받습니다.

저장 전 규칙

원본 결재 화면이 그 순간 직전에 확장의 서버 동작을 부릅니다. 게시된 확장이면 조직 전체에 적용됩니다(설치와 무관 — 설치를 지워 규칙을 피할 수 없게). 규칙이 문서 내용을 받으므로 권한 approval:read 가 필요하고, 게시 창에 규칙 목록이 보입니다.

event언제돌려줄 수 있는 것
approval.beforeSubmit기안자가 [결재 요청]을 누르면block · warn · addSteps
approval.beforeApprove결재자가 [결재(승인)]을 누르면(원본·대신 쓰는 화면·모바일 알림 창 모두)block · warn
approval.beforeReject결재자가 [반려]를 누르면block · warn
// 매니페스트: "server": { "actions": ["checkAmount"] }, "hooks": [{ "event": "approval.beforeSubmit", "action": "checkAmount" }]
action('checkAmount', async (input) => {
  // input = { event, doc: { id, title, docType, formId, status, amount, formData, drafterId, drafterDept, contentText,
  //                         steps: [{ stepOrder, kind, approverId, state }] }, formTitle?, opinion?, step?, actorId? }
  const doc = input.doc;
  if (!doc.amount || doc.amount <= 1000000) return {};                          // 통과
  if (!doc.formData.reason) return { block: '100만 원이 넘으면 사유를 적어 주세요.' };  // 막기
  return {
    warn: '재무팀 합의가 자동으로 추가됩니다.',                                  // 사람에게 확인
    addSteps: [{ kind: 'finance_agree', approverId: 'user-7', position: 'end' }]    // 결재선에 추가
  };
});

kind = approval(결재)·agree(합의)·finance_agree(재무합의)·reference(참조), position = end(기본)·start·beforeLast. 이미 있는 사람·쓸 수 없는 계정은 더하지 않고, 한 번에 5명까지. 규칙을 확인하지 못하면(오류·10초 초과) 막지 않고 건너뛰며 사용자에게 알립니다 — 확장 때문에 결재가 멈추지 않게. 저장 전 규칙은 화면 단계의 규칙이라 REST API 처럼 화면을 거치지 않는 경로에는 적용되지 않습니다.

원본 대신 쓰기

{ "slots": [{ "type": "page", "title": "전자결재", "icon": "file-check", "replaces": "approval" }],
  "permissions": ["approval:read", "approval:act", "users:read"] }
  1. 게시·설치하면 처음엔 원본과 나란히 왼쪽 메뉴에 따로 생깁니다(둘 다 그대로 동작).
  2. 쓰는 사람이 확장 화면 위 [전자결재 메뉴를 이 화면으로] 또는 설정 › 플러그인의 '원본 대신 쓰기'를 켜면, 전자결재 메뉴에서 이 화면이 열립니다.
  3. 화면 위에는 늘 [원본 화면 보기](잠깐)·[원본으로 되돌리기](계속)가 붙습니다. 결재 알림을 눌러 연 문서와 ui.openApproval 은 원본 상세로 엽니다.
  4. 관리자는 설정 › 플러그인에서 '조직 기본 화면으로'를 켤 수 있습니다 — 따로 고르지 않은 사람 모두의 기본이 되고, 각자 원본으로 되돌릴 수 있습니다.

대체할 수 있는 기능은 처리 함수를 SDK 로 열어 둔 것만입니다(지금은 전자결재). 기안 작성처럼 SDK 에 없는 일은 taskflow.ui.openApproval(null) 로 원본 화면에 연결하세요.

결재 SDK

함수설명
approval.list({ box, limit })box = need(결재할)·soon(예정)·going(처리 후 진행 중)·cc(참조)·drafted(내가 올린)·archive(보관함). 원본 결재함과 같은 분류. approval:read
approval.get(id)문서 + steps[{ stepOrder, kind, kindLabel, approverId, state, stateLabel, opinion, actedAt }] · myTurn · content(정리된 HTML) · attachments · comments
approval.forms()사용 중인 양식 [{ id, title, docType, category, fields }]
approval.approve(id, 의견)승인 → { ok, message }. 처리 전에 매번 앱이 사용자에게 확인 창을 띄웁니다(확장이 사람 모르게 결재하지 못하게). 원본과 같은 처리: 다시 읽어 차례 확인 → 저장 전 규칙 → 다음 결재자 알림·완료 처리. approval:act
approval.reject(id, 의견)반려(의견 필수). 차례가 아니거나 규칙이 막으면 Error(code: NOT_ALLOWED·BLOCKED·CANCELED)

문서 모양: { id, docNumber, title, docType, formId, status, statusLabel, amount, formData, drafterId, drafterDept, currentStep, createdAt, submittedAt, completedAt }. 규칙의 확인 요청(warn)은 확장 칸 안의 확인 창으로 사람에게 묻습니다.

서버 동작

API 키가 필요한 호출이나 정해진 시간마다 자료를 모으는 일처럼 브라우저에서 하면 안 되는 일을 서버에서 돌립니다. 코드는 TaskFlow 서버의 격리된 자바스크립트 실행기에서 돌고, 부른 사람의 권한으로만 동작합니다.

  1. 매니페스트 server.actions 에 동작 이름을 적습니다(영문 소문자로 시작, 2~41자).
  2. 설정 › 확장 만들기 › 서버 동작 탭에 코드를 씁니다.
  3. 필요한 키는 같은 탭의 비밀 값에 넣습니다.
  4. 시험 실행으로 확인한 뒤 게시합니다.
// 고객 정보를 사내 CRM 에서 가져와 업무 필드에 넣는다
action('syncCustomer', async (input, ctx) => {
  const task = await taskflow.tasks.get(input.taskId);
  const r = await taskflow.http.fetch('https://api.example.com/customers?name=' + encodeURIComponent(task.customFields.company || ''), {
    headers: { Authorization: 'Bearer ' + taskflow.secrets.CRM_API_KEY },
  });
  if (!r.ok) throw new Error('CRM 응답 ' + r.status);
  const c = r.json && r.json[0];
  if (!c) return { found: false };
  await taskflow.tasks.update(task.id, { customFields: { customerGrade: c.grade, customerOwner: c.owner } });
  taskflow.log('갱신', task.id, c.grade);
  return { found: true, grade: c.grade };
});
<button class="tf-btn tf-btn-primary" id="sync">CRM 에서 가져오기</button>
<script>
taskflow.ready().then((ctx) => {
  document.getElementById('sync').onclick = async () => {
    try {
      const r = await taskflow.server.call('syncCustomer', { taskId: ctx.task.id });
      taskflow.ui.toast(r.found ? '고객 등급: ' + r.grade : 'CRM 에 없는 고객입니다');
    } catch (e) { taskflow.ui.toast(e.message); }
  };
});
</script>

서버 SDK

이름설명
action(이름, async (input, ctx) => 결과)동작 등록. ctx = { user:{id,name}, extension:{id,version}, mode } — mode 는 'user'·'draft'(시험)·'schedule'(예약)
taskflow.tasks · projects · users · data화면 SDK 와 같은 함수(data.query 포함, tables 검사도 같음. 서버의 data.query 는 한 번에 100행까지)
taskflow.http.fetch(url, { method, headers, body }){ status, ok, contentType, text, json }. 매니페스트 network 의 https 주소만, 리다이렉트는 따라가지 않음
taskflow.secrets.이름비밀 값(읽기 전용)
taskflow.log(...) · console.log실행 기록에 남는 로그(시험 실행·관리자에게 보임)

서버 코드에는 fetch·require·import·파일·환경 변수가 없습니다. 바깥 통신은 taskflow.http.fetch 하나뿐입니다.

비밀 값

API 키·토큰처럼 코드에 적으면 안 되는 값입니다. 확장 만들기 › 서버 동작 › 비밀 값에서 관리자가 넣고, 넣은 뒤에는 이름만 보입니다. 서버 코드만 taskflow.secrets.이름 으로 읽고, 화면 코드에는 전달되지 않습니다. 이름은 영문 대문자로 시작(CRM_API_KEY), 확장마다 20개까지.

예약 실행

"server": { "actions": ["collectDaily"], "schedules": [{ "action": "collectDaily", "every": "1d" }] }

간격은 15m·30m·1h·6h·1d, 확장마다 3개까지. 예약 실행은 게시한 사람 이름으로 돌고, 비밀 업무는 보이지 않으며, 업무 읽기·만들기와 저장소·바깥 통신만 됩니다(업무 고치기는 사람이 부를 때만). 게시한 사람이 퇴사하면 멈추니 다른 관리자가 다시 게시하세요.

자동화 규칙

설정 › 자동화에서 문장처럼 만듭니다. 앱 AI 에게 "완료되면 만든 사람에게 알려 줘"처럼 말해도 됩니다. 아래는 규칙의 모양입니다.

{
  "name": "긴급 업무는 바로 접수",
  "event": "task.created",
  "event_params": {},
  "conditions": [{ "field": "title", "op": "contains", "value": "긴급" }],
  "actions": [
    { "type": "set_status", "value": "accepted" },
    { "type": "notify", "to": ["assignees", "managers"], "message": "긴급 업무: {{title}}" }
  ]
}
구분값
사건 eventtask.created · task.status_changed(from·to) · task.completed · task.assigned(user) · task.priority_changed(to) · task.due_changed · task.field_changed(field) · task.due_soon(days) · task.overdue
조건 fieldstatus · priority · assignees · title · description · project_id · task_type · created_by · custom:필드열쇠
조건 opeq · neq · contains · not_contains · empty · not_empty
업무 바꾸기set_status·set_priority{value} · add_assignee·add_manager·add_follower{value:사용자} · set_due{days} · set_field{key, value}
바깥 일notify{to:[assignees·managers·followers·creator·사용자], message} · add_note{content} · add_todo{items} · create_task{title, assignees:['same'|사용자], due_days, priority, subtask} · webhook{webhook_id}
글 자리표시{{title}} {{status}} {{priority}} {{due_date}} {{id}} {{field:열쇠}}

자동화가 만든 변경은 다시 자동화를 부르지 않습니다. 비밀 업무는 자동화하지 않습니다. 마감 사건은 1분마다 확인하고 같은 업무·같은 마감일에는 한 번만 실행합니다(한국 시간 기준). 조직마다 규칙 100개까지.

웹훅

설정 › 웹훅·연동 키에서 받는 주소(https 공개 도메인)와 사건을 고릅니다. 받는 쪽은 8초 안에 2xx 로 답하면 성공입니다. 실패하면 1분·5분·30분·2시간 뒤 다시 보내고 5번 실패하면 멈춥니다. 50번 연속 실패한 웹훅은 꺼집니다.

사건: task.createdtask.updatedtask.status_changedtask.completedtask.assignedtask.priority_changedtask.due_changedtask.field_changedtask.deletedtask.due_soontask.overdue 그리고 시험 발송 ping, 자동화가 보낸 automation.rule

POST https://hooks.example.com/taskflow
Content-Type: application/json
X-Taskflow-Event: task.status_changed
X-Taskflow-Delivery: 1842
X-Taskflow-Timestamp: 1792687200
X-Taskflow-Signature: sha256=5b1f…

{ "event": "task.status_changed", "occurredAt": "2026-10-23T01:20:00+00:00",
  "task": { "id": "TASK-…", "title": "고객사 계약서 검토", "status": "done", "priority": "high", "assignees": ["user-12"], "dueDate": "2026-10-24", "customFields": { … } },
  "previous": { "status": "in-progress", "priority": "high", "assignees": ["user-12"], "dueDate": "2026-10-24" } }

서명 확인

X-Taskflow-Signature = sha256= + HMAC-SHA256(서명 비밀, 타임스탬프 + "." + 받은 본문 원문). 본문을 다시 JSON 으로 만들지 말고 받은 그대로 검증하세요. 서명 비밀은 웹훅의 [서명 비밀]에서 봅니다.

const crypto = require('crypto');
function verifyTaskflow(headers, rawBody, secret) {
  const ts = headers['x-taskflow-timestamp'];
  const sig = headers['x-taskflow-signature'] || '';
  const want = 'sha256=' + crypto.createHmac('sha256', secret).update(ts + '.' + rawBody).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return fresh && sig.length === want.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(want));
}
import hmac, hashlib, time
def verify_taskflow(headers, raw_body: bytes, secret: str) -> bool:
    ts = headers.get('X-Taskflow-Timestamp', '')
    sig = headers.get('X-Taskflow-Signature', '')
    want = 'sha256=' + hmac.new(secret.encode(), (ts + '.').encode() + raw_body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(ts or 0)) < 300 and hmac.compare_digest(sig, want)
function verify_taskflow(string $rawBody, string $secret): bool {
    $ts  = $_SERVER['HTTP_X_TASKFLOW_TIMESTAMP'] ?? '';
    $sig = $_SERVER['HTTP_X_TASKFLOW_SIGNATURE'] ?? '';
    $want = 'sha256=' . hash_hmac('sha256', $ts . '.' . $rawBody, $secret);
    return abs(time() - (int)$ts) < 300 && hash_equals($want, $sig);
}

같은 배달이 두 번 올 수 있습니다(재시도). X-Taskflow-Delivery 로 중복을 거르세요. 비밀 업무는 보내지 않습니다.

REST API

바깥 프로그램(n8n·사내 서버 등)이 쓰는 API 입니다. 설정 › 웹훅·연동 키에서 연동 키를 만들 때 범위를 고르고, 같은 화면에 표시되는 API 주소로 부릅니다. 키는 만들 때 한 번만 보입니다.

curl -H "x-taskflow-api-key: tfk_…" "<API 주소>/tasks?status=in-progress&limit=20"
요청범위설명
GET /me—키 이름·범위 확인
GET /tasks?status=&projectId=&assignee=&query=&limit=tasks:read업무 목록(최신순, 최대 200)
GET /tasks/:idtasks:read업무 하나
POST /taskstasks:write업무 만들기. source.type + source.externalId 가 같으면 새로 만들지 않고 기존 업무(duplicate:true)
PATCH /tasks/:idtasks:write상태·우선순위·담당·마감·필드 고치기
POST /tasks/:id/archivetasks:write보관({ "archived": false } 면 해제)
POST /tasks/:id/commentstasks:write처리 기록 남기기
GET /usersusers:read사람 이름·이메일 → 사용자 id 찾기
GET /projectsprojects:read프로젝트 목록
GET /ext-data/:확장/:모음 · GET …/:문서data:read확장 저장소(조직 공용) 읽기
PUT /ext-data/:확장/:모음/:문서 · DELETE …data:write확장 저장소에 넣기(본문 { "data": … })·지우기
POST /notifications/bulknotify:send앱 알림 여러 건
curl -X POST "<API 주소>/tasks" \
  -H "x-taskflow-api-key: tfk_…" -H "Content-Type: application/json" \
  -d '{
    "title": "고객 문의 답변",
    "description": "주문번호 1234 배송 문의",
    "priority": "high",
    "assigneeIds": ["user-12"],
    "dueDate": "2026-10-25",
    "source": { "type": "web-form", "externalId": "form-98231" }
  }'
const res = await fetch(API + '/tasks?status=in-progress', { headers: { 'x-taskflow-api-key': process.env.TASKFLOW_KEY } });
const { tasks } = await res.json();
import os, requests
r = requests.patch(f"{API}/tasks/{task_id}", headers={"x-taskflow-api-key": os.environ["TASKFLOW_KEY"]}, json={"status": "done"})
r.raise_for_status()
# 사내 시스템이 매일 밤 재고를 확장 저장소에 넣으면, 확장 화면은 taskflow.data.list('stock') 로 읽는다
curl -X PUT "<API 주소>/ext-data/inventory/stock/A-100" \
  -H "x-taskflow-api-key: tfk_…" -H "Content-Type: application/json" \
  -d '{ "data": { "name": "노트북", "qty": 12 } }'

연동 키로는 비밀 업무가 보이지도 바뀌지도 않고, 업무를 지울 수 없습니다(보관을 쓰세요). createdBy 를 주지 않으면 키를 만든 관리자 이름으로 기록됩니다. 키는 서버·자동화 도구의 비밀 저장소에만 두고 브라우저 코드에 넣지 마세요.

사용 상한

대상상한
확장 화면 → SDK10초에 100번
서버 동작 한 번계산 1.5초 · 전체 20초 · 메모리 32MB · SDK 부르기 60번 · 바깥 통신 10번(각 8초·응답 1MB) · 입출력 256KB · 로그 100줄
서버 동작 횟수사람마다 1분에 30번 · 확장마다 하루 3,000번 · 예약은 확장마다 3개·15분 이상 간격
확장화면 코드 800KB · 서버 코드 200KB · 저장소 2만 건(문서 하나 256KB) · 비밀 값 20개
자동화 · 웹훅 · 연동 키규칙 100개(동작 10개·조건 10개) · 웹훅 30개 · 쓰는 중인 키 20개

오류

상황SDKREST
요청하지 않은 권한Error(code: 'PERMISSION_DENIED')403 이 연동 키에는 "…" 범위가 없습니다
볼 수 없거나 없는 업무Error 업무를 찾지 못했거나 볼 권한이 없습니다404
상한 초과Error 너무 자주 부르고 있습니다429
잘못된 키·폐기된 키—401

REST 응답은 모두 JSON 이고 실패하면 { "success": false, "error": "…" } 입니다.

변경 이력

2026-10-24SDK 판 2 — 기존 기능 바꾸기: 자리 approval-section·project-tab, 확장 전용 표(tables·data.query), 저장 전 규칙(hooks), 원본 대신 쓰기(replaces), 결재 SDK(approval.*·ui.openApproval), TypeScript 형식 정의
2026-10-23SDK 판 1 — 확장 화면·서버 동작·비밀 값·예약 실행·자동화 규칙·웹훅·연동 키(tfk_)·확장 저장소 API

문의: 조직 관리자 또는 TaskFlow 고객센터.