노션 API, 내부 연결 5단계와 데이터베이스 자동 입력 예시
노션 API로 문의 · 주문을 데이터베이스에 쌓을 때 필요한 내부 연결 만들기부터 데이터베이스에 연결 추가까지 5단계, 제목 · 선택 · 상태 · 날짜 속성의 입력 예시, 권한 없음 · 속성 이름 불일치 · 호출 한도 초과 오류와 대량 이전에 걸리는 시간 계산을 공식 문서 기준으로 정리했습니다.

노션 API는 노션 개발자 포털에서 내부 연결(예전 화면과 글에서는 내부 통합)을 만들고, 거기서 받은 토큰으로 데이터베이스를 읽고 쓰는 창구입니다. 토큰만으로는 아무 페이지도 열리지 않고, 자동 입력할 데이터베이스에 그 연결을 직접 추가해야 합니다. 호출 한도는 비즈니스 · 엔터프라이즈 요금제가 1분에 600회, 그 밖의 요금제가 1분에 180회(평균 초당 3회)입니다. 문의 · 주문처럼 건마다 한 행씩 쌓는 일에는 넉넉하지만, 수만 행을 한꺼번에 옮기는 대량 이전에는 맞지 않습니다.
노션 API로 무엇을 자동화하나요
API(프로그램끼리 데이터를 주고받는 창구)로 하는 일은 대부분 데이터베이스 한 곳에 행을 더하거나 고치는 일입니다. 노션 화면에서 위키와 데이터베이스를 꾸리는 법은 노션 사용법에 정리돼 있고, 이 글은 바깥 프로그램과 잇는 부분만 다룹니다.
- 문의 쌓기: 홈페이지 문의 폼에 들어온 이름 · 문의 유형 · 내용을 문의 데이터베이스에 한 행으로 넣고 처리 상태를 "신규"로 둡니다.
- 주문 기록: 쇼핑몰 주문이 들어오면 주문번호 · 금액 · 주문일을 넣고, 발송하면 상태만 바꿉니다.
- 보고 숫자 모으기: 시트나 사내 도구의 숫자를 하루 한 번 읽어 보고용 데이터베이스에 붙입니다.
- 바뀐 내용 알리기: 웹훅(바뀐 일이 생기면 노션이 먼저 알려 주는 방식)을 받아 상태가 바뀐 행을 메신저로 알립니다.
코드 없이 잇는 길도 있습니다. 재피어(Zapier) 같은 노코드 자동화 도구는 노션 연결을 두고 데이터 소스에 행을 만들거나 고치는 동작을 고르게 합니다. 도구별 요금 구조는 노코드 툴 비교에서 견줄 수 있습니다. 하루 건수가 많거나 여러 시스템을 거쳐야 한다면 직접 개발이 맞습니다.
내부 연결은 어떤 순서로 만드나요
연결은 워크스페이스 소유자만 만들 수 있습니다. 소유자가 아니라면 1단계를 소유자에게 맡기고 나머지를 이어서 하세요.
| 단계 | 할 일 | 확인할 것 |
|---|---|---|
| 1. 연결 만들기 | 개발자 포털에서 새 내부 연결을 만들고 쓸 워크스페이스를 고릅니다 | 워크스페이스 소유자 권한 |
| 2. 기능 고르기 | 설정(Configuration) 탭에서 콘텐츠 읽기 · 수정 · 입력 가운데 필요한 것만 켭니다 | 새 행을 만들려면 입력, 상태를 바꾸려면 수정, 기존 행을 찾으려면 읽기 |
| 3. 토큰 보관 | 같은 탭의 내부 연결 API 토큰을 서버 환경 변수에만 둡니다 | 브라우저 코드 · 공개 저장소에 넣지 않음 |
| 4. 데이터베이스에 연결 추가 | 데이터베이스 페이지 오른쪽 위 ••• 메뉴의 연결 추가(Add connections)에서 만든 연결을 고릅니다 | 추가하지 않으면 404 오류 |
| 5. 데이터 소스 ID 확인과 시험 입력 | 데이터베이스 조회 응답의 data_sources 목록에서 ID를 얻고, 행 하나를 만들어 봅니다 | 요청마다 Notion-Version 머리글 필수 |
2단계의 사용자 정보 권한은 이메일 주소까지 받을지 고르는 항목입니다. 문의를 쌓기만 한다면 사용자 정보 없음으로 두세요. 5단계의 요청은 아래처럼 생겼고, parent 에 데이터 소스 ID를, properties 에 데이터베이스의 속성 이름을 그대로 적습니다. 공식 문서 예시의 Notion-Version 값은 2026-03-11 입니다.
POST /v1/pages
Authorization: Bearer (발급받은 토큰)
Notion-Version: 2026-03-11
{"parent": {"data_source_id": "(데이터 소스 ID)"},
"properties": {"문의 제목": {"title": [{"text": {"content": "A 브랜드 견적 문의"}}]}}}
데이터베이스 속성은 어떻게 맞추나요
행을 넣을 때 속성 이름이나 ID는 데이터베이스의 속성과 정확히 같아야 합니다. 화면에서 "문의 유형"을 "유형"으로 고치면 그때부터 이름으로 보내는 입력은 실패합니다. 속성 ID는 이름을 바꿔도 그대로라 코드에는 ID를 적는 편이 오래가고, 이름으로 보낸다면 자동 입력을 붙인 날부터 속성 이름을 고정하세요. 아래는 문의 데이터베이스를 예로 든 유형별 입력 값입니다.
| 속성 유형 | 문의 데이터베이스 예 | 보내는 값 예시 | 맞출 점 |
|---|---|---|---|
| 제목(title) | 문의 제목 | {"title": [{"text": {"content": "견적 문의"}}]} | 데이터베이스마다 하나, ID는 늘 title |
| 텍스트(rich_text) | 문의 내용 | {"rich_text": [{"text": {"content": "…"}}]} | 조각 하나에 2,000자까지라 긴 글은 나눠 넣음 |
| 선택(select) | 문의 유형 | {"select": {"name": "홈페이지"}} | 없는 이름은 새 선택지로 더해짐, 이름에 쉼표 불가 |
| 상태(status) | 처리 상태 | {"status": {"name": "신규"}} | 이미 있는 선택지만 됨, 행 입력으로 새로 만들지 못함 |
| 날짜(date) | 접수일 | {"date": {"start": "2026-11-18"}} | 연-월-일 형식 |
| 수식 · 롤업 · 생성 일시 | 처리 기간 등 | 보내지 않음 | 노션이 스스로 채우는 값 |
선택 속성은 없는 이름을 보내면 연결에 쓰기 권한이 있을 때 선택지가 새로 생깁니다. 폼에서 "홈페이지"와 "홈페이지 제작"이 섞여 들어오면 선택지가 계속 늘어나니, 폼의 보기 목록과 노션 선택지 이름을 같은 표 하나로 맞춰 두세요.
한도와 오류는 어떻게 대비하나요
오류는 HTTP 상태 번호와 code 값으로 돌아옵니다. 자동 입력을 처음 붙였을 때 자주 만나는 것은 다음 다섯 가지입니다.
| 상태 · 코드 | 뜻 | 고치는 법 |
|---|---|---|
| 404 object_not_found | 대상이 없거나 그 연결에 추가되지 않음(권한 없음) | 데이터베이스에 연결 추가, 요청의 ID가 데이터 소스 ID인지 확인 |
| 401 unauthorized | 토큰이 올바르지 않음 | 토큰을 다시 복사하거나 새로 받고 환경 변수 확인 |
| 403 restricted_resource | 토큰에 그 기능이 없거나 워크스페이스 블록 한도 초과 | 2단계의 읽기 · 수정 · 입력 설정 확인 |
| 400 validation_error | 요청 본문이 형식과 다름(속성 이름 불일치, 2,000자 초과 등) | 응답의 message 를 읽고 속성 이름 · 유형을 데이터베이스와 맞춤 |
| 429 rate_limited | 호출 한도 초과 | Retry-After 머리글에 적힌 초만큼 기다렸다 다시 보냄 |
한도를 계산해 보면 대량 이전이 왜 맞지 않는지 보입니다. 엑셀 10,000행을 한 행에 요청 한 번씩 옮긴다면, 평균 초당 3회 기준으로 10,000 ÷ 3 = 약 3,333초, 55분 남짓 쉬지 않고 보내야 합니다. 그사이 같은 연결을 쓰는 다른 자동화가 돌면 429가 섞입니다. 기존 자료는 노션 화면의 CSV 가져오기로 한 번에 옮기고, API에는 그 뒤에 새로 생기는 건만 맡기세요. 한 번에 보내는 크기도 블록 1,000개 · 500KB, 배열 100개까지라 긴 본문은 나눠 붙입니다. 503 응답은 저장이 됐을 수도 있어, 같은 문의가 두 번 쌓이지 않게 다시 보내기 전에 확인합니다.
자주 묻는 질문
개인 접근 토큰과 내부 연결은 무엇이 다른가요?
개인 접근 토큰은 만든 사람의 권한으로 움직여, 그 사람이 열 수 있는 페이지면 따로 연결을 추가하지 않아도 닿습니다. 내부 연결은 워크스페이스가 가진 연결이라 추가해 준 페이지에만 닿습니다. 팀이 함께 쓰는 자동 입력은 담당자가 바뀌어도 끊기지 않도록 내부 연결로 만드세요. 공식 문서는 비즈니스 · 엔터프라이즈 요금제에서 개인 접근 토큰 만들기가 기본으로 막혀 있고, 워크스페이스 소유자가 설정의 연결 메뉴에서 열 수 있다고 적고 있습니다.
연결을 추가했는데 왜 404 오류가 나오나요?
요청에 넣은 ID가 연결을 추가한 데이터베이스의 것이 아니거나, 토큰이 다른 연결의 것일 때 같은 오류가 납니다. 데이터베이스 ID와 데이터 소스 ID는 서로 다른 값이니, 행을 만들 때는 데이터베이스 조회 응답에서 얻은 데이터 소스 ID를 쓰세요. 오류 메시지에 연결 이름이 나오면 그 이름이 데이터베이스의 연결 목록에 있는지도 함께 봅니다.
노션에서 바뀐 내용을 다른 프로그램이 바로 알 수 있나요?
내부 연결은 웹훅을 구독할 수 있습니다. 페이지가 바뀌거나 댓글이 달리면 노션이 정해 둔 주소로 알려 주므로, 몇 분마다 데이터베이스를 다시 읽어 바뀐 행을 찾는 방식보다 호출 수가 줄어듭니다. 담당자가 상태를 바꿀 때 메신저로 알림을 보내는 일이 이 방식에 맞습니다.
노션 API 연동을 외부에 맡길 때 무엇을 정해 두나요?
자동 입력할 데이터베이스와 속성 이름 · 유형 목록, 데이터가 들어오는 곳(문의 폼 · 쇼핑몰 · 시트), 하루 건수, 실패했을 때 알림을 받을 사람을 적어 두세요. 토큰은 워크스페이스 소유자가 만들어 운영 서버 설정에 직접 넣는 방식으로 합의하면 넘겨주고 받는 과정이 줄어듭니다. 비용은 연결할 시스템 수, 웹훅으로 되돌려 받는 일이 있는지, 실패 · 중복 같은 예외를 어디까지 처리할지로 정해지며, 이 목록을 그대로 보내면 업무 자동화 개발 견적을 같은 기준으로 받을 수 있습니다.
오늘 할 일
자동 입력할 데이터베이스 하나를 정해 속성 이름과 유형을 표로 적고, 그 이름을 고정하세요.
이어서 읽기 — 공공데이터 API, 활용 신청 순서와 업무 예시 5개



