TTechDNA APIAPI 테스트
DEVELOPER GUIDE / 시작하기

TechDNA API 시작하기

공통 안내

인증부터 첫 호출, 응답 처리와 오류 해결까지 TechDNA API 연동에 필요한 공통 규칙을 한 번에 확인합니다.

01API 키 발급
→
02엔드포인트 선택
→
03요청 전송
→
04응답 처리
API 버전v1
문서 최종 수정2026.09.07
상태연동 검증 중
STEP 1

인증과 API 키

모든 외부 API 요청에는 발급받은 키를 X-TD-API-KEY 헤더로 전달합니다. API 키는 호출 주체와 허용된 기능을 식별하며 URL이나 요청 본문에 포함하지 않습니다.

X-TD-API-KEY: YOUR_API_KEY
서버에서 호출키는 서버 환경변수 또는 별도의 비밀 저장소에 보관하세요.
클라이언트 노출 금지브라우저 코드, 공개 저장소, 로그에 API 키를 남기지 마세요.
이용 가능한 API발급된 API 키로 계약된 API를 이용할 수 있습니다. 403 오류가 발생하면 이용 범위를 확인하거나 담당자에게 문의해 주세요.
STEP 2

첫 번째 요청 보내기

운영 API 주소에 엔드포인트 경로를 연결하고 헤더에 API 키를 추가합니다. 아래 예제는 특허 상세정보를 조회하는 가장 단순한 GET 요청입니다.

기본 요청 주소https://td-api-service.techdna.kr/api/v1/...
cURL
curl "https://td-api-service.techdna.kr/api/v1/search/patentDetail?id=KR20190036046A" \
  -H "Accept: application/json" \
  -H "X-TD-API-KEY: YOUR_API_KEY"
GET요청값을 Query string으로 전달
POST요청값을 JSON body로 전달
Content-TypePOST 요청은 application/json 사용
날짜별도 안내가 없으면 YYYY-MM-DD 형식
페이지엔드포인트별 0 또는 1 시작 여부 확인
배열문서에 표시된 JSON 배열 또는 줄바꿈 형식 사용
성공 응답
{
  "code": 0,
  "data": { ... }
}
v1 검증 오류 · HTTP 422
{
  "code": 422,
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "요청 필드와 값의 형식을 확인해 주세요.",
    "fields": [
      {
        "field": "query.id",
        "code": "value_error.missing",
        "message": "필수값이 누락되었습니다."
      }
    ]
  },
  "requestId": "7b29f064a31e4cd98867ab5210d93e42"
}
STEP 3

API 테스트

왼쪽에서 엔드포인트를 선택하면 오른쪽 테스트 콘솔에 요청 항목과 예제가 준비됩니다. API 키는 현재 화면의 메모리에만 유지되며 새로고침하거나 창을 닫으면 제거됩니다.

1엔드포인트 선택
2API 키 입력
3요청값 확인
4응답 확인
콘솔 · 일반 API분당 10회
콘솔 · 유사특허 분석분당 3회

이 횟수는 개발 가이드 테스트 콘솔에서 키별·API별로 적용됩니다. 콘솔에서는 페이지와 결과 수를 예제 값으로 고정하며 한 번에 최대 20건을 요청합니다. 접속 위치나 동시 요청 수에 따라 추가 제한될 수 있습니다.

실제 API 이용 한도는 계약 및 서비스 정책을 확인하세요. 콘솔의 고정값은 실제 API 전체에 적용되는 제한이 아닙니다. 429 응답에 Retry-After 헤더가 있으면 안내된 시간 이후에 다시 요청하세요.

STEP 4

공통 응답과 오류 해결

v1 성공 응답은 code: 0과 결과 data를 반환합니다. 오류 응답의 code는 HTTP 상태와 같고 data는 null입니다. 오류 종류는 error.code, 안내는 error.message, 입력 오류 위치는 error.fields에서 확인하세요. 필드 정보가 없으면 빈 배열을 반환합니다.

200요청 처리 완료

code와 data 내용을 확인합니다.

400 · 422요청값 검증 오류

INVALID_REQUEST 또는 VALIDATION_ERROR입니다. 필수값, JSON 형식과 error.fields에 표시된 필드를 수정합니다.

401인증 실패

API 키 누락, 오타 또는 만료 여부를 확인합니다.

403이용 범위 확인 필요

계약된 API 이용 범위를 확인하거나 담당자에게 문의해 주세요.

404 · 405리소스 또는 메서드 오류

리소스 ID, /api/v1 경로와 GET·POST 메서드를 확인합니다.

429호출 제한 초과

Retry-After 헤더가 있으면 지정된 시간 이후에 다시 요청합니다.

500 · 502 · 503서버 또는 연결 서비스 오류

일시적인 오류일 수 있습니다. 반복되면 요청 ID와 함께 문의합니다.

504연결 서비스 응답 시간 초과

잠시 기다린 뒤 조회 요청을 다시 시도합니다.

요청 ID로 문의하기오류 응답의 requestId와 X-Request-ID 헤더는 같은 값입니다. 문의 시 요청 ID, 요청 시각, 엔드포인트와 HTTP 상태를 전달하세요. API 키는 보내지 마세요. 내부 오류 상세는 서버 로그에 기록하며 응답에는 원본 예외나 내부 주소를 표시하지 않습니다.
재시도 권장 방식429 또는 일시적인 5xx가 발생한 조회 요청만 1초, 2초, 4초 간격으로 최대 3회 재시도하세요. Retry-After 헤더가 있으면 그 시간을 우선 적용합니다. 입력·인증·권한·경로 오류는 요청을 수정하기 전까지 자동 재시도하지 않습니다.

위 형식은 v1 API 오류 응답 기준입니다. 테스트 콘솔은 원본 응답을 별도 결과 객체로 감싸 표시하며, 콘솔 자체 오류나 중간 프록시·서버 중단 시에는 응답 형식이 다를 수 있습니다.

QUICK START

무엇을 하고 싶나요?

목적에 맞는 API를 선택하면 상세 문서와 테스트 콘솔로 바로 이동합니다.

DOCUMENT

버전과 변경 정책

API 경로, 요청값, 응답 필드처럼 실제 연동에 영향을 주는 변경만 이 문서에서 안내합니다. 화면 구성이나 문서 표현 개선은 변경 이력에 포함하지 않습니다.

지원 종료가 예정된 기능은 해당 엔드포인트 제목 옆에 Deprecated 표시와 종료 예정일을 함께 안내합니다.