사전 준비

• 왈라 응답 API는 왈라로 수집한 데이터를 외부 시스템과 연동할 수 있도록 하는 API입니다.
• 왈라 응답 API를 사용하면 왈라로 수집한 데이터를 외부 시스템으로 전달할 수 있어요.
• 왈라 응답 API는 팀 내 관리자 권한을 가져야만 사용할 수 있습니다. 팀 내 관리자가 아니라면 팀 관리자에게 문의하여 권한을 받거나, 관리자로부터 API 키를 받아 사용할 수 있습니다.
• API로 탐색하고자 하는 프로젝트가 속한 팀이 Enterprise 플랜에 가입되어 있어야 합니다.

API 키 발급

왈라의 팀 관리자는 왈라의 팀 설정 페이지에서 API 키를 확인하고 발급할 수 있습니다.

API 키와 Client ID를 확인하고 메모장 등에 저장해두세요.

용어 해설

projectKey

왈라의 프로젝트 키는 작성하는 폼 별로 생성되는 고유한 값입니다.

이 값은 배포된 왈라 폼의 공유 URL에서 확인할 수 있습니다.

https://walla.my/v/{PROJECT_KEY}
https://walla.my/survey/{PROJECT_KEY}

fieldLabel

왈라 폼의 각 필드 안의 Title 을 의미합니다.

value

fieldLabel 에 대한 설문조사한 사람들의 응답 값입니다.

responseKey

왈라 설문에 대한 각 응답은 고유한 응답 키입니다.

해당 응답 키는 왈라의 응답시트에서 확인하거나 웹훅을 통해 전달받을 수 있습니다.

customerKey

왈라 설문에 참여한 사람의 고유한 식별자입니다.

해당 키는 응답자가 응답하는 설문 URL의 파라미터로 전달하여 기록할 수 있습니다.

외부 시스템에서 관리하고자 하는 고객의 고유한 식별자를 사용하여 사용자가 응답한 설문을 식별할 수 있습니다.

ex)
https://walla.my/survey/{PROJECT_KEY}?customerKey={CUSTOMER_KEY}
https://walla.my/v/{PROJECT_KEY}?customerKey={CUSTOMER_KEY}

fieldId

왈라 설문의 각 필드 당 고유한 키값입니다.

response

왈라 설문에 대해 응답한 사람들의 응답 값입니다.

• id: 필드에 대한 고유 키 값입니다. 즉 fieldId 와 같은 형태입니다.

• label: 필드에 대한 Title 입니다. 즉 fieldLabel 와 같은 형태입니다.

• answer: 필드에 대해 응답한 값입니다. 즉 value 와 같은 형태입니다.

{
  "response": [
    {
      "id": "fieldId",
      "label": "fieldLabel",
      "answer": "value"
    },
    {
      "id": "fieldId",
      "label": "fieldLabel",
      "answer": "value"
    }
  ]
}

API 사용하기

TOKEN 은 {Client ID}:{API Key} 를 base64로 인코딩한 값입니다.

API 상세 스펙

• base URL: https://staging---walla-api-thqwfj7gra-uc.a.run.app

checkFieldDataExists

특정 필드에 대한 응답이 존재하는지 확인합니다.

• method: POST
• url: https://staging---walla-api-thqwfj7gra-uc.a.run.app/checkFieldDataExists
• parameters: empty
• header: Authorization: {TOKEN}
• request body:

{
"projectKey": "string",
"fieldLabel": "string",
"value": "string"
}

• response: boolean 결과 값에 대한 true / false 값을 반환합니다.

checkCustomerKeyExists

특정 고객이 응답한 설문이 존재하는지 확인합니다.

• method: POST
• url: https://staging---walla-api-thqwfj7gra-uc.a.run.app/checkCustomerKeyExists
• parameters: empty
• header: Authorization: {TOKEN}
• request body:

{
"projectKey": "string",
"customerKey": "string"
}

• response: boolean 결과 값에 대한 true / false 값을 반환합니다.

listColumnData

특정 필드에 대한 응답을 리스트로 반환합니다.

• method: POST
• url: https://staging---walla-api-thqwfj7gra-uc.a.run.app/listColumnData
• parameters: empty
• header: Authorization: {TOKEN}
• request body:

{
  "projectKey": "string",
  "fieldLabel": "string"
}

• response: 특정 프로젝트의 특정 필드에 대한 응답에 대한 정보를 배열로 반환합니다. 각 응답에는 응답 내용, 타임스탬프, 응답 키가 포함됩니다.

{
"fieldLabel": "string",
"responses": [
    {
      "response": "string",
      "timestamp": "string",
      "responseKey": "string"
    }
  ],
"fieldId": "string"
}

listCustomerKeys

customerKey 가 사용된 응답의 데이터를 배열로 반환합니다.

• method: POST
• url: https://staging---walla-api-thqwfj7gra-uc.a.run.app/listCustomerKeys
• parameters: empty
• header: Authorization: {TOKEN}
• request body:

{
  "projectKey": "string"
}

• response: 각 응답의 customerKey, 타임스탬프를 반환합니다.

[
    {
        "customerKey": "string",
        "timestamp": "string"
    },
    {
        "customerKey": "string",
        "timestamp": "string"
    }
]

getResponseByCustomerKey

특정 고객이 응답한 설문을 반환합니다.

• method: POST
• url: https://staging---walla-api-thqwfj7gra-uc.a.run.app/getResponseByCustomerKey
• parameters: empty
• header: Authorization: {TOKEN}
• request body:

{
  "projectKey": "string",
  "customerKey": "string"
}

• response: customerKey 에 연관된 응답을 반환합니다. 타임스탬프, 프로젝트 키, 응답 키, 고객 키가 포함되어 있으며,

각각의 객체에 필드의 고유 fieldId(id), 필드의 Title(label), 그리고 필드에 대한 응답(answer)을 포함합니다.

{
  "timestamp": "string",
  "projectKey": "string",
  "responseKey": "string",
  "customerKey": "string",
  "response": [
    {
      "id": "string",
      "label": "string",
      "answer": "string"
    }
  ]
}

getResponseByResponseKey

특정 응답 키에 대한 응답을 반환합니다.

• method: POST
• url: https://staging---walla-api-thqwfj7gra-uc.a.run.app/getResponseByResponseKey
• parameters: empty
• header: Authorization: {TOKEN}
• request body:

{
  "projectKey": "string",
  "responseKey": "string"
}

• response: responseKey 에 연관된 응답을 반환합니다. 타임스탬프, 프로젝트 키, 응답 키, 고객 키가 포함되어 있으며,

각각의 객체에 필드의 고유 fieldId(id), 필드의 Title(label), 그리고 필드에 대한 응답(answer)을 포함합니다.

{
  "timestamp": "string",
  "projectKey": "string",
  "customerKey": "string",
  "response": [
    {
      "id": "string",
      "label": "string",
      "answer": "string"
    }
  ]
}

getProjectResponses

특정 프로젝트에 대한 모든 응답을 반환합니다.

• method: POST
• url: https://staging---walla-api-thqwfj7gra-uc.a.run.app/getProjectResponses
• parameters: empty
• header: Authorization: {TOKEN}
• request body:

{
  "projectKey": "string"
}

• response: 프로젝트에 대한 모든 응답을 반환합니다. 각 응답에는 fieldId(id), 필드 Title(label), 타임스탬프, hiddenFields 가 포함되어 있습니다.

{
    "projectDetails": {
        "fields": [
            {
                "id": "string",
                "label": "string"
            }
        ],
        "hiddenFields": [],
        "projectKey": "string"
    },
    "responses": [
        {
            "timestamp": "string",
            "customerKey": "string",
            "responseKey": "string",
            "response": [
                {
                    "id": "string",
                    "label": "string",
                    "answer": "string"
                }
            ]
        },
        {
            "timestamp": "string",
            "customerKey": "string",
            "responseKey": "string",
            "response": [
                {
                    "id": "string",
                    "label": "string",
                    "answer": "string"
                }
            ]
        }
    ]
}

에러 응답 코드

400 Bad Request

• 특정 키에 대해 잘못된 값이 들어갔을 때 반환됩니다.

{
  "message": "Bad Request"
}

• 조회할 프로젝트가 존재하지 않을 때 반환됩니다.

{
  "message": "Bad Request: Project does not exist"
}

403 Unauthorized & Forbidden

• 발급받는 Client ID가 프로젝트에 접근할 권한이 없는 경우 반환됩니다.

{
  "message": "Unauthorized: No Access to Project"
}

• 헤더에 Authorization 토큰이 없는 경우에 반환됩니다.

{
  "message": "Unauthorized: No API Key"
}

• 헤더에 잘못된 Authorization 토큰이 들어간 경우에 반환됩니다.

{
  "message": "Unauthorized: Invalid API Key"
}

• 팀 내 관리자가 아닌 사람이 API를 사용하려고 할 때 반환됩니다.

{
  "message": "Unauthorized: No Access to API"
}

500 Internal Server Error

• 서버상의 오류가 발생했을 때 반환됩니다.

{
  "message": "Internal Server Error"
}