ERP가 대답하기 시작했다

클로드 코드 창에 품목 하나를 대고 "지금 몇 개 있어?"라고 친다. 잠시 뒤 창고별 수량이 줄지어 돌아온다. 이카운트 ERP에 로그인한 사람은 아무도 없다.

돌아온 표에는 칸이 일곱 개뿐이다. 품목코드, 품목명, 규격, 수량, 단위, 창고코드, 창고명. 단가와 거래처는 없다. 빠진 게 아니라 내가 뺐다.

이 장면 하나를 만들기까지 막힌 곳은 대부분 이카운트 쪽에 있었다. 클로드 쪽은 생각보다 싱거웠다. 이 글은 이카운트를 클로드에 연결하려는 사람이 실제로 걸리는 자리를 순서대로 적은 것이다. 왜 만들었는지, 지금 60명이 어떻게 쓰고 있는지는 ONE STOCK 글에 따로 있다.

• 연결은 세 번의 호출이다
• 테스트키, 그리고 "검증"이라는 관문
• 이카운트 API가 주지 않는 것
• 클로드에 붙일 때 걸리는 것
• AI에게 가린 것
• 운영에서 터진 것: IP 허용목록
• 자주 받는 질문

연결은 세 번의 호출이다

이카운트 OAPI 스펙을 통째로 받아두니 222KB짜리 파일 하나였다. 기능보다 먼저 알아야 하는 게 주소 규칙이다. 로그인 주소가 회사마다 다르다.

1. Zone 조회. 회사코드를 보내면 우리 회사 서버 구역(Zone)이 돌아온다. 이 주소만 모든 회사가 같다.
2. 로그인. 받은 Zone을 주소에 끼워 인증키로 로그인한다. 응답에 SESSION_ID가 온다. 30분짜리다.
3. 호출. 이후 모든 API는 주소 끝에 SESSION_ID를 붙여 부른다.

1) POST https://oapi.ecount.com/OAPI/V2/Zone
   { COM_CODE }                                   → ZONE
 
2) POST https://oapi{ZONE}.ecount.com/OAPI/V2/OAPILogin
   { COM_CODE, USER_ID, API_CERT_KEY, LAN_TYPE, ZONE }  → SESSION_ID (30분)
 
3) POST https://oapi{ZONE}.ecount.com/OAPI/V2/{API 경로}?SESSION_ID=...

이게 전부다. "이카운트 OAPI 경로"를 검색하는 사람이 찾는 답도 대부분 여기 있다. Zone을 먼저 묻고, 그 Zone이 로그인 주소의 일부가 된다.

30분짜리 세션은 만료되면 알아서 다시 로그인하게 만들어야 한다. 이 부분에서 시스템이 30분마다 먹통이 됐던 이야기는 ONE STOCK 글의 "세션 버그"에 있다.

테스트키, 그리고 "검증"이라는 관문

이카운트 인증키는 두 종류다. 테스트키와 실서버키. 주소도 다르다.

두 번째 줄이 핵심이다. 실서버키를 받았다고 모든 API가 열리지 않는다. 테스트키로 한 번 불러서 통과한 API만 실서버키로 열린다. 이카운트는 이걸 "검증"이라고 부른다.

기준은 조회와 저장이 다르다.

• 조회 API는 응답 코드 200만 받으면 검증된다. 데이터가 틀려도 상관없다
• 저장 API는 테스트 서버에 실제로 한 건 이상 저장이 성공해야 검증된다. 입력 권한이 없거나 코드가 틀려서 난 에러로는 통과가 안 된다

그래서 쓰기 기능은 계획한 대로 열리지 않았다. 저장 API 열 개를 시도해서 검증을 통과한 건 넷(수주, 판매, 견적, 출퇴근)이다. 셋은 내 계정에 입력 권한이 없어서, 셋은 창고 유형이 생산공장이어야 해서 막혀 있다. API 문제가 아니라 ERP 안의 권한과 기준정보 문제다.

하나 더. 테스트키 발급은 기본 3회다. 넘으면 따로 요청해야 한다. 키를 막 재발급하며 실험하면 금방 바닥난다.

이카운트 API가 주지 않는 것

연결이 되고 나서 부딪힌 건 "이 데이터는 API로 안 나온다"는 벽이었다.

BOM이 없다

제조업에서 제일 필요한 BOM(자재명세서) 조회가 공식 OAPI에 없었다. 원자재가 충분한지 계산하는 기능이 통째로 날아갈 뻔했다. 결국 이카운트 웹 화면이 쓰는 내부 요청을 찾아서 붙였다. 이건 OAPI 세션이 아니라 ERP 웹 로그인 세션이 따로 필요하고, 비공식이라 이카운트가 화면을 바꾸면 깨질 수 있다. 이틀 걸려 찾은 과정은 ONE STOCK 글의 "사고 2"에 있다.

한 번에 30일, 호출 사이 1.1초

조회 기간은 한 번에 최대 30일이다. 1년 치 판매를 보려면 열두 번 나눠 불러야 한다. 호출 사이 간격은 1.1초 이상 둬야 한다. 품목 수백 개를 하나씩 물으면 몇 분이 걸린다.

여기서 구조를 정했다. AI가 물을 때마다 ERP로 가지 않는다. 동기화 도구로 ERP에서 데이터를 가져와 로컬 DB(SQLite)에 쌓아두고, AI는 거기서 읽는다. 급할 때만 ERP에 실시간으로 묻는다. 느리고 정확한 것과 빠르고 조금 늦은 것 중에, 기본값을 빠른 쪽에 두고 사람이 필요할 때 정확한 쪽을 고르게 했다.

클로드에 붙일 때 걸리는 것

이카운트와 클로드 사이에는 MCP 서버를 하나 뒀다. MCP(Model Context Protocol)는 AI가 외부 시스템을 "도구"로 부를 수 있게 하는 표준이다. 이카운트 API를 도구로 감싸두면, 클로드는 이카운트의 주소 규칙이나 세션을 몰라도 get_inventory 같은 도구 이름만 부르면 된다.

클로드 쪽에서 걸린 건 두 가지였다.

첫째, MCP 서버는 .env 파일을 알아서 읽지 않는다. 그대로 두면 인증키와 회사코드가 서버에 안 들어가 로그인부터 실패한다. 클로드 코드의 MCP 설정에 환경변수를 직접 넣어야 한다. 설정 파일은 클로드 코드가 실행 중에도 계속 고쳐 쓰기 때문에, 손으로 편집하기보다 claude mcp 명령으로 등록하는 편이 안전했다.

둘째, MCP 서버를 고치면 클로드 코드를 재시작해야 반영된다. 실행 중에는 서버를 다시 읽지 않아서, 고친 뒤에도 예전 동작이 그대로 나온다.

그다음은 도구를 어떻게 나눌지였다. 지금 도구는 37개다. 조회 18개, 동기화 4개, 쓰기 15개.

API 하나에 도구 하나를 맞추지 않았다. 현장에서 묻는 질문 단위로 나눴다. "재고 몇 개야"는 get_inventory, "창고별로 보여줘"는 get_inventory_by_warehouse, "이거 만들려면 뭐 들어가"는 get_bom. 동기화 도구는 따로 떼었다. 30일 제한과 1.1초 간격을 AI 대화 안에서 기다리게 하지 않으려고, ERP에서 가져오는 일은 동기화 도구가 하고 조회 도구는 쌓인 데이터만 본다.

AI에게 가린 것

연결보다 오래 고민한 게 이거였다. ERP에는 회사의 거의 모든 게 들어 있다. 매입 단가, 판매 금액, 거래처 연락처. 클로드는 외부 모델이다. 재고를 묻는 데 단가까지 넘길 이유가 없다.

그래서 가장 많이 불리는 재고 도구에는 MCP 서버에서 두 겹을 씌웠다.

• 먼저 가린다. 이름에 PRICE, AMT, VAT, COST, SUPPLY가 들어간 값은 ***로, 거래처 코드·거래처명·전화·이메일·주소도 ***로 바꾼다
• 그다음 남긴다. 일곱 칸만 통과시킨다. 품목코드, 품목명, 규격, 수량, 단위, 창고코드, 창고명

기록도 남긴다. 로그인 성공과 실패, 세션 만료와 재시도, 도구 오류는 전부 감사 로그에 쌓인다. 이 로그가 한 번 제 몫을 했다. 팀즈 재고봇이 당연히 우리 서버를 거친다고 믿고 있었는데, 로그에 외부 호출이 0건이었다. 확인해 보니 팀즈 쪽 Power Automate 흐름 다섯 개가 전부 이카운트 OAPI를 직접 부르고 있었다. 기록이 없었으면 틀린 구조도를 계속 믿고 있었을 거다.

운영에서 터진 것: IP 허용목록

연결이 끝나고 한참 뒤, 가장 오래 괴롭힌 건 코드가 아니라 이카운트 설정 한 칸이었다. 팀즈 방에서 품목을 물으면 창고별 수량이 돌아오는 재고봇이 있는데, 이게 멈추면 현장은 바로 안다.

이카운트 실서버키는 등록된 IP에서만 로그인된다. 등록 안 된 곳에서 부르면 Code 205 "허용되지 않은 IP". 등록 화면은 ERP의 Self-Customizing > 정보관리 > API인증키발급 > IP등록이다.

함정은 에러가 오는 방식이다. 로그인 요청의 HTTP 응답은 200으로 온다. 에러는 본문 안에 Code 205로 숨어 있다. 그러면 SESSION_ID가 비고, 다음 호출이 "Please login"으로 실패한다. 팀즈 재고봇은 그걸 재시도하느라 11분 넘게 돌다 멈췄다. 겉으로 보이는 에러는 재고 조회였지만 원인은 그 앞의 로그인이었다.

칸이 다섯 개라고 믿었다

7월 중순부터 한 달 사이 네 번 터졌다.

첫 번째는 팀즈 봇이 나가는 Azure 쪽 IP가 바뀌면서였다. 새 IP를 등록하려는데 기록에 "허용목록은 최대 5개"라고 적혀 있었다. 칸이 없다고 판단하고, 안 쓰는 줄 알았던 사무실 IP 하나를 지웠다. 사무실 회선은 IP 세 개를 돌아가며 쓰고 있었다. 다음 날 같은 허용목록을 쓰던 다른 시스템(SIGNAL)의 이카운트 동기화가 멈췄다.

며칠 뒤 등록 화면 상단 안내문을 직접 읽었다. 최대 20개였다. 다섯 개는 처음 누가 잘못 적은 숫자였고, 그 숫자를 두 번이나 믿고 지웠다. 그 뒤로 규칙은 하나다. 지우지 않는다. 추가만 한다.

고장이 아니라 확률이었다

네 번째는 증상부터 달랐다. 완전히 먹통이 아니라 됐다 안 됐다 했다.

Power Automate가 나가는 IP는 고정이 아니었다. 같은 대역 안에서 요청마다 끝자리가 바뀐다. 한 번의 실행 안에서도 로그인과 조회가 서로 다른 IP로 나갔다. 등록된 끝자리에 걸리면 성공, 아니면 실패. 체감 실패율이 절반쯤 됐다.

그래서 관측된 대역의 끝자리 열 개를 통째로 미리 등록했다. 기존 칸은 하나도 건드리지 않고 빈칸에만 넣었다. 20칸 중 15칸을 쓰고 있다. 대역 자체가 또 옮겨가면 다시 터질 수 있어서, 근본 해결은 팀즈 봇이 이카운트를 직접 부르지 않고 사무실 서버를 거치게 바꾸는 것이다. 그러면 허용목록에는 사무실 IP만 있으면 된다.

205가 뜨면 조회 쪽이 아니라 로그인 응답 본문부터 본다. 거기에 막힌 IP가 그대로 찍혀 있다.

자주 받는 질문