여러분, 혹시 매일 반복되는 단순 작업에 시간을 낭비하고 계신가요? 저도 그랬어요. 개발자로 일하면서 매일 같은 형식의 보고서를 작성하고, 테스크를 관리하고, 정보를 정리하는 작업이 너무 지루했거든요. 그런데 Notion API를 활용해 이 모든 것을 자동화했더니, 업무 시간이 확 줄었어요!
이 글에서는 제가 실제로 구축하고 사용 중인 Notion API 자동화 워크플로우를 공유해 드릴게요. 코드와 함께 실패했던 경험, 그리고 어떻게 문제를 해결했는지도 솔직하게 알려드릴게요. 노션을 활용해 업무 효율을 높이고 싶은 분들께 실질적인 도움이 될 거예요.
Notion API란 무엇이고 왜 주목해야 할까?
Notion API는 노션의 데이터와 기능을 외부 애플리케이션과 연결할 수 있게 해주는 인터페이스예요. 쉽게 말해, 노션에 있는 데이터를 가져오거나 수정하고, 새로운 페이지나 데이터베이스를 만드는 등의 작업을 프로그래밍 방식으로 할 수 있게 해준답니다.
처음 API를 접했을 때 너무 복잡해 보여서 포기할 뻔했어요. “아, 이건 전문 개발자가 아니면 못 쓰겠다” 싶었거든요. 하지만 몇 번의 시행착오 끝에 기본적인 사용법을 익히고 나니, 이게 얼마나 강력한 도구인지 깨달았어요.
Notion API의 핵심 기능은 다음과 같아요:
- 페이지와 데이터베이스 생성 및 관리
- 데이터 검색 및 필터링
- 블록 콘텐츠 조작
- 사용자 및 권한 관리
이런 기능들을 활용하면, 정말 다양한 작업을 자동화할 수 있어요. 회의록 자동 정리부터 프로젝트 진행 상황 추적, 고객 데이터 관리까지 말이죠.
Notion API 시작하기: 내가 겪은 실패와 해결책
Notion API를 처음 사용할 때 이런 오류 메시지를 받은 적 있으신가요? “API token missing or invalid.” 저는 이 메시지 때문에 반나절을 날려먹었어요. 😅
API를 시작하기 위한 기본 설정 과정을 제가 겪은 시행착오와 함께 알려드릴게요.
1. API 통합(Integration) 생성하기
먼저 Notion 개발자 페이지 (새 탭에서 열림)에 접속해야 해요.
여기서 저지른 첫 번째 실수는 개인 계정이 아닌 회사 계정으로 로그인한 것이었어요. API 통합은 계정별로 관리되기 때문에, 어떤 계정으로 시작할지 신중하게 결정하세요.
// API 키 사용 예시
const { Client } = require('@notionhq/client');
const notion = new Client({
auth: 'YOUR_NOTION_API_KEY',
});
// 이렇게 하면 '인증 오류'가 발생할 수 있어요!
// 항상 환경 변수를 사용하는 것이 좋습니다
처음에 위와 같은 코드를 작성했다가 API 키가 그대로 노출되는 보안 문제를 경험했어요. 이후에는 항상 환경 변수를 사용하게 됐죠.
// 안전한 방식
require('dotenv').config();
const notion = new Client({
auth: process.env.NOTION_API_KEY,
});
2. 통합 권한 설정하기
두 번째로 겪은 문제는 권한 설정이었어요. API 통합을 만들었는데, “You don’t have permission to access this resource” 오류가 계속 발생했죠.
중요한 점은 통합을 생성한 후에 반드시 해당 통합을 노션 페이지나 데이터베이스에 연결해야 한다는 거예요. 이 과정을 놓치면 아무리 API 키가 올바르더라도 데이터에 접근할 수 없어요.
- 노션 페이지나 데이터베이스 우측 상단의 ‘…’을 클릭
- ‘연결(Connections)’을 선택
- 만든 통합을 검색해서 추가
이렇게 했는데도 안 된다면, 통합 설정에서 필요한 기능(읽기/쓰기)에 대한 권한을 제대로 설정했는지 확인해보세요.
실제 사용 중인 Notion API 자동화 워크플로우 3가지
1. 데일리 스크럼 회의록 자동 생성 시스템
매일 아침 스크럼 회의를 하는데, 매번 같은 형식의 회의록을 만드는 게 너무 지루했어요. 그래서 특정 시간에 자동으로 회의록 템플릿을 생성하는 시스템을 만들었죠.
// 데일리 스크럼 노트 자동 생성 코드
async function createDailyScrum() {
const today = new Date();
const formattedDate = today.toISOString().split('T')[0];
try {
const response = await notion.pages.create({
parent: {
page_id: "YOUR_PARENT_PAGE_ID", // 회의록을 저장할 페이지 ID
},
properties: {
title: {
title: [
{
text: {
content: `데일리 스크럼 - ${formattedDate}`,
},
},
],
},
},
children: [
{
paragraph: {
rich_text: [
{
text: {
content: "## 오늘의 목표",
},
},
],
},
},
{
bulleted_list_item: {
rich_text: [
{
text: {
content: "목표 1",
},
},
],
},
},
// 나머지 템플릿 내용...
],
});
console.log("성공적으로 스크럼 노트가 생성되었습니다!");
return response;
} catch (error) {
console.error("스크럼 노트 생성 중 오류 발생:", error);
}
}
처음에는 이 코드를 cron 작업으로 돌렸는데, 우리 팀이 재택과 출근을 병행하다 보니 주말이나 휴일에도 불필요하게 회의록이 생성되는 문제가 있었어요. 그래서 Google Calendar API와 연동해서 실제 회의가 있는 날에만 회의록이 생성되도록 개선했죠.
이 자동화로 매주 약 50분의 시간을 절약하게 됐어요. 작아 보이지만, 1년이면 약 40시간이나 되는 시간이죠!
2. 외부 데이터 자동 수집 및 대시보드 생성
두 번째 워크플로우는 외부 API에서 데이터를 수집해 노션 데이터베이스에 자동으로 입력하고, 이를 대시보드 형태로 보여주는 시스템이에요.
저희 팀은 여러 마케팅 채널의 성과를 추적해야 했는데, 매번 수동으로 데이터를 수집하고 노션에 입력하는 게 너무 비효율적이었어요. 그래서 외부 API(Google Analytics, Facebook Ads 등)에서 데이터를 가져와 노션에 자동으로 업데이트하는 시스템을 만들었죠.
async function updateMarketingMetrics() {
// 외부 API에서 데이터 가져오기 (예: Google Analytics)
const gaData = await fetchGoogleAnalyticsData();
// 노션 데이터베이스에 데이터 업데이트
try {
const response = await notion.pages.create({
parent: {
database_id: "YOUR_DATABASE_ID",
},
properties: {
날짜: {
date: {
start: new Date().toISOString().split('T')[0],
},
},
방문자수: {
number: gaData.visitors,
},
전환율: {
number: gaData.conversionRate,
},
매출: {
number: gaData.revenue,
},
// 기타 필요한 메트릭...
},
});
console.log("마케팅 메트릭이 성공적으로 업데이트되었습니다!");
return response;
} catch (error) {
console.error("메트릭 업데이트 중 오류 발생:", error);
}
}
이 과정에서 가장 어려웠던 점은 외부 API의 인증 문제와 데이터 형식의 불일치였어요. 특히 Google Analytics API는 복잡한 인증 과정을 거쳐야 했고, 받아온 데이터의 형식을 노션이 이해할 수 있는 형태로 변환하는 작업이 필요했죠.
또한 처음에는 데이터가 제대로 입력되지 않는 문제가 있었는데, 노션 데이터베이스의 속성(property) 이름을 정확히 일치시켜야 한다는 것을 뒤늦게 알았어요.
이 자동화 덕분에 매주 약 3시간의 데이터 수집 및 입력 시간을 절약하게 됐어요. 게다가 실시간에 가깝게 데이터가 업데이트되어 의사결정 속도도 빨라졌죠!
3. 자동 태스크 관리 및 알림 시스템
세 번째 워크플로우는 프로젝트 관리를 위한 태스크 자동화 시스템이에요. 노션에서 태스크 상태가 변경되면 Slack으로 알림을 보내고, 마감일이 다가오는 태스크는 자동으로 우선순위를 조정하도록 만들었어요.
// 노션 데이터베이스 쿼리하기
async function queryTasksAndNotify() {
try {
// 마감일이 3일 이내인 태스크 조회
const response = await notion.databases.query({
database_id: "YOUR_TASKS_DATABASE_ID",
filter: {
and: [
{
property: "상태",
select: {
does_not_equal: "완료",
},
},
{
property: "마감일",
date: {
before: threeDaysFromNow(),
},
},
],
},
});
// 가져온 태스크들에 대해 처리
for (const task of response.results) {
// Slack으로 알림 보내기
await sendSlackNotification(task);
// 우선순위 자동 업데이트
await updateTaskPriority(task);
}
console.log(`${response.results.length}개의 태스크가 처리되었습니다.`);
return response;
} catch (error) {
console.error("태스크 처리 중 오류 발생:", error);
}
}
// 마감일 3일 후 날짜 계산
function threeDaysFromNow() {
const date = new Date();
date.setDate(date.getDate() + 3);
return date.toISOString().split('T')[0];
}
이 시스템을 구축하면서 가장 힘들었던 부분은 노션의 필터 문법을 이해하는 것이었어요. 문서를 여러 번 읽어도 이해가 안 되서 결국 일일이 테스트해가며 알아냈죠. 특히 날짜 필터링이 직관적이지 않아서 어려웠어요.
또 다른 문제는 노션 API의 속도였어요. 태스크가 많아지면 API 응답 시간이 느려져서, 결국 페이지네이션 처리와 병렬 요청 기법을 활용해 최적화했답니다.
이 자동화 덕분에 마감일을 놓치는 일이 크게 줄었고, 팀원들이 자신의 태스크를 더 잘 관리할 수 있게 됐어요. 매주 약 2시간의 프로젝트 관리 시간이 절약됐죠.
Notion API에서 자주 발생하는 오류와 해결 방법
Notion API를 사용하다 보면 여러 오류 상황을 마주하게 돼요. 제가 경험한 가장 흔한 오류들과 해결책을 정리해봤어요.
1. 권한 관련 오류
가장 흔한 오류는 역시 권한 문제예요.
"code": "object_not_found",
"message": "Could not find object with ID: ..."
이런 메시지가 나오면, 통합(Integration)이 해당 페이지/데이터베이스에 연결되어 있는지 확인해보세요. 또한 API 키가 유효한지, 환경 변수가 제대로 로드되는지도 체크해야 해요.
2. 요청 형식 오류
"code": "validation_error",
"message": "body failed validation: ..."
이런 오류는 보통 요청 본문의 형식이 잘못되었을 때 발생해요. 특히 properties 객체의 구조나 rich_text 배열의 형식이 정확해야 해요. 노션 API 문서에서 각 속성의 정확한 형식을 확인하는 것이 중요해요.
제가 자주 실수했던 부분은 숫자 타입의 속성에 문자열을 전달하는 것이었어요.
// 잘못된 방식
properties: {
가격: {
number: "1000", // 문자열로 전달 -> 오류 발생!
}
}
// 올바른 방식
properties: {
가격: {
number: 1000, // 숫자로 전달
}
}
3. API 속도 제한 초과
"code": "rate_limited",
"message": "Rate limited..."
노션 API는 초당 요청 수 제한이 있어요. 많은 데이터를 한꺼번에 처리할 때 주의해야 해요. 저는 이런 오류를 만났을 때 요청 사이에 지연을 추가하는 방식으로 해결했죠.
// API 요청 사이에 지연 추가
async function processWithDelay(items) {
for (const item of items) {
await processItem(item);
// 요청 사이에 500ms 지연 추가
await new Promise(resolve => setTimeout(resolve, 500));
}
}
Perplexity와 Notion API를 활용한 고급 자동화 워크플로우
API 자동화의 다음 단계로, 제가 최근에 구현한 Perplexity API와 Notion API의 조합 워크플로우를 소개해 드릴게요. 이 방식은 정말 강력한 자동화를 가능하게 해요!
// Perplexity API로 콘텐츠 분석 후 Notion에 저장하는 예시
async function analyzeContentAndStore() {
// 1. Notion에서 분석할 콘텐츠 가져오기
const contentPages = await notion.databases.query({
database_id: "YOUR_CONTENT_DATABASE_ID",
filter: {
property: "분석완료",
checkbox: {
equals: false,
},
},
});
for (const page of contentPages.results) {
// 2. 페이지 내용 가져오기
const pageContent = await getPageContent(page.id);
// 3. Perplexity API로 콘텐츠 분석
const analysis = await perplexity_ask({
messages: [
{
role: "system",
content: "You are a content analyst that provides concise insights."
},
{
role: "user",
content: `Analyze this content and provide key themes, sentiment, and improvement suggestions: ${pageContent}`
}
]
});
// 4. 분석 결과를 Notion에 업데이트
await notion.pages.update({
page_id: page.id,
properties: {
"분석결과": {
rich_text: [
{
text: {
content: analysis.substring(0, 2000), // 노션은 텍스트 길이 제한이 있어요
},
},
],
},
"분석완료": {
checkbox: true,
},
},
});
console.log(`"${page.properties.제목.title[0].plain_text}" 콘텐츠 분석 완료`);
await new Promise(resolve => setTimeout(resolve, 1000)); // API 속도 제한 방지
}
}
// 페이지 내용 가져오는 함수
async function getPageContent(pageId) {
const blocks = await notion.blocks.children.list({
block_id: pageId,
});
let content = "";
for (const block of blocks.results) {
if (block.type === 'paragraph' && block.paragraph.rich_text.length > 0) {
content += block.paragraph.rich_text.map(text => text.plain_text).join("") + "\n\n";
}
// 다른 블록 타입도 필요에 따라 처리...
}
return content;
}
이 워크플로우를 통해 콘텐츠 분석 작업이 완전히 자동화되었어요. 마케팅 팀은 노션에 콘텐츠를 작성하기만 하면, 시스템이 자동으로 분석해서 인사이트를 제공해주죠. 이전에는 이 작업에 콘텐츠당 약 30분씩 소요됐는데, 이제는 거의 즉시 결과를 얻을 수 있게 됐어요.
자주 묻는 질문
Q: Notion API를 사용하려면 꼭 프로그래밍을 알아야 하나요?
A: 기본적인 API 호출은 프로그래밍 지식이 필요하지만, Zapier나 Make(구 Integromat) 같은 노코드 도구를 사용하면 코딩 없이도 Notion API를 활용할 수 있어요. 다만, 복잡한 워크플로우를 구현하려면 JavaScript 같은 프로그래밍 언어의 기초는 알아두는 게 좋아요.
Q: Notion API 사용 시 보안 문제는 없나요?
A: API 키는 매우 중요한 보안 정보이므로, 절대로 코드에 직접 하드코딩하지 마세요. 항상 환경 변수나 보안 저장소를 사용해야 해요. 그리고 통합에는 필요한 최소한의 권한만 부여하는 것이 좋습니다.
Q: Notion API의 요청 제한은 어떻게 되나요?
A: 무료 계정의 경우, 분당 3회, 시간당 180회의 요청 제한이 있어요. 대규모 자동화를 구현할 때는 이 제한을 고려해서 설계해야 해요. Enterprise 계획에서는 더 높은 제한이 제공됩니다.
Q: 노션 페이지의 특정 블록만 어떻게 업데이트하나요?
A: 블록 ID를 사용해 특정 블록을 업데이트할 수 있어요. 먼저 blocks.children.list로 모든 블록을 가져온 다음, 원하는 블록의 ID를 찾아 blocks.update로 업데이트하면 돼요. 이 부분은 처음에 이해하기 어려울 수 있지만, API 문서의 예제를 참고하면 도움이 될 거예요.
Q: Notion API 학습을 위한 좋은 자료가 있나요?
A: 공식 API 문서가 가장 기본이지만, GitHub에 있는 notionjs 라이브러리의 예제들도 매우 유용해요. 또한 유튜브에서 “Notion API tutorial”을 검색하면 많은 실전 예제들을 찾을 수 있어요.
이제 실천할 시간
Notion API를 활용한 자동화는 처음에는 어렵게 느껴질 수 있어요. 저도 시작할 때 정말 헤맸거든요. 하지만 기본적인 사용법만 익히면, 정말 다양한 업무를 자동화할 수 있다는 장점이 있어요.
제가 공유한 세 가지 워크플로우는 시작점일 뿐이에요. 여러분의 업무 환경과 필요에 맞게 커스터마이징하면, 더 많은 시간을 절약할 수 있을 거예요. 특히 반복적인 데이터 입력이나 문서 생성 작업이 많다면, Notion API 자동화는 게임 체인저가 될 수 있어요.
다음 글에서는 Notion API와 다른 서비스(Slack, Google Calendar, Airtable 등)를 연동해 더 복잡한 워크플로우를 구축하는 방법을 다룰 예정이에요. 업무 자동화에 관심 있으신 분들은 기대해 주세요!