PG·공공기관 API 문서를 OpenAPI 로 옮기는 일

결제·정산 팀이 이 작업을 반복하는 진짜 이유

국내 PG사(KG이니시스, 나이스페이, 토스페이먼츠 등), 금융결제원, 지자체 공공 API, 그리고 ERP(SAP, 더존 등) 연동을 직접 담당해 본 사람이라면 이 풍경이 낯설지 않다. 수십 페이지짜리 연동 규격서를 받아 들고, 병합셀로 뒤엉킨 파라미터 표를 한 줄씩 읽어가며 OpenAPI 스펙 파일을 손으로 옮겨 적는 일. 문서가 PDF면 그나마 낫다. HWP나 Word, 심지어 Excel로 오는 경우도 허다하다.

HEDVION 팀의 경험으로 말하자면, 엔드포인트 2030개짜리 PG 규격서를 OpenAPI 3.1로 옮기는 데 숙련된 개발자 기준으로도 최소 46시간이 소요된다. 공공기관 API처럼 100페이지 이상 규격서가 붙으면 12 man-day가 통으로 날아간다. 연간 35개 벤더를 새로 연동하는 소규모 팀이라면, 이 단순 변환 작업에만 연간 5~10 man-day를 소진하고 있다는 계산이 나온다. 더 나쁜 건, 이게 일회성 비용이 아니라는 점이다. 벤더가 규격서를 업데이트할 때마다 같은 작업이 반복된다.

OpenAPI로는 다 표현되지 않는다 — 그래서 더 위험하다

가장 큰 함정은, 레거시 API 문서에 적힌 내용 중 상당수가 OpenAPI 스키마로 깔끔하게 표현되지 않는다는 데 있다. 구체적으로 세 가지 유형이 문제를 일으킨다. 첫째, 암호화 규칙: 카드번호를 SEED-CBC 또는 ARIA로 암호화한 뒤 Base64로 인코딩해 필드에 담아라. OpenAPI의 format: byte는 이걸 표현할 수 없다. 둘째, HMAC-SHA256 서명: 요청 body + timestamp + nonce를 특정 순서로 이어 붙인 뒤 서명을 헤더에 첨부하라. securitySchemes의 apiKey 타입은 서명 생성 로직 자체를 담지 못한다. 셋째, 에러코드 별첨 처리: 표에는 없고 "별첨 참조" 또는 "담당자 문의"로만 처리된 케이스들.

문제는 많은 자동 변환 도구가 이 부분을 조용히 누락시킨다는 것이다. 스펙은 그럴듯하게 생성되지만, 연동을 시작하면 HMAC 서명이 맞지 않아 401이 터지고, 암호화 방식이 달라 결제가 거부된다. HEDVION 팀이 직접 겪은 사례로, KG이니시스 연동 시 SEED-CBC 암호화 규칙이 자동 생성 스펙에 누락된 상태로 SDK를 뽑았다가 QA 단계에서 카드 승인 요청 전체가 실패한 일이 있었다. 원인 파악까지 반나절, 수정과 재검증까지 추가 반나절 — 자동화로 절약하려던 시간을 고스란히 날렸고, 일정에 버퍼가 없던 상황이라 배포가 하루 밀렸다. 연동 실패의 80% 이상이 암호화·서명·토큰 흐름 세 지점에서 나온다는 게 우리 팀의 경험칙이다.

분할·병합 전략 — 수치로 보는 현실

큰 문서를 LLM으로 한 번에 처리하려 하면 벽에 부딪힌다. 현재 대부분의 LLM API는 출력 토큰 한계(일반적으로 4,096~8,192 토큰)가 있어, 100페이지짜리 규격서를 통째로 입력하면 결과 JSON이 중간에 잘려 엔드포인트가 0개로 나오거나, paths 블록이 열린 채 닫히지 않아 파싱 자체가 실패하는 황당한 상황이 생긴다. 직접 실험해 보면 60페이지 이상 문서에서 이 현상이 재현 가능할 정도로 잦다.

HEDVION의 pdf2api에서 실제로 적용하는 분할 전략은 이렇다. 규격서를 1520페이지 단위로 슬라이싱하되, 경계에 걸친 엔드포인트 누락을 막기 위해 앞뒤 1페이지씩 오버랩을 둔다. 각 청크를 개별 추출한 뒤 HTTP메서드 + 경로 조합을 기준 키로 삼아 중복을 제거하고 병합한다. 실제 처리 사례로, 금융결제원 오픈뱅킹 API 연동 가이드(PDF 약 180페이지)에서 엔드포인트 47개, 공통 스키마 23개를 추출하는 데 걸린 시간은 약 40초였다. 손으로 했다면 1.52 man-day 규모다. 단, 이 전략도 완벽하지 않다. 동일 엔드포인트가 두 청크에 걸쳐 서로 다른 필드 정보를 담고 있을 때, 필드 수가 더 많은 쪽을 우선하는 병합 규칙을 쓰는데, 간혹 deprecated된 필드가 살아남는 경우가 있다. 완벽한 자동화는 없고, 생성된 초안을 반드시 리뷰하는 프로세스를 붙이는 것이 필수다.

'정직한 초안' 원칙 — 누락보다 경고가 낫다

우리가 잡은 핵심 원칙은 단순하다. 표현할 수 있는 건 OpenAPI 3.1로 정확히, 표현할 수 없는 건 버리지 말고 명시적인 경고로 내보낸다. 엔드포인트, 파라미터, 요청/응답 본문처럼 구조화 가능한 정보는 스펙으로 옮기고, SEED 암호화·HMAC 서명 생성 로직·벤더 특화 토큰 흐름처럼 스키마로 담을 수 없는 것들은 x-hedvion-warning 확장 필드로 뽑아낸다.

x-hedvion-warning:
  - type: encryption
    field: card_number
    message: "SEED-CBC 암호화 후 Base64 인코딩 필요. OpenAPI 스키마로 표현 불가. 개발자 직접 구현 필수."
  - type: hmac-signature
    header: X-Signature
    message: "HMAC-SHA256 서명 생성 로직은 별첨 문서 3.2절 참조. 서명 대상: body + timestamp + nonce 순."

이렇게 하면 스펙을 받은 개발자는 "여기서 추가 작업이 필요하다"는 신호를 놓치지 않는다. 실제로 이 경고 필드 덕분에 연동 코드를 처음 작성하는 팀원이 HMAC 구현을 빠뜨리는 실수를 방지한 사례가 있었다. 조용히 누락시키는 것보다 "여기 위험하다"고 짚어주는 쪽이 연동하는 사람 입장에서 훨씬 안전하다. 완벽한 스펙을 흉내 내는 것보다 정직한 초안이 실무에서 더 가치 있다는 게 우리의 결론이다.

HEDVION 팀이라면 이렇게 쓴다 — 실제 적용 시나리오

새 PG사를 추가 연동해야 하는 상황을 구체적으로 가정해 보자. 기존 흐름에서는 담당자에게 규격서 PDF(보통 5080페이지)를 받고, 개발자가 파라미터 표를 보며 OpenAPI YAML을 수작업으로 작성하는 데 35시간, Postman 컬렉션을 별도로 작성하는 데 12시간이 더 들었다. 총 47시간, 여기에 HMAC·암호화 규칙을 놓쳐 QA에서 터지는 디버깅 시간까지 더하면 실질적으로 하루를 넘기는 경우가 잦았다.

pdf2api를 쓰는 현재 흐름은 이렇다. 규격서 PDF를 업로드(1분 이내) → OpenAPI 3.1 초안·Postman 컬렉션·TypeScript SDK 초안 수령(3060초) → 경고 섹션 확인, SEED 암호화·HMAC 서명 등 수동 구현 대상 파악(30분) → 초안 리뷰·누락 수정(12시간) → 연동 코드 작성. 총 소요 시간이 2~3시간으로 줄었고, 경고 섹션 덕분에 "모르고 지나치는" 실수가 눈에 띄게 줄었다. 연동 초기 QA에서 발견되는 서명·암호화 관련 오류가 체감상 절반 이하로 줄었다는 게 팀 내부 평가다. 또 다른 활용은 규격서 버전 관리다. 벤더가 규격서를 업데이트하면 새 버전을 다시 업로드해 생성된 스펙을 이전 버전과 diff하면, 변경된 필드·추가된 엔드포인트·deprecated된 파라미터가 바로 보인다. 수작업 비교로는 놓치기 쉬운 변경사항을 구조적 diff로 잡아낼 수 있다.

바로 써먹을 실행 시사점

지금 손에 PG나 공공기관 API 규격서가 있다면 이 다섯 가지를 순서대로 적용하라.

1. 암호화·서명·토큰 흐름을 먼저 별도 메모로 분리하라. 규격서를 받았을 때 제일 먼저 할 일은 이 세 항목을 찾아 따로 정리해 두는 것이다. 자동화 도구가 누락시키기 가장 쉬운 부분이고, 연동 실패의 대부분이 여기서 나온다.

2. LLM으로 직접 변환한다면 출력 크기를 반드시 제한하라. 전체 규격서를 한 번에 넣지 말고, 10~20페이지 단위로 잘라 처리한 뒤 병합하라. 잘린 JSON은 파싱조차 안 된다.

3. 자동 생성 스펙의 경고 섹션을 반드시 읽어라. 스펙이 그럴듯하게 나왔더라도 경고를 무시하면 401·암호화 오류로 시간을 날린다. 경고가 없는 도구일수록 오히려 의심해야 한다.

4. 생성된 초안은 '검토 대상'으로 취급하라. 완성본이 아니다. 리뷰 없이 프로덕션에 바로 쓰면 반드시 문제가 생긴다. 초안 리뷰 1~2시간이 연동 후 디버깅 반나절을 막는다.

5. 규격서 업데이트 시 diff 루틴을 CI에 붙여라. 변경된 규격서를 재변환해 이전 스펙과 구조적 diff를 뽑는 스크립트를 파이프라인에 연결해 두면, 필드 변경·파라미터 추가를 자동으로 감지할 수 있다. 수작업 비교보다 빠르고 누락이 없다.

지금 손에 지저분한 규격서가 있다면 pdf2api에 던져 보고 경고 섹션이 제대로 잡히는지 확인해 보라. 미리보기는 무료다. 어떤 문서에서 추출 품질이 좋지 않은지 피드백을 주면, 그게 곧 우리 팀의 실제 개선 방향이 된다.