외부 API 연동 실무 체크리스트: 준비물·심사·호출 상한

외부 서비스를 붙이는 작업은 코드보다 행정에 시간이 더 든다. 견적서에 한 줄로 적히는 "API 연동"이 실제로는 키 발급, 도메인 등록, 심사, 예외 처리, 운영 점검까지 다섯 덩어리로 나뉘기 때문이다. 이 글은 연동 유형별로 무엇을 준비해야 하고 어디서 일정이 새는지 정리한다.

---

연동 유형별 준비물 대조표

---

| 유형 | 준비물 | 심사 여부 | 일정을 늦추는 지점 |
|---|---|---|---|
| 소셜 로그인 | 개발자 계정, 실서비스 도메인, 동의항목 정의 | 민감 항목은 별도 검수 | 받을 정보를 과하게 요구해 검수가 길어짐 |
| 결제 | 사업자등록증, 통신판매업 신고증, 정산 계좌 | 사업자 심사 필수 | 심사 완료 전 실거래 키가 안 나옴 |
| 지도·주소 | 개발자 키, 도메인 등록 | 대체로 자동승인 | 호출량 초과 시 과금 또는 차단 |
| 공공데이터 | 활용신청, 인증키 | 자동승인/심의승인으로 갈림 | 심의는 승인까지 며칠 대기 |
| 알림톡·문자 | 발신번호 등록, 템플릿 승인 | 템플릿 검수 | 문구를 바꾸면 다시 검수 |

표의 오른쪽 열이 핵심이다. 개발이 아니라 승인·검수가 오픈일을 정한다.

---

키 관리 원칙

---

연동에서 사고가 나는 자리는 대부분 키다.

• 시크릿 키는 코드에 넣지 않는다. 서버 환경변수로 분리하고 저장소에 커밋하지 않는다.
• 개발용 키와 실서비스용 키를 분리한다. 테스트 결제가 실거래로 나가는 사고를 막는다.
• 앱은 반드시 발주자(대표자·법인) 명의 계정으로 등록한다. 개발사 개인 계정으로 등록하면 업체 교체 시 서비스가 통째로 멈춘다.
• 유출 시 재발급 절차를 미리 확인해 둔다. 키를 갈아 끼우면 배포가 한 번 더 필요하다.

---

호출 상한을 계산하는 습관

---

외부 API는 무제한이 아니다. 예를 들어 공공데이터포털은 개발계정에 하루 평균 1,000건, 운영계정에 하루 최대 10만 건의 트래픽을 준다. 활용신청도 자동승인과 심의승인으로 나뉘고 심의승인은 신청 후 2~3일이 걸린다.

그래서 기획 단계에서 이 계산을 한 번 해 두는 게 좋다. 하루 방문자 수 × 한 사람이 그 기능을 쓰는 횟수 = 하루 호출량. 여기에 여유를 두 배쯤 얹어 상한과 비교한다. 상한에 걸리는 순간 그날의 그 기능은 죽는다. 이벤트나 광고 집행처럼 트래픽이 튀는 날을 기준으로 잡아야 한다.

---

계약서에 넣을 한 줄

---

외부 API는 우리가 통제하지 못하는 구간이 있다. 상대 서버 장애, 사업자 심사 반려, 규격 변경은 개발사가 손쓸 수 없다. 그래서 계약서에 다음 취지의 문장을 한 줄 넣어 두면 분쟁이 줄어든다. 외부 서비스의 장애·심사 지연으로 발생한 일정 지연은 개발사 귀책이 아니며, 규격 변경에 따른 수정은 유지보수 범위로 처리한다.

---

Q. 직접 개발과 API 연동, 어느 쪽이 싼가요?
A. 초기 비용은 연동이 압도적으로 싸다. 대신 호출량이나 건당 수수료가 계속 나가고 일정 통제권을 상대에게 넘긴다. 우리 사업의 차별점이 아닌 기능(로그인·지도·결제)은 연동이 맞고, 손님이 우리를 고르는 이유가 되는 기능은 직접 만드는 게 맞다.

Q. 연동한 기능이 어느 날 갑자기 멈추면 누구 책임인가요?
A. 원인부터 갈라야 한다. 상대 서버 장애나 규격 변경이면 개발사가 예방할 수 없고, 대응 속도만 문제가 된다. 유지보수 계약이 없으면 그 대응조차 별도 비용이 붙으니 계약 시점에 범위를 정해 두는 편이 낫다.

원문: https://nova-lab.dev/r/t/what-is-an-api

---

자주 묻는 질문

---

Q. API 연동은 이미 만들어진 기능을 쓰는 건데 왜 비용이 드나요?

붙이는 코드 자체는 짧습니다.

시간을 잡아먹는 건 앱 등록과 키 발급, 동의항목 검수, 그리고 토큰 만료나 동의 거절 같은 예외 처리입니다.

결제처럼 사업자 심사가 필요한 연동은 개발이 끝나도 심사가 끝나야 실거래를 열 수 있습니다.

 

Q. 외부 API를 쓰면 우리 마음대로 기능을 바꿀 수 있나요?

없습니다.

무엇을 요청할 수 있고 무엇이 돌아오는지는 상대가 정합니다.

상대가 열어 주지 않은 정보는 가져올 방법이 없고, 상대가 규격을 바꾸면 우리 쪽 코드도 따라 고쳐야 합니다.

 

Q. 발주자가 미리 준비하면 좋은 것은 무엇인가요?

사업자등록증과 통신판매업 신고증, 대표자나 회사 명의 계정, 실제로 쓸 도메인을 먼저 준비해 두면 연동 일정이 며칠씩 당겨집니다.

특히 앱은 개발사 개인 계정이 아니라 발주자 명의 계정으로 등록해야 나중에 업체를 바꿔도 로그인이 살아 있습니다.

글 · 노바랩 NovaLab · https://nova-lab.dev