YouArePlan

API 문서

YouArePlan API Gateway 사용 가이드. 고객 등록부터 API 호출까지 모든 과정을 안내합니다.

Base URL: https://api.youareplan.co.kr

시작하기

3단계로 API를 바로 사용할 수 있습니다.

1고객 등록
POST /v1/customers/register 로 회원가입합니다. 인증 불필요.
bash
curl -X POST https://api.youareplan.co.kr/v1/customers/register \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "내 회사",
    "contact_name": "홍길동",
    "contact_email": "hong@example.com"
  }'
2API Key 받기
응답의 api_key 필드에서 키를 확인합니다.
json
{
  "customer": {
    "id": "cust_abc123",
    "company_name": "내 회사",
    "status": "active"
  },
  "api_key": "yap_a1b2c3d4e5f6..."
}
3API 호출
X-YAP-Key 헤더에 키를 넣어 요청합니다.
bash
curl https://api.youareplan.co.kr/v1/me \
  -H "X-YAP-Key: yap_a1b2c3d4e5f6..."

인증

모든 보호된 엔드포인트는 X-YAP-Key 헤더를 통해 인증합니다.

헤더 형식

API 키는 yap_ 접두사로 시작하며, 32자의 랜덤 문자열이 뒤따릅니다.

text
X-YAP-Key: yap_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
curl 예시
bash
curl https://api.youareplan.co.kr/v1/me \
  -H "X-YAP-Key: yap_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

엔드포인트 레퍼런스

공개 API인증 불필요

POST/v1/customers/register
고객 등록 및 API Key 발급. 회사명, 담당자명, 이메일은 필수입니다.
bash
curl -X POST https://api.youareplan.co.kr/v1/customers/register \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "주식회사 예시",
    "business_number": "123-45-67890",
    "contact_name": "홍길동",
    "contact_email": "hong@example.com",
    "contact_phone": "010-1234-5678",
    "usage_purpose": "정책자금 매칭 서비스"
  }'

# Response
{
  "customer": {
    "id": "cust_abc123",
    "company_name": "주식회사 예시",
    "status": "active"
  },
  "api_key": "yap_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}
GET/health
API Gateway 헬스체크. 서비스 상태를 확인합니다.
bash
curl https://api.youareplan.co.kr/health

# Response
{ "status": "ok" }

고객 APIX-YAP-Key 필요

GET/v1/me
내 고객 정보를 조회합니다.
bash
curl https://api.youareplan.co.kr/v1/me \
  -H "X-YAP-Key: yap_your_api_key"

# Response
{
  "id": "cust_abc123",
  "company_name": "주식회사 예시",
  "contact_name": "홍길동",
  "contact_email": "hong@example.com",
  "status": "active",
  "plan": "free"
}
GET/v1/me/usage
월별 API 사용량을 조회합니다. month 파라미터로 조회 월을 지정합니다 (YYYY-MM).
bash
curl "https://api.youareplan.co.kr/v1/me/usage?month=2026-02" \
  -H "X-YAP-Key: yap_your_api_key"

# Response
{
  "month": "2026-02",
  "total_requests": 1234,
  "limit": 5000,
  "remaining": 3766
}
GET/v1/me/keys
발급된 API Key 목록을 조회합니다.
bash
curl https://api.youareplan.co.kr/v1/me/keys \
  -H "X-YAP-Key: yap_your_api_key"

# Response
{
  "keys": [
    {
      "id": "key_001",
      "label": "production",
      "prefix": "yap_a1b2...",
      "status": "active",
      "created_at": "2026-01-15T09:00:00Z"
    }
  ]
}
POST/v1/me/keys
새 API Key를 추가 발급합니다. label로 용도를 구분할 수 있습니다.
bash
curl -X POST https://api.youareplan.co.kr/v1/me/keys \
  -H "X-YAP-Key: yap_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "label": "staging" }'

# Response
{
  "id": "key_002",
  "label": "staging",
  "api_key": "yap_new_key_here...",
  "created_at": "2026-02-01T12:00:00Z"
}
DELETE/v1/me/keys/{key_id}
API Key를 비활성화합니다. 비활성화된 키는 즉시 사용 불가합니다.
bash
curl -X DELETE https://api.youareplan.co.kr/v1/me/keys/key_002 \
  -H "X-YAP-Key: yap_your_api_key"

# Response
{ "status": "deactivated" }

프록시 APIX-YAP-Key 필요

Gateway를 통해 Polink, LaWink 등 연결된 서비스에 접근합니다. 경로가 그대로 프록시됩니다.

GET/polink/**Polink API (정책자금, 기업재무, AI매칭)
bash
# 정책자금 목록 조회
curl https://api.youareplan.co.kr/polink/v1/policies \
  -H "X-YAP-Key: yap_your_api_key"

# 기업 재무정보 조회
curl https://api.youareplan.co.kr/polink/v1/companies/123/financials \
  -H "X-YAP-Key: yap_your_api_key"
GET/lawink/**LaWink API (부동산, 법률)
bash
# 법률 검색
curl "https://api.youareplan.co.kr/lawink/api/v1/law/search?query=전세" \
  -H "X-YAP-Key: yap_your_api_key"

# 부동산 정보 조회
curl https://api.youareplan.co.kr/lawink/api/v1/realestate/123 \
  -H "X-YAP-Key: yap_your_api_key"

Rate Limiting

API 호출량은 플랜에 따라 제한됩니다.

플랜별 한도
Free월 5,000건
Enterprise맞춤 한도
응답 헤더
모든 응답에 Rate Limit 정보가 포함됩니다.
http
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 3766
X-RateLimit-Reset: 2026-03-01T00:00:00Z
429 Too Many Requests
한도 초과 시 429 응답이 반환됩니다. Reset 시간 이후 다시 호출할 수 있습니다.
json
{
  "error": "rate_limit_exceeded",
  "message": "월간 API 호출 한도를 초과했습니다.",
  "limit": 5000,
  "reset_at": "2026-03-01T00:00:00Z"
}

에러 코드

API는 표준 HTTP 상태 코드를 사용합니다.

코드상태설명
400Bad Request잘못된 요청. 필수 필드가 누락되었거나 형식이 올바르지 않습니다.
401UnauthorizedAPI Key가 누락되었거나 잘못되었습니다.
403Forbidden비활성화된 계정이거나 접근 권한이 없습니다.
404Not Found요청한 리소스를 찾을 수 없습니다.
429Too Many RequestsRate Limit 초과. 잠시 후 다시 시도하세요.
500Internal Server Error서버 내부 오류. 지속되면 문의해 주세요.
json
// 에러 응답 형식
{
  "error": "unauthorized",
  "message": "유효하지 않은 API Key입니다."
}

시작할 준비가 되셨나요?

지금 바로 API 키를 발급받고 YouArePlan Gateway를 사용해 보세요.

API 키 발급받기가격 확인하기