노션 API 연동 방법, 연결 안 될 때 딱 정리

노션 페이지에 데이터베이스를 만들어 놓고 외부 서비스와 연동하려고 보니 막막해서 노션 API 연동 방법을 찾고 계신 것 같습니다. 이 문제는 대부분 통합 생성 후 데이터베이스에 대한 접근 권한을 명시적으로 추가하지 않아서 발생합니다. 이 글에서는 노션 개발자 페이지에서 통합을 생성하는 과정부터 내부 통합 토큰을 발급받고, 데이터베이스 ID를 추출하여 Python 코드로 실제 데이터를 불러오는 노션 API 연동 방법까지 단계별로 상세히 설명하겠습니다. 노션 API 연동은 단순한 데이터 가져오기를 넘어, 업무 자동화, 데이터 통합, 커스텀 솔루션 구축 등 다양한 가능성을 열어주는 핵심 기술입니다. 이 글을 통해 노션 API의 강력함을 직접 경험하고 여러분의 워크플로우를 한 단계 발전시키시길 바랍니다.

노션 API 연동을 위한 통합 생성 및 준비

노션 API를 사용하려면 먼저 외부 프로그램이나 스크립트가 노션 워크스페이스에 접근할 수 있는 '증명서' 역할을 하는 통합(Integration)을 만들어야 합니다. 이 과정은 노션 공식 개발자 사이트에서 이루어지며, 개발 지식이 없어도 몇 번의 클릭만으로 완료할 수 있습니다. 통합이 생성되지 않은 상태에서는 아무리 코드를 작성해도 접근 권한이 없다는 401 Unauthorized 오류가 발생하므로 첫 단계를 꼼꼼하게 진행해야 합니다. 마치 새로운 집에 들어가기 위해 열쇠를 발급받는 것과 같습니다.

실제 사용자들은 종종 API 연동 시 복잡한 설정보다는 단순한 권한 누락 때문에 어려움을 겪습니다. 한 사용자는 커뮤니티에서 "또하나의 단점은 챗지피티와는 달리 노션AI는 프롬프트를 지우고 거기에 답변을 입혀버립니다. 그래서 예전에 내가 내린 명령이 자료로 남지 않습니다."라고 언급하며 노션의 데이터 처리 방식에 대한 아쉬움을 토로한 바 있습니다. (출처: clien.net) API 연동 역시 데이터의 영속성과 접근 방식을 명확히 이해하는 것이 중요하며, 통합 생성은 그 첫 단추를 제대로 끼우는 과정입니다.

통합 생성을 위해 웹 브라우저의 주소창에 https://www.notion.so/my-integrations을 입력하고 접속합니다. 이 페이지는 노션 사용자가 자신의 워크스페이스에 연결할 애플리케이션을 관리하는 허브 역할을 합니다. 페이지가 로드되면 우측 상단에 보이는 'New integration' 버튼을 클릭하여 새로운 통합을 생성하는 과정을 시작합니다. 통합 생성은 크게 세 단계로 나눌 수 있습니다.

통합 생성 시 'Internal integration'과 'Public integration' 두 가지 옵션이 있습니다. 'Internal integration'은 특정 워크스페이스 내에서만 사용되는 통합으로, 일반적으로 API 연동 시 가장 많이 사용됩니다. 'Public integration'은 다른 노션 사용자의 워크스페이스에서도 사용할 수 있도록 공개되는 통합으로, 앱 스토어에 등록하거나 다른 사용자와 공유할 때 사용됩니다. 이번 글에서는 개인적인 데이터베이스 연동 및 자동화에 초점을 맞추므로 'Internal integration'을 선택하는 것이 맞습니다.

Photo by Jean-Daniel Francoeur on Pexels

내부 통합 토큰 발급 및 보안 관리

통합이 성공적으로 생성되었다면, 이제 외부 프로그램이 "나는 이 통합의 권한을 가지고 있다"는 것을 증명할 수 있는 비밀 키인 'Internal Integration Token'을 발급받아야 합니다. 이 토큰은 마치 노션 워크스페이스의 비밀번호와 같으므로 절대 타인에게 노출되어서는 안 됩니다. 깃허브(GitHub)와 같은 공개 저장소에 코드를 올릴 때는 실제 토큰을 그대로 작성하지 않고 환경 변수(Environment Variable)로 분리하여 관리하는 것이 보안상 필수적입니다. 이는 마치 집 열쇠를 아무에게나 보여주지 않는 것과 같은 이치입니다.

이전 단계에서 생성한 통합 대시보드의 'Internal Integration Token' 섹션을 보면 'Show' 또는 'Copy' 버튼이 있습니다. 'Show' 버튼을 클릭하면 secret_로 시작하는 긴 문자열을 볼 수 있습니다. 이것이 바로 API 요청 시 헤더에 포함해야 하는 인증 토큰입니다. 이 문자열을 복사하여 메모장이나 비밀번호 관리 도구에 안전하게 보관합니다. 이 토큰은 단순히 문자열이 아니라, 여러분의 노션 데이터에 접근할 수 있는 마스터 키와 같습니다.

토큰 발급 외에도 API 요청을 보낼 때 사용할 버전을 명시해야 합니다. 노션 API는 지속적으로 업데이트되며, 특정 버전을 명시해야 서버가 요청을 올바르게 처리하고 예상치 못한 동작을 방지할 수 있습니다. 현재 안정적인 최신 버전은 2022-06-28이며, 모든 API 요청 시 HTTP 헤더에 이 버전 정보를 포함시켜야 합니다. 버전 정보가 누락되거나 구버전을 사용할 경우 일부 기능이 정상적으로 작동하지 않거나, 향후 API 변경 시 문제가 발생할 수 있습니다.

API 요청 시 필요한 주요 정보는 다음과 같습니다.

이 두 가지 정보는 API 요청 헤더에 포함되어야 하며, 노션 서버가 어떤 버전의 API를 기준으로 요청을 처리해야 하는지 알려주는 역할을 합니다. 항상 최신 안정 버전(현재 2022-06-28)을 사용하는 것이 권장됩니다.

데이터베이스 ID 추출 및 연결 대상 설정

API 토큰이 준비되었다면, 이제 데이터를 가져오거나 수정할 대상인 특정 데이터베이스의 고유 ID를 찾아야 합니다. 노션에서 각 페이지나 데이터베이스는 32자리의 고유한 ID를 가집니다. API를 통해 데이터를 요청할 때는 웹 브라우저의 URL에 표시되는 ID와는 약간 다른 형태일 수 있으며, 데이터베이스 자체의 고유 ID를 사용해야 합니다. 많은 사용자들이 페이지 URL과 데이터베이스 ID를 혼동하여 연동 오류를 겪곤 합니다. 마치 편지를 보낼 때 받는 사람의 정확한 주소를 알아야 하는 것처럼, API도 정확한 데이터베이스 ID를 필요로 합니다.

데이터베이스 ID를 찾는 방법은 직관적입니다. 먼저, API로 접근하고자 하는 데이터베이스가 포함된 노션 페이지로 이동합니다. 그 후, 웹 브라우저의 주소창을 주의 깊게 살펴보세요. URL 구조는 일반적으로 https://www.notion.so/username/[Database-ID]?v=... 와 같은 형태를 띱니다. 여기서 ? 물음표 앞쪽에 위치한 32자리의 연속된 영숫자 조합이 바로 해당 데이터베이스의 고유 ID입니다. 만약 데이터베이스가 다른 페이지 안에 임베디드(embedded)되어 있다면, 해당 데이터베이스를 전체 화면 모드(Full page)로 열었을 때의 브라우저 주소창에서 ID를 확인하는 것이 가장 정확합니다.

데이터베이스 ID를 추출할 때 주의할 점은, ID가 포함된 URL의 형태가 노션 업데이트에 따라 약간씩 달라질 수 있다는 것입니다. 하지만 기본적인 구조는 유지되므로 ? 앞의 32자리 문자열을 추출하는 원칙은 동일하게 적용됩니다. 또한, 데이터베이스 ID는 대소문자를 구분하지 않으므로, 추출한 ID를 그대로 사용해도 무방합니다.

Python을 활용한 노션 API 연동 테스트 및 데이터 조회

이제 모든 준비가 끝났습니다. 발급받은 내부 통합 토큰과 확인한 데이터베이스 ID를 사용하여 실제로 Python 코드로 노션 API에 데이터를 요청해 보겠습니다. Python은 강력한 HTTP 요청 라이브러리인 requests를 통해 매우 간단하게 API 통신을 수행할 수 있습니다. 이 과정을 통해 API 연동이 정상적으로 이루어졌는지 확인하고, 노션에 저장된 데이터베이스의 내용을 JSON 형식으로 출력해 볼 수 있습니다. 마치 새로운 도구를 꺼내 실제로 사용해보는 단계입니다.

먼저, Python 환경에 requests 라이브러리가 설치되어 있는지 확인해야 합니다. 설치되어 있지 않다면, 터미널 또는 명령 프롬프트를 열고 다음 명령어를 입력하여 설치를 진행합니다. 최신 버전의 Python 3 환경이라면 아래 명령어를 사용하면 됩니다.

pip install requests

설치가 완료되었다면, 다음과 같은 Python 스크립트를 작성합니다. 이 코드는 노션 API 서버에 POST 요청을 보내 특정 데이터베이스의 내용을 조회하는 역할을 합니다. 코드 내의 YOUR_DATABASE_ID와 YOUR_INTERNAL_TOKEN 부분은 반드시 여러분이 발급받은 실제 값으로 교체해야 합니다. 또한, https://api.notion.com/v1/databases/{database_id}/query 엔드포인트는 데이터베이스의 내용을 조회하는 데 사용되며, headers에 인증 정보와 API 버전을 포함시키는 것이 중요합니다.

import requests
import json

# --- 설정 값 ---
# 실제 발급받은 내부 통합 토큰으로 교체하세요.
token = "YOUR_INTERNAL_TOKEN"
# API 연동 대상 데이터베이스의 실제 ID로 교체하세요.
database_id = "YOUR_DATABASE_ID"

# 노션 API 엔드포인트 URL
url = f"https://api.notion.com/v1/databases/{database_id}/query"

# API 요청 헤더 설정
headers = {
    "Authorization": f"Bearer {token}",          # 인증 토큰
    "Notion-Version": "2022-06-28",             # API 버전 명시
    "Content-Type": "application/json"         # 요청 본문의 타입
}

# --- API 요청 실행 ---
try:
    response = requests.post(url, headers=headers)
    response.raise_for_status() # HTTP 오류 발생 시 예외를 발생시킵니다.

    # --- 응답 결과 처리 ---
    data = response.json()
    print(" 데이터 조회 성공!")
    # JSON 데이터를 보기 좋게 출력합니다. ensure_ascii=False는 한글이 깨지지 않도록 합니다.
    print(json.dumps(data, indent=2, ensure_ascii=False))

    # 'results' 배열에 실제 데이터가 담겨 있습니다.
    if data.get("results"):
        print(f"\n총 {len(data['results'])}개의 항목을 찾았습니다.")
        # 첫 번째 항목의 일부 데이터만 예시로 출력해 볼 수 있습니다.
        first_item = data['results'][0]
        print("\n--- 첫 번째 항목 예시 ---")
        print(f"ID: {first_item.get('id')}")
        # 속성(properties)은 데이터베이스의 컬럼에 해당합니다.
        properties = first_item.get('properties')
        if properties:
            print("Properties:")
            for prop_name, prop_value in properties.items():
                # 속성 타입에 따라 값이 다르게 표현됩니다. (예: title, rich_text, number 등)
                # 여기서는 간단히 속성 이름과 해당 속성의 'title' 또는 'rich_text' 필드 값을 가져옵니다.
                if prop_value.get('type') == 'title' and prop_value.get('title'):
                    print(f"- {prop_name}: {prop_value['title'][0]['plain_text']}")
                elif prop_value.get('type') == 'rich_text' and prop_value.get('rich_text'):
                    print(f"- {prop_name}: {prop_value['rich_text'][0]['plain_text']}")
                elif prop_value.get('type') == 'number' and prop_value.get('number') is not None:
                    print(f"- {prop_name}: {prop_value['number']}")
                else:
                    # 다른 타입의 속성은 생략하거나 필요에 따라 추가합니다.
                    pass
        else:
            print("No properties found for this item.")
    else:
        print("\n데이터베이스에 항목이 존재하지 않습니다.")

except requests.exceptions.RequestException as e:
    print(f" API 요청 중 오류 발생: {e}")
    if hasattr(e, 'response') and e.response is not None:
        print(f"응답 상태 코드: {e.response.status_code}")
        print(f"응답 내용: {e.response.text}")
except Exception as e:
    print(f" 예상치 못한 오류 발생: {e}")

API 응답으로 받은 JSON 데이터는 매우 상세하며, 노션 데이터베이스의 모든 정보를 포함하고 있습니다. data['results']는 데이터베이스의 각 행(페이지)을 나타내는 리스트이며, 각 행은 다시 'properties'라는 딕셔너리를 통해 컬럼별 데이터를 담고 있습니다. 속성(property)의 이름과 값은 노션 데이터베이스의 구조에 따라 달라지므로, 실제 사용하는 데이터베이스의 구조를 파악하고 필요한 정보만 추출하는 로직을 구현해야 합니다.

연동 실패 시 원인별 해결 방법 및 주의사항

모든 설정을 바르게 따랐음에도 불구하고 API 연동 시 오류가 발생하는 경우가 종종 있습니다. 가장 흔하게 마주치는 오류 코드는 401 Unauthorized, 403 Forbidden, 그리고 404 Not Found입니다. 각 오류 코드는 서버가 왜 여러분의 요청을 거절했는지에 대한 명확한 단서를 제공합니다. 오류 메시지를 꼼꼼히 읽고 원인을 파악하는 것이 문제 해결의 지름길입니다. 마치 의사가 환자의 증상을 보고 진단을 내리는 것처럼, 오류 코드를 통해 문제의 근본 원인을 파악해야 합니다.

실제 사용자 후기를 보면 데이터를 가져오는 과정에서 URL 구조, 데이터베이스 ID 오류, 또는 권한 설정 문제 때문에 겪는 어려움이 자주 언급됩니다. 한 사용자는 "노션 오류 내용만 봤을때도 이미지 URL 이 잘못되었다고 하고, 구글 드라이브 공유 URL 이 이미지만 바로 내려줄 것 같지 않네요. 구글드라이브의 공유 URL 이 구글드라이브 사이트 내에서 이미지가 보이는 주소가 아니라, 정말 이미지만 바로 볼 수 있는 직접 링크가" 필요하다고 지적한 바 있습니다. (출처: clien.net) 이는 외부 데이터 소스를 노션과 연동할 때 리소스의 주소를 명확히 확인해야 함을 시사하며, API 연동에서도 유사한 맥락으로 접근해야 합니다.

다음은 API 연동 실패 시 점검해야 할 주요 항목들을 오류 코드별로 정리한 표입니다. 이 표를 참고하여 차근차근 문제를 해결해 나가시길 바랍니다.

이 외에도 네트워크 문제, 서버 측 일시 오류 등