예산 집행 관리 시스템 API 연동 개발 전 반드시 확인해야 할 항목을 정리했습니다. API 명세 확보, 인증 방식, 코드표 매핑, 정합성 검증까지 실패 없는 연동 점검 순서를 단계별로 안내합니다.
- 1단계: 연동 대상별 API 목록·버전 확인과 제공사 협의 절차
- 연동은 기술이 아니라 '서류 싸움'부터 시작됩니다
##
연동 실패의 숫자를 정확히 잴 수는 없지만, 현장에서 겪는 실패의 대부분은 코드가 아니라 순서에서 나옵니다. 개발이 막바지에 이른 뒤 첫 연동 테스트에서 상대 예산 시스템의 계정과목 코드표가 우리 쪽 분류 체계와 다르다는 걸 발견하는 장면을 상상해 보세요. 이미 짜둔 집행 내역 전송 로직을 처음부터 다시 짜야 하고, 견적과 일정은 그대로 깨집니다.
- API 명세: 요청·응답 필드 정의서를 파일로 받았는가
- 버전: 연동 대상 API의 버전과 변경 이력
- 인증 방식: 키·토큰 발급 절차와 만료 주기
- 코드표: 예산과목·집행 구분 코드의 매핑 기준
이 중 하나라도 "나중에 알려드릴게요" 상태로 개발에 들어가면, 그때까지 짠 코드는 전부 가정 위에 서 있게 됩니다. 그래서 순서를 지켜야 합니다.
목업(모의 응답) 환경 없이 개발에 들어가면, 연동 단계에서 재작업이 아니라 사실상 재개발이 시작됩니다.
1단계: 연동 대상별 API 목록·버전 확인과 제공사 협의 절차
연동은 기술이 아니라 '서류 싸움'부터 시작됩니다
개발자를 앉혀놓고 "이제 API 붙여보자"고 하면 열에 아홉은 막힙니다. 붙일 API가 문서로 존재하는지, 우리 회사가 쓸 자격이 있는지, 담당자가 누구인지가 먼저 결정되기 때문이에요. 예산 집행 관리 시스템은 ERP·회계·인사·전자결재까지 여러 시스템을 한 번에 붙이는 구조라, 이 1단계에서 놓치면 뒤에서 전부 재작업이 됩니다.
실제 구축 사례를 보면 이게 체감됩니다. 비오케이솔루션이 운영한 racekra는 KRA 오픈 API를, NCS Passport는 Work24 공공 API를 연동했는데, 두 건은 요구하는 신청 절차와 검증 방식이 각각 달랐습니다. 같은 '공공 API'여도 제공사 기관마다 문턱이 다르니, "공공 API는 이렇게 하는 거다"라는 통일된 매뉴얼은 없다고 보는 게 정확해요. 그래서 연동 대상 시스템별로 아래 표처럼 갈라서 접근해야 합니다.
2단계: 인증 방식·발급 절차와 코드표 매핑, 정합성 맞춤 전략
인증과 코드표는 API 연동 프로젝트에서 개발 도중에 가장 자주 터지는 지점이에요. 스펙 문서는 다 정리됐는데 막상 연동 테스트에서 "토큰이 만료됐다", "부서코드가 매칭이 안 된다"는 메시지를 만나면 일정이 순식간에 밀립니다. 그래서 이 단계에서는 인증과 코드 매핑을 한 세트로 점검하는 게 좋습니다.
인증 방식별로 관리 포인트가 다르다
| 항목 | API키 | OAuth2 | 공인인증서 |
|---|---|---|---|
| 발급 절차 | 담당자 요청 후 키 수령 | 클라이언트 등록 후 토큰 발급 | 사설/공동 인증서 설치·등록 |
| 유효기간 | 발급처 정책에 따라 상이 | 액세스·리프레시 토큰 만료 주기별 갱신 | 만료일 도래 전 갱신 필요 |
| 갱신 실패 시 영향 | 호출 전면 차단 | 자동 재발급 로직 없으면 장애 | 전송 자체가 불가 |
여기서 실수하기 쉬운 건 "발급만 하고 갱신 관리는 안 하는" 경우예요. 특히 토큰 만료 주기와 갱신 자동화 여부는 개발 착수 전에 반드시 상대 시스템 담당자와 확인하세요. 만료 시점에 운영자가 수동으로 재발급하는 구조라면, 그 업무가 누구 몫인지까지 문서로 남겨야 합니다.
3단계: 트래픽 제한·배치 설계와 실패 대응, 보안·감사 요건
3단계: 트래픽 제한·배치 설계와 실패 대응, 보안·감사 요건
연동 개발에서 가장 늦게 발견하고 가장 크게 터지는 게 바로 이 단계다. 기능은 다 만들었는데, 막상 운영 시점에 API 호출 제한에 걸려서 참가자 신청 데이터가 밀리고, 결제 내역과 신청 내역이 어긋나는 상황이 생긴다. 개발 착수 전에 이 세 가지를 먼저 정해두자.
시간당 쿼터 확인과 배치 설계
API 제공처마다 시간당 호출 가능 횟수(쿼터)가 다르다. 이 숫자를 모르고 개발을 시작하면, 행사 신청이 몰리는 시점에 정확히 막힌다. 그래서 설계는 "실시간 호출"부터가 아니라 배치 처리 시간 계산부터 해야 한다.
-
- 이 소요 시간이 쿼터 회복 주기 안에 들어가는지 확인
- 신청 마감 직전처럼 트래픽이 집중되는 시간대를 역산해서 배치 주기 배치
예컨대 학회 홈페이지 구축 자체도 표준 기준 약 4~6주, 커스텀 요건이 붙으면 6~10주가 일반적이다. API 연동이 여기에 얹히는 일이라면, 배치 설계 논의를 구축 일정 앞단에 넣어야 나중에 일정을 다시 짜는 일이 없다.
실패했을 때의 재시도 정책
API 연동 전 최종 체크리스트와 전문 개발사 활용 판단 기준
지금까지 확인한 내용을 한 장의 점검표로 만들어 두면, 개발 착수 후에 "그걸 미리 안 물어봤네" 하는 순간을 크게 줄일 수 있습니다. 실제로 API 연동이 꼬이는 지점은 코드가 아니라 연동 전 계약·설계 단계에서 못 정한 항목들이거든요.
개발 전날 반드시 체크할 7가지
- API 명세 확보 — 예산과목·집행 내역 조회에 필요한 엔드포인트, 요청·응답 필드, 에러 코드 문서를 받았는가
- 인증 정보 발급 — API 키, 토큰 발급 절차와 유효기간, 갱신 주기를 담당자와 확인했는가
- 코드 매핑표 작성 — 우리 회계 코드와 API 응답 코드의 대응 관계를 표로 정리했는가
- 쿼터·호출 제한 확인 — 일 단위 호출 한도가 있는지, 초과 시 응답이 어떻게 오는지 물었는가
- 재시도 정책 정의 — 타임아웃, 일시 오류 시 재시도 횟수, 실패 건의 재처리 방식을 정했는가
- 보안·감사 요건 — 전송 구간 암호화(SSL), 접속 로그 보존 기준, 데이터 파기 시점을 점검했는가
- 외부 유료 API 비용 분리 — 구독료와 별도로 청구되는 API 사용료를 예산에 반영했는가