HTTP API

위젯이 쓰는 API 입니다. 문의 화면을 직접 만들고 싶을 때 같은 API 를 부르면 됩니다. 대부분은 설치 스크립트로 충분합니다.

두 엔드포인트 모두 브라우저에서 부르는 것을 전제로 합니다. 요청의 출처(Origin)가 프로젝트의 「위젯을 띄울 주소」에 있어야 하고, 서버 대 서버 호출은 받지 않습니다. 앱 키는 projectKey 쿼리로 넘깁니다.

폼 설정 조회

요청

GET https://polytalk.polymorph.co.kr/api/widget-config?projectKey=pk_...

응답 200

{
  "projectName": "우리 쇼핑몰",
  "categories": [
    {
      "key": "order",
      "label": "주문 문의",
      "description": "주문번호를 함께 적어 주세요.",
      "messageLabel": "무엇이 궁금하신가요?",
      "fields": [
        { "key": "order_no", "label": "주문번호", "type": "text", "required": true, "options": [] }
      ]
    }
  ]
}

문의 접수

요청

POST https://polytalk.polymorph.co.kr/api/inquiries?projectKey=pk_...
Content-Type: application/json

{
  "categoryKey": "order",
  "message": "사이즈를 바꾸고 싶어요.",
  "email": "[email protected]",
  "answers": [{ "key": "order_no", "value": "A-1042" }],
  "pagePath": "/orders/1042",
  "userId": "user_123",
  "userSignature": "..."
}

필드	필수	설명
`categoryKey`	권장	없거나 모르는 값이면 첫 카테고리로 받습니다.
`message`	예	본문. 4,000자까지.
`email`	비로그인 시	답변을 받을 주소.
`answers`	폼에 따라	추가 항목의 답. 필수 항목은 서버가 다시 검사합니다.
`pagePath`	아니요	어느 화면에서 보냈는지.
`userId`	아니요	로그인 회원. `userSignature` 가 맞을 때만 「확인됨」.

응답 200

{
  "lookupToken": "…",
  "lookupUrl": "https://polytalk.polymorph.co.kr/t/…"
}

lookupUrl 은 문의자가 답변을 확인하는 주소입니다. 반드시 문의자에게 보여 주세요 — 메일이 빠져도 답에 닿는 유일한 길입니다.

오류

상태	뜻
400	앱 키가 없거나 요청 형식이 잘못됨
403	허용되지 않은 출처이거나, 문의 받기가 꺼진 프로젝트
422	입력값 문제 (본문 없음·너무 김·필수 항목 누락). error 에 사유가 있습니다
429	같은 곳에서 너무 자주 보냄(1분에 5건). `Retry-After` 초 뒤에 다시 시도하세요