API란 무엇인가, 견적서 속 연동 항목의 정체

API는 프로그램끼리 주고받는 주문서 양식이다. 손님이 주방에 들어가는 대신 주문서를 넘기듯, 내 사이트도 카카오나 결제사의 속을 들여다보지 않고 정해진 형식으로 요청을 넣어 답을 받는다. 견적서에 적힌 "카카오 로그인 연동", "결제 연동" 한 줄이 이 주문서를 주고받는 작업이다.

핵심 요약

• API는 남의 시스템에 요청을 보내는 정해진 창구다. 무엇을 물어볼 수 있고 무엇이 돌아오는지는 상대가 미리 정해 둔다.
• 견적서의 "API 연동"은 키 발급부터 도메인 등록, 화면 연결, 오류 처리, 운영 중 점검까지 딸려 오는 작업 묶음이다.
• 남의 API를 쓰면 남의 규칙도 따라온다. 호출 횟수 상한과 승인 심사가 우리 일정에 그대로 얹힌다.
• 발주자가 사업자 정보와 계정을 미리 챙겨 두면 연동 일정이 며칠씩 당겨진다.
• 연동이 막히는 원인은 대체로 코드가 아니라 설정과 심사다. 계약 때 책임 경계를 적어 두는 편이 낫다.

API는 주방에 넣는 주문서다

식당에서 손님은 주방에 들어가지 않는다. 메뉴판에 적힌 것 중에서 고르고 주문서를 넘기면 완성된 접시가 나온다. 주방이 어떤 팬을 쓰는지는 알 필요가 없다. API도 마찬가지다. 카카오는 "인가 코드를 이 주소로 보내면 토큰을 내주겠다"는 메뉴판을 공개해 둔다. 내 사이트는 그 형식에 맞춰 요청만 보낸다. 카카오 서버 안에서 무슨 일이 벌어지는지는 알 필요도 없고 알 수도 없다.

메뉴판을 정하는 쪽은 상대다. 없는 메뉴는 주문할 수 없다. 카카오가 열어 주지 않은 정보는 아무리 필요해도 가져올 방법이 없다. 상대가 메뉴 구성을 바꾸면 내 주문서도 따라 고쳐야 한다. 사이트가 화면·처리·저장 세 층으로 나뉜다는 이야기를 웹사이트 구조 편에서 했는데, API는 그 처리 층이 바깥 회사의 서버와 이야기하는 통로다. 서버라는 말이 아직 낯설다면 서버란 무엇인가를 먼저 보면 이해가 빠르다.

"카카오 로그인 연동" 한 줄에 실제로 들어 있는 일

견적서에는 한 줄이다. 그 안에 든 작업은 여러 개다. 카카오 로그인 REST API 공식 문서를 보면 연동에 REST API 키, 카카오 로그인 활성화, 리다이렉트 URI, 동의항목, 클라이언트 시크릿이 필요하다. 동작도 한 번의 호출로 끝나지 않는다. 사용자를 카카오 화면으로 보내 인가 코드를 받고 그 코드로 토큰을 발급받은 뒤 토큰을 들고 사용자 정보를 조회하는 세 걸음을 거친다.

1. 개발자 콘솔에 앱을 등록하고 키를 발급받는다. 사업자 정보나 서비스 설명을 요구하기도 한다.
2. 돌아올 주소(리다이렉트 URI)를 등록한다. 실서비스 주소와 테스트 주소를 각각 넣어야 한다.
3. 어떤 정보를 받을지 동의항목을 설정한다. 이메일처럼 민감한 항목은 별도 검수를 거치기도 한다.
4. 내 사이트에 로그인 버튼을 붙이고 인가 코드와 토큰이 오가는 흐름을 구현한다.
5. 토큰 만료, 동의 거절, 이미 가입된 이메일 같은 예외를 처리한다. 실제 개발 시간의 절반이 여기서 나간다.
6. 시크릿 키를 코드에 박지 않고 서버 설정에 숨긴다. 유출되면 남이 내 이름으로 요청을 보낸다.

연동은 "붙였다"로 끝나지 않는다. 예외까지 막았을 때 끝난다. 견적을 볼 때 "로그인 연동 포함"이라는 문구만 믿지 말고 오류 화면과 재시도까지 범위에 들어가는지 물어봐야 하는 이유다.

남의 API를 쓰면 남의 규칙도 따라온다

직접 만드는 기능은 우리가 일정을 쥔다. 외부 API는 상대의 승인과 상한이 일정에 얹힌다. 공공데이터포털 이용가이드를 보면 이 구조가 잘 드러난다. 활용신청은 자동승인과 심의승인으로 나뉘고 심의승인은 신청 후 2~3일이 걸린다. 계정도 개발계정은 하루 평균 1,000건, 운영계정은 하루 최대 10만 건으로 트래픽이 정해져 있다. 손님이 몰려 호출이 상한을 넘으면 그날은 데이터가 안 나온다.

비교 항목	직접 만드는 기능	외부 API 연동
개발 시간	길다. 처음부터 다 짠다	짧다. 다만 설정과 심사가 붙는다
일정 통제	우리 손에 있다	상대 심사 일정에 묶인다
비용 구조	초기 개발비가 크다	호출량·건당 수수료가 계속 나간다
고장 났을 때	우리가 고친다	상대가 복구할 때까지 기다린다
바뀔 때	우리가 결정한다	상대 공지에 맞춰 우리가 고친다

그래도 로그인·결제·지도처럼 남이 훨씬 잘 만들어 둔 기능은 연동이 정답이다. 직접 만들면 보안과 유지보수 부담이 통째로 넘어온다. 기준은 간단하다. 우리 사업의 차별점이 아닌 기능이면 API를 붙이고 손님이 우리를 고르는 이유가 되는 기능이면 직접 만든다.

상담에서 자주 나오는 오해 세 가지

첫째, API 연동은 이미 만들어진 걸 가져다 쓰니 싸고 빠르다는 오해다. 붙이는 코드 자체는 짧다. 시간을 잡아먹는 건 앱 심사, 동의항목 검수, 예외 처리다. 특히 결제는 사업자 심사가 끝나야 실거래 키가 나온다. 개발이 끝나도 며칠은 더 기다린다.

둘째, 한 번 붙이면 계속 돌아간다고들 여긴다. 상대가 규격을 바꾸면 우리 쪽도 고쳐야 한다. 유지보수 계약이 없으면 어느 날 로그인 버튼이 조용히 멈춘다.

셋째, 연동이 안 되면 개발사 잘못이라는 오해다. 상대 서버가 죽었거나 사업자 심사가 반려된 상황이면 개발사가 손쓸 방법이 없다. 계약할 때 외부 API 장애와 심사 지연은 누구 책임인지 한 줄 적어 두면 나중에 다툴 일이 준다.

발주자가 미리 챙기면 일정이 당겨지는 것들

연동 일정은 개발사보다 발주자 손에 달려 있을 때가 많다. 사업자등록증과 통신판매업 신고증, 대표자 명의 계정, 실서비스 도메인은 미리 준비해 둘수록 좋다. 도메인이 없어 심사를 못 넣고 기다리는 일이 흔하다. 계정은 반드시 대표자나 회사 명의로 만든다. 개발사 개인 계정으로 앱을 등록해 두면 나중에 업체를 바꿀 때 로그인이 통째로 막힌다.

상담에서 그대로 물어볼 문장 하나를 남긴다. "이 API 연동에서 심사가 필요한 항목은 무엇이고, 저희가 언제까지 무슨 서류를 드리면 되나요?" 여기에 날짜와 서류 목록으로 답하는 업체라면 일정 관리를 하고 있다고 봐도 된다.

가상 예시를 들어 본다. 원데이 클래스를 파는 B씨는 카카오 로그인과 카드 결제를 넣은 예약 사이트를 맡겼다. 개발은 3주 만에 끝났는데 오픈은 2주가 더 걸렸다. 결제사 사업자 심사가 남아 있었고 도메인을 뒤늦게 사는 바람에 리다이렉트 주소를 다시 등록해야 했다. 두 번째 사이트를 만들 때 B씨는 서류와 도메인을 먼저 준비해 뒀다. 같은 기능을 3주 만에 열었다. 견적서를 읽는 법이 궁금하면 제작 비용 편을, 데이터가 어디에 쌓이는지는 데이터베이스 편을 보면 된다.

어떤 API를 붙여야 할지 판단이 서지 않으면 만들려는 서비스를 적어 문의로 보내 달라. 필요한 연동과 심사 일정을 함께 짚어 준다.