가게끼리 주고받는 창구(API)

외주 견적서와 개발자 말에 계속 나오는 "연동"의 실체예요. 내 서비스가 다른 서비스에 정해진 양식으로 일을 부탁하고 답을 받아 오는 창구를 API라고 불러요.

쉽게 말하면

도매상에 물건을 받을 때 사장님이 창고에 직접 들어가서 상자를 뒤지지는 않죠. 창구에 주문서를 내밀어요. 품목, 수량, 배송지를 그쪽이 정한 칸에 적어서요. 그러면 창구 직원이 안에서 무슨 일이 벌어지는지 설명하지 않고 물건과 명세서만 내줘요. API는 이 창구를 프로그램끼리 쓰는 것이에요. 내 서비스가 결제사 창구에 "이 손님, 3만 원, 카드"라고 적은 쪽지를 내밀면, 결제사가 카드사와 은행 사이 일을 알아서 처리하고 성공인지 실패인지만 답을 줘요.

그래서 API를 배운다는 건 새 기술을 배우는 게 아니에요. 거래처를 쓰는 법을 배우는 것에 가까워요. 어디에 주문서를 내는지, 그 칸에 뭘 적어야 하는지, 답이 안 오면 어떻게 하는지. 사장님이 도매상·배달업체·세무사를 쓸 때 이미 하던 판단이 그대로 옮겨 와요.

창구 없이 하려면

"카드 결제 기능을 밑바닥부터" (카드사·은행 규정까지 내가 전부)

몇 달이 걸리고, 규정 심사도 직접 받고, 고장 나면 새벽에도 내가 고쳐요.

창구에 주문서를 내면

"결제사 창구에 정해진 양식으로" (내가 적는 건 손님·금액·품목)

그 회사가 몇 년 쌓은 기능이 며칠 안에 내 사이트에 들어와요. 대신 쓴 만큼 요금이 나가요.

"연동"이라는 말이 실제로 가리키는 것

사장님이 개발자에게 가장 많이 듣는 말이 "연동"이에요. 그런데 이 말은 너무 넓어서, 그대로 들으면 견적이 왜 그 금액인지 알 수가 없어요. 연동이라고 부르는 일의 실체는 대개 아래 다섯 가지 중 하나예요. 어느 쪽인지만 갈라 물어도 대화가 확 구체적으로 바뀌어요.

듣게 되는 말	실체는 이거예요	사장님이 되물을 것
"결제 연동할게요"	결제사 창구에 주문서를 내고 답을 받는 코드를 붙이는 일	어느 결제사인가요. 수수료율과 정산 주기는요
"지도 연동할게요"	지도 회사 창구에서 지도 조각과 주소 검색 결과를 받아 오는 일	무료 한도가 어디까지고, 넘으면 얼마인가요
"카카오 로그인 연동할게요"	로그인 제공사 창구에 손님 확인을 맡기고 결과만 받는 일	손님 정보 중 무엇을 받나요. 꼭 필요한 것만 받아 주세요
"문자 발송 연동할게요"	문자 회사 창구에 보낼 번호와 내용을 넘기는 일	건당 얼마인가요. 발신번호 등록은 누가 하나요
"저쪽 시스템과 연동할게요"	상대 회사가 열어 준 창구에 맞춰 주문서 양식을 짜는 일	그쪽 연동 문서는 있나요. 담당자 연락은 누가 하나요

마지막 줄이 견적이 가장 크게 흔들리는 칸이에요. 큰 회사의 창구는 문서가 잘 정리돼 있어서 붙이는 데 며칠이면 되지만, 문서가 없거나 담당자에게 물어봐야 하는 창구는 기다리는 시간이 곧 개발 기간이 돼요. "연동 문서 있느냐"는 질문 하나가 견적의 절반을 설명해요.

연동은 기능 이름이 아니에요

"연동 20만 원" 같은 한 줄 견적은 무슨 일을 얼마나 하는지 알 수 없어요. 어느 회사의 창구인지, 주문서 종류가 몇 개인지, 실패했을 때 처리까지 포함인지를 갈라 적어 달라고 하세요. 이건 깎으려는 게 아니라 나중에 서로 다르게 기억하는 걸 막는 일이에요.

주문서에 들어가는 칸은 네 개예요

창구에 내는 주문서는 어느 회사 것이든 구조가 거의 같아요. 칸 네 개예요. 연동 문서를 펼쳤을 때 눈이 어디를 봐야 하는지 알려 주는 게 이 네 칸이에요.

1어느 접수대인지. 창구 하나에도 접수대가 여러 개예요. 주문 넣는 곳, 취소하는 곳, 조회하는 곳이 각각 다른 주소를 갖고 있어요. 문서에서 주소 목록이 길게 나열된 부분이 이거예요.
2출입증. 창구는 아무나 받아 주지 않아요. 가입해서 받은 열쇠 값을 주문서에 같이 얹어야 일을 해 주고, 요금도 그 열쇠 주인에게 달아요. 이 열쇠 이야기는 API 키에서 자세히 다뤄요.
3부탁 내용. 누가, 얼마를, 무엇을. 문서에서 "필수"라고 표시된 칸을 하나라도 비우면 창구가 그냥 거절해요. 사람 직원이라면 되물어 주겠지만 기계 창구는 안 되물어요.
4답장. 성공인지 실패인지, 성공이면 결과가 무엇인지 돌아와요. 이 답장을 받아서 손님 화면에 보여주는 것까지가 한 왕복이에요. 보통 1초에서 2초 안에 끝나요.

여기서 사장님이 꼭 알아야 할 성질이 하나 나와요. 상대가 답을 안 주면 내 화면도 같이 기다려요. 내 코드가 멀쩡해도 거래처가 멈추면 내 기능이 멈춰요. 그래서 연동이 낀 기능에는 "내가 만든 게 아닌 고장"이 생기고, 이 고장은 내 코드를 뒤져도 안 나와요.

답장에 찍히는 숫자 표지판

창구의 답장에는 세 자리 숫자 도장이 찍혀요. 개발자 화면에도 뜨고, 가끔은 손님 화면에도 그대로 새어 나와요. 이 숫자는 코드가 아니라 표지판이라서, 뜻만 알면 사장님도 읽을 수 있어요. 그리고 이 숫자가 누구 탓인지를 절반은 알려 줘요.

숫자	무슨 뜻인가	누구 쪽 사정인가
200	잘 처리됐어요. 정상 답장이에요	문제 없어요
400	주문서에 빠진 칸이나 잘못된 값이 있어요	부탁한 쪽. 내 서비스 문제예요
401 · 403	출입증이 없거나, 그 일을 할 권한이 없어요	부탁한 쪽. 열쇠나 권한 설정 문제예요
404	그런 접수대는 없어요. 주소가 틀렸거나 대상이 사라졌어요	부탁한 쪽. 주소 문제일 때가 많아요
429	너무 자주 왔어요. 한도를 넘었어요	부탁한 쪽. 요금제 한도 문제예요
500 · 503	창구 안쪽이 고장 났거나 잠시 멈췄어요	받는 쪽. 거래처 사정이에요

규칙은 간단해요. 400번대는 내가 낸 주문서 문제, 500번대는 거래처 문제예요. 이것만 알아도 밤새 내 코드를 뒤질 일과 거래처 상태 페이지를 열 일이 갈려요. 숫자를 화면에서 봤다면 그 숫자를 그대로 적어서 AI에게 주세요. 원인을 사장님이 밝힐 필요는 없어요.

500이 떠도 내 사이트가 죽은 건 아니에요

500은 대개 그 기능 하나의 창구가 멈춘 거예요. 지도 창구가 500이면 지도 자리만 비고 나머지 화면은 잘 돌아요. 그래서 연동을 붙일 때 "이 창구가 멈추면 손님이 뭘 보게 되나"를 미리 정해 두는 게 좋아요. 빈 화면 대신 주소 글자라도 나오게 하는 식이에요.

사장님이 실제로 겪는 장면

장면 1 · 외주 개발자가 견적을 설명하며

“결제랑 알림톡은 API 연동이라 금액이 좀 붙어요. 대신 직접 만드는 것보다 훨씬 싸고, 그쪽 요금은 매달 사장님 카드로 따로 나갑니다.”

두 가지 돈을 말한 거예요. 개발비는 나에게 한 번, 창구 요금은 거래처에 매달이에요. 견적서에 둘째 항목이 안 적혀 있으면 반드시 물어보세요. 문 열고 석 달 뒤에 처음 알게 되는 고정비가 여기서 자주 생겨요. 손님 1,000명 기준으로 한 달에 얼마인지 어림해 달라고 하면 대답이 나와요.

장면 2 · 어제까지 되던 지도가 오늘 회색이다

“코드는 아무것도 안 건드렸는데 지도 자리만 비어 있어요.”

내가 뭘 잘못 만진 게 아닐 수 있어요. 코드를 안 건드렸는데 멈췄다면 거래처 쪽 사정일 때가 많아요. 그쪽이 잠깐 멈췄거나, 출입증이 만료됐거나, 무료 한도를 다 썼거나요. 전화를 안 받는 도매상 때문에 내 전화기를 뜯을 필요는 없죠. 그 회사 장애 공지를 먼저 열어 보고, 멀쩡하면 그때 내 쪽을 봐요.

장면 3 · 상대 회사에서 메일이 왔다

“구 버전 API는 다음 달 말에 종료됩니다. 신규 규격으로 전환해 주세요.”

이 메일을 흘리면 그날 기능이 통째로 멈춰요. 창구 양식에도 세대가 있어서, 옛 양식으로 보낸 주문서를 어느 날부터 거절하는 거예요. 이런 메일은 광고가 아니라 통보라서, 받는 즉시 만들어 준 사람이나 AI에게 전달하고 언제까지 고칠지 날짜를 잡아 두세요. 거래처 공지 메일을 스팸함에 두지 않는 게 연동 관리의 절반이에요.

증상 그대로 말하면 돼요

연동이 낀 고장은 증상이 몇 가지로 정해져 있어요. 왼쪽에서 내 증상을 찾아서 오른쪽 문장을 AI에게 그대로 말하면 돼요. 원인 이름을 맞힐 필요는 없어요. 사장님은 보이는 것을 말하고, 원인은 그쪽이 찾아요.

화면에서 보이는 증상	짚이는 곳	이렇게 말하세요
결제 버튼을 누르면 "잠시 후 다시 시도"만 떠요	결제사 창구가 답을 못 주고 있어요	"결제 요청이 실패하면 손님에게 원인을 안내하고 다시 시도 버튼을 보여줘"
지도나 날씨 자리가 비어 있거나 회색이에요	출입증이 없거나 만료됐을 가능성이 커요	"지도 키 설정을 확인하고, 지도가 안 뜰 때는 주소 글자라도 나오게 해줘"
화면에 401이나 403 같은 숫자가 보여요	출입증이나 권한이 안 맞아요	"이 화면에 401이 떠. 키 설정이 맞는지 확인하고 손님에게는 숫자 대신 안내 문구를 보여줘"
손님이 몰리는 시간에만 그 기능이 먹통이에요	창구 호출 한도에 걸린 거예요	"같은 요청 결과를 잠깐 저장해서 다시 쓰게 만들어서 외부 호출 횟수를 줄여줘"
특정 기능 하나만 유난히 오래 돌아요	상대 답장이 늦는 거예요	"외부 요청이 5초 안에 답이 없으면 기다리지 말고 안내 문구를 보여주게 해줘"
어느 날부터 그 기능이 통째로 죽었어요	상대가 창구 양식을 바꿨을 수 있어요	"이 기능이 쓰는 외부 서비스의 변경 공지를 확인하고 새 규격에 맞게 고쳐줘"

내 탓부터 하지 마세요

연동 고장의 절반은 상대 쪽 사정이에요. 규모 있는 회사는 장애 상태를 알리는 페이지를 따로 운영해요. 내 코드를 뒤집기 전에 그쪽 상태부터 열어 보는 습관이 시간을 크게 아껴 줘요. 자주 끊기는 창구가 있다면 시간 초과와 재시도가 다음에 볼 문서예요.

지금은 신경 쓰지 않아도 되는 때

정직하게 말하면, 사장님 사이트가 가게 소개·메뉴판·포트폴리오라면 이 문서는 아직 남 얘기예요. 남의 기능을 빌린 자리가 없으면 창구를 두드릴 일 자체가 없어요. 여기까지 읽고 덮으셔도 손해가 없어요. 결제나 예약을 붙이는 날 다시 펴면 늦지 않아요.

붙이고 나서도 처음부터 다 챙길 필요는 없어요. 손님이 하루 열 명인 가게에 호출 한도 계산, 재시도 설계, 창구 두 곳 이중화는 시간 낭비예요. 하루 열 명이면 한도에 닿지도 않고, 창구가 한 시간 멈춰도 손님 한 명이 다시 눌러 보면 끝나는 일이에요. 그런 설계는 청구서와 문의가 먼저 알려 줘요. 그때 하면 돼요.

지금 챙길 것	나중에 챙길 것
창구 요금표와 무료 한도	호출 한도 계산과 대기열
출입증을 코드에 안 적기	창구 두 곳 이중화
멈췄을 때 손님이 볼 화면	실패한 요청 자동 재시도
거래처 공지 메일 챙기기	사용량 그래프 상시 감시

사장님이 등장할 순간은 두 번이에요

바이브캠퍼스에서 만들 때 이 용어를 외울 필요는 없어요. "카카오맵 넣어줘", "결제 붙여줘"라고 말하면 창구를 두드리는 코드는 AI가 써요. 사장님 차례는 빌릴지 결정할 때(요금표를 보는 일)와 멈췄을 때(위 표의 문장을 건네는 일)예요. 영어로 된 두꺼운 연동 문서를 읽는 건 AI 몫이에요.

자주 묻는 것

Q. 연동하면 그 회사가 제 손님 정보를 다 보게 되나요?: 그 일에 필요한 만큼만 넘어가요. 문자 회사에는 번호와 문구가, 결제사에는 금액과 결제 정보가 가요. 문제는 필요 이상으로 넘기는 경우예요. 견적 단계에서 "어떤 항목이 그쪽으로 넘어가나요"를 목록으로 받아 두세요. 개인정보에서 더 다뤄요.
Q. 연동 개발비를 한 번 내면 끝인가요?: 개발비는 한 번이지만 창구 요금은 매달이에요. 이 둘이 다른 주머니에서 나간다는 걸 견적 단계에서 확인하세요. 그리고 상대가 규격을 바꾸면 손볼 일이 또 생겨요. 그때 비용을 누가 대는지도 계약에 적어 두면 좋아요.
Q. API랑 API 키는 뭐가 달라요?: API는 창구고, 키는 그 창구에 들어가는 출입증이에요. 창구는 누구에게나 열려 있지만 출입증을 보여준 사람에게만 일을 해 주고, 요금도 그 사람에게 달아요.
Q. 웹훅이라는 말도 자주 보이는데 같은 건가요?: 방향이 반대예요. 내가 알고 싶을 때 물어보는 게 API고, 저쪽에 무슨 일이 생겼을 때 나에게 알려 주는 게 웹훅이에요. 주문 전화와 배송 완료 문자의 차이예요.
Q. 빌려 쓰던 회사가 서비스를 접으면 사이트가 죽나요?: 그 창구를 쓰던 기능만 멈추고 나머지는 돌아가요. 같은 일을 하는 다른 거래처로 갈아 끼우면 되는데 품이 들어요. 그래서 처음부터 오래 갈 만한 곳을 고르는 게 안전해요.
Q. 연동한 기능이 멈춘 게 개발자 잘못인지 어떻게 알아요?: 화면이나 기록에 뜬 숫자로 절반은 갈려요. 400번대는 우리가 낸 주문서 문제라서 손볼 여지가 있고, 500번대는 거래처 사정이에요. 500이 계속 뜬다면 개발자를 다그칠 일이 아니라 그 회사 장애 공지를 볼 일이에요.
Q. 제 서비스도 창구를 열어 줄 수 있나요?: 네. 빌리는 쪽에서 열어 주는 쪽이 될 수도 있어요. 제휴사가 내 재고나 예약을 받아 가게 하는 식이죠. 규모가 커진 뒤 이야기라 지금은 그런 방향이 있다는 것만 알면 충분해요.

확인해 보세요

외주 개발자가 견적서에 "문자 발송 API 연동"이라고 적었어요. 가장 먼저 물어볼 것은?

하나 더

결제 화면에 500이라는 숫자가 떴어요. 이 숫자가 알려 주는 건?

직접 해보기

연결 센터에서 창구 목록을 훑어보세요

결제사·데이터베이스 같은 바깥 서비스를 내 프로젝트에 잇는 곳이에요. 출입증을 넣는 칸이 어떻게 생겼는지, 어떤 창구가 준비돼 있는지 눈으로만 봐도 견적서가 다르게 읽혀요. 지금 연결하지 않아도 돼요.

연결 센터 열기

더 깊이 (안 읽어도 괜찮아요)

창구 비유가 어디서부터 안 맞는가 · 사람 창구는 주문서에 오타가 있으면 직원이 되물어 주고, 사정을 말하면 융통성도 있어요. 기계 창구는 둘 다 없어요. 필수 칸이 비면 아무 설명 없이 거절하고, 정해진 양식에서 한 글자만 달라도 거절해요. 대신 사람과 달리 1초에 수백 통을 받아요. 융통성이 없는 대신 지치지 않는다가 이 비유가 갈리는 지점이에요.

문서에서 REST와 엔드포인트라는 말을 만나면 · REST는 주문서 양식의 가장 흔한 표준 스타일 이름이에요. 개발자가 "REST라서 붙이기 쉬워요"라고 하면 "업계 표준 양식이니 사람 구하기도 쉽고 기간도 짧다"는 뜻으로 들으면 거의 맞아요. 엔드포인트는 창구 안의 개별 접수대 주소예요. 문서 목차에 접수대가 40개 나열돼 있다면 그중 내 기능에 필요한 게 몇 개인지가 곧 견적의 크기예요. 더 자세한 갈래는 서비스끼리 대화하는 창구에 있어요.

주소에 붙은 v1, v2는 양식의 세대예요 · 창구 주소에 v1이나 v2 같은 표시가 붙는 건 양식이 몇 번째 판인지를 뜻해요. 회사가 "v1을 몇 월에 닫습니다"라고 공지하면 옛 양식으로 보낸 주문서가 그날부터 거절돼요. 인수인계 문서에 내 서비스가 어느 창구의 몇 번째 판을 쓰는지 적어 두면, 나중에 다른 사람이 봐도 무엇을 고쳐야 하는지 바로 알아요.

이것만 기억하세요

·"연동"은 남의 창구에 정해진 양식으로 주문서를 내는 일이에요
·견적서에서는 개발비 한 번과 창구 요금 매달, 두 개의 돈을 따로 확인해요
·400번대는 내가 낸 주문서 문제, 500번대는 거래처 문제예요
·고장이 나면 원인을 맞히지 말고 증상 표의 문장을 그대로 전달해요
·손님이 하루 열 명이면 한도 계산과 이중화는 아직 신경 쓸 일이 아니에요