본문바로가기

테크 가이드

개발자를 위한 API 연동 첫날 핵심 점검 가이드

김도용
· 2026.11.17

1. API 연동 사전 점검의 필요성 및 개요

시스템 간 API 연동 과정에서 개발자가 소스 코드를 작성하기에 앞서 최우선으로 검증해야 할 핵심 요소를 다룹니다. 

신규 API 연동 초기 단계에서  인증 키 관리 ,  테스트 환경 구성 ,  호출 한도 및 제어 메커니즘  등 세 가지 기반 요소를 명확히 정의하지 않고 개발을 진행할 경우, 검증 과정이나 운영 전환 직전에 키 불일치, 요청 차단, 데이터 누락 등 심각한 장애가 복합적으로 발생할 위험이 커집니다.

인포텍 API 공통 가이드 기준에 따르면, 전체 서비스는 단일 인프라 게이트웨이 엔드포인트를 중심으로 수신되며 기관 코드(orgCd)와 서비스 코드(svcCd)의 조합으로 각 비즈니스 업무를 식별합니다. 

따라서 연동 첫날 공통가이드 규격을 정교하게 정립해 두면, 향후 신규 서비스 추가 시에도 동일한 아키텍처와 오류 처리 파이프라인을 재활용할 수 있어 개발 생산성과 운영 안정성을 동시에 확보할 수 있습니다. 본 보고서는 담당 개발자가 연동 시작 30분 이내에 점검하고 구현해야 할 기술 사양과 보안 체계를 상세히 분석합니다.

2. 인증 키(API Cloud Key) 관리 및 보안 가이드

2.1. 인증 헤더 구조 및 발급 체계

인포텍 API 서비스의 모든 요청은 HTTP 요청 헤더에 포함되는 api-cloud-key 하나로 인증을 수행합니다. 연동 첫날 수령하는 키는 테스트 목적의 **개발 키(Dev Key)**이며, 실제 운영 환경에서 사용하는 **운영 키(Prod Key)**는 서비스 오픈 승인 시점에 별도로 발급됩니다.

최초 테스트를 수행할 때 구성해야 하는 HTTP 표준 요청 명세는 다음과 같습니다.


// POST /api/service

// Header: Content-Type: application/json

// Header: api-cloud-key: {발급받은 개발 키}

 

{

  "reqCd": "UUID20200716000001",

  "affix": "userno000001",

  "appCd": "infotech-api",

  "orgCd": "gov",

  "svcCd": "B7001"

}

 


2.2. 보안 권장 사항 및 키 수명주기 관리

API 키 유출은 시스템 전체의 보안 침해로 직결되므로, 연동 첫날 다음과 같은 보안 가이드라인을 엄격히 적용해야 합니다.


●     키 성격 재확인 : 발급받은 키가 개발 키인지 운영 키인지 담당자를 통해 명확히 구분 및 확인합니다.

●     HTTP 헤더 전송 원칙 : API 키는 반드시 HTTP 헤더(api-cloud-key)로만 전송해야 합니다. URL 쿼리 파라미터로 전송할 경우 웹 서버, 프록시, API 게이트웨이의 접근 로그에 그대로 노출될 위험이 존재합니다. 이는 OWASP REST Security Cheat Sheet의 핵심 권고 사항과 일치합니다.

●     소스코드 하드코딩 금지 : 소스코드 내부 문자열 형태로 키를 직접 입력하는 방식은 금지됩니다. Java 샘플 코드 등에 명시된 하드코딩 방식은 형상 관리 저장소(Git 등)에 키가 그대로 노출되는 사고를 유발합니다.

●     시크릿 매니저(Secrets Manager) 활용 : 보안 강화를 위해 API 키는 AWS Secrets Manager, HashiCorp Vault 등 전용 시크릿 관리 시스템에 보관하는 것을 최우선으로 합니다. 환경 변수는 다른 프로세스 탐색, 시스템 로그, 크래시 덤프 등을 통해 유출될 가능성이 있으므로 전용 시크릿 관리가 불가능한 경우에만 제한적으로 사용합니다. (OWASP Secrets Management Cheat Sheet 참조)

●     환경별 설정 분리 : 개발 환경과 운영 환경의 설정 이름을 엄격히 분리합니다 (예: IFT_API_KEY_DEV, IFT_API_KEY_PROD).

●     서버 간(Server-to-Server) 호출 구조 준수 : API 키는 반드시 서버 측 백엔드에서만 사용해야 합니다. 클라이언트 앱이나 웹 브라우저 JavaScript 코드에 키를 매베딩하지 않고, 자사 백엔드 서버가 인증 키를 결합하여 외부 API를 호출하는 아키텍처를 유지합니다. 이는 Google Cloud의 API 키 관리 모범 사례에 부합합니다.

●     키 폐기 및 교체 절차 마련 : 키 유출 의심 시 즉시 담당자에게 폐기 및 재발급을 요청할 수 있는 비상 연락 채널을 확인하고, 정기적인 키 로테이션 절차를 수립합니다.


2.3. 인증 관련 주요 오류 응답 코드 분석

응답 코드,오류 의미,주요 발생 원인 및 첫날 점검 사항

K001,헤더에 API KEY 미포함,"HTTP 헤더 이름 오타(api-cloud-key), 방화벽이나 중간 프록시 장비의 헤더 필터링 여부 확인"

K002,유효하지 않은 API KEY,"개발 키와 운영 키의 혼용, 키 문자열 복사 시 불필요한 공백이나 줄바꿈(`"

`) 포함 여부 확인,,

V008,약정되지 않은 서비스 요청 (운영 키),계약 및 신청된 기관 코드(orgCd) 및 서비스 코드(svcCd)와 실제 요청 바디 값이 일치하는지 확인

3. 테스트 환경 설정 및 검증 체계

3.1. 게이트웨이 환경 및 설정 분리

인포텍 API는 개발 환경과 운영 환경이 동일한 게이트웨이 엔드포인트를 공유합니다. 환경의 구별은 요청 헤더에 전달되는 api-cloud-key에 의해 결정됩니다. 따라서 애플리케이션 아키텍처 구성 시 키 교체 단 한 줄의 설정 변경만으로 운영 전환이 가능하도록 환경 분리 설계를 진행해야 합니다.

애플리케이션 구현 시 필수적으로 포함해야 하는 요청 식별 파라미터는 다음과 같습니다.


●     reqCd (거래 고유값): 요청마다 고유한 비즈니스 트랜잭션 ID를 부여하며, 추적성을 위해 UUID 형태의 생성을 권장합니다.

●     affix (최종 사용자 구분값): 시스템을 이용하는 최종 사용자나 서비스 계정을 식별하기 위한 파라미터입니다.

●     appCd (애플리케이션 코드): 호출을 수행하는 시스템 및 앱의 명칭을 식별할 수 있도록 부여합니다 (예: companyname-api).

●     orgCd / svcCd (기관 및 서비스 코드): 서비스정의서에 명시된 대상 기관 및 세부 서비스 코드를 입력합니다.

●     데이터 인코딩: 모든 요청과 응답은 UTF-8 인코딩의 JSON 형식을 사용하며, HTTP 헤더에 Content-Type: application/json을 명시해야 합니다.


3.2. 2단계 성공 판정 체계

API 호출 후 결과 수신 시 단순 HTTP 상태 코드(HTTP 200 OK)만으로 성공 여부를 판단하면 내부 비즈니스 처리 오류를 누락하게 됩니다. 반드시 다음의 2단계 검증 로직을 거쳐야 합니다.

  1. 1단계:  resCd  통신 성공 여부 확인 : 응답 바디의 resCd 값이 0000인지 확인합니다. 이 값은 API 게이트웨이와의 네트워크 통신 및 기본 제어 검증이 정상 완료되었음을 의미합니다.
  2. 2단계:  out.errYn  비즈니스 처리 성공 여부 확인 : 응답 데이터 내부 out.errYn 값이 N인지 검증합니다. 만약 Y인 경우 대상 기관 연동이나 실제 데이터 수집 과정에서 오류가 발생한 것이므로 out.errMsg에 담긴 세부 사유를 확인해야 합니다.

3.3. 주요 입력 및 요청 오류 응답 코드

연동 초기 단계에서 빈번히 발생하는 입력 오류는 모두 클라이언트 측 요청 명세를 수정하여 재요청해야 하는 항목들입니다. 동일한 요청을 수정 없이 재시도할 경우 동일한 실패가 반복됩니다.

응답 코드,오류 의미,주요 원인 및 조치 방안

V001,Content-Type 미적용,HTTP Header에 application/json이 아닌 x-www-form-urlencoded 등 기본 폼 전송 방식 사용

V002,유효하지 않은 JSON 규격,"문자열 연산으로 JSON을 직접 생성할 때 따옴표, 쉼표 등 문법 누락 (JSON 라이브러리 사용 권장)"

V003,요청 본문(Body) 누락,HTTP GET 메서드로 호출하거나 POST 요청 시 페이로드를 전달하지 않은 경우

V005 / V006,orgCd / svcCd 누락,필수 파라미터 누락 또는 JSON 키 이름의 대소문자 오타

E101 / E102,수집 결과 NULL / 공백,"업무별 필수 입력값 누락, 또는 대상 기관 측에 조회가 가능한 데이터가 존재하지 않는 경우"

E999,알 수 없는 시스템 오류,"예외적 오류 발생 시점으로, 해당 요청의 reqCd와 호출 시각 로그를 수집하여 기술 지원 문의"

주의사항 : API 공통가이드에서는 게이트웨이 영역의 오류 코드와 세부 수집 서버 영역의 오류 코드를 독립적으로 정의하고 있습니다. 이에 따라 동일한 코드(예: V001)라 하더라도 발생 경로에 따라 세부 의미가 다를 수 있으므로, 로그 저장 시 코드값과 함께 resMsg 및 errMsg 원문을 반드시 함께 기록해야 합니다.

4. 호출 한도 관리, 타임아웃 및 재시도 메커니즘

4.1. 호출 한도(Rate Limit) 제어 및 관리

개발 키에는 기본적으로 요청 횟수 제한이 설정되어 있으며, 이를 초과할 경우 V007(요청제한 횟수 초과) 응답 코드가 반환됩니다. 운영 환경의 호출 한도는 고정된 스펙이 아니며, 서비스 계약 단계에서 사전 협의하여 결정됩니다.


●     호출량 사전 산정 : 연동 첫날 일 평균 및 피크 시간대 예상 트래픽을 산정하여 계약 한도를 확인하고, 개발 키에 부여된 쿼터 한도를 숫자로 파악해 두어야 합니다.

●     부하 테스트 금지 : 개발 키를 대상으로 부하 테스트를 수행해서는 안 됩니다. 단위 테스트는 미리 저장된 Mock 응답 데이터를 활용하고 실제 API 호출은 필요한 최소 수준으로 제한합니다.

●     프록시 이용 협의 : 대량 트래픽 처리가 필요한 업무의 경우 proxyUseYn(프록시 서비스 이용 여부, 기본값 Y) 옵션 활용을 사전 협의합니다.

●     한도 초과 판단 : 범용 HTTP 재시도 라이브러리는 HTTP 429(Too Many Requests) 상태 코드만을 감지하는 경우가 많으나, 본 가이드 체계에서는 응답 바디 내부의 resCd가 V007인지를 직접 검증해야 합니다.

●     표준 스펙 참조 : RFC 6585 표준에 따른 HTTP 429 응답 시 서버는 Retry-After 헤더를 통해 대기 시간을 초(Seconds) 또는 HTTP 날짜 형식으로 전달할 수 있으며(MDN 명세), IETF Draft-11 단계의 RateLimit 헤더 규격도 업계 표준으로 논의되고 있습니다.


4.2. 연결 및 읽기 타임아웃(Timeout) 분리 설정

스크래핑 기반 API는 내부적으로 대상 기관과의 통신 및 결과 집계를 거치므로 일반 REST API에 비해 응답 지연이 길어질 수 있습니다. 따라서 타임아웃 설정 시 연결(Connection)과 읽기(Read) 타임아웃을 반드시 분리하여 설정해야 합니다.


●     연결 타임아웃(Connection Timeout) : 네트워크 핸드셰이크 지연을 방지하기 위해 3초 수준으로 짧게 설정합니다 (Java 샘플 가이드 기준).

●     읽기 타임아웃(Read Timeout) : 모든 원격 호출에는 읽기 타임아웃이 필수적으로 지정되어야 합니다 (AWS Builders' Library 권고). 업무별 실측 응답 시간에 충분한 여유를 더해 설정합니다 (Java 샘플 주석 기준 600초/10분 예시 참조).

●     실측 데이터 수집 : 연동 첫날 모든 호출 응답의 reqTm(요청 시각)과 resTm(응답 시각)을 로그에 기록하여 실제 응답 속도 데이터를 체계적으로 수집합니다.


4.3. 코드별 차등 재시도(Retry) 전략

모든 오류에 대해 무조건 재시도를 수행할 경우 한도가 빠르게 소진되고 시스템 부하를 가중시킵니다. 오류의 성격에 따라 차등적인 재시도 전략을 수립해야 합니다.


[API 오류 발생]

   │

   ├─► [인증/입력/계약 오류] (K001, K002, V001~V006, V008) ──► 재시도 금지 (요청 수정 필요)

   ├─► [호출 한도 초과] (V007) ──────────────────────────► 호출 즉시 중단 (한도 리셋 대기)

   ├─► [업무 대기 오류] (E201, E203) ─────────────────────► 대기 시간 충족 후 재요청

   └─► [일시적 서버/네트워크 오류] (E901~E903, C021) ──────► 지수 백오프 기반 재시도 적용

 

재시도 대응 분류표

오류 응답 코드,세부 의미,대응 및 재시도 전략

"K001, K002, V001~V006, V008","인증, 입력 값, 계약 미약정 오류",재시도 금지 . 요청 파라미터나 키 설정을 수정 후 호출

V007,요청 제한 횟수 초과,호출 중단 . 한도 초기화 시점까지 추가 호출 차단

E201,동일 계정 이미 수집 중,"동일 계정에 대한 동시 요청을 제거하고, 선행 요청 처리 완료 후 재시도"

E203,여신금융협회 수집 대기시간 남음,응답 메시지(resMsg)에 명시된 수집 가능 시각 이후에 재요청

"E901, E902, E903","수집 가능 서버 없음, 워커 접속 불가",지수 백오프(Exponential Backoff)  및 횟수 제한을 두어 재시도

C021,인증서 풀(Pool) 모두 사용 중,지수 백오프  및 횟수 제한을 두어 재시도

탄력적 재시도 아키텍처 수칙 (AWS Builders' Library)
  1. 지수 백오프 및 지터(Jitter) 적용 : 재시도 간격을 지수적으로 증가시키고(예: 1초 → 2초 → 4초), 무작위 변동치(Jitter)를 추가하여 여러 클라이언트가 동시에 재요청하여 발생하는 동시성 폭주(Thundering Herd Problem)를 방지합니다.
  2. 재시도 상한 및 단일 계층 처리 : 최대 재시도 횟수(예: 3회)를 제한하고, 마이크로서비스 아키텍처 다단 호출 경로 중 단 하나의 계층에서만 재시도를 수행합니다. (5단계 호출 경로에서 계층마다 3회씩 재시도할 경우 최하위 시스템 부하는  $3^5 = 243$ 배로 증폭됨)
  3. 비멱등성 작업의 자동 재시도 금지 : 신청, 결제, 구매 등 원상복구가 불가능한 비멱등성 서비스는 타임아웃 발생 시 자동 재시도를 수행하지 않습니다. 반드시 reqCd를 활용하여 이전 요청의 실제 처리 여부를 우선 조회한 후 후속 조치를 결정합니다.

5. API 연동 첫날 최종 점검 체크리스트

다음 9가지 핵심 항목에 대해 검증을 완료하면 API 연동 첫날의 필수 기본 설정 및 보안 점검이 완성됩니다.

인증 키 관리

✔     발급받은 키의 구분이 개발 키(Dev Key)임을 담당자를 통해 확인 완료했는가?

✔     API 키를 소스코드 및 저장소 외부(시크릿 매니저 등)에 보관하고 환경별 설정 명칭을 분리했는가?

✔     HTTP 헤더의 api-cloud-key 항목을 통해 최초 테스트 호출에 성공했는가?

테스트 환경 구성

✔     인증 키 교체만으로 개발에서 운영 환경으로 전환 가능하도록 설정을 이원화했는가?

✔     모든 요청에 reqCd(UUID), affix, appCd 파라미터를 포함하고 시스템 로그에 남기는가?

✔     응답의 resCd(0000) 및 out.errYn(N) 두 단계를 조합하여 성공 여부를 정확히 판정하는가?

호출 한도 및 운용 제어

✔     계약상 확정한 운영 호출 한도와 개발 키 수량 제한을 수치로 파악했는가?

✔    연결 타임아웃(3초 수준)과 읽기 타임아웃(업무별 실측 기반)을 개별적으로 설정했는가?

✔    오류 코드별 재시도 가능 여부를 분류하고, 지수 백오프와 재시도 상한선을 로직에 반영했는가?

참고 문헌 및 기술 규격 :

●     인포텍 API 공통가이드 (공통부, 응답코드 정의 및 Java Sample)

●     OWASP REST Security Cheat Sheet & Secrets Management Cheat Sheet

●     Google Cloud Best Practices for Managing API Keys

●     RFC 6585 (429 Too Many Requests) & MDN Retry-After Header Specification

●     AWS Builders' Library: Timeouts, retries, and backoff with jitter

 


  • #가이드
  • #API
  • #연동
  • #체크리스트

우리 회사에 맞는 데이터 인프라가 궁금하신가요?

1,000+ 기업이 선택한 인포텍코퍼레이션의 기술력을 직접 경험해보세요.

무료 상담 신청하기