μ™ˆλΌ 응닡 API
μ‹œμž‘ 및 μŠ€νŽ™
πŸ””
μ™ˆλΌ 응닡 APIλŠ” Enterprise ν”ŒλžœλΆ€ν„° 이용 κ°€λŠ₯ν•©λ‹ˆλ‹€.

μ™ˆλΌ 응닡 APIλŠ” μ™ˆλΌλ‘œ μˆ˜μ§‘ν•œ 데이터λ₯Ό μ™ΈλΆ€ μ‹œμŠ€ν…œκ³Ό 연동할 수 μžˆλ„λ‘ ν•˜λŠ” APIμž…λ‹ˆλ‹€. μ™ˆλΌ 응닡 APIλ₯Ό μ‚¬μš©ν•˜λ©΄ μ™ˆλΌλ‘œ μˆ˜μ§‘ν•œ 데이터λ₯Ό μ™ΈλΆ€ μ‹œμŠ€ν…œμœΌλ‘œ 전달할 수 μžˆμŠ΅λ‹ˆλ‹€.

사전 μ€€λΉ„

🚨
μ™ˆλΌ 응닡 APIλŠ” Enterprise ν”ŒλžœλΆ€ν„° 이용 κ°€λŠ₯ν•©λ‹ˆλ‹€.
  • μ™ˆλΌ 응닡 APIλŠ” νŒ€ λ‚΄ κ΄€λ¦¬μž κΆŒν•œμ„ κ°€μ Έμ•Όλ§Œ μ‚¬μš©ν•  수 μžˆμŠ΅λ‹ˆλ‹€. νŒ€ λ‚΄ κ΄€λ¦¬μžκ°€ μ•„λ‹ˆλΌλ©΄ νŒ€ κ΄€λ¦¬μžμ—κ²Œ λ¬Έμ˜ν•˜μ—¬ κΆŒν•œμ„ λ°›κ±°λ‚˜, κ΄€λ¦¬μžλ‘œλΆ€ν„° API ν‚€λ₯Ό λ°›μ•„ μ‚¬μš©ν•  수 μžˆμŠ΅λ‹ˆλ‹€.
  • API둜 νƒμƒ‰ν•˜κ³ μž ν•˜λŠ” ν”„λ‘œμ νŠΈκ°€ μ†ν•œ νŒ€μ΄ Enterprise ν”Œλžœμ— κ°€μž…λ˜μ–΄ μžˆμ–΄μ•Ό ν•©λ‹ˆλ‹€.

API ν‚€ λ°œκΈ‰

μ™ˆλΌμ˜ νŒ€ κ΄€λ¦¬μžλŠ” μ™ˆλΌμ˜ νŒ€ μ„€μ • νŽ˜μ΄μ§€μ—μ„œ API ν‚€λ₯Ό ν™•μΈν•˜κ³  λ°œκΈ‰ν•  수 μžˆμŠ΅λ‹ˆλ‹€.

Untitled

API 킀와 Client IDλ₯Ό ν™•μΈν•˜κ³  λ©”λͺ¨μž₯ 등에 μ €μž₯ν•΄λ‘μ„Έμš”.

🚨
API ν‚€λŠ” 외뢀에 λ…ΈμΆœλ˜μ§€ μ•Šλ„λ‘ μ£Όμ˜ν•΄μ•Ό ν•©λ‹ˆλ‹€.

μš©μ–΄ ν•΄μ„€

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 μ‚¬μš©ν•˜κΈ°

Authorization 토큰 λ§Œλ“€κΈ°

  • μ™ˆλΌ 응닡 APIλ₯Ό μ‚¬μš©ν•˜κΈ° μœ„ν•΄μ„œλŠ” λ¨Όμ € Headers μ•ˆμ— key: "Authorization" value: TOKEN 을 λ„£μ–΄μ•Ό ν•©λ‹ˆλ‹€.
TOKEN 은 {Client ID}:{API Key} λ₯Ό base64둜 μΈμ½”λ”©ν•œ κ°’μž…λ‹ˆλ‹€.

API ν…ŒμŠ€νŠΈν•˜κΈ°

이 링크 (opens in a new tab)λ₯Ό 톡해 μ™ˆλΌ 응닡 APIλ₯Ό ν…ŒμŠ€νŠΈν•΄λ³Ό 수 μžˆμŠ΅λ‹ˆλ‹€.

Untitled

ν•΄λ‹Ή μœ„μΉ˜μ—μ„œ μƒμ„±ν•œ 토큰을 μž…λ ₯ν•˜κ³ , Try it out λ²„νŠΌμ„ ν΄λ¦­ν•˜μ—¬ APIλ₯Ό ν…ŒμŠ€νŠΈν•  수 μžˆμŠ΅λ‹ˆλ‹€.

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: νŠΉμ • ν”„λ‘œμ νŠΈμ˜ νŠΉμ • ν•„λ“œμ— λŒ€ν•œ 응닡에 λŒ€ν•œ 정보λ₯Ό λ°°μ—΄λ‘œ λ°˜ν™˜ν•©λ‹ˆλ‹€. 각 μ‘λ‹΅μ—λŠ” 응닡 λ‚΄μš©, νƒ€μž„μŠ€νƒ¬ν”„, 응닡 ν‚€κ°€ ν¬ν•¨λ©λ‹ˆλ‹€.
πŸ””
timestampλŠ” ISO 8601 ν˜•μ‹μ˜ Date λ¬Έμžμ—΄μž…λ‹ˆλ‹€. ex) 2024-04-15T09:28:55.000Z
{
"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"
                }
            ]
        }
    ]
}

μ—λŸ¬ 응닡 μ½”λ“œ

🚨
λͺ¨λ“  API ν˜ΈμΆœμ—λŠ” TOKEN 이 ν•„μš”ν•©λ‹ˆλ‹€.

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"
}