커스텀 도메인 API 레퍼런스

조직에 등록된 커스텀 도메인 조회 (3개 엔드포인트)

참고인증

모든 Service API 요청에는 X-API-KEY 헤더를 포함해야 합니다. API Key는 콘솔 > 개발자 > API 키 관리에서 발급받을 수 있습니다. 공통 규칙은 API 개요를 참고하세요.

GET /api/v1/service/custom-domains

조직에 등록된 커스텀 도메인 목록을 조회합니다. 검색어와 상태 필터, 페이지 분할을 지원합니다.

Query Parameters

파라미터	타입	설명
search	String	도메인 이름 검색 키워드 (부분 일치)
status	String	상태 필터 (PENDING / VERIFIED / ACTIVE / FAILED / REVOKED)
page	Integer	페이지 번호 (0부터 시작, 기본: 0)
size	Integer	페이지 크기 (기본: 20)
sort	String	정렬 기준 (기본: createdAt,desc)

Response

Spring Page 응답 형식으로 반환됩니다. content[] 배열의 각 항목 필드는 아래와 같습니다.

필드	타입	설명
id	Long	도메인 ID
domainName	String	도메인 이름 (예: link.example.com)
ownerUsername	String	도메인 소유자 계정 ID
status	String	도메인 상태 (PENDING / VERIFIED / ACTIVE / FAILED / REVOKED)
cnameRecordName	String	DNS 인증용 CNAME 레코드 이름 (외부 도메인 전용, 플랫폼 서브도메인은 null)
cnameRecordValue	String	DNS 인증용 CNAME 레코드 값 (외부 도메인 전용, 플랫폼 서브도메인은 null)
createdAt	String	등록 일시 (yyyy-MM-dd'T'HH:mm 형식)
deletionRequested	Boolean	삭제 요청 여부
deletionRequestedAt	String	삭제 요청 일시 (요청 전 null)

페이지 메타 필드:

필드	타입	설명
totalElements	Long	전체 도메인 수
totalPages	Integer	전체 페이지 수
size	Integer	페이지 크기
number	Integer	현재 페이지 번호 (0부터 시작)
numberOfElements	Integer	현재 페이지의 실제 항목 수
first	Boolean	첫 번째 페이지 여부
last	Boolean	마지막 페이지 여부
empty	Boolean	결과가 비어있는지 여부
pageable	Object	페이지 상세 정보 (pageNumber, pageSize, offset, sort 등)

참고status 값 의미

PENDING: DNS 인증 대기 중 | VERIFIED: 인증 완료 (외부 도메인은 로드밸런서 미설정) | ACTIVE: 완전 활성화 (외부 도메인 로드밸런서 연결 완료) | FAILED: 인증 실패 | REVOKED: 인증 취소

cURL

curl "https://fplink.net/api/v1/service/custom-domains" \
  -H "X-API-KEY: your-api-key"

# 상태 필터 + 검색 + 페이지
curl "https://fplink.net/api/v1/service/custom-domains?status=ACTIVE&search=example.com&size=10" \
  -H "X-API-KEY: your-api-key"

JSON

{
  "content": [
    {
      "id": 7,
      "domainName": "link.example.com",
      "ownerUsername": "user@example.com",
      "status": "ACTIVE",
      "cnameRecordName": "_acme-challenge.link.example.com.",
      "cnameRecordValue": "abc123.authorize.certificatemanager.goog.",
      "createdAt": "2026-03-15T10:23",
      "deletionRequested": false,
      "deletionRequestedAt": null
    },
    {
      "id": 3,
      "domainName": "go.myservice.net",
      "ownerUsername": "user@example.com",
      "status": "VERIFIED",
      "cnameRecordName": null,
      "cnameRecordValue": null,
      "createdAt": "2026-01-20T09:10",
      "deletionRequested": false,
      "deletionRequestedAt": null
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 20,
    "sort": { "sorted": true, "unsorted": false, "empty": false },
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "totalElements": 2,
  "totalPages": 1,
  "size": 20,
  "number": 0,
  "numberOfElements": 2,
  "first": true,
  "last": true,
  "empty": false
}

GET /api/v1/service/custom-domains/{id}

특정 커스텀 도메인의 상세 정보를 조회합니다. 다른 조직의 도메인 ID를 지정하면 404 Not Found가 반환됩니다.

Path Parameters

파라미터	타입	필수	설명
id	Long	필수	도메인 ID

Response

목록 조회 content[]의 단일 도메인 객체와 동일한 필드를 반환합니다.

cURL

curl "https://fplink.net/api/v1/service/custom-domains/7" \
  -H "X-API-KEY: your-api-key"

JSON

{
  "id": 7,
  "domainName": "link.example.com",
  "ownerUsername": "user@example.com",
  "status": "ACTIVE",
  "cnameRecordName": "_acme-challenge.link.example.com.",
  "cnameRecordValue": "abc123.authorize.certificatemanager.goog.",
  "createdAt": "2026-03-15T10:23",
  "deletionRequested": false,
  "deletionRequestedAt": null
}

GET /api/v1/service/custom-domains/verified

단축 URL 생성 및 캠페인에 실제로 사용 가능한 도메인만 반환합니다. VERIFIED 또는 ACTIVE 상태의 도메인 전체를 페이지 래퍼 없이 배열로 반환합니다.

Response

도메인 객체 배열을 반환합니다. 각 항목의 필드 구성은 목록 조회의 content[] 항목과 동일합니다.

cURL

curl "https://fplink.net/api/v1/service/custom-domains/verified" \
  -H "X-API-KEY: your-api-key"

JSON

[
  {
    "id": 3,
    "domainName": "go.myservice.net",
    "ownerUsername": "user@example.com",
    "status": "VERIFIED",
    "cnameRecordName": null,
    "cnameRecordValue": null,
    "createdAt": "2026-01-20T09:10",
    "deletionRequested": false,
    "deletionRequestedAt": null
  },
  {
    "id": 7,
    "domainName": "link.example.com",
    "ownerUsername": "user@example.com",
    "status": "ACTIVE",
    "cnameRecordName": "_acme-challenge.link.example.com.",
    "cnameRecordValue": "abc123.authorize.certificatemanager.goog.",
    "createdAt": "2026-03-15T10:23",
    "deletionRequested": false,
    "deletionRequestedAt": null
  }
]

← 앱 API

웹훅 연동 가이드 →