창구 주소(엔드포인트)
연동 설정 화면에서 "주소"를 넣으라는 그 한 줄이에요. 어느 회사 창구인지에서 끝나지 않고, 그 창구 안의 어느 접수대인지까지 가리켜요. 어느 칸에 무엇을 넣는지만 알면 연동 화면에서 헤매지 않아요.
쉽게 말하면
거래처에 전화를 걸 때 대표번호만 알면 주문이 안 들어가요. 대표번호를 누른 다음 "주문 접수는 1번, 반품은 2번, 배송 조회는 3번"까지 눌러야 담당 접수대에 닿죠. 엔드포인트는 대표번호와 내선번호를 붙여 놓은 한 줄이에요. 앞부분이 어느 회사인지, 뒷부분이 그 회사의 어느 접수대인지를 말해요. 창구(API)가 거래처라면 엔드포인트는 그 거래처의 접수대 하나예요.
그래서 연동 문서에는 주소가 하나가 아니라 여러 줄로 나열돼 있어요. 결제 만들기, 결제 취소, 결제 조회가 각각 다른 접수대라서요. 사장님이 할 일은 이 목록에서 지금 필요한 줄을 골라 설정 칸에 그대로 옮기는 것뿐이에요.
회사 문 앞까지만 갔어요. 화면에는 404 같은 숫자가 뜨고, 사장님은 "연동이 안 된다"고만 느껴요.
문서에 적힌 그 줄을 통째로 복사해 넣은 거예요. 연동 설정에서 이게 정답인 경우가 대부분이에요.
주소 한 줄을 토막 내서 읽기
긴 영어 한 줄로 보이지만, 토막마다 하는 일이 정해져 있어요. 토막 이름을 알면 개발자가 "경로가 틀렸어요"라고 할 때 어디를 말하는지 바로 짚을 수 있어요.
| 토막 | 이렇게 생겼어요 | 무슨 뜻인가 | 사장님이 볼 곳 |
|---|---|---|---|
| 앞머리 | https:// | 자물쇠가 걸린 안전한 길로 간다는 표시 | http로 시작하면 요즘은 대부분 막혀요. 자물쇠(HTTPS) 편을 같이 보세요 |
| 회사 이름 | api.결제사.com | 어느 회사의 창구인지. 사람이 보는 홈페이지와 주소가 다른 게 정상이에요 | 회사를 헷갈렸거나 오타면 여기서 틀려요 |
| 버전 표시 | /v1 또는 /v2 | 창구 양식의 세대. 회사가 양식을 바꿀 때 새 번호를 달아요 | 문서는 v2인데 설정은 v1이면 안 붙어요 |
| 접수대 이름 | /payments, /orders | 무슨 일을 접수하는 곳인지. 여기가 내선번호예요 | "주소가 틀렸다"는 말의 대부분이 이 토막이에요 |
| 물음표 뒤 | ?기간=지난달 | 조건을 적어 붙이는 쪽지. 접수대는 그대로 두고 조건만 바꿔요 | 문서가 붙이라고 한 곳에만 붙여요 |
글자 하나가 남의 일이 아니에요
주소 끝의 슬래시 하나, 대문자와 소문자 하나 차이로 접수가 안 되는 창구가 실제로 있어요. 눈으로 옮겨 적지 말고 문서에서 복사해서 붙여 넣으세요. 앞뒤에 빈칸이 딸려 들어가는 것도 흔한 사고예요.
설정 칸마다 원하는 게 달라요
연동 화면에서 사장님을 가장 많이 헷갈리게 하는 건 주소 자체가 아니라 칸이 여러 개라는 점이에요. 이름이 비슷해 보여도 원하는 게 다르고, 어떤 칸은 방향이 반대예요.
| 칸 이름 | 무엇을 원하나 | 잘못 넣으면 |
|---|---|---|
| 엔드포인트 / API 주소 | 접수대까지 다 적힌 전체 한 줄 | 앞부분만 넣으면 없는 접수대라고 나와요 |
| 기본 주소 / Base URL | 접수대 앞까지만. 뒷부분은 프로그램이 알아서 붙여요 | 여기에 접수대 이름까지 넣으면 주소가 두 번 겹쳐서 실패해요 |
| 콜백 주소 / 웹훅 주소 | 방향이 반대예요. 상대 회사가 나에게 알려 줄 때 두드릴 내 쪽 주소예요 | 상대 회사 주소를 넣으면 아무 소식도 안 와요. 알림 받는 창구(웹훅) 편이 여기 이야기예요 |
| 리다이렉트 주소 / 승인 후 돌아올 곳 | 손님이 로그인이나 결제를 마친 뒤 되돌아올 내 화면 주소 | 손님이 결제는 됐는데 빈 화면에 멈춰 있게 돼요 |
| 키 / 시크릿 | 주소가 아니라 열쇠예요. 주소 칸에 넣는 값이 아니에요 | 열쇠를 주소 칸에 넣으면 연동도 안 되고 열쇠가 기록에 남아요. 이용 열쇠(API 키) 편을 보세요 |
정리하면 이래요. 내가 남을 부르는 주소는 상대 회사 문서에서 복사해 오고, 남이 나를 부르는 주소는 내 서비스 주소를 적어 줘요. 이 두 방향만 갈라 놓으면 연동 화면의 절반이 정리돼요.
화면에 뜬 말로 원인 찾기
주소가 틀렸을 때 화면은 "주소가 틀렸어요"라고 친절하게 말해 주지 않아요. 대신 숫자나 짧은 영어를 보여 줘요. 그건 코드가 아니라 표지판이에요. 표지판을 읽고 그대로 AI에게 옮기면, 사장님이 원인을 몰라도 고칠 수 있어요.
| 화면에 이렇게 떠요 | 대개 이런 뜻 | AI에게 이렇게 말하세요 |
|---|---|---|
| 404 / Not Found | 그런 접수대가 없어요. 경로 오타, 버전 불일치, 끝 슬래시 문제 | "연동 주소가 404를 돌려줘요. 접수대 경로가 틀린 것 같아요. 문서에 적힌 주소와 지금 설정된 주소를 나란히 비교해서 다른 곳을 찾아 주세요." |
| 405 / Method Not Allowed | 접수대는 맞는데 부르는 방식이 안 맞아요. 조회 접수대에 등록을 요청한 경우 | "주소는 맞는데 405가 나와요. 이 접수대가 요구하는 방식으로 요청을 바꿔 주세요." |
| 401 또는 403 | 주소가 아니라 열쇠 문제예요. 주소는 손대지 마세요 | "주소는 문서와 같은데 401이 나와요. 열쇠를 붙이는 자리와 테스트 열쇠 여부를 확인해 주세요." |
| 차단됐다는 경고, 혼합 콘텐츠 | 내 사이트는 자물쇠인데 부르는 주소가 자물쇠가 아니에요 | "연동 주소가 보안 경고로 막혀요. https로 시작하는 주소로 바꾸고 남은 곳이 없는지 봐 주세요." |
| 한참 돌다가 실패, 500 | 주소는 닿았는데 상대 쪽이 늦거나 아파요. 내 설정 문제가 아닐 수 있어요 | "연동이 오래 걸리다 실패해요. 기다리는 시간과 다시 시도하는 횟수를 정해 주세요." 기다림과 재시도 편과 함께요 |
| 연습에서는 됐는데 진짜 결제만 실패 | 연습 창구 주소를 그대로 두고 개업했어요. 가장 아까운 사고예요 | "연습용 주소가 남아 있는지 전부 찾아서 실제 주소로 바꿔 주세요." |
표지판을 그대로 옮기는 게 요령이에요. "안 돼요"라고 말하면 스무 가지를 찍어 봐야 하지만, "404가 떠요"라고 말하면 후보가 세 가지로 줄어요. 화면 글자를 읽는 더 넓은 요령은 오류 메시지 읽는 법에 있어요.
견적서와 연동 문서를 읽는 눈
이 말들을 알아 두는 진짜 이유가 여기예요. 견적서와 연동 문서는 원래 개발자끼리 보는 종이라, 뜻을 모르면 금액이 적정한지 판단할 방법이 없어요. 아래 표만 알아도 견적 회의에서 질문을 할 수 있어요.
| 문서·견적서에 나오는 말 | 사장님 말로 | 이렇게 물어보세요 |
|---|---|---|
| 엔드포인트 12개 연동 | 접수대 12곳과 이야기를 맞춰야 한다는 뜻 | "이 12곳이 각각 손님 화면의 무엇인가요? 1차 개업에 꼭 필요한 건 몇 개예요?" |
| Base URL 환경별 분리 | 연습용 창구와 실제 창구 주소를 갈라 둔다는 뜻. 좋은 신호예요 | "연습 창구에서 제가 직접 눌러 볼 수 있게 해 주세요." 연습 무대 편 참고요 |
| GET / POST | 꺼내 오기와 보내 넣기. 접수대가 받는 방식의 이름이에요 | 따로 물을 것 없어요. 405가 떴을 때만 기억하면 돼요 |
| 파라미터, 쿼리 | 주소 뒤에 붙이는 조건 쪽지 | "손님이 조건을 바꿔 검색하면 이 쪽지가 바뀌는 건가요?" |
| 헤더 | 봉투 겉면. 열쇠를 붙이는 자리가 보통 여기예요 | "열쇠는 어디에 보관하나요? 코드에 적히나요?" |
| Rate limit, 호출 한도 | 시간당 접수 가능 횟수. 손님이 몰리면 여기서 막혀요 | "한도를 넘으면 손님 화면에 뭐가 보여요?" 접수 한도 편이 이 이야기예요 |
| Deprecated, v1 종료 예정 | 지금 쓰는 접수대가 언젠가 닫힌다는 예고 | "언제 닫혀요? 그때 옮기는 작업 비용이 이 견적에 들어 있나요?" |
| 응답 형식은 JSON | 답이 오는 종이 양식 이름 | 따로 물을 것 없어요. 주고받는 종이 양식(JSON)에 설명이 있어요 |
견적을 볼 때 하나만 기억하세요
접수대 개수는 화면 개수와 다릅니다. 화면 세 개를 만드는데 접수대가 열 곳 필요할 수도 있고, 반대로 화면 열 개가 접수대 두 곳만 쓸 수도 있어요. "접수대가 많아서 비싸다"는 말을 들으면, 그중 몇 개가 개업 첫날에 필요한지부터 물어보세요. 맡기기 편에 견적 질문 목록이 더 있어요.
사장님이 실제로 겪는 장면
장면 1 · 배달 대행사 담당자와 통화
“주문이 접수되면 알려 드릴 테니, 받으실 주소 하나 알려 주세요.”
여기서 사장님이 상대 회사 주소를 다시 읽어 주면 아무 소식도 안 와요. 이 칸은 방향이 반대예요. 상대가 두드릴 내 쪽 문패를 알려 주는 자리예요. "내 서비스 쪽 주소를 만들어 알려 드리면 되나요?"라고 되물으면 대화가 바로 정리돼요.
장면 2 · 개업 첫날 결제만 안 된다
“연습할 때는 다 됐는데, 손님 카드만 계속 실패해요.”
화면도 코드도 멀쩡하고, 주소 한 줄이 연습용으로 남아 있는 경우예요. 결제사는 연습 창구와 실제 창구를 아예 다른 주소로 나눠 둬요. 개업 전 점검 목록에 "연습용 주소 전부 바꿨나" 한 줄을 넣어 두면 이 사고는 다시 안 나요.
장면 3 · 외주 개발자에게 받은 인수 문서
“운영 Base URL은 여기고, 스테이징은 여기입니다. 키는 별도로 전달드립니다.”
번역하면 "실제 창구 앞주소와 연습 창구 앞주소는 이것이고, 열쇠는 따로 보낸다"예요. 열쇠를 문서에 같이 적어 보내는 개발자보다 이렇게 나눠 보내는 개발자가 일을 제대로 하는 쪽이에요. 받은 주소 두 줄은 지우지 말고 보관하세요. 나중에 사람이 바뀌어도 여기서 다시 시작할 수 있어요.
지금은 신경 쓰지 않아도 되는 때
정직하게 말하면, 이 문서는 읽어 두고 덮어 두는 문서예요. 아래에 해당하면 지금 주소 이야기에 시간을 쓰지 않아도 돼요.
- 1외부 서비스를 아직 안 붙였다면. 소개 화면, 메뉴판, 문의 받기까지는 남의 창구를 부를 일이 없어요. 손님을 먼저 모으는 게 훨씬 급해요.
- 2바이브캠퍼스 안에서 만든 것끼리 주고받는 중이라면. 화면과 데이터를 잇는 주소는 만들 때 자동으로 맞춰져요. 사장님이 손으로 넣을 칸이 안 나와요.
- 3주소가 안 되는 게 아니라 화면이 이상하다면. 글자가 안 맞거나 버튼이 안 예쁜 건 주소 문제가 아니에요. 여기 표를 뒤지지 말고 화면을 고쳐 달라고 말하세요.
- 4손님이 하루 열 명이라면. 접수대를 몇 개로 쪼갤지, 어떻게 빠르게 할지는 지금 고민할 일이 아니에요. 그 고민은 줄이 생긴 다음에 해도 늦지 않아요.
다시 펴 볼 때
결제·문자·지도·배달 중 하나라도 붙이기로 한 날, 그리고 견적서를 받은 날이에요. 그 두 날에만 이 문서가 값을 해요. 그 사이에 외워 둘 필요는 없어요.
자주 묻는 것
- Q. 주소가 왜 이렇게 여러 개예요? 회사 하나에 하나면 안 돼요?
- 접수대마다 받는 일이 다르기 때문이에요. 주문 받는 곳과 취소 받는 곳이 같으면, 부탁을 잘못 알아듣는 사고가 생겨요. 창구를 나눠 두면 어디서 문제가 났는지도 바로 보여요.
- Q. 엔드포인트와 도메인은 뭐가 달라요?
- 가게 간판(도메인)은 회사 이름 토막 하나예요. 엔드포인트는 그 이름에 버전과 접수대 이름까지 붙인 전체 한 줄이에요. 간판이 건물 이름이면 엔드포인트는 몇 층 몇 호까지 적은 주소예요.
- Q. 제가 이 주소를 직접 만들어야 하나요?
- 남을 부르는 주소는 만들 필요 없어요. 상대 회사 문서에 이미 있어요. 만드는 쪽은 남이 나를 부를 주소예요. 그건 보통 만들면서 자동으로 생기고, 사장님은 생긴 주소를 복사해 상대에게 알려 주기만 해요.
- Q. 주소는 비밀이에요? 남이 알면 위험한가요?
- 주소 자체는 비밀이 아니에요. 회사 문서에 공개돼 있는 게 보통이에요. 위험한 건 열쇠예요. 다만 주소 뒤에 열쇠나 손님 정보를 붙여 쓰는 방식이면 그 주소 줄 전체가 비밀이 돼요. 그럴 땐 카톡방이나 메일로 돌리지 마세요.
- Q. 문서에 적힌 대로 넣었는데 안 돼요. 제가 뭘 잘못한 거예요?
- 복사할 때 빈칸이 딸려 왔거나, 끝 슬래시가 있거나 없거나, 연습용과 실제용을 섞은 경우가 대부분이에요. 세 가지를 순서대로 보세요. 그래도 안 되면 화면에 뜬 숫자를 그대로 AI에게 말하면 후보가 확 줄어요.
- Q. 개발자가 "엔드포인트를 새로 하나 파야 한다"고 하면 큰 일이에요?
- 그 자체로는 큰 일이 아니에요. 접수대 하나를 새로 여는 작업이에요. 다만 개수만큼 시간이 붙는 건 사실이니, 지금 만드는 화면에 정말 필요한 접수대인지 한 번 되물어 보는 건 좋아요.
확인해 보세요
배달 대행사가 "주문이 들어오면 알려 드릴 콜백 주소를 알려 주세요"라고 했어요. 무엇을 넣어야 할까요?
하나 더
연동을 눌렀더니 화면에 404가 떴어요. 제일 먼저 볼 곳은?
직접 해보기
연결 센터에서 주소 칸을 눈으로 확인해 보세요
결제사와 데이터 보관함을 붙이는 곳이에요. 주소를 넣는 칸과 열쇠를 넣는 칸이 어떻게 나뉘어 있는지 눈으로만 봐도 충분해요. 지금 연결하지 않아도 돼요.
연결 센터 열기더 깊이 (안 읽어도 괜찮아요)
비유가 어디까지 맞고 어디부터 다른가 · 내선번호 비유는 "앞은 회사, 뒤는 담당 접수대"까지 정확해요. 다른 점은 두 가지예요. 첫째, 전화 내선은 사람이 받지만 접수대는 프로그램이 받아서 정해진 양식만 알아들어요. 양식이 어긋나면 되묻는 대신 그냥 거절해요. 둘째, 같은 주소에 부탁하는 방식이 여러 가지예요. 같은 접수대라도 꺼내 가는 방식과 보내 넣는 방식이 다른 창구처럼 취급돼요. 405 표지판이 바로 이 차이에서 나와요.
버전 번호가 붙어 있는 이유 · 회사가 창구 양식을 바꾸면 이미 붙여 놓은 가게들이 전부 멈춰요. 그래서 새 양식은 새 번호로 열고, 옛 번호는 한동안 같이 열어 둬요. 사장님 입장에서 중요한 건 하나예요. 견적이나 인수 문서에 v1이 적혀 있으면, 그 v1이 언제 닫히는지 물어보고 달력에 적어 두세요. 창구가 닫히는 날은 예고 없이 오지 않지만, 예고를 읽는 사람이 없으면 사고처럼 와요.
연습 창구와 실제 창구를 섞지 않는 습관 · 대부분의 회사는 주소 앞부분만 다르게 해서 연습 창구를 따로 줘요. 여기서 실수가 두 방향으로 나요. 연습 주소로 개업하면 손님 결제가 실패하고, 실제 주소로 연습하면 진짜 돈이 오가고 진짜 문자가 나가요. 후자가 더 무서워요. 그래서 연습과 실제 주소를 한 곳에 모아 적어 두고, 개업 전에 그 목록만 확인하는 게 정석이에요.
이것만 기억하세요
- ·엔드포인트는 회사 이름에 접수대 이름까지 붙인 주소 한 줄이에요
- ·남을 부르는 주소는 상대 문서에서 복사하고, 남이 나를 부르는 주소는 내 쪽 주소를 적어요
- ·화면의 404, 405, 401은 코드가 아니라 표지판이에요. 그대로 말하면 원인이 좁혀져요
- ·견적서의 "접수대 개수"는 화면 개수와 다르니, 개업 첫날에 필요한 수를 되물어요
- ·외부 서비스를 아직 안 붙였다면 지금은 덮어 둬도 되는 문서예요