REST API 사용 및 에러 안내

Endpoint

모든 API 요청은 아래 Base URL을 기준으로 합니다.

https://api.1badge.world/api/v1/ext

TLS

모든 요청은 HTTPS로 이루어집니다. 정보를 안전하게 보호하기 위해 TLS 1.2 이상 사용을 권장하며, 가급적 TLS 1.3을 사용하시기 바랍니다.

Content-Type

1Badge REST API는 application/json Content Type을 사용합니다. POST 요청의 본문(Body)은 반드시 JSON 형식으로 전송해야 하며, 아래 헤더를 함께 지정하시기 바랍니다.

Content-Type: application/json; charset=utf-8

인증

모든 요청에는 X-API-Key 헤더를 포함해야 합니다. 자원은 API Key에 연결된 기관 범위로 자동 한정됩니다.

X-API-Key: {발급받은_API_Key}

자세한 내용은 인증을 참고하세요.

요청 수 제한

요청 수 제한(Rate Limit)과 발급 한도 정책은 API 요청건수 제한 안내를 참고하세요.

인코딩

GET 요청의 쿼리 파라미터 값에 한글, 공백, 이메일의 +·@, 또는 예약문자(& = ? # % 등)가 포함될 경우 반드시 UTF-8 기준 URL 인코딩(percent-encoding) 하여 전송해야 합니다.

• 인코딩하지 않으면 값이 잘못 해석되어 조회 결과가 비거나 의도와 다른 대상이 조회될 수 있습니다. (예: email=user+01@x.com 의 + 를 인코딩하지 않으면 공백으로 해석됩니다.)
• 배지정의·발급이력 목록은 sort·order로 정렬합니다(예: ?sort=reg_date&order=desc). 두 API에서 기존 sort_by·sort_type은 무시합니다. 다른 API의 정렬 방식은 각 레퍼런스를 확인하세요. / Badge template and issuance history lists use sort and order; both ignore sort_by and sort_type. See each reference for other APIs.
• 두 목록 API의 날짜 조건은 yyyy-MM-dd 형식의 실제 날짜(1000~9999년)이며 종료일 당일까지 포함합니다. 잘못된 날짜·허용값 밖의 정렬 조건은 HTTP 400, 본문 code=1400으로 응답합니다. / Both list APIs accept calendar dates in yyyy-MM-dd format (years 1000–9999), including the entire end date. Invalid dates or unsupported sort options return HTTP 400 with body code=1400.

응답 구조

1Badge API의 모든 응답은 공통된 JSON 형식으로 반환됩니다. 처리 결과는 code, 안내 메시지는 message, 응답 데이터는 data 필드에 담깁니다.

{
  "code": "0001",
  "message": "요청 성공하였습니다.",
  "data": {}
}

필드	타입	설명
code	String	처리 결과 코드 (성공·오류 구분)
message	String	처리 결과 안내 메시지
data	Object	응답 데이터 (오류 발생 시 null)

성공 코드

HTTP	code	의미
200 OK	0001	조회 성공
202 Accepted	0002	발급 요청 접수
202 Accepted	0003	회수 요청 접수

오류 코드

오류는 HTTP 상태 코드로 1차 분류되며, 응답 본문의 code 필드로 세부 사유를 확인할 수 있습니다. 예외 처리 시 두 값을 함께 확인하시기 바랍니다.

HTTP 상태 코드	code	발생 이유	해결 방법
400 Bad Request	1400	요청 파라미터·본문 형식 오류 또는 비즈니스 규칙 위반 (필수값 누락, 잘못된 JSON 등)	응답 message 와 요청 형식·필수 파라미터를 확인한 후 재요청하시기 바랍니다.
401 Unauthorized	1401	X-API-Key 헤더 누락 또는 무효한 키	발급받은 유효한 API Key를 헤더에 포함하여 요청하시기 바랍니다.
403 Forbidden	1403	유효한 계약 없음(계약 만료·비활성) 또는 허용되지 않은 IP에서의 요청	서비스 계약 상태와 허용 IP 목록을 확인하시기 바랍니다.
404 Not Found	1404	대상 리소스 미존재	요청한 식별자(ID) 값이 올바른지 확인하시기 바랍니다.
409 Conflict	1409	요청 충돌 (중복 등)	응답 message 를 확인하여 조건에 맞게 재요청하시기 바랍니다.
422 Unprocessable Entity	1422	발급 한도 초과 등 처리 불가	잔여 발급 한도와 계약 상태를 확인한 후 재요청하시기 바랍니다.
429 Too Many Requests	1429	요청 수 제한(Rate Limit) 초과	응답 헤더의 Retry-After 에 명시된 시간(초)만큼 대기한 후 재시도하시기 바랍니다.
500 Internal Server Error	1500	서버 오류	잠시 후 재시도하시고, 반복될 경우 고객센터로 문의하시기 바랍니다.

오류 응답 예시

오류 발생 시에도 응답은 공통 형식을 따릅니다. code 에 에러 코드, message 에 오류 메시지가 담기며 data 는 null 입니다.

{
  "code": "1400",
  "message": "필수 파라미터가 누락되었습니다.",
  "data": null
}