하이퍼스쿨 DB 유입 API 안내

협력업체용 · 2026-10-22

1. 개요

협력업체에서 수집한 신청자 정보(이름, 연락처)를 하이퍼스쿨로 전달하는 API입니다.

2. 사용 전 준비 (서버 IP 등록)

등록된 서버 IP에서 온 요청만 받습니다. 두 API 모두 같은 기준이 적용됩니다.

  1. API를 호출할 서버에서 forms.php를 한 번 호출합니다.
  2. 등록 전이라 아래처럼 응답에 호출한 IP가 표시됩니다. 
    {"success":false,"message":"허용되지 않은 IP","ip":"203.0.113.10"}
  3. 표시된 IP를 담당자에게 전달해 주세요. 등록 후 바로 사용할 수 있습니다.

서버가 여러 대이거나 IP가 바뀌는 경우 미리 알려주세요. IP 대역(예: 203.0.113.0/24)으로도 등록할 수 있습니다.

3. 유입구분 목록 조회

GEThttps://api.hyperschool.co.kr/forms.php

현재 접수 가능한 유입구분 목록이며 강사별로 정렬되어 있습니다. 수시로 추가·종료되므로, 접수 전에 이 목록으로 form_id를 확인해 주세요.

요청 예시

curl https://api.hyperschool.co.kr/forms.php

응답 예시

{
  "success": true,
  "count": 2,
  "forms": [
    { "form_id": 1, "instructor": "A강사", "title": "A강사 라이브" },
    { "form_id": 2, "instructor": "B강사", "title": "B강사 라이브" }
  ]
}
항목설명
form_id유입구분 번호. 접수할 때 이 값을 보냅니다.
instructor강사명
title페이지 제목 (참고용)

4. DB 접수

POSThttps://api.hyperschool.co.kr/lead.php

JSON(Content-Type: application/json)과 폼 방식(application/x-www-form-urlencoded) 모두 받습니다. 신청자 1명당 1번 호출합니다.

요청 항목

항목필수설명
name필수신청자 이름 (최대 50자)
phone필수휴대폰 번호. 010, 011, 016~019로 시작하는 10~11자리. 010-1234-5678, +82 10-1234-5678 형식도 받습니다.
form_id필수유입구분 번호. 목록 조회 결과에 있는 값만 받습니다.
source선택 (권장)유입경로 코드 (최대 45자).
코드를 입력해야 유입경로가 구분됩니다. 비워서 보내면 접수는 되지만 어느 경로로 들어온 DB인지 확인할 수 없으니 꼭 함께 보내주세요.

요청 예시 (JSON)

curl -X POST https://api.hyperschool.co.kr/lead.php \
  -H "Content-Type: application/json" \
  -d '{"name":"홍길동","phone":"01012345678","form_id":1,"source":"abc"}'

요청 예시 (폼 방식)

curl -X POST https://api.hyperschool.co.kr/lead.php \
  -d "name=홍길동" -d "phone=010-1234-5678" -d "form_id=1" -d "source=abc"

성공 응답

{
  "success": true,
  "log_id": 281500,
  "data": {
    "form_id": 1,
    "instructor": "A강사",
    "phone": "01012345678",
    "source": "abc",
    "received_at": "2026-10-22 14:30:00"
  }
}

success가 true이면 정상 접수입니다. log_id는 접수 번호이니 문의 시 함께 알려주세요.

5. 오류 응답

실패하면 success가 false이고, message에 사유가 들어갑니다.

HTTPmessage조치
403허용되지 않은 IP응답의 ip 값을 담당자에게 전달해 등록
405POST만 허용lead.php는 POST로 호출
400잘못된 요청 형식 (JSON 또는 form)JSON 문법 또는 Content-Type 확인
400필수값 누락 (name, phone, form_id)필수 항목 확인
400유효하지 않은 전화번호휴대폰 번호 형식 확인
400없는 form_id (forms.php 로 확인)목록 조회로 현재 form_id 확인
500DB 연결 실패 / 저장 실패잠시 후 재시도, 계속되면 담당자 문의

6. 권장 연동 흐름과 유의사항

  1. 하루 1회 또는 접수 전에 forms.php로 목록을 갱신합니다.
  2. 신청자마다 lead.php로 접수하고, 응답의 success를 확인합니다.
  3. 500 오류일 때만 재시도해 주세요. 400 오류는 같은 값으로 다시 보내도 실패합니다.