1. 시작하기: API 인증

Walla API를 사용하려면 먼저 API 키를 발급받아 인증을 설정해야 합니다.

1) API 키 발급받기

1. Walla 대시보드(app.walla.my)에 로그인합니다.

2. API 키를 발급받고자 하는 팀의 설정 메뉴로 이동합니다.

3. 팀 설정 > API에서 클라이언트 ID(clientId)와 API 키(apiKey)를 발급받아 안전한 곳에 보관합니다.

   

2) 인증 요청 보내기

Walla API는 Basic 인증 방식을 사용합니다. 발급받은 clientId와 apiKey를 사용하여 다음과 같이 인증 토큰을 생성합니다.

1. {clientId}:{apiKey} 형태의 문자열을 만듭니다. (예: myClientId:myApiKey)

2. 이 문자열을 Base64로 인코딩합니다.

3. API 요청 시, HTTP 헤더에 다음과 같이 Authorization 값을 포함합니다.

   • Authorization: Basic {Base64로 인코딩된 토큰}

cURL 예시:

Bash
# 1. 토큰 생성 (macOS / Linux)
TOKEN=$(echo -n "YOUR_CLIENT_ID:YOUR_API_KEY" | base64)

# 2. API 요청
curl -X GET "https://walla-api.datalab.workers.dev/workspace/list" \
     -H "Authorization: Basic $TOKEN"

2. API 엔드포인트 상세

모든 API 엔드포인트는 https://walla-api.data-lab.workers.dev를 기본 URL로 사용합니다.

1) 워크스페이스 (Workspaces)

팀 내 워크스페이스 정보를 조회합니다.

• GET /workspace/list

  • 설명: 팀에 속한 모든 워크스페이스 목록을 가져옵니다.

  • 응답 예시:

    JSON
    [
      {
        "workspaceName": "마케팅팀 워크스페이스",
        "workspaceKey": "ws-key-12345",
        "createdAt": "2025-07-03T10:00:00Z",
        "creator": "user-uid-abcde",
        "storage": { "used": 102400 }
      }
    ]

• GET /workspace/{workspaceKey}

  • 설명: 특정 워크스페이스의 상세 정보를 가져옵니다.

  • 파라미터: workspaceKey (경로) - 조회할 워크스페이스의 고유 키

• GET /workspace/query/projectKey

  • 설명: 프로젝트 키(projectKey)를 사용하여 해당 프로젝트가 속한 워크스페이스의 키(workspaceKey)를 찾습니다.

  • 파라미터: projectKey (쿼리) - 프로젝트의 고유 키

  • 응답 예시:

    Json
    {
      "workspaceKey": "ws-key-12345"
    }

2) 프로젝트 (Projects)

워크스페이스 내 프로젝트 정보를 조회합니다.

• GET /workspace/{workspaceKey}/project/list

  • 설명: 특정 워크스페이스에 속한 모든 프로젝트 목록을 가져옵니다.

  • 파라미터: workspaceKey (경로)

• GET /workspace/{workspaceKey}/project/{projectKey}

  • 설명: 특정 프로젝트의 상세 정보를 가져옵니다.

  • 파라미터: workspaceKey, projectKey (경로)

• 
  

3) 응답 데이터 (Responses)

프로젝트에 제출된 응답 데이터를 조회하고 관리합니다.

• GET /workspace/{workspaceKey}/project/{projectKey}/response/list

  • 설명: 특정 프로젝트의 모든 응답 데이터를 Parquet 파일 형식으로 다운로드합니다. 대용량 데이터 분석에 용이합니다.

  • 응답: application/octet-stream (Parquet 파일)

• GET /workspace/{workspaceKey}/project/{projectKey}/response/get/responseKey/{responseKey}

  • 설명: 응답의 고유 키(responseKey)를 사용하여 단일 응답 데이터를 가져옵니다.

  • 파라미터: workspaceKey, projectKey, responseKey (경로)

• GET /workspace/{workspaceKey}/project/{projectKey}/response/get/customerKey/{customerKey}

  • 설명: 고객 키(customerKey)를 사용하여 단일 응답 데이터를 가져옵니다. (고객 키는 응답 제출 시 별도로 설정한 값입니다.)

  • 파라미터: workspaceKey, projectKey, customerKey (경로)

• GET /workspace/{workspaceKey}/project/{projectKey}/response/check/customerKey/{customerKey}

  • 설명: 특정 customerKey를 가진 응답이 존재하는지 확인합니다.

  • 파라미터: workspaceKey, projectKey, customerKey (경로)

  • 응답 예시:

    JSON
    {
      "exists": true
    }

• GET /workspace/{workspaceKey}/project/{projectKey}/response/query/dateRange

  • 설명: 지정된 날짜 범위 내의 응답들을 조회합니다.

  • 파라미터: workspaceKey, projectKey (경로), startDate, endDate (쿼리, ISO 날짜 형식)

• GET /workspace/{workspaceKey}/project/{projectKey}/response/listCustomerKeys

  • 설명: 프로젝트 내에서 null이 아닌 모든 customerKey 목록을 가져옵니다.

  • 응답 예시:

    JSON
    {
      "customerKeys": ["customer-001", "customer-002", "customer-003"]
    }

4) 컬럼 (Columns)

프로젝트의 응답 데이터 구조(컬럼 정보)를 조회합니다.

• GET /workspace/{workspaceKey}/project/{projectKey}/columns

  • 설명: 프로젝트의 폼 필드 및 히든 필드에 해당하는 컬럼 정보를 가져옵니다.

  • 파라미터: workspaceKey, projectKey (경로)

  • 응답 예시:

    JSON
    {
      "field_columns": [
        { "column_name": "field_abcd", "label": "이름", "type": "TEXT" }
      ],
      "hidden_field_columns": [
        { "column_name": "hf_1234", "label": "유입경로", "type": "TEXT" }
      ]
    }

3. 주요 사용 예시

1) 예시 1: 특정 프로젝트의 모든 응답 데이터를 다운로드하여 분석하기

1. GET /workspace/list 또는 GET /workspace/query/projectKey를 호출하여 원하는 프로젝트가 속한 workspaceKey를 찾습니다.

2. GET /workspace/{workspaceKey}/project/{projectKey}/response/list를 호출하여 응답 데이터를 Parquet 파일로 다운로드합니다.

3. 다운로드한 Parquet 파일을 Pandas(Python), R 등 데이터 분석 도구로 읽어와 분석을 시작합니다.

2) 예시 2: CRM 시스템과 연동하여 특정 고객의 응답 이력 확인하기

1. CRM 시스템의 고객 ID를 Walla의 customerKey와 동기화합니다.

2. CRM에서 특정 고객 조회 시, GET .../response/check/customerKey/{customerKey} API를 호출하여 해당 고객의 Walla 응답 여부를 확인합니다.

3. 응답이 존재("exists": true)하면, GET .../response/get/customerKey/{customerKey} API를 호출하여 상세 응답 내용을 CRM 시스템 내에 표시합니다.

4. 주의사항 및 FAQ

• API 버전: 현재 API 버전은 v1.0입니다. 향후 변경 사항이 있을 경우 새로운 버전으로 제공될 수 있습니다.

• 에러 처리: API 요청이 실패하면 표준 HTTP 상태 코드(예: 400 Bad Request, 401 Unauthorized, 404 Not Found)가 반환됩니다. 응답 본문에 에러에 대한 추가 정보가 포함될 수 있습니다.

• Rate Limiting: 과도한 호출을 방지하기 위해 API 요청 횟수 제한(Rate Limiting)이 적용될 수 있습니다. 응답 헤더를 확인하여 현재 상태를 파악하세요.

API 사용 중 궁금한 점이나 문제가 발생하면 언제든지 Walla 고객센터로 문의해주세요.