외부연동 API
현장 시스템(MES)·물류사·자체 개발 프로그램이 볼테나와 자료를 주고받는 방법입니다. ERP 관리자가 시스템 > API 키 관리에서 키를 발급해 전달하면 바로 시작할 수 있습니다.
사람이 쓰는 화면 사용법은 도움말에 있습니다 — 이 페이지는 시스템끼리 자료를 주고받는 방법입니다.
시작하기
- ERP 관리자가 시스템 > API 키 관리에서 연동 상대 이름을 넣고 키를 발급합니다.
- 발급된 키는 그 자리에서 한 번만 표시됩니다 — 복사해 안전하게 보관합니다.
- 모든 요청 헤더에
x-api-key로 그 키를 넣습니다. 회사코드는 보내지 않습니다(키에 담겨 있습니다). - 먼저
GET /api/ext/ping으로 연결과 보유 모듈을 확인합니다.
curl -H "x-api-key: 발급받은키" \
https://app.boltena.com/api/ext/ping
기계가 읽는 스펙(OpenAPI)
코드 생성기·Postman·AI 에이전트가 그대로 소비할 수 있는 OpenAPI 3.1 스펙입니다. 아래 목록과 같은 원본에서 생성되므로 문서와 스펙이 어긋나지 않습니다.
openapi.json 내려받기
제품에서 최신본: GET /api/ext/openapi.json (키 없이 조회 가능)
제공 API
| 메서드 | 경로 | 설명 | 필요 모듈 |
|---|---|---|---|
GET | /api/ext/ping | 연결 확인 키가 유효한지, 어느 회사에 연결되는지, 그 회사가 어떤 모듈을 쓰는지 돌려줍니다. 연동을 시작할 때 가장 먼저 호출합니다. | - |
GET | /api/ext/masters/{entity} | 기준정보 내려받기 품목·거래처·창고·사원·BOM·작업지시를 내려받습니다. `since` 를 주면 그 시각 이후 변경분만 옵니다(증분 동기화). 한 번에 최대 1000행이며, 더 있으면 `truncated: true` 로 알려줍니다. | - |
POST | /api/ext/production/result | 생산실적 보내기 현장 시스템의 생산실적을 ERP 에 기록합니다. `extRef`(보내는 쪽의 고유번호)가 멱등키라, 같은 값으로 다시 보내면 중복 저장 없이 이전 결과를 돌려줍니다(통신 실패 재전송이 안전합니다). `matIssues` 를 함께 보내면 그 실적의 자재는 실투입 기준으로 기록됩니다(BOM 자동차감과 이중공제되지 않습니다). | - |
DELETE | /api/ext/production/result/{extRef} | 생산실적 취소 보냈던 실적을 취소합니다. 보낸 쪽의 고유번호로 지웁니다 — ERP 문서번호를 몰라도 됩니다. | - |
POST | /api/ext/eqp/downtime | 설비 비가동 보내기 설비가 멈춘 시간을 기록합니다(OEE 계산의 재료). 생산실적과 같은 멱등 규칙이 적용됩니다. | EQP 모듈 |
DELETE | /api/ext/eqp/downtime/{extRef} | 설비 비가동 취소 보냈던 비가동 기록을 취소합니다. | EQP 모듈 |
POST | /api/ext/mcp | AI 비서 연결(MCP) AI 비서(Claude·ChatGPT 등)가 이 회사 장부를 **조회**하는 표준 연결부입니다. MCP(Model Context Protocol) 규격 2025-06-18, JSON-RPC 2.0 over HTTP. `initialize` · `tools/list` · `tools/call` · `ping` 을 처리합니다. **조회 전용** — 입력·수정·삭제 도구는 제공하지 않습니다. 도구는 그 회사에서 실제로 열리는 것만 목록에 나옵니다. | - |
POST | /api/ext/attendance | 근태 보내기 근태기(출퇴근 기록기)의 월 근태를 보냅니다. 급여 계산의 근태 자료가 됩니다. 이미 마감된 달은 거부됩니다(마감 후 조용한 변경 금지). | HR 모듈 |
요청·응답 항목의 상세(필수값·예시)는 제품 안 시스템 > API 키 관리 화면의 "연동 문서"에서 항상 최신 상태로 확인할 수 있습니다 — 이 페이지와 같은 원본에서 생성됩니다.
AI 비서에 연결하기 (MCP)
Claude·ChatGPT 같은 AI 비서가 볼테나에 직접 물어보게 할 수 있습니다 — "이번 달 미수채권 큰 거래처 알려줘" 같은 질문에 우리 회사 장부로 답합니다.
연결 주소
POST https://app.boltena.com/api/ext/mcp
인증은 API 키와 같습니다(x-api-key 헤더). 표준 프로토콜(MCP)을 지원하는 AI 도구라면 그대로 연결됩니다.
할 수 있는 것
현재고 · 월별 매출 · 미수채권 · 수주 미납 · 발주 미납 · 합계잔액시산표 · 자재부족 · 미수채권 연체구간 · 재고금액 · 자금일보 조회(10종). 키가 회사를 정하고, 계약하지 않은 모듈과 관리자 전용 자료의 도구는 목록에 나타나지도 않습니다. 키는 개인 계정이 아니라 회사 단위이므로 개인 권한과는 별개로 관리하십시오.
하지 않는 것 — 쓰기
입력·수정·삭제 도구는 제공하지 않습니다. AI 가 장부에 쓰면 사고를 되돌리기 어렵습니다. 장부는 사람이 씁니다.
약속
- 모든 요청에 `x-api-key` 헤더로 발급받은 키를 넣습니다. 키에 회사 정보가 담겨 있어 회사코드를 따로 보내지 않습니다.
- 호출 주소는 모든 고객이 같습니다(회사별 주소가 따로 있지 않습니다) — 어느 회사인지는 키가 정합니다. 전용 서버(온프렘)로 쓰시는 경우에만 계약된 주소를 사용하세요.
- 외부연동은 연동(CONN) 모듈 계약이 있어야 열립니다. 계약이 해지되면 조회(GET)와 취소(DELETE)는 계속 되지만 새로 보내는 것(POST)은 막힙니다 — 이미 보낸 자료를 정리할 길은 항상 열어 둡니다.
- 보내는 쪽 고유번호(extRef)를 반드시 남겨 두세요. 통신이 끊겨 같은 자료를 다시 보내도 중복이 생기지 않고, 나중에 취소할 때도 이 번호로 찾습니다.
- 기준정보는 ERP 가 원본입니다. 외부에서 품목·거래처를 만들거나 고치는 API 는 열려 있지 않습니다(한 장부 원칙).
- 호출 한도는 분당 600회입니다(초과 시 429).
- AI 비서 연결(MCP): 같은 키로 `POST /api/ext/mcp` 에 연결하면 Claude·ChatGPT 같은 AI 비서가 재고·매출·미수채권·수주/발주 잔량·시산표를 직접 조회합니다. 조회 전용이며 입력·수정·삭제 도구는 제공하지 않습니다.
- 키를 발급할 때 그 키의 AI 조회 범위를 지정할 수 있습니다(미지정이면 전체). 범위 밖 도구는 `tools/list` 에 나오지 않고, 이름을 알고 호출해도 데이터 없이 사유만 돌아옵니다. 발급 후 범위 변경은 불가하며 새 키를 발급합니다.
- MCP 조회는 감사 기록에 남습니다 — 어느 키가 언제 어떤 자료를 읽었는지 제품의 사용현황 화면에서 확인할 수 있습니다.
오류 응답
| 코드 | 상황 |
|---|---|
401 | 키가 없거나 유효하지 않음 |
403 | 연동(CONN) 또는 해당 모듈 미계약 · 해지 상태에서 신규 전송 |
400 | 필수값 누락·형식 오류(메시지에 어느 값인지 명시) |
404 | 없는 기준정보 종류·없는 취소 대상 |
429 | 분당 호출 한도 초과 |
자주 묻는 것
같은 자료를 두 번 보내면요?
보내는 쪽 고유번호(extRef)가 같으면 중복 저장되지 않고 처음 결과를 그대로 돌려줍니다. 통신이 끊겨 재전송해도 안전합니다.
외부에서 품목·거래처를 만들 수 있나요?
아니요. 기준정보는 ERP 가 원본이고 내려받기만 제공합니다 — 장부가 둘이 되면 어느 쪽이 맞는지 아무도 답할 수 없기 때문입니다.
계약이 끝나면 어떻게 되나요?
조회(GET)와 취소(DELETE)는 계속 열립니다. 새로 보내는 것만 막힙니다 — 이미 보낸 자료를 정리할 길은 항상 남겨 둡니다.
다른 회사 자료가 섞이지 않나요?
키가 회사를 정하고 서버가 요청값을 믿지 않습니다. 그 키로는 발급한 회사의 자료에만 닿습니다.